Replace pgmoil with pamoil for Netpbm Oil Effects

You will finish with a tested pamoil command, a small image conversion you can inspect, and a safe way to update scripts that still call pgmoil. On this machine, both names are supplied by Netpbm package version 2:11.05.02-1.1build1, but pgmoil is retained only for compatibility.

Allow about fifteen minutes. You need a shell, the Netpbm package, and a readable Netpbm image such as PGM, PPM or PAM. The examples write into the current directory or a named working directory. They do not need sudo, and they do not modify the input image.

1. Confirm what is installed

Check the two executable names and the package version before changing a script. This 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 pgmoil manual says that it was replaced by pamoil in Netpbm 9.16, released in July 2001. It also says that pamoil is backward compatible with pgmoil and adds support for colour images. The old command being present does not make it the right name for new scripts.

2. Use a new output path

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

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

The input path is optional. With no path, pamoil reads standard input, which is useful in a pipeline:

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

That pipeline is only an example of stream composition. The first and last tools must be installed, and the first tool must produce a Netpbm image. For a simple migration, keep the input path and output redirection visible so that a failure is easier to locate.

If the 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

The final mv happens only after pamoil has completed. If conversion fails, leave the existing output in place and inspect or remove the .new file after checking its contents. The backup is your recovery copy; deleting it is irreversible, so make that a separate, deliberate cleanup step.

3. Run a reproducible smoke test

When no real photograph is available, make a tiny greyscale PGM in a temporary directory. The test image is plain text, so this command is safe to copy:

$ 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

The temporary directory name will contain different characters on your machine. The useful checks are a successful command, a non-empty output file, and dimensions of 5 by 3. The output is binary PGM even though the input above is the text-based P2 variant.

4. Adjust the neighbourhood deliberately

pamoil chooses the most common value in a square neighbourhood for each pixel. The -n option controls how far that neighbourhood reaches in each direction. Its default is 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

A larger value can produce broader smearing and more visible loss of fine detail. It can also make the result less useful for a small image. Treat the value as part of your application behaviour, not as a cosmetic switch to change without reviewing output.

The same calculation is applied independently to each channel for colour or other multi-channel images. At an image edge, the neighbourhood is clipped rather than read beyond the image. That means edge pixels can legitimately differ from pixels in the middle even when their input values look similar.

5. Migrate a script from pgmoil

For an ordinary call, replace the command name and keep the arguments and output handling unchanged:

$ 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

This produces a review copy. Do not use a broad replacement across an entire source tree until you have checked that each match is a command name rather than documentation, a test fixture or an intentionally supported legacy interface. If the diff contains only the intended command-name changes, replace the script with your normal version-control workflow. Keep the old version available so you can undo the change:

$ 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 previous command. On this installation, pgmoil and pamoil produce identical output for the same tested PGM input, but an application should still validate the image it needs rather than relying on a name substitution alone.

6. Diagnose failures without guessing

A missing or unreadable input normally means the path or permissions are wrong. Check those 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

If file reports an unexpected format, inspect the producer before changing pamoil options. The program writes the same type of Netpbm image as its input, so a downstream tool must accept that format. A non-zero exit status is a failed conversion, not permission to promote a partial output over a known-good file.

Do not add sudo just because a conversion failed. Use elevated privileges only when the input or destination directory is intentionally restricted, and write to a user-owned staging path first where possible. Avoid running a script as root merely to make its output directory convenient.