Antialias a Two-Colour PNM Image with pnmalias

pnmalias smooths the jagged staircase edges in a black-and-white PNM image so the boundary looks like a curve instead of a set of stairs. You will finish with a checked output file and a clear idea of which pixels it actually changed. The examples use Netpbm 11.5.2 from package version 2:11.05.02-1.1build1, and take about fifteen minutes.

• You need: a shell, the netpbm package, and a readable PBM, PGM or PPM image.
• No sudo required: the command reads standard input when no file is named and writes to standard output.

1. Confirm the installed command

Check the binary and package version before trusting anything below it. 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 upstream documentation page is dated 15 March 2004, so the installed manual and this guide can drift apart over time. Note the local command and package version in your own notes when a script depends on this behaviour.

2. Inspect the input before touching it

Run file against the path to confirm it is really an image, and to see its dimensions:

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

• Replace the path. Swap /path/to/input.pbm for your real file.
• Keep the original. pnmalias never edits an input file in place unless you redirect output back onto it, which is unsafe because the shell truncates the destination first.
• Start with a PBM if you can. A PBM holds only black and white pixels, so the format change is obvious: 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 goes to standard error, so it stays visible while the image bytes land in output.pgm. Check both the exit 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 own file wording may differ, but the dimensions should match and the type should be a PGM greymap rather than a PBM bitmap. The output is normally a raw PGM with binary pixel data, so do not open it in a text editor.

4. Understand the default colours

By default pnmalias treats black as background and white as foreground, and smooths the boundary between them. That default is wrong for a source with different colours, or when the logical foreground is black on a light background and only one side of the edge should change.

Set the colours with -bgcolor and -fgcolor. Netpbm's colour parser accepts common names and numeric specifications:

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

• These describe pixels, not a recolour. They are not a general recolouring operation.
• On a PGM, only red matters. pnmalias still parses the options as colours and uses each colour's red component as the greyscale pixel value, so pick values that match the real pixel range rather than assuming a colour name turns the file into a colour image.

5. Limit which pixels get smoothed

Use -bonly to touch only background pixels, or -fonly for foreground pixels only. These flags matter when one side of an edge has to stay crisp, but they do not delete the other side:

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

Render both files in an image viewer and keep whichever edge treatment matches the purpose of the image. Use distinct output names if you repeat the test, so one result cannot hide another.

6. Control neighbouring pixels and filter weight

• Default reach. Without -balias or -falias, the filter only touches neighbouring background and foreground pixels.
• -balias includes all pixels surrounding background pixels.
• -falias includes all pixels surrounding foreground pixels; both widen the affected area, so test on a copy when sharp regions matter.

-weight sets the filter's central weight: a real number strictly between 0 and 1, default 1/3. Lower values blur more:

$ 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 wording of the diagnostic can vary by build, so trust the strict range and the non-zero status instead. Check that should-not-be-used.pgm is not a file you already needed before removing it; in a real workflow use a fresh temporary name instead.

7. Replace an existing image only after verification

Once the new file checks out, back it up and replace the destination as a separate, deliberate step:

$ 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

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

That restore overwrites the current output, so only run it once you have confirmed you still need the backup and not the replacement.