Join Netpbm Images with pamcat Without Losing Alignment

You will combine two or more PBM, PGM, PPM or PAM images into one Netpbm image, either left to right or top to bottom. You will also control the padding colour and alignment when the input sizes differ, then inspect the output rather than trusting a successful exit status. Allow about ten minutes for a small batch once the input files are ready.

1. Check the installed command

You need the netpbm package and readable input images. No elevated privileges are normally needed: pamcat reads the inputs and writes its output to standard output. This machine has Netpbm 11.05.02, and the installed command reports that version through the common 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 displayed version use different punctuation here, but both identify the same installed Netpbm release. pamcat was introduced in Netpbm 11.00. Older installations may provide pnmcat instead, but do not assume it has pamcat's PAM and transparency behaviour.

Checkpoint: direction chosen

Decide whether the images should form a column or a row. pamcat requires exactly one direction option. Use -topbottom, or its short form -tb, for a column. Use -leftright, or -lr, for a row.

2. Stack images from top to bottom

Give the inputs after the options and redirect standard output to a new file. This example 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. A narrower image is padded to that width. -jleft places it against the left edge, -jright places it against the right edge, and -jcenter centres it. Centre alignment is the default, but writing it explicitly makes a script easier to review.

Check the dimensions and format before using the result elsewhere:

$ 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 replacing anything useful.

3. Join images from 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. The shorter image is padded to that height. Use -jtop, -jbottom or -jcenter to choose its vertical position. The example makes all padding black and aligns shorter images at the bottom, as if they were sitting on a baseline.

-white and -black cannot be used together. If neither is supplied, pamcat chooses a likely background colour, potentially a different colour for each input. That default can be useful for an interactive command, but choose one explicitly for reproducible output.

Checkpoint: padding is intentional

Before continuing, compare the output dimensions with the layout you wanted. A direction and a justification option are not interchangeable: -jleft and -jright apply to top-to-bottom joins, while -jtop and -jbottom apply to left-to-right joins. The command rejects a justification option used with the wrong direction.

4. Process a longer list of files

For a batch, put one input path on each newline-delimited 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 beginning with # is not a comment mechanism. Do not add input paths as ordinary arguments when using -listfile. The option was added in Netpbm 11.01, so the installed 11.05.02 command supports it.

You can use -listfile=- to read the list from standard input, but that consumes standard input for the file names. At most one input image may otherwise be named - as 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 it exceeds that limit.

5. Preserve formats and transparency

pamcat writes the highest input format in the order PBM, PGM, PPM, PAM. It can combine 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 are promoted to a type that can represent them. If transparency is present, padding is opaque rather than transparent. Inspect the output and check the visual result if that distinction matters.

The program writes a new image to standard output; it does not edit the input files. The risky part is shell redirection. > existing.ppm truncates the existing file before pamcat has finished. Use a new destination, or make a backup before an intentional replacement:

$ 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 after checking the error. The backup is a recovery copy; do not delete it until the replacement has been opened or otherwise verified.

Common failure checks

• An error about a missing magic number usually means an input is empty, truncated or not a Netpbm image. Run pamfile /path/to/input.ppm on each source.
• A wrong-looking result can still have a successful exit status. Check dimensions with pamfile and view the output with a trusted image viewer or a later converter.
• If the result is the wrong shape, check the direction, input order and justification. pamcat does not create a general grid; use pamundice for a regular grid.
• If you need to reverse the operation, use pamdice for equal-sized pieces or pamcut for a selected rectangle. Keep the original until the split result is checked.