Antialias a Two-Colour PNM Image with pnmalias

You will finish with a smoothed PNM image, a checked output format, and a clear understanding of which pixels pnmalias changed. The examples use Netpbm 11.5.2 from package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, the netpbm package, and a readable PBM, PGM or PPM image. The command reads standard input when no input file is named, and writes the converted image to standard output. These examples do not require sudo.

1. Confirm the installed command

Check the binary and package version before relying on examples. This is read-only:

$ command -v pnmalias
/usr/bin/pnmalias
$ pnmalias --version
pnmalias: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmalias: Built from source dated 2024-03-31 09:09:47
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The installed manual and upstream page describe the same interface. The documentation page is dated 15 March 2004, so keep the local command and package version in your notes when a script depends on this behaviour.

2. Inspect the input before changing it

Use file to check that the path names an image and to see its dimensions. It does not decode the image for you, but it catches an accidentally selected text file or an unexpected format:

$ file /path/to/input.pbm
/path/to/input.pbm: Netpbm image data, size = 640 x 480, bitmap, ASCII text

Replace /path/to/input.pbm with your actual path. Keep the original. pnmalias does not edit an input file in place unless you deliberately redirect output back to that same path, which is unsafe because the shell truncates it first.

For a first run, a PBM is useful because it makes the format change visible. A PBM contains black and white pixels only. pnmalias promotes PBM input to PGM because antialiasing needs intermediate grey values.

3. Run the default filter into a new file

Pass the input path and redirect standard output to a new destination:

$ pnmalias /path/to/input.pbm > /path/to/output.pgm
pnmalias: promoting from PBM to PGM

The promotion message is written to standard error, so it remains visible while the image bytes go to output.pgm. The command's exit status should be zero. Check both the status and the result:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file /path/to/output.pgm
/path/to/output.pgm: Netpbm image data, size = 640 x 480, rawbits, greymap

Your file wording may differ. The useful facts are the same dimensions and a PGM greymap rather than a PBM bitmap. The output is normally a raw PGM, whose pixel data is binary. Do not inspect it in a text editor.

4. Understand the default colours

By default pnmalias treats black as the background and white as the foreground. It smooths pixels at the boundary between those values. That default is a poor fit if your source uses different colours, or if the image's logical foreground is black on a light background and you need to change only one side of the boundary.

Set the colours with -bgcolor and -fgcolor. Names accepted by Netpbm's colour parser include common names and numeric colour specifications. Verify the result visually or with the image tool used by your workflow:

$ pnmalias -bgcolor white -fgcolor black /path/to/input.ppm > /path/to/inverted-boundary.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0

Colour options describe pixels to recognise; they are not a general recolouring operation. With a PGM, pnmalias still parses the options as colours and uses each specified colour's red component as the greyscale pixel value. For a greyscale image, choose values that correspond to the actual pixel range rather than assuming that a colour name changes the file into a colour image.

5. Limit which pixels receive antialiasing

Use -bonly when the operation should apply only to background pixels, or -fonly when it should apply only to foreground pixels. These flags are useful when one side of an edge must remain crisp, but they do not mean "background only" and "foreground only" in the sense of deleting the other pixels.

$ pnmalias -bonly /path/to/input.pbm > /path/to/background-smoothed.pgm
$ pnmalias -fonly /path/to/input.pbm > /path/to/foreground-smoothed.pgm

Do not combine these examples blindly with a visual comparison. Render both files in an image viewer and keep the version whose edge treatment matches the purpose of the image. If you need to repeat the test, use distinct output names so that one result cannot hide another.

6. Control neighbouring pixels and filter weight

Without -balias or -falias, the filter is applied only among neighbouring background and foreground pixels. Add -balias to include all pixels surrounding background pixels, or -falias to include all pixels surrounding foreground pixels. These options broaden the area affected; test them on a copy when preserving sharp regions matters.

-weight changes the central weight of the filter. It must be a real number strictly greater than 0 and strictly less than 1. The default is 1/3. Lower values produce a blurrier result:

$ pnmalias -weight 0.5 /path/to/input.pbm > /path/to/weight-half.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ pnmalias -weight 1 /path/to/input.pbm > /tmp/should-not-be-used.pgm
pnmalias: ... weight ...
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic for an invalid weight can vary with the build, so the important checks are the strict range and the non-zero status. Do not use the invalid output path in a later step. Remove it only after checking that it is not an existing file you meant to keep; in a real workflow, use a fresh temporary name instead.

7. Replace an existing image only after verification

If the new file is correct, make a backup and replace the destination as a separate, deliberate action:

$ cp --preserve=all /path/to/output.pgm /path/to/output.pgm.bak
$ pnmalias /path/to/input.pbm > /path/to/output.pgm.new
$ file /path/to/output.pgm.new
/path/to/output.pgm.new: Netpbm image data, size = 640 x 480, rawbits, greymap
$ mv /path/to/output.pgm.new /path/to/output.pgm

If pnmalias fails, the old output remains in place because the command wrote to .new. Remove the incomplete .new file after inspecting the failure. Keep the backup until the replacement has passed your image checks. Restoring it is the undo operation:

$ mv /path/to/output.pgm.bak /path/to/output.pgm

That restore overwrites the current output, so use it only when you have identified the backup and no longer need the replacement.