Replace Obsolete pnmarith Calls with pamarith

You will leave an old pnmarith script working with the supported Netpbm command, while checking the one compatibility difference that can change image results. On this machine, the netpbm package is version 2:11.05.02-1.1build1 and provides Netpbm 11.5.2. Allow about fifteen minutes if you already have two small Netpbm images to test.

You need a shell, the netpbm package and readable PBM, PGM, PPM or PAM inputs. The checks below are ordinary, unprivileged commands. Do not use sudo unless your input or output directory has deliberately been made inaccessible to your account.

1. Confirm what pnmarith is on this host

Start with the installed command, rather than assuming an old script still runs the old implementation:

$ command -v pnmarith
/usr/bin/pnmarith
$ ls -l /usr/bin/pnmarith
lrwxrwxrwx 1 root root 8 Mar 31  2024 /usr/bin/pnmarith -> pamarith
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

Here, pnmarith is already a symbolic link to pamarith. The installed manual page still describes the historical interface: starting with Netpbm 10.3, pnmarith is obsolete and pamarith is the replacement. Keep the old name only as a compatibility clue. New scripts should call pamarith explicitly.

Checkpoint: check the function syntax without changing a file:

$ pamarith --help
pamarith: Use 'man pamarith' for help.

The help message is brief, so the useful contract is in man pamarith. One operation is required, followed by two or more input files. For example, -add, -subtract, -difference, -minimum, -maximum, -mean, -equal and the bit operations are documented there. The command writes the calculated image to standard output.

2. Make a harmless two-image test

If you do not have test images, create two tiny PGM files in a temporary directory. The files are disposable, and this example does not touch your project or image archive:

test_dir=$(mktemp -d /tmp/pamarith-test.XXXXXX)
printf 'P2\n2 1\n10\n2 8\n' > "$test_dir/left.pgm"
printf 'P2\n2 1\n10\n3 4\n' > "$test_dir/right.pgm"
printf 'test files: %s\n' "$test_dir"

Each image is two pixels wide and one pixel high, with a maximum sample value of 10. The arithmetic result is not printed as text: it is an image stream. Redirect it to a new path, not to either input.

3. Replace the command name and verify the output

Run the supported name first. This adds the corresponding samples, so the expected values are 5 and 10:

$ pamarith -add "$test_dir/left.pgm" "$test_dir/right.pgm" > "$test_dir/sum.pgm"
$ file "$test_dir/sum.pgm"
/tmp/pamarith-test.XXXXXX/sum.pgm: Netpbm image data, size = 2 x 1, rawbits, greymap
$ pnmtoplainpnm "$test_dir/sum.pgm"
P2
2 1
10
5 10

The temporary directory suffix and file wording vary. The important checks are a successful exit status, a 2 by 1 PGM result and sample values 5 10. If pnmtoplainpnm is not installed, inspect the header with head or use another Netpbm reader. That optional inspection tool is not part of pamarith.

Now prove that an old invocation is currently equivalent on this installation:

$ pnmarith -add "$test_dir/left.pgm" "$test_dir/right.pgm" > "$test_dir/old-name.pgm"
$ cmp "$test_dir/sum.pgm" "$test_dir/old-name.pgm"
$ printf 'same output\n'
same output

cmp producing no diagnostic means the files are byte-for-byte identical. This is a migration check, not a reason to retain the obsolete spelling in new code.

4. Check the image-shape boundary before migrating a real job

The important difference is image depth. Historical pnmarith converted the input with the lesser depth to the higher depth before doing arithmetic. pamarith requires equal depths, unless one image has depth one. A grayscale PGM has depth one, while an RGB PPM has depth three, so that common pairing is accepted. Other mismatches can fail:

$ pamarith -add depth-two.pam colour.ppm > result.pam
pamarith: The images must have the same depth or depth 1.  But one has depth 2 and another 3

The exact diagnostic may differ slightly by release, but a non-zero status means the result is not available. Do not solve this by guessing at a conversion or by silently dropping channels. First inspect both files with a Netpbm-aware tool and decide what each tuple should mean.

5. Normalise a mismatched input deliberately

The pnmarith manual specifically points to pgmtoppm for the separate conversion step. Use it only when converting the grayscale input to an RGB image is the intended operation. This changes the intermediate file, so write a new file and retain the original until the result has been checked:

$ pgmtoppm '#808080' depth-two-source.pgm > normalised.ppm
$ pamarith -add normalised.ppm colour.ppm > result.ppm

That example is for a PGM source and produces an RGB PPM with the chosen background colour. It is not a universal repair for PAM images with arbitrary tuple types. For alpha, multi-channel scientific data or a service pipeline, choose a conversion that preserves the data model and test it with representative images.

Warning: shell redirection with > truncates an existing destination before pamarith starts. Use a new name or a temporary output, then replace the old file only after validation:

set -o noclobber
pamarith -add "$test_dir/left.pgm" "$test_dir/right.pgm" > "$test_dir/sum.new.pgm"
set +o noclobber
test -s "$test_dir/sum.new.pgm" && mv "$test_dir/sum.new.pgm" "$test_dir/sum.pgm"

If the conversion fails, leave the previous output alone and investigate the error. To undo the successful replacement, restore your own backup or regenerate the old output from its original inputs. The arithmetic command itself has no rollback operation.

6. Keep scripts explicit

Change only the command name in a straightforward script, then add an image-shape check where inputs can vary:

if ! pamarith -add "$left_image" "$right_image" > "$new_output"; then
    printf 'pamarith failed; keeping the existing output\n' >&2
    exit 1
fi
test -s "$new_output" || {
    printf 'pamarith produced an empty output\n' >&2
    exit 1
}

Remember that matching width and height are also required. Arithmetic is performed at corresponding pixel positions, and the output format is the more general of the inputs. For a multi-input operation such as -add, the installed documentation permits repeated binary addition across multiple images. Subtraction and several comparison operations remain two-image operations.