Measure PGM Shapes Across Thresholds with pgmminkowski

You will turn one grayscale PGM image into a tabular report of shape measurements at every intensity threshold. The report covers the white foreground's area, boundary information and Euler characteristic, and is suitable for plotting with gnuplot. Allow about fifteen minutes for a first run. You need a shell, a readable PGM file and the Netpbm package. The commands below only read the image and write results to standard output, so they do not need elevated privileges and there is no state to undo.

This guide describes Netpbm 11.05.02-1.1build1, the package version installed here. The manual page is dated 29 October 2002 and the program has no pgmminkowski-specific options, so verify output if your package is substantially different.

1. Check the installed command

First confirm which executable your shell will run:

$ command -v pgmminkowski
/usr/bin/pgmminkowski
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pgmminkowski --help
pgmminkowski: Use 'man pgmminkowski' for help.

The help response is deliberately brief. The synopsis is pgmminkowski pgmfile. There are no command-line switches specific to this program. Netpbm's shared options may still be accepted, but this workflow does not depend on them.

2. Confirm the input is a PGM

A PGM image has a width, height, maximum grey value and raster. The raw form starts with P5; the plain form starts with P2 and stores pixel values as decimal text. Pixel values run from zero, black, to the maximum value, white. Comments beginning with # are allowed in the format.

Inspect the header without altering the file:

$ sed -n '1,5p' input.pgm
P2
# example image
4 3
9
0 9 0 0

Do not treat the first few lines as proof that the entire raster is valid. A truncated or damaged image can fail later. If you have Netpbm's other inspection tools installed, use the one already in your normal image workflow; pgmminkowski itself reports a read error rather than repairing an input.

3. Run the measurement

Pass the PGM path as the only required argument:

$ pgmminkowski input.pgm
#threshold   tiles  x-edges y-edges vertices
#---------   -----  ------- ------- --------
0.000000        12       15      16       20  1       1          1
1.000000         2        4       3        6  0.166667 0.428571  1
#  check:       0        0       0        0

The installed program prints a comment header, then one row for each threshold it considers. The first value is the threshold. The following integer columns are the tile, horizontal-edge, vertical-edge and vertex counts shown by the program. The trailing values are the normalised measurements used by the tool's Minkowski analysis. Use the header and the documentation for the column identities, and do not silently relabel columns in a downstream script.

Conceptually, a threshold classifies pixels as black or white. The white pixels form the foreground. As the threshold changes, the foreground area can change, and the boundary and Euler-characteristic measurements describe how its shape changes. This is why a single grayscale image produces several rows instead of one summary number.

Redirect the report when you want to preserve it for plotting:

$ pgmminkowski input.pgm > measurements.dat
$ sed -n '1,4p' measurements.dat
#threshold   tiles  x-edges y-edges vertices
#---------   -----  ------- ------- --------
0.000000        12       15      16       20  1       1          1

This creates or replaces measurements.dat. That is the only state-changing example in this guide. Before running it, choose a new output path or make a backup if the destination already contains useful data. To recover from an accidental replacement, restore that file from your backup or rerun the command with the original input and a different destination; pgmminkowski cannot reconstruct an overwritten file.

4. Check success and diagnose failures

For a valid image, the command returns status zero. Capture the status immediately after the run:

$ pgmminkowski input.pgm > measurements.dat
$ printf 'exit status: %s\n' "$?"
exit status: 0

A missing file is different from a successful run with no interesting shapes:

$ pgmminkowski /path/to/missing.pgm
pgmminkowski: Unable to open file '/path/to/missing.pgm' for reading.  fopen() returns errno 2 (No such file or directory)
$ printf 'exit status: %s\n' "$?"
exit status: 1

Check the path, spelling and read permissions. An ordinary user can read an image that is accessible to that user. Do not reach for sudo merely because the command failed; elevated access can hide an ownership problem and is unnecessary for normal analysis. If the file is readable but malformed, inspect its PGM header and raster, then test a known-good sample to separate an input problem from an installation problem.

5. Use the data without losing the meaning

The output is designed to be a gnuplot datafile. Keep comment lines beginning with #; gnuplot treats them as comments, and they document the columns. If you parse the file in another program, skip comment lines and preserve the threshold as a numeric field. Avoid assuming that a threshold is a percentage or that the first row is the only useful one. It represents one point in the image's progression through intensity levels.

For a quick visual check, plot a measurement column against the threshold after inspecting the header and a few rows. Do not compare two images using only a raw row number: images with different maximum grey values can place their meaningful changes at different thresholds. Compare the threshold and the measured values together.

The result is a shape descriptor, not a replacement for the original image. The manual describes area, total perimeter length and Euler characteristic as the three Minkowski integrals, with horizontal and vertical edge counts also reported. The foreground is the collection of white pixels after thresholding, not the rectangular extent of the PGM canvas. A large black border therefore does not count as foreground area.