Reassemble Image Tiles Reliably with pamundice

You will finish with one Netpbm image rebuilt from a grid of numbered tiles, plus a repeatable way to use a list when the filenames do not encode positions. This guide uses the installed Netpbm package, version 2:11.05.02-1.1build1, whose library reports Netpbm 11.5.2. Allow about 15 minutes if the tiles already exist.

pamundice reads image files and writes the combined image to standard output. It does not edit the input tiles. Keep the output filename separate from the inputs, and do not redirect over an existing source image unless you have a tested backup. No command here needs elevated privileges.

1. Check the tile contract

Before assembling anything, confirm that the tiles are all Netpbm images with the same format and maxval. PAM tiles must also have the same depth and tuple type. Every tile in one horizontal row must have the same height, and every tile in one vertical column must have the same width. Rows may have different heights, and columns may have different widths.

This is a layout contract, not just a naming convention. A missing tile or a tile with the wrong dimensions can stop the command or produce an image that is not the composition you intended. Inspect a representative file with a Netpbm tool such as pamfile if it is installed:

$ pamfile tiles/tile_0_0.ppm tiles/tile_0_1.ppm
tiles/tile_0_0.ppm: PPM raw, 320 by 240 pixels, maxval 255
tiles/tile_0_1.ppm: PPM raw, 320 by 240 pixels, maxval 255

Checkpoint: write down the number of columns and rows. In the examples below, there are two tiles across and two down, so the command must find four inputs.

2. Reassemble a numbered grid

Use a printf-style input pattern when the filename contains the tile position. The d conversion is the row number, called "down" by the command. The a conversion is the column number, called "across". Both numbers start at zero, and the precision between % and the letter is required.

$ pamundice 'tiles/tile_%1d_%1a.ppm' -across=2 -down=2 > assembled.ppm

The quotes protect the percent signs from shells or scripts that assign special meaning to them. They are not required in an ordinary POSIX shell, but they make the filename pattern explicit. The command looks for tile_0_0.ppm, tile_0_1.ppm, tile_1_0.ppm and tile_1_1.ppm, then writes the result to assembled.ppm.

Use a wider precision when the filenames contain leading zeroes:

$ pamundice 'tiles/tile_%2d_%2a.ppm' -across=10 -down=8 > assembled.ppm

For example, row 0 and column 5 become tile_00_05.ppm. A common distraction trap is swapping the conversions: %d is vertical position and %a is horizontal position. The output is written on standard output, so always make the destination visible in the command.

Verify the result rather than trusting a successful exit status:

$ pamfile assembled.ppm
assembled.ppm: PPM raw, 640 by 480 pixels, maxval 255

For a two-by-two grid of 320 by 240 tiles with no overlap, the expected dimensions are 640 by 480. If you used overlap, subtract the overlap between adjacent tiles as described in step 4.

3. Use a list file for arbitrary names

When filenames do not contain positions, use -listfile instead of a pattern. The list has one filename per line in row-major order: the upper-left tile first, then the remaining tiles across the first row, followed by the next row. The number of lines must equal across multiplied by down.

$ printf '%s\n' \
    'camera/front-left.ppm' \
    'camera/front-right.ppm' \
    'camera/rear-left.ppm' \
    'camera/rear-right.ppm' > tile-list.txt
$ pamundice -listfile=tile-list.txt -across=2 -down=2 > assembled.ppm

The names in the list are used as written. A repeated name is allowed, which is useful for deliberate checkerboards or repeated backgrounds. The list file itself is input state: review it before running the command, especially if it was generated by another program.

Checkpoint: count the entries and compare the result with the product of the two dimensions:

$ wc -l < tile-list.txt
4

If the list is wrong, recreate or edit that list and rerun into a new output path. Do not delete the old assembled image until you have inspected the replacement and have a copy you can restore.

4. Account for intentional overlap

Use -hoverlap when adjacent tiles overlap horizontally. The command clips that many pixels from the right edge of every tile except the rightmost tile in each row. Use -voverlap for vertical overlap; it clips from the bottom edge of each tile except the bottom row.

$ pamundice 'tiles/tile_%1d_%1a.ppm' \
    -across=2 -down=2 -hoverlap=9 -voverlap=6 > assembled.ppm

Every input tile must be at least as wide as the horizontal overlap and tall enough for the vertical overlap. For two columns of width 320 with a nine-pixel horizontal overlap, the output width is 631 pixels. For two rows of height 240 with a six-pixel vertical overlap, the output height is 474 pixels. The option reverses the corresponding overlap behaviour of pamdice, so use the same values when undoing a split.

Do not use overlap to stitch photographs whose seams are not already aligned. pamundice clips fixed edges; it does not discover registration, blend seams or correct perspective. Use pnmstitch for that job.

5. Diagnose a failed assembly

A message about being unable to open a file usually means the pattern generated a different name from the one on disk. Check one expected name directly, including its zero padding:

$ ls -l tiles/tile_00_05.ppm
$ pamundice 'tiles/tile_%2d_%2a.ppm' -across=10 -down=8 > assembled.ppm

If a tile is missing, stop and repair the input set. Do not fill a gap with a neighbouring tile unless duplication is intentional. If the command reports format, maxval or geometry trouble, compare the headers and dimensions of the affected row and column, then convert or regenerate the outlier into a new file.

For diagnostics, add -verbose to print processing information on standard error. It does not change the image data. The command cannot read image data from standard input, and its inputs must be files that can be closed, reopened and read again. A named pipe is therefore not a safe substitute for a regular tile file.

The installed 11.5.2 manpage documents filename patterns and list files. Newer upstream documentation also describes -indexfile, introduced in Netpbm 11.10, but that option is not part of this installed command's documented interface. Do not copy an -indexfile example to this machine without first checking the local version and help output.