\
.\" 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 "Pamcat User Manual" 0 "30 November 2022" "netpbm documentation"

.SH NAME

pamcat - concatenate Netpbm images

.UN synopsis
.SH SYNOPSIS

\fBpamcat\fP

{\fB-leftright\fP | \fB-lr\fP | \fB-topbottom\fP | \fB-tb\fP}

[\fB-white\fP|\fB-black\fP]

[\fB-jtop\fP|\fB-jbottom\fP|\fB-jcenter\fP]
[\fB-jleft\fP|\fB-jright\fP|\fB-jcenter\fP]

[\fInetpbmfile\fP ... | \fB-listfile=\fP{\fIfilename\fP|\fB-\fP}]
.PP
Minimum unique abbreviation of option is acceptable.  You may use
double hyphens instead of single hyphen to denote options.  You may
use white space in place of the equals sign to separate an option name
from its value.

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpamcat\fP reads one or more Netpbm images as input, concatenates them
either left to right or top to bottom, and produces a single Netpbm image as
output.
.PP
Options \fB-leftright\fP and \fB-topbottom\fP determine the direction
  of the concatenation.
  
.PP
The images do not have to be the same shape:  You can concatenate images
  of different widths top to bottom and of different heights left to right.
  You can concatenate images of different depths (numbers of planes).  You
  can concatenate a PBM image with a PPM image.  Et cetera.
.PP
The format of the output image is the highest of the formats of the
  input images, in the order PBM, PGM, PPM, PAM.
.PP
For PAM output, if all of the input images have the same tuple type
  (including implied tuple types of PNM images), that is the tuple type of the
  output.  If the inputs differ, but are all visual tuple types, the
  output's tuple type is the most primitive that can represent all the
  input.  E.g. if inputs are GRAYSCALE and RGB, the output is RGB, and if the
  inputs are GRAYSCALE_ALPHA and RGB, the output is RGB_ALPHA.  If the inputs
  differ and are not all visual, the output tuple type is a null string.
.PP
When the output is PAM, its depth is the maximum of the depths of the
  inputs (including implied depths of PNM images), but at least enough to
  represent the tuple type specified above.  In the case of nonvisual PAM
  output, input images are padded to this output depth with higher numbered
  planes of all zeroes.
.PP
Where the input images are of different widths and you concatenate top
  to bottom, \fBpamcat\fP generates output as wide as the widest of the
  inputs and pads the narrower ones.  The images can be justified either
  left, right, or center within this padded field.  Use options
  \fB-jleft\fP, \fB-jright\fP, and \fB-jcenter\fP to control this.
.PP
Similarly, where the input images are of different heights and you
  concatenate left to right, \fBpamcat\fP generates output as tall as the
  tallest of the inputs and pads the shorter ones.  The images can be
  justified either top, bottom, or center within this padded field.  Use
  options
  \fB-jtop\fP, \fB-jbottom\fP, and \fB-jcenter\fP to control this.
.PP
You can make the padding black or white or let \fBpamcat\fP determine a
  likely background color, with possibly different colored padding for each
  input image.  Control this with the \fB-black\fP and \fB-white\fP options.
.PP
Where the output image contains transparency information (because at least
  one of the input images does), the padding is opaque.  (That is consistent
  with the result for an output image without transparency information, because
  such an image is defined to be opaque).
  
.PP
The arguments are names of input files.  Any one of these, but not more
than one, may be "-" to indicate Standard Input.  If you have no arguments
(and do not specify \fB-listfile\fP), that means a single input image from
Standard Input (and that is pointless - the output is the same as the input).
You can supply the file names in a file instead of as arguments with a
\fB-listfile\fP option.
.PP
Regardless of how you specify the input files, you may not concatenate
  more files than your system's limit on the number of concurrently
  open files by one process.  16 is a typical number for that.
.PP
To assemble a regular grid of images, you can use \fBpamundice\fP.
.PP
To do the reverse, you might use \fBpamdice\fP to split an image
up into smaller ones of equal size or \fBpamcut\fP to chop off part
of an image or extract part of an image.
.PP
\fBpnmtile\fP concatenates a single input image to itself repeatedly.


.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
\&), \fBpamcat\fP recognizes the following
command line options:

.UN direction
.SS Direction


