Select Images from a Netpbm Stream with pampick

You will finish with a repeatable way to select one or more images from a multi-image Netpbm stream and write the selected images to a new stream. The examples use Netpbm 11.05.02, installed here as Debian package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need pampick and, for the inspection steps, pamfile. The input must be a PNM or PAM stream. No elevated privileges are needed when the input and output are in directories you can already read and write.

1. Confirm the installed tools

Check the command paths and package version before putting the operation into a script:

$ command -v pampick pamfile
/usr/bin/pampick
/usr/bin/pamfile
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The installed manual describes pampick as a filter. Its image sequence numbers are arguments, while the image stream is read from standard input. That means a file name is not an input argument.

2. Count the images before selecting them

Use pamfile -count as a read-only inspection. Replace the placeholder with the path to your own stream:

$ pamfile -count /path/to/input-stream.pam
/path/to/input-stream.pam:  4 images

The exact spacing and file name in the output can vary. The count is the useful part. To inspect each image's format and dimensions, use -allimages:

$ pamfile -allimages /path/to/input-stream.pam
/path/to/input-stream.pam:  Image 0:  PPM raw, 640 by 480  maxval 255
/path/to/input-stream.pam:  Image 1:  PPM raw, 800 by 600  maxval 255
/path/to/input-stream.pam:  Image 2:  PPM raw, 1024 by 768  maxval 255
/path/to/input-stream.pam:  Image 3:  PPM raw, 320 by 240  maxval 255

Sequence numbering starts at zero, so the first image is 0 and the fourth image is 3. Do not use a human-facing count directly as an index. If the input is a pipe, pamfile -count also consumes the stream, so run it against a file or regenerate the pipe for the later extraction.

3. Select one image into a new file

Use standard input and redirect standard output to a new destination. This example selects the first image:

$ pampick 0 < /path/to/input-stream.pam > selected-0.pam
pampick: Extracting Image #0
$ pamfile selected-0.pam
selected-0.pam:  PPM raw, 640 by 480  maxval 255

The diagnostic is written by the installed command while the selected image data goes to selected-0.pam. The output remains in the same Netpbm format as the selected input image. In this example that is PPM, but a PAM input can produce PAM output for a selected PAM image.

Shell redirection truncates an existing destination before pampick starts. If the destination already contains useful data, choose a new name or use a temporary name and replace the old file only after checking the result:

$ pampick 0 < /path/to/input-stream.pam > selected-0.pam.new
$ pamfile selected-0.pam.new
$ mv selected-0.pam.new selected-0.pam

The mv step changes the destination. Before running it, stop if the inspection command failed or reported an unexpected format. If the extraction fails, the original selected-0.pam remains in place and the incomplete .new file can be removed after you have checked that it is not needed.

4. Select several images in one pass

Give the requested sequence numbers in strictly increasing order, without duplicates. This selects images 0 and 2 and writes a two-image stream:

$ pampick 0 2 < /path/to/input-stream.pam > selected-0-and-2.pam
pampick: Extracting Image #0
pampick: Extracting Image #2
$ pamfile -count selected-0-and-2.pam
selected-0-and-2.pam:  2 images

pampick emits the selected images in the same order as the input. The output order is therefore 0 followed by 2, even if your later processing gives them different names. Do not rely on behaviour for arguments such as 2 0 or 1 1: the manual says the results are undefined when the numbers are not increasing and unique.

5. Use a pipe when the stream is generated on demand

Because the input is standard input, a producer can feed pampick directly. Keep the sequence numbers at the end of the command line for clarity:

$ netpbm-producing-command | pampick 1 3 > selected.pam
$ pamfile -count selected.pam
selected.pam:  2 images

netpbm-producing-command is a placeholder, not a Netpbm program name. Replace it with the command that creates your stream. Check the producer separately if the pipeline fails. pampick always reads the entire input stream, including images it does not select. This is deliberate: a producer on a pipe can otherwise fail when its output buffer fills or its reader exits early.

For a stream that contains no images selected by the arguments, the command writes no image data. With no sequence numbers, the installed program exits without producing output:

$ pampick < /path/to/input-stream.pam > nothing.pam
$ wc -c < nothing.pam
0

6. Handle bad indexes and choose the right tool

If you request an index beyond the stream, pampick fails with an error rather than silently producing a partial image:

$ pampick 4 < /path/to/four-image-stream.pam > selected.pam
pampick: You asked for image sequence number 4 (relative to 0). The number of images in the input stream is only 4.

The wording can vary slightly, but the boundary is clear: for four images, valid indexes are 0 through 3. Check the count again if another process may have changed the input.

Use pampick when you want a new stream containing chosen images. Use pamsplit when you want every image in its own named file. For example, its output pattern uses the first %d as the zero-based image number:

$ pamsplit /path/to/input-stream.pam extracted-%d.pam
$ ls extracted-*.pam
extracted-0.pam  extracted-1.pam  extracted-2.pam  extracted-3.pam

Do not run that example in a directory containing files you need to preserve without checking the names first. A generated output name can collide with an existing file, depending on the command and filesystem permissions. When you only need to discover the stream's contents, use pamfile and avoid creating extraction files.