\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pamstack User Manual" 1 "18 May 2023" "netpbm documentation"

.SH NAME
pamstack - stack planes of multiple PAM images into one PAM image

.UN synopsis
.SH SYNOPSIS

\fBpamstack\fP
[\fB-tupletype \fP\fItupletype\fP]
[\fB-firstmaxval\fP,\fB-lcmmaxval\fP]
[\fIinputfilespec\fP ...]
.PP
All options may be abbreviated to the shortest unique prefix.  You
may use two hyphens instead of one.  You may separate an option from
its value with a space instead of \fB=\fP.

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpamstack\fP reads multiple PAM or PNM images as input and
produces a PAM image as output, consisting of all the planes
(channels) of the inputs, stacked in the order specified.
.PP
It can also just change the tuple type of a single PAM image.
  
.PP
For any one (but not more) of the input files, you may specify "-" to mean
Standard Input.  If you specify no arguments at all, the input is one file:
Standard Input.
.PP
The output is the same dimensions as the inputs, except that the depth is
  the sum of the depths of the inputs.  The maxval is the same as the inputs
  if they are all alike, and controlled by \fB-firstmaxval\fP
  and \fB-lcmmaxval\fP if not.  The tuple type is a null string unless you
  specify the \fB-tupletype\fP option.
  
.PP
 \fBpamstack\fP fails if the inputs are not all the same width and height.
It also fails if they do not all have the same maxval, unless you specify
\fB-firstmaxval\fP or \fB-lcmmaxval\fP.
.PP
\fBpamstack\fP works with multi-image streams.  It stacks the 1st
image in all the streams into one output image (the first one in the
output stream), then stacks the 2nd image in all the streams into the
2nd image in the output stream, and so on, until one of the streams
runs dry.  It's like a matrix operation.
.PP
Before Netpbm 10.32 (February 2006), \fBpamstack\fP ignored all but
the first image in each input stream.
.PP
\fBpamchannel\fP does the opposite of \fBpamstack\fP:  It extracts
individual planes from a single PAM.
.PP
Use
.BR "pamtopnm" (1)\c
\& to convert a suitable PAM
image to a more traditional PNM (PBM, PGM, or PPM) image.  (But there's
no need to do that if you're going to feed it to a modern Netpbm program --
they all take suitable PAM input directly).
.PP
One example of using \fBpamstack\fP is that some Netpbm programs
accept as input a PAM that represents graphic image with transparency
information.  Taking a color image for example, this would be a PAM
with tuple type "RGB_ALPHA".  In Netpbm, such images were
traditionally represented as two images - a PPM for the color and a
PGM for the transparency.  To convert a PPM/PGM pair into
PAM(RGB_ALPHA) input that newer programs require, do something like
this:

.nf
\f(CW
$ pamstack -tupletype=RGB_ALPHA myimage.ppm myalpha.pgm | \e
      pamtouil >myimage.uil
\fP

.fi

.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBpamstack\fP recognizes the following
command line option:



.TP
\fB-tupletype \fP\fItupletype\fP
This specifies the tuple type name to be recorded in the output.  You may
use any string up to 255 characters.  Some programs recognize some names.
If you omit this option, the default tuple type name is null.

.TP
\fB-firstmaxval\fP
This says to make the maxval of the output the same as the maxval of the first
image of the input; the program scales sample values of other images are as
necessary.
.sp
By default, \fBpamstack\fP requires all the input images to have the same
maxval.  If they don't, it fails.
.sp
You cannot specify this with \fB-lcmmaxval\fP.
.sp
This option was new in Netpbm 11.03 (June 2023).
  
.TP
\fB-lcmmaxval\fP
This says to make the maxval of the output the least common multiple of the
maxvals of the input images, limited to 65535 if the LCM is above that; the
program scales sample values of other images are as necessary.
.sp
By default, \fBpamstack\fP requires all the input images to have the same
maxval.  If they don't, it fails.
.sp
You cannot specify this with \fB-firstmaxval\fP.
.sp
This option was new in Netpbm 11.03 (June 2023).



.UN seealso
.SH SEE ALSO
.BR "pam" (1)\c
\&
.BR "pamchannel" (1)\c
\&

.UN history
.SH HISTORY
.PP
\fBpamstack\fP was new in Netpbm 10.0 (June 2002).
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pamstack.html
.PP