Measure Image Regions Precisely with pamgetcolor

pamgetcolor pulls a repeatable colour reading from a Netpbm image: one pixel, a labelled set of coordinates, or a circular patch. It only reads the image and prints Netpbm colour specifications, nothing gets written back. Allow about ten minutes. You need a shell, the netpbm package, and a PAM, PPM or other format the installed Netpbm readers accept.

This guide uses Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1. The command reports itself as built from source dated 2024-03-31. Other releases can differ, so check the local manual when scripting on another host.

1. Confirm the installed command

Start by checking which executable your shell will actually run:

$ command -v pamgetcolor
/usr/bin/pamgetcolor
$ pamgetcolor -version 2>&1 | head -4
pamgetcolor: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamgetcolor: Built from source dated 2024-03-31 09:09:47
pamgetcolor: Built by Debian
pamgetcolor: BSD defined

That version output is diagnostic text, not a measurement. No elevated privileges are needed when the image is readable and the output goes to your terminal, do not reach for sudo as a first response to a bad coordinate or a broken image.

2. Read one pixel

A region is written as column,row. Both coordinates are zero-based: column 0 is the leftmost pixel, row 0 is the top row. The default radius is zero, so the measurement covers exactly one pixel.

$ pamgetcolor 10,14 -infile /path/to/image.ppm
10,14: rgb-255:128/64/32

The exact numbers depend on the image. With the default int format, the components are decimal integers normalised to 255. The output starts with the coordinate, then a Netpbm colour specification. Add a label after a colon and it replaces the coordinate in the display:

$ pamgetcolor 10,14:sample -infile /path/to/image.ppm
 sample: rgb-255:128/64/32

3. Measure several locations in one run

Pass multiple region arguments after the options. Every region shares the same input image and the same radius:

$ pamgetcolor \
    10,10:topleft \
    100,100:middle \
    200,200:bottomright \
    -infile /path/to/image.ppm
  topleft: rgb-255:42/18/9
    middle: rgb-255:130/131/132
bottomright: rgb-255:240/241/242

You get one line per region. The sample values above are just illustrative formatting, not a claim about your image, run the command against a known test image if you need a stable check in a script.

For a small generated test image, standard input avoids creating or overwriting a file:

$ printf 'P3\n1 1\n255\n1 2 3\n' | pamgetcolor 0,0
0,0: rgb-255:1/2/3

Prefer to make the input explicit? Use -infile - for standard input. The ordinary shell pipeline is unprivileged and leaves no image file behind.

4. Average a circular region

Set a positive radius to inspect a circular area around each centre:

$ pamgetcolor -radius 4 100,100:patch -infile /path/to/image.ppm
patch: rgb-255:96/112/138

• The radius is measured in pixels and applies to every region in that invocation. Zero is the default, single-pixel measurement.
• The centre must be inside the image, but part of the circle can extend beyond an edge. Only the pixels actually inside the image contribute to the calculation.
• Do not confuse the centre with a width and height. 100,100 identifies one centre; -radius 4 asks for the circular neighbourhood around it. Need differently sized regions? Run separate commands.

$ printf 'P3\n1 1\n255\n1 2 3\n' | pamgetcolor 1,0
pamgetcolor: Region at 1,0 is outside the image boundaries.

5. Choose a machine-friendly colour format

The default is int with a maximum value of 255. Reach for -format when another program needs a different precision or representation:

$ printf 'P3\n1 1\n255\n128 64 32\n' | pamgetcolor -format int:65535 0,0
0,0: rgb-65535:32896/16448/8224
$ printf 'P3\n1 1\n255\n128 64 32\n' | pamgetcolor -format norm:3 0,0
0,0: rgbi:0.502/0.251/0.125
$ printf 'P3\n1 1\n255\n128 64 32\n' | pamgetcolor -format x11:2 0,0
0,0: rgb:80:40:20

• The format has the shape format-id:parameter.
• int uses the parameter as the maximum sample value.
• norm emits floating-point values normalised to one, with the parameter controlling fractional precision.
• x11 emits hexadecimal components, with the parameter choosing the number of digits. The parameter is required even when the default format would already suit you.

Keep the default if your next tool expects ordinary RGB integers. If it wants normalised floating-point input or fixed-width hex, pick that format explicitly and test the parser against a known one-pixel image.

6. Use standard input and linear intensity deliberately

Without -infile, pamgetcolor reads the image from standard input, handy when another Netpbm command produces the image, or when a small test image comes down a shell pipeline:

$ printf 'P3\n1 1\n255\n1 2 3\n' | pamgetcolor 0,0:stdin
 stdin: rgb-255:1/2/3

Use the same pattern with a producer you have already verified on your machine. Compare the complete output when building a check around it, do not parse a decorative label as if it were a coordinate.

7. Handle failures without damaging the source

pamgetcolor never edits the input image, so there is no rollback to worry about there. The real shell hazard sits elsewhere: redirecting output with > truncates an existing destination before the command even runs. Measurements normally print to standard output, so inspect them first or pick a new destination:

$ pamgetcolor 10,14 -infile /path/to/image.ppm > /tmp/measurement.txt
$ test -s /tmp/measurement.txt && cat /tmp/measurement.txt
10,14: rgb-255:128/64/32

When a run fails, check the image path and readability first, then check the coordinate against the image dimensions. A valid centre does not prove the image is the one you actually meant to read. For reproducible automation, capture the exit status and treat any non-zero result as a failed measurement rather than parsing partial output.

Done means

• You confirmed the command and Netpbm version with command -v and -version.
• Coordinates were zero-based column,row values inside the image.
• Radius zero was used for a pixel, or one shared positive radius for circular regions.
• Labels identify measurements without changing their coordinates.
• You chose the output format explicitly when a downstream parser requires it.
• The source image was read only, and any redirected report was checked before replacement.