Stack Image Channels with pamstack Without Losing Their Metadata

You will finish with a PAM image whose channels come from two or more matching Netpbm images, plus a check that confirms its dimensions, depth, maxval and tuple type. The examples use pamstack from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need readable PAM, PNM, PBM, PGM or PPM inputs, a shell, and enough disk space for the output. The commands write files in the working directory unless you choose another path. They do not require root. This guide does not overwrite an input.

1. Check the installed contract

Confirm that the command and package are the ones you intend to use. These are ordinary, read-only checks:

$ command -v pamstack
/usr/bin/pamstack
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pamstack -version 2>&1
pamstack: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

pamstack reads several images and emits one PAM image. The input planes are appended in the order you name them. If you give it one input, it can also change that image's tuple type. With no input names, it reads one image from standard input. At most one named input may be -, meaning standard input.

2. Check dimensions and choose channel order

Every input must have the same width and height. Use pamfile or another suitable Netpbm inspector before stacking:

$ pamfile image.ppm alpha.pgm
image.ppm: PAM, 1920 by 1080 by 3 maxval 255
    Tuple type: RGB
alpha.pgm: PAM, 1920 by 1080 by 1 maxval 255
    Tuple type: GRAYSCALE

The output depth is the sum of the input depths, so this pair becomes a four-channel image. Put the colour image first and the alpha plane second if you want the conventional RGB_ALPHA arrangement. pamstack does not inspect your intent: reversing the arguments reverses the channel order.

Those sample lines are representative, not a promise about your files. Run pamfile yourself and check the actual dimensions. A mismatch makes pamstack fail rather than crop or resize the inputs. Resize or regenerate a copy first if the dimensions do not match; do not expect stacking to repair them.

3. Stack equal-maxval inputs and name the result

Use a new destination and record the tuple type explicitly:

$ pamstack -tupletype=RGB_ALPHA image.ppm alpha.pgm > image-with-alpha.pam
$ pamfile image-with-alpha.pam
image-with-alpha.pam: PAM, 1920 by 1080 by 4 maxval 255
    Tuple type: RGB_ALPHA

The -tupletype value is written into the output header and may be up to 255 characters. Applications recognise particular names, so use the spelling expected by the next tool. If you omit the option, the tuple type is a null string. The samples above assume both inputs have maxval 255. When all inputs have the same maxval, that value is retained.

Do not redirect straight to an existing useful output unless replacement is intentional. Shell redirection truncates the destination before pamstack has finished. If you need an atomic replacement, write a new file, inspect it, then move it into place only after the check succeeds:

$ pamstack -tupletype=RGB_ALPHA image.ppm alpha.pgm > image-with-alpha.pam.new
$ pamfile image-with-alpha.pam.new
$ mv image-with-alpha.pam.new image-with-alpha.pam

The final mv changes state and replaces the old path. If you have not checked the new file, do not run it. To recover before that point, remove only the incomplete .new file. If you already replaced the old output, restore it from your backup or regenerate it from the original inputs; pamstack has no undo record.

4. Handle different maxvals deliberately

By default, all inputs must also have the same maxval. For example, a PBM plane commonly has maxval 1 while a PGM plane commonly has maxval 255. Without an explicit policy, pamstack fails with a message recommending one of two options:

$ pamstack image.pbm alpha.pgm > output.pam
pamstack: Inputs do not all have same maxval. Consider -firstmaxval or -lcmmaxval

Choose -firstmaxval when the first input's scale is the one your consumer requires. Other planes are scaled to it:

$ pamstack -firstmaxval image.pbm alpha.pgm > output-max1.pam
pamstack: Input maxvals vary; making output maxval 1 per -firstmaxval
$ pamfile output-max1.pam
output-max1.pam: PAM, 4 by 3 by 2 maxval 1

Choose -lcmmaxval when retaining a common multiple of the input scales is more useful. The least common multiple is capped at 65535, and sample values are scaled:

$ pamstack -lcmmaxval image.pbm alpha.pgm > output-lcm.pam
pamstack: Input maxvals vary; making output maxval 255 per -lcmmaxval
$ pamfile output-lcm.pam
output-lcm.pam: PAM, 4 by 3 by 2 maxval 255

Do not combine -firstmaxval and -lcmmaxval. They are alternative policies. Check the resulting maxval, because it affects how later programs interpret sample values.

5. Use streams and diagnose failures

pamstack supports multi-image streams. It stacks the first image from every stream, then the second image from every stream, continuing until one stream runs out. This is useful for synchronised sequences, but a short stream ends the operation; it is not padded. Test a small sample before processing a long sequence.

You can pipe one input, provided the other input is named:

$ cat alpha.pgm | pamstack -tupletype=RGB_ALPHA image.ppm - > image-with-alpha.pam
$ pamfile image-with-alpha.pam
image-with-alpha.pam: PAM, 1920 by 1080 by 4 maxval 255

Only one input may be standard input, so do not use two hyphens. If pamstack reports a read error, check the file type and permissions without changing anything:

$ test -r image.ppm && echo readable
readable
$ pamfile image.ppm alpha.pgm

If the dimensions or maxvals are wrong, fix a copy or select an explicit maxval policy. If the output has an unexpected depth or tuple type, check the argument order and the exact -tupletype value. No elevated privilege is needed for these checks or for normal image conversion.