NAME
pamcat - concatenate Netpbm images
SYNOPSIS
pamcat
{-leftright | -lr | -topbottom | -tb}
[-white|-black]
[-jtop|-jbottom|-jcenter] [-jleft|-jright|-jcenter]
[netpbmfile ... | -listfile={filename|-}]
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.
DESCRIPTION
This program is part of Netpbm(1).
pamcat 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.
Options
-leftright and -topbottom determine the
direction
of the concatenation.
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.
The format of
the output image is the highest of the formats of the
input images, in the order PBM, PGM, PPM, PAM.
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.
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.
Where the input
images are of different widths and you concatenate top
to bottom, pamcat 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
-jleft, -jright, and -jcenter to control
this.
Similarly,
where the input images are of different heights and you
concatenate left to right, pamcat 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
-jtop, -jbottom, and -jcenter to control
this.
You can make
the padding black or white or let pamcat determine a
likely background color, with possibly different colored
padding for each
input image. Control this with the -black and
-white options.
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).
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 -listfile), 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 -listfile option.
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.
To assemble a regular grid of images, you can use pamundice.
To do the reverse, you might use pamdice to split an image up into smaller ones of equal size or pamcut to chop off part of an image or extract part of an image.
pnmtile concatenates a single input image to itself repeatedly.
OPTIONS
In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options ), pamcat recognizes the following command line options:
Direction
-topbottom, -tb
Combine images vertically, top to bottom.
-leftright, -lr
Combine images horizontally, left to right.
You must
specify the direction by specifying one of the above. You
cannot
specify both.
Justification
-jleft |
Left-justify images in a top-bottom concatenation. |
You cannot specify this with -jright
This option is invalid in a left-right concatenation.
-jright
Right-justify images in a top-bottom concatenation.
You cannot specify this with -jleft
This option is invalid in a left-right concatenation.
-jtop |
Top-justify images in a left-right concatenation. |
You cannot specify this with -jbottom
This option is invalid in a top-bottom concatenation.
-jbottom
Bottom-justify images in a left-right concatenation.
You cannot specify this with -jtop
This option is invalid in a top-bottom concatenation.
-jcenter
Center images
(valid for both left-right and top-bottom concatenations).
This is the default.
By default,
pamcat centers the smaller images.
-topbottom -jleft would stack the images on top of each
other, flush
with the left edge. -leftright -jbottom would line up
the images
left to right with their bottom edges aligned as if sitting
on a table.
Padding
Color
These options specify what color to use to fill in the extra
space when doing the justification. If neither is specified,
pamcat chooses whichever color seems to be right for
the images, and the color may be different for each
image.
-white |
Make all padding white. |
You may not specify this with -black
-black |
Make all padding black. |
You may not specify this with -white
Miscellaneous
-listfile={filename|-}
This specifies the name of a
file that contains the list of input files.
Option value - means the list comes from Standard
Input.
The file
contains one file name per newline-delimited line in
whatever
code the system fopen 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
pamcat).
You may not
specify file names as command line arguments together with
-listfile
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.
This option was new in Netpbm 11.01 (December 2022).
SEE ALSO
pamundice(1), pamdice(1), pnmtile(1), pamcut(1), pnm(1), pam(1)
HISTORY
pamcat
was new in Netpbm 11.00 (September 2022); in earlier
versions,
pnmcat does most of the same thing.
Primordial
Netpbm/Pbmplus contained concatenation tools, but there were
two
of them: pbmcatlr for left-right concatenation of PBM
images
and pbmcattb for top-bottom concatenation. When the
PGM and PPM
formats were added, these programs were combined and
extended to handle all
three formats, as pnmcat. All of this work was done
by Pbmplus
author Jef Poskanzer.
In Netpbm 10.44
(September 2008), Akira F Urushibata added special fast
processing for raw PBM images, exploiting bitstring
processing CPU
facilities.
pnmcat
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
pamcat to
replace it. It reused the raw PBM fast path code from
pnmcat almost
verbatim.
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool ’makeman’ from HTML source. The master documentation is at