Split a Multi-image Netpbm Stream with pamsplit

Chase down pnmsplit and you hit a wall fast: its own manual says it is obsolete and tells you to use pamsplit instead. On this machine, Netpbm 11.5.2 still ships 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. None of this needs root. It does create new files, so check the destination first and never point the pattern at anything valuable.

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 the command was replaced starting with Netpbm 10.31, back in December 2005. It also says pamsplit is backward compatible with the old command, with one catch: when checking newer documentation against an old script, ignore anything added after Netpbm 10.30. The practical migration is simple: swap the executable name, then test the files it produces.

2. Check the input and choose a safe destination

pamsplit reads a PNM or PAM stream, either 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

Swap in your real path for INPUT_STREAM.pam. If the destination already has files matching the pattern you plan to use, pick a new directory or a new prefix; the command writes output files without asking, and it will happily overwrite a path that already resolves to something.

3. Split the stream with an explicit filename pattern

Pass the input followed by an output pattern containing %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

How many lines you get depends on the input. Numbering starts at 0, the pattern must contain %d, and only the first occurrence gets replaced: text after the marker is kept as-is, so frame%d.pam gives you frame0.pam, frame1.pam, and so on.

Check the result rather than trusting the status lines 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 format and dimensions. If your input is PGM, PPM or PBM rather than PAM, use a matching suffix such as frame%d.pgm: the suffix is just part of the name and does not convert anything.

4. Use standard input from a pipeline

A hyphen means standard input, letting another command feed the stream straight in without an intermediate file:

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

Swap in a real producer for some-netpbm-command. Test it on its own, or pipe it to a temporary destination first, before wiring up a long pipeline: a clean pamsplit exit status cannot turn malformed upstream data into the images you actually wanted.

5. Pad names for predictable sorting

Unpadded names sort badly once the sequence hits two digits: frame10 can land before frame2. Set a minimum numeric width with -padname:

$ 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 pads with leading zeroes to reach the requested width; it never truncates a bigger number, so a sequence past 999 still gets all its digits. It can also be written with a space, -padname 3, and the manual accepts a double-hyphen spelling too.

Keep the option separate from the output pattern. A pattern with no %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

6. Choose the next Netpbm tool deliberately

• Just need basic image information? The pamfile manual is the better fit than splitting anything.
• Selecting images from a stream into one output stream? Use pampick.
• Processing every image without the temporary files this guide makes? Use pamexec.
• Recombining separate single-image files? The pnmsplit manual points to ordinary cat, provided the files form a valid Netpbm stream in the right order.

None of those choices needs elevated privileges. Treat any later command that replaces source files, feeds a live service, or handles untrusted image data as a separate review: image parsers can be resource-hungry, so keep untrusted batches in a controlled directory with limits that suit your environment.