Split Large Netpbm Images into Verifiable Tiles with pamdice

You will finish with a repeatable way to split a PAM, PBM, PGM or PPM image into a regular grid of smaller files, check what was created, and optionally join the tiles again. The examples use pamdice from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need an input Netpbm image, a writable output directory, and the Netpbm tools pamdice and, if you want to reassemble the tiles, pamundice. The normal commands are unprivileged. Do not use sudo just because the image is large: write to a directory your account owns.

1. Check the installed command

Confirm that the command resolves to the program you intend to use, then record its Netpbm version. This is read-only:

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

The installed manual describes the command as splitting PAM, PBM, PGM or PPM input into equal-sized pieces. The last piece in a row or column can be smaller when the input dimensions are not exact multiples of the requested tile size.

Checkpoint: if command -v pamdice prints nothing, stop here and install Netpbm through your normal package-management process. Do not copy a binary from an unrelated host.

2. Inspect the input before splitting

Use pamfile to check the image type and dimensions without changing it:

$ pamfile /path/to/input.ppm
/path/to/input.ppm: PPM raw, 1920 by 1080

Your wording may differ slightly, but you need the width, height and image type. Keep those values nearby when choosing tile dimensions. pamdice does not resize the image. Its -width and -height options describe the maximum width and height of each output piece.

Make a new output directory first. This avoids mixing fresh tiles with files from an earlier run:

$ mkdir -- /path/to/pamdice-run
$ test -w /path/to/pamdice-run && echo writable
writable

Do not point -outstem at a directory containing valuable files with the same names. Existing files may be replaced by the run, depending on the tool and filesystem behaviour. If you need to preserve an earlier tile set, rename or copy that directory before continuing.

3. Create a regular grid

Give pamdice the input file, an output stem, and the tile dimensions. This example creates tiles no wider than 640 pixels and no taller than 360 pixels:

$ pamdice /path/to/input.ppm \
    -outstem=/path/to/pamdice-run/tile \
    -width=640 \
    -height=360

The output names contain the input position, not a one-based tile number. A tile beginning at the top-left corner is named tile_0_0.ppm; a tile beginning 640 pixels from the left is tile_640_0.ppm. The extension follows the input format: PBM produces .pbm, PGM produces .pgm, PPM produces .ppm, and PAM produces .pam.

Checkpoint: list the result and inspect one tile:

$ find /path/to/pamdice-run -maxdepth 1 -type f -name 'tile_*' -print | sort | head
/path/to/pamdice-run/tile_0_0.ppm
/path/to/pamdice-run/tile_0_360.ppm
/path/to/pamdice-run/tile_0_720.ppm
/path/to/pamdice-run/tile_0_1080.ppm
/path/to/pamdice-run/tile_640_0.ppm
$ pamfile /path/to/pamdice-run/tile_0_0.ppm
/path/to/pamdice-run/tile_0_0.ppm: PPM raw, 640 by 360

The final row or column can be smaller. For a 1920 by 1080 image, 640 by 360 divides evenly, but a 2000 by 1100 image would produce smaller edge pieces. Check the actual dimensions rather than assuming every tile matches the requested size.

4. Add overlap only when the workflow needs it

Overlap is useful when a later operation needs neighbouring pixels at each tile boundary. -hoverlap overlaps adjacent tiles horizontally, while -voverlap overlaps adjacent rows vertically. Values are pixels:

$ pamdice /path/to/input.ppm \
    -outstem=/path/to/pamdice-run-overlap/tile \
    -width=640 \
    -height=360 \
    -hoverlap=16 \
    -voverlap=16

Overlap is zero by default. It increases the amount of data in the output and changes how you must reassemble or crop the tiles. Do not add it as a precaution when a plain grid is enough. Keep overlapped output in a separate directory so that it cannot be mistaken for non-overlapped tiles.

If the overlap is greater than or equal to a tile dimension, the grid can become confusing or invalid for the intended use. Choose a smaller value and verify the resulting positions with pamfile and the file names.

5. Reassemble a non-overlapped grid

For a regular grid without overlap, pamundice can join the pieces. Its input pattern uses conversion placeholders for the horizontal and vertical tile positions:

$ pamundice '/path/to/pamdice-run/tile_%1d_%1a.ppm' \
    -across=3 \
    -down=3 > /path/to/rejoined.ppm
$ pamfile /path/to/rejoined.ppm
/path/to/rejoined.ppm: PPM raw, 1920 by 1080

Use the number of tiles across and down, not the pixel dimensions. The exact pattern and counts must match the files you created. The overlap example is not a drop-in input for this command: joining overlapped pieces without a deliberate cropping or compositing plan can duplicate boundary pixels.

Redirection creates or truncates the destination before pamundice runs. To protect an existing image, write to a new name first:

$ pamundice '/path/to/pamdice-run/tile_%1d_%1a.ppm' \
    -across=3 -down=3 > /path/to/rejoined.ppm.new
$ pamfile /path/to/rejoined.ppm.new
$ mv -- /path/to/rejoined.ppm.new /path/to/rejoined.ppm

If the join fails, remove the incomplete .new file after checking that it is the temporary output, then retry with the original destination untouched. Removing files is irreversible, so verify the path before using rm.

6. Diagnose the likely failures

If pamdice says that -outstem is missing, add it. The option is required even when the input name seems like an obvious basis for output names. If it cannot open the input, check the path and read permission:

$ ls -l /path/to/input.ppm
$ test -r /path/to/input.ppm && echo readable

If the output directory is empty, check that it exists and is writable, and inspect the command for a typo in the stem. If the dimensions are surprising, run pamfile on several tiles, including the rightmost and bottom pieces. A smaller edge tile is normal when the input is not divisible by the requested size.

Use -verbose when you need processing information on standard error:

$ pamdice /path/to/input.ppm -outstem=/path/to/pamdice-run/tile \
    -width=640 -height=360 -verbose

Do not treat a successful exit status as proof that the visual result is correct. Check dimensions, open representative tiles in a suitable viewer, and retain the original until the whole workflow has been inspected.