Replace pgmoil with pamoil for Netpbm Oil Effects

pgmoil still runs on this machine, but its own manual page says it was replaced by pamoil back in Netpbm 9.16, in July 2001. Both names come from Netpbm package 2:11.05.02-1.1build1, and by the end of this guide, about fifteen minutes, you will have a tested pamoil command and a safe way to update any script still calling the old name.

You need a shell, the Netpbm package and a readable Netpbm image, PGM, PPM or PAM. Everything writes into the current directory or a named working directory: nothing here needs sudo, and nothing modifies the input image.

1. Confirm what is installed

Check both executable names and the package version before touching a script. This step is read-only:

$ command -v pgmoil
/usr/bin/pgmoil
$ command -v pamoil
/usr/bin/pamoil
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The installed manual also notes that pamoil is backward compatible with pgmoil and additionally supports colour images. The old command still being present does not make it the right one to use in new scripts.

2. Use a new output path

Both commands read an input image and write the result to standard output. Shell redirection with > truncates its target before the program even starts, so never redirect straight over the source. Pick a separate name:

$ pamoil /path/to/input.pgm > /path/to/output-oil.pgm

The input path is optional: leave it out and pamoil reads standard input, which is handy in a pipeline:

$ pnmtopng /path/to/input.ppm | pamoil | pnmtopng > /path/to/output-oil.png

That pipeline is only an example of stream composition; both surrounding tools need to be installed, and the first has to actually produce Netpbm data. For a simple migration, keep the input path and output redirect visible so a failure is easy to trace.

Destination already exists and matters? Preserve it before replacing it:

$ cp --preserve=all /path/to/output-oil.pgm /path/to/output-oil.pgm.bak
$ pamoil /path/to/input.pgm > /path/to/output-oil.pgm.new
$ mv /path/to/output-oil.pgm.new /path/to/output-oil.pgm

3. Run a reproducible smoke test

No real photograph handy? Build a tiny greyscale PGM in a temporary directory. The test image is plain text, so this is safe to paste:

$ testdir=$(mktemp -d /tmp/pamoil-test.XXXXXX)
$ printf 'P2\n5 3\n255\n0 0 0 255 255\n0 0 128 255 255\n0 64 128 192 255\n' > "$testdir/input.pgm"
$ pamoil "$testdir/input.pgm" > "$testdir/output.pgm"
$ file "$testdir/output.pgm"
/tmp/pamoil-test.XXXXXX/output.pgm: Netpbm image data, size = 5 x 3, rawbits, greymap

Your own temporary directory name will look different. What actually matters: a successful command, a non-empty output file, and dimensions of 5 by 3. Notice the output is binary PGM even though the input above is plain-text P2.

4. Adjust the neighbourhood deliberately

pamoil picks the most common value in a square neighbourhood around each pixel. The -n option sets how far that neighbourhood reaches in each direction, and it defaults to 3:

$ pamoil -n 3 /path/to/input.ppm > /path/to/oil-default.ppm
$ pamoil -n 6 /path/to/input.ppm > /path/to/oil-broader.ppm

Push that value higher and you get broader smearing and more lost fine detail, sometimes making the result less useful on a small image. Treat it as part of your application's actual behaviour, not a cosmetic knob to flip without checking the output.

Colour and other multi-channel images get the same calculation applied independently per channel. At an image edge, the neighbourhood is clipped rather than read beyond the frame, so edge pixels can legitimately look different from otherwise similar pixels in the middle.

5. Migrate a script from pgmoil

For an ordinary call, swap the command name and leave the arguments and output handling exactly as they are:

$ sed 's/\bpgmoil\b/pamoil/g' ./make-thumbnails.sh > ./make-thumbnails.sh.new
$ sh -n ./make-thumbnails.sh.new
$ diff -u ./make-thumbnails.sh ./make-thumbnails.sh.new

That gives you a review copy. Never run a broad find-and-replace across a whole source tree until you have confirmed each match is actually a command invocation, not documentation, a test fixture or an intentional legacy reference. Diff clean? Replace the script through your normal version-control workflow, and keep the old version around so you can undo:

$ cp --preserve=all ./make-thumbnails.sh ./make-thumbnails.sh.pgmoil-backup
$ mv ./make-thumbnails.sh.new ./make-thumbnails.sh

Run one representative input through the migrated script and compare its output with the old command. On this installation, pgmoil and pamoil produce identical output for the same tested PGM input, but any application should still validate the image it needs rather than trusting a name swap alone.

6. Diagnose failures without guessing

A missing or unreadable input usually means a wrong path or permissions. Check both without changing anything:

$ ls -l /path/to/input.pgm
$ test -r /path/to/input.pgm && echo readable
$ test -s /path/to/output-oil.pgm && echo output-is-non-empty

file reports an unexpected format? Look at whatever produced the input before touching pamoil's options, since the program writes the same image family it was given. A non-zero exit status means a failed conversion, never permission to promote a partial output over a known-good file.

Do not add sudo just because a conversion failed. Reach for elevated privileges only when the input or destination directory is intentionally restricted, and write to a user-owned staging path first wherever that is possible.