Split a Multi-image Netpbm Stream with pamsplit

You will finish with separate numbered files from a multi-image PNM or PAM stream, while avoiding a common trap: pnmsplit is obsolete and its own manual tells you to use pamsplit. On this machine, Netpbm 11.5.2 still provides both names, but new scripts should use the replacement.

Allow about fifteen minutes. You need Netpbm, a readable multi-image input, and a directory where you can create output files. These examples do not need root. They create new files, so check the destination first and do not point the pattern at valuable existing files.

1. Check the installed version and replacement

Confirm which commands are present and which package supplied them:

$ command -v pnmsplit
/usr/bin/pnmsplit
$ command -v pamsplit
/usr/bin/pamsplit
$ pnmsplit --version
pnmsplit: 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 pnmsplit(1) page says that the command was replaced starting with Netpbm 10.31, in December 2005. It also says that pamsplit is backward compatible with the old command, with one qualification: when consulting newer documentation for old scripts, ignore features added after Netpbm 10.30. That makes the practical migration simple: replace the executable name, then test the resulting files.

2. Check the input and choose a safe destination

pamsplit reads a PNM or PAM stream. The input can be a file or - for standard input. Inspect the source before writing anything:

$ file INPUT_STREAM.pam
INPUT_STREAM.pam: Netpbm image data, ...
$ mkdir -p ./split-output
$ find ./split-output -maxdepth 1 -type f -print

Replace INPUT_STREAM.pam with your real path. If the destination already contains files matching the pattern you plan to use, choose a new directory or a new prefix. The command writes output files; it does not ask before overwriting a path that resolves to an existing file.

This is the first safety boundary. Do not use a broad pattern such as /tmp/%d when other jobs might use the same directory, and do not run the split as root just to bypass a permissions error. Fix ownership or choose a directory you can write instead.

3. Split the stream with an explicit filename pattern

Pass the input followed by an output pattern containing the first %d. That marker becomes the zero-based image number:

$ pamsplit INPUT_STREAM.pam ./split-output/frame%d.pam
pamsplit: WRITING ./split-output/frame0.pam
pamsplit: WRITING ./split-output/frame1.pam

The number of output lines depends on the input. The default sequence starts at 0, and the output pattern must contain %d. Text after the marker is retained, so frame%d.pam produces frame0.pam, frame1.pam, and so on. Only the first occurrence is replaced.

Check the result without trusting the status line alone:

$ find ./split-output -maxdepth 1 -type f -name 'frame*.pam' -print | sort
./split-output/frame0.pam
./split-output/frame1.pam
$ file ./split-output/frame0.pam ./split-output/frame1.pam
./split-output/frame0.pam: Netpbm image data, ...
./split-output/frame1.pam: Netpbm image data, ...

file should recognise each result as Netpbm data. The exact description depends on the image format and dimensions. If your input is PGM, PPM or PBM rather than PAM, use a matching filename suffix such as frame%d.pgm; the suffix is part of the name and does not convert the image.

4. Use standard input when the stream comes from a pipeline

A hyphen means standard input. This lets another command provide the multi-image stream without first creating an intermediate file:

$ some-netpbm-command | pamsplit - ./split-output/frame%d.pgm
pamsplit: WRITING ./split-output/frame0.pgm
pamsplit: WRITING ./split-output/frame1.pgm

Replace some-netpbm-command with a real producer that emits a PNM or PAM stream. Before using a long pipeline, test the producer by itself or pipe it to a temporary destination. A successful pamsplit exit status cannot make malformed or unintended upstream data into the images you wanted.

5. Pad names for predictable sorting

Unpadded names sort awkwardly once the sequence reaches two digits: frame10 can appear before frame2. Use -padname to set the minimum width of the numeric field:

$ pamsplit INPUT_STREAM.pam ./split-output/frame%d.pam -padname=3
pamsplit: WRITING ./split-output/frame000.pam
pamsplit: WRITING ./split-output/frame001.pam

The option adds leading zeroes to reach the requested width. It does not truncate larger numbers, so a sequence longer than 999 still gets all its digits. The option can also be written with a space, as -padname 3, and the manual permits a double hyphen spelling.

Keep the option separate from the output pattern. A pattern without %d is an error:

$ pamsplit INPUT_STREAM.pam ./split-output/no-number.pgm
pamsplit: output file spec pattern parameter must include the string '%d',
to stand for the image sequence number.
$ printf 'exit status: %s\n' "$?"
exit status: 1

That failure should leave no useful output from that invocation. If you are recovering from a partially completed run, list the destination, move confirmed results to a separate directory, then rerun with a fresh prefix. Do not blindly delete files when their provenance is unclear.

6. Choose the next Netpbm tool deliberately

Splitting is useful when later commands need individual files. If you only need basic image information, the pamfile manual is the better fit. To select images from a stream into one output stream, use pampick. To process every image without the temporary files created here, use pamexec. To combine separate single-image files again, the pnmsplit manual points to ordinary cat, provided the files form a valid Netpbm stream in the intended order.

None of those choices needs elevated privileges. Treat any later command that replaces source files, feeds a service, or handles untrusted image data as a separate review. Image parsers can be resource-intensive, so keep untrusted batches in a controlled directory and impose the limits appropriate to your environment.