Turn a PAM Image into an Oil-Style Effect with pamoil

You will finish with a second Netpbm image whose pixels have been replaced by the most common values in local square neighbourhoods. That produces the smearing effect described by pamoil as an oil transfer. The command writes the same Netpbm image type it reads, so you can keep the result in PAM format for a later conversion.

Allow about ten minutes. You need the netpbm package, a readable PAM image, and enough free space for a second copy of the image. The examples are ordinary, unprivileged commands. Do not use sudo unless your input directory is separately protected by its file permissions.

1. Check the installed command and version

Start by confirming which executable your shell will run. The package version matters because the local manual describes the installed tool, while the manual page itself is older than the current Debian build.

$ command -v pamoil
/usr/bin/pamoil
$ pamoil --version
pamoil: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

On this machine, pamoil comes from Netpbm package version 2:11.05.02-1.1build1. The version output includes build details, so the ellipsis above represents additional lines rather than output you should type. If the command is missing, install Netpbm through your normal package-management process before continuing.

Checkpoint: command -v pamoil should print a path, and pamoil --version should identify Netpbm. Neither check changes an image.

2. Apply the default effect without overwriting the source

Use a new destination name and redirect standard output to it. The input argument is optional, but giving it explicitly makes a script easier to review.

$ pamoil /path/to/input.pam > /path/to/input-oil.pam

The manual's default neighbourhood size is 3. In practical terms, pamoil examines that many pixels in each of the four directions around a pixel, then chooses the most common intensity for each channel. Colour channels are processed separately. At an edge, the neighbourhood is clipped instead of extending beyond the image.

A successful run normally prints the transformed image to the redirected file and leaves the terminal otherwise quiet. Verify the output as a PAM image:

$ pamfile /path/to/input-oil.pam
/path/to/input-oil.pam: PAM, ...

The exact pamfile wording depends on the image dimensions and maximum value. The useful result is that it identifies PAM, rather than reporting an empty or unrecognised file. Check the exit status immediately after the conversion if you are scripting it:

$ printf '%s\n' "$?"
0

3. Choose a different neighbourhood size

Pass -n followed by the size when the default effect is not suitable:

$ pamoil -n 5 /path/to/input.pam > /path/to/input-oil-5.pam
$ pamfile /path/to/input-oil-5.pam

The number controls how far the local search reaches in all four directions. A larger value can make the result look more broadly smeared and can remove more small detail. A smaller value preserves more local variation. The option is a processing setting, not an output width or height, and it does not resize the image.

Do not infer visual quality from the exit status alone. Keep the source image, inspect the new file in an image viewer or pass it to another Netpbm converter, and compare it with the original. If the result is too soft, rerun from the unchanged source with a smaller value. There is no undo operation inside pamoil; recovery is simply to discard the derived file and run the command again.

4. Use standard input in a pipeline

With no pamfile argument, pamoil reads the image from standard input. This lets you place another Netpbm command before it:

$ cat /path/to/input.pam | pamoil -n 3 > /path/to/input-oil-pipeline.pam
$ pamfile /path/to/input-oil-pipeline.pam

A direct filename is usually clearer for one file. Use a pipeline when the preceding command genuinely produces PAM data. Do not pipe text from an unrelated command and expect an image; pamoil will fail or produce no usable result.

5. Protect an existing output

Shell redirection with > truncates its destination before pamoil starts. That is a destructive operation if the destination already contains a useful image. Generate a temporary sibling file, verify it, then replace the destination only when you are ready:

$ pamoil -n 3 /path/to/input.pam > /path/to/input-oil.pam.new
$ pamfile /path/to/input-oil.pam.new
$ mv /path/to/input-oil.pam.new /path/to/input-oil.pam

If conversion fails, leave the existing destination alone and remove the incomplete .new file after checking that it is not needed. If the replacement is wrong, the original source remains available, but mv has replaced the old destination. If that old destination matters, copy it to a clearly named backup before the final command:

$ cp --preserve=all /path/to/input-oil.pam /path/to/input-oil.pam.backup

Removing that backup is irreversible, so make that a separate, deliberate cleanup step rather than part of a batch command.

6. Diagnose a failed conversion

First check the input without changing it:

$ ls -l /path/to/input.pam
$ test -r /path/to/input.pam && echo readable
$ pamfile /path/to/input.pam

A missing path, unreadable file, or non-Netpbm input must be fixed at the source. If the output file is zero bytes, remember that redirection created it before the program reported its error. Remove or replace that failed output, then rerun using a new destination. If pamfile identifies the output but the picture is not what you expected, try another -n value and inspect the result rather than editing the source.

For a short list of supported options, run pamoil --help. The installed command reports that its recognised program-specific option is -n; -quiet is a common libnetpbm option mentioned by the manual. There is no pamoil switch here that enables an image format, resizes a picture, or changes a file in place.