Home / Alt manpages / pampick(1)

  • pampick(1)
  • User command
  • linux

Select Images from a Netpbm Stream with pampick

A multi-image Netpbm stream hides its contents from you until you pick them apart, and pampick is the tool that picks. It reads one PNM or PAM stream and writes out only the images you name, in the order you named them.

The route

Jump straight to the step you need, or tick off Done means at the end.

Allow about fifteen minutes. You need pampick and, for the inspection steps, pamfile. No elevated privileges are needed when the input and output live in directories you can already read and write. The examples use Netpbm 11.05.02, installed here as Debian package version 2:11.05.02-1.1build1.

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, but the image stream itself comes from standard input. A file name is not an input argument.

Checkpoint

A command shaped like pampick 0 /path/to/stream is wrong on this interface. Use input redirection or a pipe instead.

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, add -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
  • Numbering starts at zero. The first image is 0 and the fourth is 3, so do not use a human-facing count directly as an index.
  • Counting a pipe consumes it. If the input is a pipe, pamfile -count reads the whole thing, so run it against a file, or regenerate the pipe for the later extraction.

3. Select one image into a new file

Redirect standard input from the stream and standard output to a new destination. This 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 line comes from pampick itself; the image data goes to selected-0.pam. The output stays in the same Netpbm format as the selected input image: PPM here, but a PAM input produces PAM output for a selected PAM image.

Warning

Shell redirection truncates an existing destination before pampick even starts. If the destination already holds something useful, pick a new name or write to a temporary one first:

$ 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 is the state-changing step. Stop before running it if the inspection command failed or reported an unexpected format. If the extraction fails outright, the original selected-0.pam is untouched and the incomplete .new file can be removed once you have confirmed you do not need it.

4. Select several images in one pass

Give the 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, so the output order here is 0 then 2, whatever you rename them to later. Do not rely on 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 whatever creates your stream, and check that producer separately if the pipeline fails.

Tip

pampick always reads the entire input stream, including images it does not select. That is deliberate: a producer on a pipe would otherwise fail when its output buffer fills or its reader exits early.

Ask for a sequence number that is not in the stream and you get nothing, cleanly. With no sequence numbers at all, the command 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

Ask for an index beyond the stream and pampick fails outright, rather than silently handing you 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 run 0 through 3. Check the count again if another process may have changed the input in the meantime.

  • Use pampick when you want one new stream containing your chosen images.
  • Use pamsplit when you want every image in its own named file, its output pattern using 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

Warning

Do not run that example in a directory holding files you need to keep without checking the names first. A generated output name can collide with an existing file, depending on the command and filesystem permissions. If you only need to know what the stream contains, stick to pamfile and skip creating extraction files altogether.

Done means

  • You confirmed that the installed Netpbm version reads the stream from standard input.
  • You counted images and mapped the required zero-based indexes before selecting them.
  • Your requested indexes are increasing, unique and within the stream.
  • You verified the selected output with pamfile.
  • You protected existing output by writing to a new or temporary destination before replacement.
  • You chose pamsplit instead when the job was really one file per input image.