Join Netpbm Images Safely with pnmcat and pamcat

pnmcat glues two or more Netpbm images together, side by side or stacked. On this machine the installed pnmcat is only a compatibility name for pamcat from Netpbm 11.5.2. Allow about fifteen minutes, and have readable Netpbm image files plus a writable output directory ready.

No elevated privileges are normally needed: this workflow reads the inputs and writes a new output file, and never edits the sources. Take care with shell redirection, because > truncates an existing destination before the command starts.

1. Confirm which command you have

The old pnmcat(1) manual says the program was replaced by pamcat, introduced in Netpbm 11.00. Check the package and the executable before putting an example into a script:

$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ command -v pnmcat
/usr/bin/pnmcat
$ ls -l /usr/bin/pnmcat
... /usr/bin/pnmcat -> pamcat

The exact package revision and the ls timestamp can differ. What matters is the package name, the command path and the link target. Use pamcat in new documentation when you can; keep pnmcat only when maintaining an older script or following a workflow that names it.

2. Choose the direction explicitly

• -leftright, or -lr: places the inputs side by side.
• -topbottom, or -tb: stacks them vertically.

$ pnmcat -leftright /path/to/left.ppm /path/to/right.ppm > joined.ppm
$ pamcat -topbottom /path/to/top.ppm /path/to/bottom.ppm > stacked.ppm

The output goes to standard output, hence the redirection. Input order matters: the first file is leftmost for a horizontal join and topmost for a vertical join. The files do not need matching dimensions, but the result may need padding around the smaller image.

Do not omit the direction. The installed command rejects that mistake instead of guessing:

$ pnmcat /path/to/first.ppm /path/to/second.ppm
pnmcat: You must specify either -leftright or -topbottom

3. Protect an existing output

Before writing, choose a new destination or make a backup, because a failed conversion can still leave a truncated file once the shell has opened the destination:

$ test ! -e joined.ppm && echo 'destination is unused'
$ pnmcat -leftright /path/to/left.ppm /path/to/right.ppm > joined.ppm.new
$ file joined.ppm.new
$ mv joined.ppm.new joined.ppm

The final mv replaces an old destination only after the command has produced the new file. If the conversion fails, leave the original alone and inspect the error.

4. Control alignment and padding

When images have different heights in a left-to-right join, the default is to centre the shorter image vertically:

• Left-right join: use -jtop, -jbottom or -jcenter to choose the alignment.
• Top-bottom join: use -jleft, -jright or -jcenter instead.

$ pamcat -leftright -jbottom -white /path/to/left.ppm /path/to/right.ppm > joined-bottom.ppm
$ pamcat -topbottom -jright -black /path/to/top.ppm /path/to/bottom.ppm > stacked-right.ppm

-white makes all padding white and -black makes it black. If neither is supplied, pamcat chooses what it considers a likely background colour, possibly separately for each input. Do not combine -white and -black, and use the full option names in scripts so the intended layout is obvious.

A horizontal join with inputs of heights 1 and 2 has the height of the taller input. If the first input is 2 pixels wide and the second is 1 pixel wide, the result is 3 pixels wide. Verify the dimensions rather than trusting a viewer to make the layout clear.

5. Verify the result

Check the exit status and inspect the output as an image file:

$ pamcat -leftright -white /path/to/left.ppm /path/to/right.ppm > joined.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file joined.ppm
joined.ppm: Netpbm image data, size = 3 x 2, rawbits, pixmap

The dimensions above come from two small test images, not a promise about your files, and your own file wording may differ. Confirm the width and height are what the join requires, then open the result with a trusted image viewer or pass it to a separate Netpbm converter.

The output format is the highest input format in the order PBM, PGM, PPM and PAM, so combining a PPM with a PAM can produce PAM output. That is expected: do not infer the format from the filename extension alone.

6. Handle larger batches carefully

You can list more than two input files:

$ pamcat -topbottom -jcenter image-01.pnm image-02.pnm image-03.pnm > contact-sheet.pnm

The program opens the inputs concurrently, and the manual notes that the system's open-file limit applies, with 16 files being typical. For a long list, split the work into groups, or use -listfile=FILE when your installed version supports it. Netpbm added that option in 11.01. The list contains one filename per line, ignores empty lines and does not support comments:

$ pamcat -leftright -listfile=image-list.txt > strip.pam

Do not mix -listfile with filenames on the same command line. Read the list back before running a large job if another program generated it, because each line is treated as a filename, never as a shell command.