Measure PBM Shape Geometry with pbmminkowski

You will finish with the three Minkowski measurements for a black-and-white PBM image: area, perimeter and Euler characteristic. The command also prints tile, edge and vertex counts that make the calculation easier to inspect. The examples use the Netpbm 11.5.2 build installed here as Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, a readable PBM file and the pbmminkowski program. No elevated privileges are needed. This guide reads the image only; it does not alter the input or any persistent system setting.

1. Check the installed command

Confirm the executable and package version before relying on output in a script:

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

The version query is useful because the program does not have a separate option reference beyond its manpage. This build prints its library and build information to standard error, then exits. The command's actual synopsis is simply pbmminkowski pbmfile.

2. Make a small, known PBM test image

Use a temporary plain PBM when you want a reproducible smoke test. In PBM, 1 is black and 0 is white. pbmminkowski measures the white foreground, so this example contains a two-pixel white shape on a black background:

$ test_file=$(mktemp --suffix=.pbm)
$ trap 'rm -f "$test_file"' EXIT
$ printf 'P1\n3 2\n0 1 0\n1 0 0\n' > "$test_file"

The mktemp command chooses a fresh file, while the shell redirection writes only that temporary file. The trap removes it when the shell exits. If you use a real input image instead, do not redirect into its path: that would truncate it before the program reads it.

Check the header and dimensions without changing the image:

$ head -n 2 "$test_file"
P1
3 2

P1 identifies plain PBM. Netpbm also uses raw PBM, identified by P4. The input must be a PBM image, not a PGM or PPM file renamed with a different suffix.

3. Run pbmminkowski and read the result

Pass exactly one input file. The program writes a labelled report to standard output:

$ pbmminkowski "$test_file"
   tiles:  4
 x-edges:  7
 y-edges:  7
vertices:  11
    area:  4
perimeter:  12
 eulerchi:  1

The spacing is for alignment, not syntax. The tile count is the number of white image cells in the lattice. The horizontal and vertical edge counts, and the vertex count, are intermediate topological counts. The final three fields are the useful measurements: area, total boundary length and Euler characteristic for the white foreground.

For a single connected region with no hole, Euler characteristic is normally 1. Multiple disconnected regions increase it; holes reduce it. Treat that as a shape property, not as a pixel count. Perimeter is the total boundary of all white regions, so separate regions contribute their boundaries independently.

Do not assume that a visually black object is the foreground. PBM stores black as 1 and white as 0, and this tool's foreground is white. If your source image uses black marks on a white page, invert it before measuring if the black marks are the shapes you intend to analyse. Keep the original file and write the inverted image to a new path.

4. Verify a result with a second shape

A blank image is a useful boundary check. It contains no white tiles, so every reported measurement is zero:

$ blank_file=$(mktemp --suffix=.pbm)
$ printf 'P1\n3 3\n1 1 1\n1 1 1\n1 1 1\n' > "$blank_file"
$ pbmminkowski "$blank_file"
   tiles:  0
 x-edges:  0
 y-edges:  0
vertices:  0
    area:  0
perimeter:  0
 eulerchi:  0
$ rm -f "$blank_file"

The final removal is safe for this newly created temporary file, but it is irreversible. If you replaced blank_file with a valuable path, stop: the printf redirection would already have destroyed its contents. Use mktemp for experiments and preserve source images elsewhere.

For a machine-checkable smoke test, capture standard output and test the exit status:

$ report=$(pbmminkowski "$test_file")
$ status=$?
$ test "$status" -eq 0 && printf '%s\n' "$report"
   tiles:  4
 x-edges:  7
 y-edges:  7
vertices:  11
    area:  4
perimeter:  12
 eulerchi:  1

A zero status means the program accepted the file and completed the calculation. It does not prove that the intended pixels were white, that the image is the right one, or that the measurement is suitable for your scientific model. Check the PBM header and inspect the image separately when those distinctions matter.

5. Diagnose the common failures

A missing file is reported on standard error and returns a non-zero status:

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

Check the path and read permission rather than using sudo immediately:

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

If the first bytes are not a PBM magic number, the program reports an error reading the Netpbm magic number. Use head -n 2 for a plain PBM or od -An -tx1 -N2 for a raw PBM. A file extension does not determine its format.

The installed manpage lists no pbmminkowski-specific options. It does recognise common libnetpbm options, but do not add an option from a different Netpbm program and assume it applies here. Keep automated calls to the one documented input operand unless you have verified the common option against your installed version.