pamcat - Man Page

concatenate Netpbm images

Synopsis

pamcat

{-leftright | -lr | -topbottom | -tb}

[-white|-black]

[-jtop|-jbottom|-jcenter] [-jleft|-jright|-jcenter]

netpbmfile ...

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 has 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, that means a single input image from Standard Input (and that is pointless - the output is the same as the input).

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

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

http://netpbm.sourceforge.net/doc/pamcat.html

Referenced By

pamcut(1), pnmcat(1), pnmindex(1), pnmmontage(1), ppmrough(1).

30 July 2022 netpbm documentation