Join Netpbm Images with pamcat

pamcat glues two or more PBM, PGM, PPM or PAM images into one, stacking them or sitting them side by side. This covers getting the padding and alignment right rather than trusting a green exit status; allow about ten minutes for a small batch once your input files are ready.

1. Check the installed command

You need the netpbm package and readable input images. No elevated privileges: pamcat reads its inputs and writes to standard output. This machine has Netpbm 11.05.02, and the installed command reports that version through the usual Netpbm version option.

$ command -v pamcat
/usr/bin/pamcat
$ pamcat -version
pamcat: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The package version and the library's own displayed version use different punctuation here, but both name the same installed Netpbm release. pamcat was introduced in Netpbm 11.00. Older installations may only provide pnmcat instead, but do not assume it has pamcat's PAM and transparency behaviour.

2. Stack images top to bottom

Give the inputs after the options and redirect standard output to a new file. This puts the second image below the first and fills any extra width with white:

$ pamcat -topbottom -white -jcenter \
    /path/to/top.ppm /path/to/bottom.ppm > stacked.ppm

With top-to-bottom concatenation, the output width is the widest input, and a narrower image gets padded to match it. -jleft places it against the left edge, -jright against the right, and -jcenter centres it. Centre is the default, but writing it explicitly makes a script easier to review later.

Check the dimensions and format before you use the result anywhere else:

$ pamfile stacked.ppm
stacked.ppm: PPM raw, 120 by 180  maxval 255

The exact wording can vary with the installed pamfile, but the reported size should be the widest input and the sum of the input heights. If the command fails, the shell may already have created an empty or partial destination. Use a new filename and inspect it before you replace anything useful.

3. Join images left to right

Use the horizontal direction when the images should sit beside one another:

$ pamcat -leftright -black -jbottom \
    /path/to/left.ppm /path/to/right.ppm > row.ppm
$ pamfile row.ppm
row.ppm: PPM raw, 320 by 90  maxval 255

For a left-to-right join, pamcat makes the output as tall as the tallest input, and the shorter image is padded to match. Use -jtop, -jbottom or -jcenter to choose its vertical position. This example makes all padding black and sits the shorter images at the bottom, as if lined up on a baseline.

-white and -black cannot be used together. Supply neither and pamcat picks a likely background colour, potentially a different one for each input. Fine for something interactive, but choose one explicitly if you want reproducible output.

4. Process a longer list of files

For a batch, put one input path per line and pass the list with -listfile:

$ sed -n '1,3p' /path/to/images.txt
/path/to/part-01.ppm
/path/to/part-02.ppm
/path/to/part-03.ppm
$ pamcat -tb -listfile=/path/to/images.txt > combined.ppm
$ pamfile combined.ppm

Empty lines are ignored. Lines are file names, not comments, so a line starting with # is not a comment mechanism, it is a filename. Do not also pass input paths as ordinary arguments when you use -listfile. The option was added in Netpbm 11.01, so the installed 11.05.02 command has it.

You can use -listfile=- to read the list from standard input, but that consumes standard input for the file names, and at most one input image may otherwise be named - for standard input. pamcat also depends on the system's limit for concurrently open files; the manual describes 16 as typical. Split a very large batch into smaller joins if you hit that limit.

5. Preserve formats and transparency

pamcat writes the highest input format in the order PBM, PGM, PPM, PAM. It combines different widths, heights, depths and compatible Netpbm image kinds, so you do not need to resize every input first. For PAM output, differing visual tuple types get promoted to a type that can represent them all. If transparency is present, padding comes out opaque rather than transparent, so inspect the output if that distinction matters to you.

The program writes a new image to standard output; it never edits the input files. The risky part is shell redirection: > existing.ppm truncates that file before pamcat has even finished. Use a new destination, or back up first if you mean to replace something:

$ cp --preserve=all combined.ppm combined.ppm.bak
$ pamcat -tb /path/to/part-01.ppm /path/to/part-02.ppm > combined.ppm.new
$ pamfile combined.ppm.new
$ mv -- combined.ppm.new combined.ppm

If the new command fails, leave the original in place and remove only the incomplete combined.ppm.new once you have checked the error. The backup is a recovery copy; do not delete it until you have opened or otherwise verified the replacement.

Common failure checks

• Missing magic number. Usually means an input is empty, truncated or not a Netpbm image. Run pamfile /path/to/input.ppm on each source.
• Wrong-looking result, clean exit. A successful exit status proves nothing about the visual result. Check dimensions with pamfile and view the output in a trusted image viewer or a later converter.
• Wrong shape. Check the direction, input order and justification. pamcat does not build a general grid; use pamundice for that.
• Need to reverse it. Use pamdice for equal-sized pieces or pamcut for a selected rectangle, and keep the original until you have checked the split result.