Map Image Sharpness with pamsharpmap

pamsharpmap turns a Netpbm photo into a heat map showing exactly where the detail sits, without touching the source file. You will generate that map, check its dimensions and format, and confirm the original is untouched. The examples use pamsharpmap from Netpbm package version 2:11.05.02-1.1build1 on this machine.

• Time: about fifteen minutes.
• You need: a readable PNM or PAM image, the pamsharpmap command, and a Netpbm viewer or inspection tool such as pamfile.
• Privileges: none. Do not use sudo unless the input or output directory is deliberately restricted.

1. Check the installed command

Confirm that the command resolves to the Netpbm program you expect and record the package version. These are read-only checks:

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

There are no pamsharpmap-specific switches. Its synopsis is pamsharpmap [imagefile], so a file name is optional. It also accepts the common options provided by the Netpbm library, but this guide does not need any of them.

2. Choose a new output path

pamsharpmap writes the result to standard output, and shell redirection with > truncates an existing destination before the program even starts. Use a new name while testing. This example assumes your source is called photo.ppm:

$ test -r photo.ppm && echo 'input is readable'
input is readable
$ pamfile photo.ppm
photo.ppm: PPM raw, 1920 by 1080  maxval 255

The exact pamfile wording varies with the input. The useful checks are that the file is readable and that it is a PNM image, or a PAM image whose tuple type is compatible with PNM. pamsharpmap assumes that format family; for anything else, convert it first with an appropriate Netpbm tool.

3. Generate the sharpness map

Run the command with the input file and capture standard output in a new PPM file:

$ pamsharpmap photo.ppm > photo-sharpness.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ pamfile photo-sharpness.ppm
photo-sharpness.ppm: PPM raw, 1920 by 1080  maxval 255

A zero exit status means the command completed, and the inspection confirms the output is a PPM with the expected dimensions. The output keeps the input's dimensions, depth and tuple type, but its maxval is always 255. That last detail matters when you compare it with an input that used a different maxval.

$ test -s photo.ppm && test -s photo-sharpness.ppm && echo 'both images are present'
both images are present

4. Read what the map means

Sharpness here is not a camera-lens score. At each pixel, pamsharpmap calculates the average intensity difference between that pixel and the eight surrounding pixels. A sudden local change produces a brighter component in the result; a flat area produces a darker one.

• Colour matters. The calculation runs separately for red, green and blue, so an edge that is strong in red and green but weak in blue shows up yellow. That is useful for seeing which channels carry local detail, not just where luminance changes.
• Edges are special-cased. The outside row and column do not behave like interior pixels: the program assumes a black border where neighbouring pixels are missing, which can make the outer edge look sharper than a similar flat area inside the image.

Use an image viewer or convert the PPM for visual inspection. If pnmtopng is installed, make a separate preview:

$ pnmtopng photo-sharpness.ppm > photo-sharpness.png
$ file photo-sharpness.png
photo-sharpness.png: PNG image data, 1920 x 1080, 8-bit/color RGB, non-interlaced

That PNG conversion is optional and belongs to pnmtopng, not pamsharpmap. If the map looks uniformly dark, that can be a real result: the input may contain broad, gradual changes rather than strong local edges.

5. Feed it from a pipeline

Because the image argument is optional, you can supply a PNM image on standard input. This is useful when another Netpbm command produces the image:

$ pamtopnm source.pam | pamsharpmap > source-sharpness.ppm
$ pamfile source-sharpness.ppm
source-sharpness.ppm: PPM raw, 1920 by 1080  maxval 255

Keep the stages separate while troubleshooting. First save and inspect the converted input if the pipeline fails, then run pamsharpmap on that saved file. A producer that emits a non-PNM stream can make the failure look like a sharpness calculation problem when it is not.

Common traps

If pamsharpmap cannot open the input, check the path and permissions:

$ ls -l photo.ppm
$ test -r photo.ppm && echo readable
readable

• Rejected or nonsense input. Inspect the header with pamfile or file. The manual only promises meaningful results for PNM or a PNM-equivalent PAM image; a JPEG, PNG or unrelated PAM tuple type needs conversion first.
• Wrong output size. Check the output with pamfile rather than trusting the file name. pamsharpmap does not resize an image; it preserves the input dimensions, so an unexpected size normally comes from the input or an earlier pipeline stage.