Split a Multi-Image Netpbm Stream with pamsplit

You will split one multi-image PAM or PNM stream into separate, numbered image files without changing the source. The examples use Netpbm 11.5.2, installed from the Debian netpbm package. Allow about ten minutes if the input is ready and you only need a one-off split.

1. Check the command and prepare a destination

pamsplit reads a PNM or PAM stream and copies each image to its own file in the same format. It does not need root privileges. Work in a new destination directory so existing files are not confused with this run.

$ command -v pamsplit
/usr/bin/pamsplit
$ pamsplit --version
pamsplit: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamsplit: Built from source dated 2024-03-31 09:09:47
$ mkdir split-output

The version text contains build details after the version line. The manual page installed with this package is dated 11 August 2011, so the commands here describe the installed Netpbm 11.5.2 behaviour.

2. Split a file with numbered output names

Give the input file followed by an output pattern. The first %d in that pattern becomes the image number, starting at 0. The pattern must contain %d; a name without it is rejected.

$ pamsplit /path/to/stack.pam split-output/frame-%d.pam
pamsplit: WRITING split-output/frame-0.pam
pamsplit: WRITING split-output/frame-1.pam

Do not mistake the first output number for a count. It is the index of the first image, and the sequence continues for every image in the input. Check the results with pamfile, which reads the image headers rather than relying on filenames:

$ pamfile split-output/frame-*.pam
split-output/frame-0.pam: PAM, 2 by 1 by 1 maxval 1
    Tuple type:
split-output/frame-1.pam: PAM, 2 by 1 by 1 maxval 1
    Tuple type:

Your dimensions, depth and maxval will differ. The useful check is that there is one valid Netpbm report for each expected input image.

Checkpoint: confirm the split

• The source file is still present.
• The output directory contains one file per image.
• pamfile can read every output file.

3. Use zero-padded names for sorting

Without an option, the sequence is not padded, so names can sort as frame-0, frame-1, then frame-10. Use -padname to set the minimum width of the number. The option can use either an equals sign or whitespace.

$ pamsplit /path/to/stack.pam split-output/frame-%d.pam -padname=3
pamsplit: WRITING split-output/frame-000.pam
pamsplit: WRITING split-output/frame-001.pam

Padding changes the names, not the image data. A width of three gives 000 through 999 before a larger number needs more than three characters. The default is no padding, equivalent to -padname=0.

Use the shortest unambiguous option spelling if you need it, but the full -padname form is clearer in scripts. Double hyphens are also accepted by this program.

4. Split standard input

Use - as the input filename when another command produces the Netpbm stream, or when the input is arriving through a pipe. Keep the output pattern as the second positional argument.

$ cat /path/to/stack.pam | pamsplit - split-output/from-stdin-%d.pam -padname=2
pamsplit: WRITING split-output/from-stdin-00.pam
pamsplit: WRITING split-output/from-stdin-01.pam
$ pamfile split-output/from-stdin-*.pam

The default input is standard input, so the explicit - is useful when it makes a script's data flow obvious. If you omit both positional arguments, the default output pattern is image%d and the files are written in the current directory.

That default is easy to overlook. Prefer an explicit directory and pattern for repeatable work:

$ mkdir default-output
$ pamsplit /path/to/stack.pam default-output/image-%d.pam

5. Avoid common mistakes and recover safely

Before running a batch, check the input and destination names without changing anything:

$ test -r /path/to/stack.pam && echo readable
readable
$ find split-output -maxdepth 1 -type f -name 'frame-*.pam' -print

A missing %d is a command error, not a request for one output file. A mistyped input path produces no useful split. A pattern containing a directory that does not exist also cannot produce the requested files, so create that directory first.

Shell redirection is not involved in the normal pamsplit form, but the command still writes named output files. Treat the destination as disposable and use a new directory when the source matters. If a run is incomplete, stop using its partial files, make another empty directory, and rerun from the original source. The source is the recovery copy; do not delete it until every output has passed inspection.

To undo this guide's example outputs, remove only the directory you created after checking its path:

$ find split-output -maxdepth 1 -type f -print
$ rm -i split-output/frame-000.pam split-output/frame-001.pam
$ rmdir split-output

The removal commands are destructive and require no elevated privileges. Do not use a broad wildcard if the directory contains unrelated work. If you need the files later, leave the directory in place instead.