Inspect Netpbm Images Reliably with pamfile

You will finish with a quick way to identify a PAM or PNM image, print dimensions for a script, count images in a file, and avoid the pipe-reading trap. The examples use pamfile from Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell and a readable PBM, PGM, PPM or PAM file. The commands only inspect image data. They do not need sudo, do not modify the input and do not change system configuration.

1. Confirm the installed command

Check which binary your shell will run and record the package version. This matters when a script depends on output introduced by a newer Netpbm release:

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

The installed manual is the contract for this machine. It permits minimum unique option abbreviations and double hyphens, but full option names are clearer in scripts. If pamfile is missing, install Netpbm through your normal package-management process rather than copying a binary from an unrelated host.

2. Read the normal human-oriented description

Run pamfile with the input path as the final argument. This example uses a sample PPM shipped by the installed package:

$ pamfile /usr/share/netpbm/pcxstd.ppm
/usr/share/netpbm/pcxstd.ppm:    PPM plain, 16 by 1  maxval 255

The wording is intended for people rather than parsers. It identifies the file, format, subformat, width, height and maximum sample value. PAM and PNM are families of formats, so a result such as PPM is more useful than a generic claim that the file is merely an image.

pamfile normally reads only the first image header. That is fast, but it means it does not prove that every later image in a multi-image stream is readable.

3. Get dimensions for a script

Use -size when you need exactly two whitespace-separated values, width followed by height:

$ pamfile -size /usr/share/netpbm/pcxstd.ppm
16 1

This output deliberately omits the file name. That is convenient for one input, but unsafe when several files or several images are involved because you cannot map each pair back to its source. Check the exit status as well as the values in a script:

$ dimensions=$(pamfile -size /usr/share/netpbm/pcxstd.ppm) && printf 'dimensions: %s\n' "$dimensions"
dimensions: 16 1

Keep the command substitution separate from any later numeric validation. A successful pamfile command says that the inspection completed; it does not tell your script whether a 16 by 1 image is suitable for the next operation.

4. Use machine output when filenames matter

-machine emits one line per image and keeps the filename with the metadata. The fields are format, subformat, width, height, depth, maxval and tuple type:

$ pamfile -machine /usr/share/netpbm/pcxstd.ppm
/usr/share/netpbm/pcxstd.ppm: PPM PLAIN 16 1 3 255 RGB

For multiple inputs, each line still starts with its source:

$ pamfile -machine /usr/share/netpbm/pcxstd.ppm /usr/share/netpbm/pcxstd.ppm
/usr/share/netpbm/pcxstd.ppm: PPM PLAIN 16 1 3 255 RGB
/usr/share/netpbm/pcxstd.ppm: PPM PLAIN 16 1 3 255 RGB

Do not parse the human-oriented output by guessing where a phrase ends. If a program needs stable fields, use -machine and document the Netpbm version you tested against. Quote filenames when constructing commands from external input, and prefer passing them as separate arguments instead of building a shell string.

5. Count all images without printing their metadata

Use -count when the question is only how many images are present:

$ pamfile -count /usr/share/netpbm/pcxstd.ppm
/usr/share/netpbm/pcxstd.ppm:    1 images

-count reads all images. That is different from the default header-only inspection and can take longer for a large stream. The options -count, -machine and -size are alternatives: specify at most one of them. If you combine them, pamfile rejects the combination rather than choosing a priority for you.

6. Handle pipes and comments deliberately

Without an option, pamfile may stop after the first header. On a pipe, the process producing the input may expect its whole stream to be consumed. Add -allimages when the source is a pipe, even if you believe it contains one image:

$ cat /usr/share/netpbm/pcxstd.ppm | pamfile -allimages -
-:    Image 0:    PPM plain, 16 by 1  maxval 255

The final - names standard input. -allimages also reports every image in a regular multi-image file. It has no effect with -count, because counting already reads the complete input.

If PAM header comments matter, add -comments:

$ pamfile -comments /usr/share/netpbm/pcxstd.ppm
/usr/share/netpbm/pcxstd.ppm:    PPM plain, 16 by 1  maxval 255
Comments:

For PBM, PGM and PPM files, the command reports that there are no comments even if comment-like header material exists. The option is useful chiefly for PAM images.

7. Diagnose failures without changing the file

If pamfile cannot open an input, inspect the path and permissions first:

$ ls -l /path/to/image.pam
$ test -r /path/to/image.pam && echo readable
readable

If the file is readable but the format is rejected, keep the original and test a known-good Netpbm file. Do not rename a file to make its extension look like a PPM or run an image inspector as root. pamfile reads the format data, not the filename suffix, and elevated privileges do not repair malformed image data.

When a pipeline feeds pamfile, check both commands' behaviour. A producer that receives a broken pipe can report an error if pamfile reads only a header. In that situation, retry with -allimages and use the producer's documented error handling. The option consumes input; it does not make corrupt pixels valid.