Reassemble Image Tiles Reliably with pamundice

pamundice glues a grid of numbered Netpbm tiles back into one image, the exact reverse of pamdice. It reads the tile files and writes the combined image to standard output, leaving every input untouched. 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.

• No elevated privileges needed. This is an ordinary user command.
• Keep the output filename separate from the inputs. Do not redirect over an existing source image unless you have a tested backup.

1. Check the tile contract

Before assembling anything, confirm the tiles satisfy pamundice's layout rules. This is a contract, not just a naming convention: a missing tile or a wrong dimension can stop the command or silently produce the wrong composition.

• Same format and maxval. Every tile must be a Netpbm image with matching format and maxval.
• Same depth and tuple type for PAM tiles. Mixed PAM tiles will not assemble cleanly.
• Matching heights along a row. Every tile in one horizontal row must share a height.
• Matching widths down a column. Every tile in one vertical column must share a width. Rows can differ in height from each other, and columns can differ in width from each other.

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

2. Reassemble a numbered grid

Use a printf-style input pattern when the filename already encodes the tile position. The d conversion is the row number, which pamundice calls "down". The a conversion is the column number, called "across". Both 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 treat them specially. An ordinary POSIX shell does not require them, but they make the 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 carry leading zeroes:

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

Row 0, column 5 becomes tile_00_05.ppm. The classic mix-up: %d is vertical position and %a is horizontal, the opposite of what the letters suggest. The output goes to standard output, so always make the destination visible in the command.

Verify the result rather than trusting a clean exit status:

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

3. Use a list file for arbitrary names

When filenames do not carry positions, use -listfile instead of a pattern. The list holds one filename per line in row-major order: the upper-left tile first, then the rest of the first row, then the next row. The line count 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

Names in the list are used exactly as written. A repeated name is allowed, which suits deliberate checkerboards or repeated backgrounds. Treat the list file as input state: review it before running the command, especially if another program generated it.

$ wc -l < tile-list.txt
4

If the list is wrong, edit or recreate it 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 for horizontal overlap. It clips that many pixels from the right edge of every tile except the rightmost one in each row.
• Use -voverlap for vertical overlap. It clips from the bottom edge of every tile except the bottom row.

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

Every tile must be at least as wide as the horizontal overlap and tall enough for the vertical overlap. Two columns of width 320 with a nine-pixel horizontal overlap give an output width of 631 pixels; two rows of height 240 with a six-pixel vertical overlap give an output height of 474 pixels. The option reverses the equivalent 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.

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

• Missing tile. Stop and repair the input set. Do not fill the gap with a neighbouring tile unless duplication is intentional.
• Format, maxval or geometry error. Compare the headers and dimensions of the affected row and column, then convert or regenerate the outlier into a new file.
• Still unclear what is wrong? Add -verbose to print processing information on standard error; it does not touch the image data.

pamundice cannot read image data from standard input, and its inputs must be files that can be closed, reopened and read again, so a named pipe is 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.