.TP
\fB-topbottom\fP, \fB-tb\fP
Combine images vertically, top to bottom.

.TP
\fB-leftright\fP, \fB-lr\fP
Combine images horizontally, left to right.
.sp
You must specify the direction by specifying one of the above.  You cannot
    specify both.



.UN justification
.SS Justification


.TP
\fB-jleft\fP
  
Left-justify images in a top-bottom concatenation.
.sp
You cannot specify this with \fB-jright\fP
.sp
This option is invalid in a left-right concatenation.

.TP
\fB-jright\fP
  
Right-justify images in a top-bottom concatenation.
.sp
You cannot specify this with \fB-jleft\fP
.sp
This option is invalid in a left-right concatenation.

.TP
\fB-jtop\fP
  
Top-justify images in a left-right concatenation.
.sp
You cannot specify this with \fB-jbottom\fP
.sp
This option is invalid in a top-bottom concatenation.

.TP
\fB-jbottom\fP
  
Bottom-justify images in a left-right concatenation.
.sp
You cannot specify this with \fB-jtop\fP
.sp
This option is invalid in a top-bottom concatenation.

.TP
\fB-jcenter\fP
  
Center images (valid for both left-right and top-bottom concatenations).
    This is the default.
    

.PP
By default, \fBpamcat\fP centers the smaller images.
  \fB-topbottom -jleft\fP would stack the images on top of each other, flush
  with the left edge.  \fB-leftright -jbottom\fP would line up the images
  left to right with their bottom edges aligned as if sitting on a table.


.UN paddingcolor
.SS Padding Color
These options specify what color to use to fill in the extra space when
doing the justification.  If neither is specified, \fBpamcat\fP chooses
whichever color seems to be right for the images, and the color may be
different for each image.

.TP
\fB-white\fP
Make all padding white.
.sp
You may not specify this with \fB-black\fP
.TP
\fB-black\fP
Make all padding black.
.sp
You may not specify this with \fB-white\fP



.UN miscellaneousopt
.SS Miscellaneous


.TP
\fB-listfile=\fP{\fIfilename\fP|\fB-\fP}
This specifies the name of a file that contains the list of input files.
  Option value \fB-\fP means the list comes from Standard Input.
.sp
The file contains one file name per newline-delimited line in whatever
    code the system \fBfopen\fP service expects.  You may omit the newline
    on the last line.  Empty lines are ignored.  There is no mechanism for
    including comments in the list (so if you want to have a commented list,
    preprocess it to remove comments before supplying it to \fBpamcat\fP).
.sp
You may not specify file names as command line arguments together with
    \fB-listfile\fP
.sp
You may not list more files than than your system's limit on the
  number of concurrently open files by one process.  16 is a typical number
  for that.
.sp
This option was new in Netpbm 11.01 (December 2022).



.UN seealso
.SH SEE ALSO
.BR "pamundice" (1)\c
\&,
.BR "pamdice" (1)\c
\&,
.BR "pnmtile" (1)\c
\&,
.BR "pamcut" (1)\c
\&,
.BR "pnm" (1)\c
\&,
.BR "pam" (1)\c
\&


.UN history
.SH HISTORY
.PP
\fBpamcat\fP was new in Netpbm 11.00 (September 2022); in earlier versions,
  \fBpnmcat\fP does most of the same thing.
.PP
Primordial Netpbm/Pbmplus contained concatenation tools, but there were two
  of them: \fBpbmcatlr\fP for left-right concatenation of PBM images
  and \fBpbmcattb\fP for top-bottom concatenation.  When the PGM and PPM
  formats were added, these programs were combined and extended to handle all
  three formats, as \fBpnmcat\fP.  All of this work was done by Pbmplus
  author Jef Poskanzer.
.PP
In Netpbm 10.44 (September 2008), Akira F Urushibata added special fast
  processing for raw PBM images, exploiting bitstring processing CPU
  facilities.
.PP
\fBpnmcat\fP was one of the most essential programs in Netpbm, but one
  thing it could not concatenate was PAM images with transparency.  So in
  Netpbm 11.00 (September 2022), Bryan Henderson wrote \fBpamcat\fP to
  replace it.  It reused the raw PBM fast path code from \fBpnmcat\fP almost
  verbatim.
.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/pamcat.html
.PP