Build a Pop9-Style Image Grid with pampop9

You will turn one PNM image into a multi-lens style grid, where each tile is taken from a slightly different position in the source. The examples use the installed pampop9 from Netpbm 11.5.2 and write a new image without changing the input. Allow about fifteen minutes if you already have a suitable PGM or PPM file.

1. Check the installed command and input

You need the netpbm package and a readable PNM-family image. PGM and PPM are convenient examples, but the command accepts the Netpbm input named by its synopsis, or - for standard input. This is an ordinary image conversion, so it normally needs no elevated privileges.

$ command -v pampop9
/usr/bin/pampop9
$ pampop9 --version
pampop9: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ pnmfile /path/to/source.pgm
/path/to/source.pgm: PGM raw, 100 by 100  maxval 255

The version output contains build details after the Netpbm version. The useful check here is that the command resolves to the expected binary and the source dimensions are known. If pnmfile is not installed, use another Netpbm inspection tool you already have, but do not guess the dimensions.

2. Choose the grid and offsets

The command takes five positional arguments:

pampop9 INPUT XTILES YTILES XDELTA YDELTA

XTILES and YTILES select the number of columns and rows. The two delta values select how far the source position moves between neighbouring columns and rows. The first tile starts at the source origin. The next column starts XDELTA pixels further right, and the next row starts YDELTA rows further down.

For a 100 by 100 source, this documented example creates nine 80 by 80 tiles:

pampop9 /path/to/source.pgm 3 3 10 10

The tile width is the source width minus the total horizontal offset, and the tile height is the source height minus the total vertical offset. In this example, the last column starts at 20 pixels and the last row at 20 pixels, leaving 80 pixels in each direction. Keep enough source area for every requested offset. A delta that leaves no positive tile dimension is rejected.

Checkpoint: write down the expected tile size before running the conversion. It is the quickest way to spot a swapped argument or an unsuitable source image.

3. Write the grid to a new file

Use shell redirection because pampop9 writes the resulting image to standard output. The command has no pampop9-specific options; it recognises common libnetpbm options, but the image and five positional arguments are the core interface.

$ pampop9 /path/to/source.pgm 3 3 10 10 > /path/to/pop9-grid.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the command completed. It does not make an existing destination safe: > truncates that file before the program starts. If the destination matters, use a temporary name and replace the old file only after checking the result:

$ pampop9 /path/to/source.pgm 3 3 10 10 > /path/to/pop9-grid.pgm.new
$ pnmfile /path/to/pop9-grid.pgm.new
/path/to/pop9-grid.pgm.new: PGM raw, 240 by 240  maxval 255
$ mv /path/to/pop9-grid.pgm.new /path/to/pop9-grid.pgm

The mv is the state-changing step. Do not run it until the temporary file has the expected dimensions and you have viewed or otherwise checked the image. If conversion fails, remove only the incomplete .new file and the previous output remains in place:

$ rm /path/to/pop9-grid.pgm.new

That removal is irreversible, so confirm the pathname before pressing Enter.

4. Verify the layout, not just the exit status

For the 100 by 100 input and the 3 by 3 grid above, the output is 240 by 240: three 80-pixel tiles across and three down. Check the actual file:

$ pnmfile /path/to/pop9-grid.pgm
/path/to/pop9-grid.pgm: PGM raw, 240 by 240  maxval 255

Open the image in a viewer or pass it to a later Netpbm conversion if you need a format such as PNG. For example, this optional step creates a separate PNG and leaves the PGM available for troubleshooting:

$ pnmtopng /path/to/pop9-grid.pgm > /path/to/pop9-grid.png
$ file /path/to/pop9-grid.png
/path/to/pop9-grid.png: PNG image data, 240 x 240, ...

The exact file wording depends on the installed version. The dimensions and a successful exit status are the useful checks.

5. Use standard input when the image is in a pipeline

The synopsis accepts - as the input name, so another Netpbm command can feed it directly. This example generates a test ramp and sends it through pampop9 without creating an intermediate source file:

$ pgmramp -lr 100 100 | pampop9 - 3 3 10 10 > /path/to/pipeline-grid.pgm
$ pnmfile /path/to/pipeline-grid.pgm
/path/to/pipeline-grid.pgm: PGM raw, 240 by 240  maxval 255

The pgmramp command is only a reproducible test source. Replace it with a producer that emits a valid PGM, PPM or other supported Netpbm image. Keep the five arguments after the input marker; omitting one changes the command shape and causes an argument error.

6. Diagnose the common failures

If the command says it cannot read a magic number, the input is empty, not a Netpbm image, or a preceding pipeline command failed. Inspect the source first:

$ pnmfile /path/to/source.pgm
$ test -r /path/to/source.pgm && echo readable

If you see invalid argument, check that all four numeric values were supplied and that the tile counts and deltas are positive. If you see an error such as xtilesize must be positive, the requested horizontal offsets consume the source width. Reduce the number of columns or the horizontal delta, or provide a wider source. Apply the same reasoning vertically for rows and YDELTA.

The program does not offer a flag for resizing, cropping or choosing an output format. Resize or crop the source with a separate Netpbm tool before this step, and verify that change independently. Do not use sudo merely to convert an image. If the source or destination is protected, fix the file ownership or choose a directory where your account can work, following your system's normal access policy.

Keep the original image until the grid has been inspected. If a batch job writes into a directory shared with other processes, use unique temporary names and check for an existing destination before replacing it.