Tile a PNM Image to Exact Dimensions with pnmtile

You will repeat a PNM image until it fills an output rectangle of the exact width and height you specify, then verify the result without opening binary image data in a text editor. Allow about ten minutes if the input file is ready. The examples use the installed Netpbm 11.5.2 command, from package version 2:11.05.02-1.1build1.

You need the netpbm package, a readable PNM image, and write access to the output directory. No example needs elevated privileges. Use sudo only if your input or destination is genuinely protected by the host's file permissions.

1. Check the command and input format

Confirm which executable is being used and inspect its installed version. These are ordinary, read-only commands:

$ command -v pnmtile
/usr/bin/pnmtile
$ pnmtile --version 2>&1 | sed -n '1,3p'
pnmtile: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmtile: Built from source dated 2024-03-31 09:09:47

pnmtile reads a PNM image. That is the Netpbm family of portable bitmap, greymap and pixmap formats, not a PNG or JPEG. Convert another image format first if necessary. The command has no pnmtile-specific switches: its positional arguments are width, height, and an optional input file.

Checkpoint: inspect the source before choosing output dimensions:

$ pamfile input.pnm
input.pnm: PPM raw, 320 by 200  maxval 255

The wording can vary between Netpbm versions. Record the useful facts: the input is a PNM image and its dimensions are plausible.

2. Tile to a new output file

Give the desired output width and height in pixels. The input file is optional; when it is absent, standard input supplies the image.

$ pnmtile 1200 800 input.pnm > tiled-1200x800.pnm

The image is repeated from its top-left corner. If the requested rectangle is not an exact multiple of the source dimensions, the final repetition is cropped at the right or bottom edge. The output is still a PNM image. On this installed version, a plain PBM or PPM input is emitted as raw PBM or PPM, so do not expect the textual P1 or P3 spelling to be preserved.

Standard input is useful in a pipeline:

$ pnmtopnm input.pnm | pnmtile 1200 800 > tiled-1200x800.pnm

pnmtopnm is optional here and is only useful when another Netpbm command produces a PNM stream that needs normalising. If you already have a PNM file, pass it directly.

3. Verify the exact result

Do not rely only on the shell command returning successfully. Inspect the output with another Netpbm reader:

$ pamfile tiled-1200x800.pnm
tiled-1200x800.pnm: PPM raw, 1200 by 800  maxval 255

Your format and maxval may differ. The important check is 1200 by 800. A small, self-contained smoke test demonstrates the same rule without needing an existing image file:

$ printf 'P1\n2 1\n1 0\n' | pnmtile 5 3 | pamfile -
-:  PBM raw, 5 by 3

The one-row, two-pixel source is repeated across five columns and three rows. The output dimensions describe the requested rectangle, not the number of whole copies that fit.

4. Protect an existing destination

Shell redirection with > truncates its destination before pnmtile starts. That matters if a conversion fails or the dimensions were mistyped. When replacing a useful file, write to a temporary name in the same directory, verify it, then rename it:

$ pnmtile 1200 800 input.pnm > tiled-1200x800.pnm.new
$ pamfile tiled-1200x800.pnm.new
tiled-1200x800.pnm.new: PPM raw, 1200 by 800  maxval 255
$ mv -- tiled-1200x800.pnm.new tiled-1200x800.pnm

The final mv replaces the old destination. Treat that as a deliberate, potentially destructive step. If the command or verification fails, leave the original alone and remove only the incomplete .new file after checking its path. If you need a reversible replacement across filesystems or a directory with unusual rename semantics, make a backup first:

$ cp --preserve=all tiled-1200x800.pnm tiled-1200x800.pnm.bak

Keep the backup until the new image has been checked visually or by the next tool in your workflow. Removing that backup is irreversible.

5. Diagnose failed runs

A non-positive dimension is rejected. For example, the installed command reports an error and exits non-zero for zero width:

$ pnmtile 0 800 input.pnm > failed.pnm
pnmtile: Width argument must be a positive number.  You specified 0.
$ printf 'exit status: %s\n' "$?"
exit status: 1

Do not treat the existence of failed.pnm as success: redirection can create an empty or partial file before the command fails. Check the status immediately, and remove the failed output only after confirming it is the disposable path. If the input cannot be read, check its path and permissions with ls -l and test -r; do not run the image operation as root just to hide a permission mistake.

If the output has the wrong dimensions, check the two positional numbers and rerun to a new destination. If the dimensions are correct but the image looks wrong, verify that the source itself is the expected image and that a later viewer or converter supports its PNM variant. pnmtile does not resize, crop to a smaller centre, or convert PNM into a compressed format.