Pamcat User Manual

# pamcat

Updated: 30 July 2022
Table Of Contents

## NAME

pamcat - concatenate Netpbm images

## SYNOPSIS

pamcat {-leftright | -lr | -topbottom | -tb} [-extendplane] [-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.

pamcat reads one or more Netpbm images as input, concatenates them either left to right or top to bottom, and produces a single PAM image as output.

As an exception for greater efficiency, pamcat produces raw PBM output if all of the input images are raw PBM.

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.

Where the input images are of different depths, the depth of the output is the maximum of the depths of the inputs. pamcat adds higher numbered planes to the input images as padding. You can choose whether those higher planes have all zero (black) sample values or duplicate the highest numbered plane in the input. Use the -extendplane option for this. The duplication function is useful when your inputs are visual images, without transparency planes, because it effectively translates black and white pixels from a 1-plane black and white input image to black and white pixels in 3-plane color output and gray pixels from a 1-plane grayscale input image to the same grays in 3-plane color output.

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.

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

### Depth Extension

  This option controls what happens when the input image have different depths (number of planes), so pamcat adds planes to the shallower input images.

  The default is to make the additional planes all zero.

-extendplane
  Make the additional planes copies of the highest numbered plane in the input.

  This is appropriate whenever the input images are visual images without a transparency plane. PBM, PGM, and PPM images are all examples of visual images without a transparency plane. PAM images with tuple types "BLACKANDWHITE", "GRAYSCALE", and "RGB" are also examples.

## SEE ALSO

pamundice, pamdice, pnmtile, pamcut, pnm, pam

## HISTORY

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.

At that time, Netpbm continued to include pnmcat, but now it did nothing but invoke pamcat with an -extendplane option and pipe the output through pnmtopnm. It was intended for backward compatibility only.

## Table Of Contents

- SYNOPSIS
- DESCRIPTION
- OPTIONS
  - Direction
  - Justification
  - Padding Color
  - Depth Extension
- SEE ALSO
- HISTORY