Join Netpbm Images Safely with pnmcat and pamcat

You will finish with one Netpbm image made by joining two or more input images, with deliberate alignment and padding. On this machine, the installed pnmcat is 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.

No elevated privileges are normally needed. This workflow reads the inputs and writes a new output file. It does not edit the source images. Take care with shell redirection: > truncates an existing destination before the command starts.

1. Confirm which command you have

The old pnmcat(1) manual says that 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. The useful checks are the package name, the command path and the link target. Use pamcat in new documentation when you can; keep pnmcat when maintaining an older script or following a workflow that names it.

2. Choose the direction explicitly

Every useful invocation needs one direction. -leftright, also written -lr, places the inputs side by side. -topbottom, also written -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 is written to standard output, so the examples use 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. This 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. This matters because a failed conversion can still leave a truncated file when the destination was opened by the shell.

$ 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. To recover an accidental replacement, restore your own backup, for example with cp --preserve=all joined.ppm.bak joined.ppm. Do not remove a backup until you have checked the new image.

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. Use -jtop, -jbottom or -jcenter to choose the alignment. For a top-to-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. Use the full option names in scripts so the intended layout is obvious.

A horizontal join with inputs of heights 1 and 2, for example, 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 relying on 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 in this output are an example from two small test images, not a promise about your files. Your file wording may differ. Confirm that the width and height are what the join requires, and 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. Therefore, combining a PPM with a PAM can produce PAM output. This is expected; do not infer the format only from the filename extension.

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. 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 it was generated by another program, because each line is treated as a filename, not as a shell command.