Convert PGM Images to PBM with pgmtopbm

pgmtopbm turns a greyscale PGM image into a one-bit PBM image, either with a hard threshold or with dithering that keeps some sense of tone. Allow about ten minutes for a repeatable command and a way to choose between the two.

The examples were checked with Netpbm 11.5.2 from package version 2:11.05.02-1.1build1.

• You need: a shell, the netpbm package, and a PGM file you can read.
• It will not touch: the input. The conversion writes to standard output, so you choose the output file explicitly, and no elevated privileges are needed unless the input or output directory is protected.

1. Check the installed command

Confirm that the executable and package are the ones you expect. This is an ordinary read-only check:

$ command -v pgmtopbm
/usr/bin/pgmtopbm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pgmtopbm --version
pgmtopbm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The installed version matters here: the local manual describes pgmtopbm as mostly obsolete since Netpbm 10.23, and recommends pamditherbw for newer dithering work. Keep that boundary in mind before building a new long-lived pipeline around this command.

2. Inspect the PGM without changing it

A portable, plain-text PGM starts with P2, followed by width, height, maximum sample value, and greyscale samples. Binary PGM files use P5. You do not need to rewrite either form before passing it to pgmtopbm, but identifying the format helps when a file is not what its name suggests:

$ head -4 input.pgm
P2
640 480
255
0 12 24 36 ...

Use a trusted viewer or a format-aware Netpbm tool for a complete inspection. Do not treat a file extension as proof that the contents are greyscale; a colour PPM or arbitrary binary data can produce unusable results.

3. Use thresholding for a predictable cut-off

Thresholding maps each input sample to black or white using the command's simple threshold method. Run it with the PGM as the optional input argument and redirect standard output to a new file:

$ pgmtopbm -threshold input.pgm > output-threshold.pbm
$ head -3 output-threshold.pbm
P4
640 480

P4 identifies a binary PBM. The pixel data is packed after the header, so a command such as head will show non-printing bytes after the first lines. The original PGM is unchanged, but if the output file already exists, the shell truncates it before pgmtopbm runs.

$ cp -- output-threshold.pbm output-threshold.pbm.bak
$ pgmtopbm -threshold input.pgm > output-threshold.pbm
$ test -s output-threshold.pbm && echo 'PBM written'
PBM written

4. Choose dithering when a hard cut loses detail

Thresholding gives a sharp binary decision. Dithering represents intermediate shades as patterns of black and white pixels, which can preserve the look of detail at a distance. Floyd-Steinberg is available as -floyd or -fs:

$ pgmtopbm -floyd input.pgm > output-floyd.pbm
$ head -3 output-floyd.pbm
P4
640 480

• Other methods this manual lists: -hilbert, -dither8, -cluster3, -cluster4, and -cluster8.
• Start with thresholding when you need a simple, stable cut.
• Start with Floyd-Steinberg when visual tone matters, then inspect the actual image rather than judging the binary bytes in a terminal.

5. Make dithered tests reproducible

The command accepts -randomseed integer. Set it when you are comparing runs or recording a reproducible conversion:

$ pgmtopbm -floyd -randomseed 7 input.pgm > output-seeded.pbm
$ pgmtopbm -floyd -randomseed 7 input.pgm > output-seeded-again.pbm
$ cmp -- output-seeded.pbm output-seeded-again.pbm
$ echo $?
0

An exit status of zero from cmp means the two files are byte-for-byte identical. The seed is useful for a test fixture or a documented batch job, but it does not improve the visual quality by itself.

6. Know when to use another Netpbm tool

pgmtopbm applies the older treatment of PGM samples, so it is not the preferred general-purpose ditherer any more. The manual points instead to pamditherbw, which performs gamma adjustment and produces PAM output, followed by pamtopnm if an actual PBM file is required. That route suits a new workflow that can accept PAM in the middle of the pipeline.

If the PGM already has a maximum value of 1 and you only need format conversion, the manual recommends pamtopnm instead. Do not add dithering to a file that already contains only black and white samples.

When a command fails, preserve its diagnostic and check the input path, permissions, and file format first:

$ pgmtopbm -threshold missing.pgm > output.pbm
pgmtopbm: Unable to open file missing.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 1

Do not treat an empty or partial output as a valid conversion. Write to a temporary name in the same directory, verify it, then rename it if you need an atomic replacement.