Paste a Rectangle into a PNM Image with pnmpaste

You will finish with a repeatable way to place one PNM image inside another, check the result, and avoid losing the original. The examples use pnmpaste from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need two PNM files, a shell, and enough space for a new output file. No command in this guide needs elevated privileges. Keep the input images unchanged and write each result to a new path while you are testing.

1. Check the installed command

Confirm which executable will run and record its version. This is an ordinary, read-only check:

$ command -v pnmpaste
/usr/bin/pnmpaste
$ pnmpaste --version 2>&1 | head -2
pnmpaste: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmpaste: Built from source dated 2024-03-31 09:09:47

The command reads a pasted image first and a base image second. Its output keeps the base image's dimensions and type. The essential form is:

$ pnmpaste [OPTION] FROM.pnm X Y [INTO.pnm] > OUTPUT.pnm

Here, X and Y are the position of the pasted image's top-left corner in the base image. They are pixel coordinates, not a requested offset to apply after the paste.

2. Inspect both inputs before changing anything

Use pnmfile or pamfile to check the format and dimensions. The following example uses placeholders; replace them with paths you can read:

$ pnmfile /path/to/patch.pnm /path/to/base.pnm
/path/to/patch.pnm: PPM raw, 80 by 40
/path/to/base.pnm: PPM raw, 640 by 480

Do not treat those lines as fixed output. Your installed tool may report a different PNM subtype or wording. The useful facts are the width, height, and whether the files are PBM, PGM or PPM. The pasted rectangle must fit completely at the requested position. If it does not, pnmpaste exits with an error instead of producing a cropped image.

Checkpoint: write down the rectangle size and the base size. For an 80 by 40 patch at position 100 120, the occupied area ends at x 179 and y 159 when counting pixels from zero.

3. Perform a normal replacement paste

The default operation is -replace, so the patch pixels replace the corresponding base pixels:

$ pnmpaste /path/to/patch.pnm 100 120 /path/to/base.pnm > /path/to/base-with-patch.pnm
$ pnmfile /path/to/base-with-patch.pnm
/path/to/base-with-patch.pnm: PPM raw, 640 by 480

Shell redirection creates or truncates the output before pnmpaste runs. Never redirect to the only copy of the base image while experimenting. If the output path already contains useful work, choose a new name or make a backup first. A safer replacement pattern is:

$ cp --preserve=all /path/to/base-with-patch.pnm /path/to/base-with-patch.pnm.bak
$ pnmpaste /path/to/patch.pnm 100 120 /path/to/base.pnm > /path/to/base-with-patch.pnm.new
$ pnmfile /path/to/base-with-patch.pnm.new
$ mv /path/to/base-with-patch.pnm.new /path/to/base-with-patch.pnm

The final mv is the point at which the checked result replaces the old output. To undo it, restore the backup with mv /path/to/base-with-patch.pnm.bak /path/to/base-with-patch.pnm. Do not remove the backup until you have inspected the result; deleting it is irreversible.

4. Use negative coordinates when anchoring to an edge

A negative coordinate measures the pasted rectangle back from the far edge. For a 2-pixel-wide patch, -2 places its rightmost column against the base image's rightmost column. Likewise, a 2-pixel-high patch needs -2 on the vertical axis to meet the bottom edge:

$ pnmpaste /path/to/patch.pnm -2 -2 /path/to/base.pnm > /path/to/base-with-corner-patch.pnm
$ pnmfile /path/to/base-with-corner-patch.pnm
/path/to/base-with-corner-patch.pnm: PPM raw, 640 by 480

Be careful when translating a desired margin into a negative value. A patch that is 80 pixels wide with a 10-pixel right margin starts at -90, not -10. Use non-negative coordinates when the position is easier to audit from the top-left corner.

5. Combine PBM masks with a Boolean operation

The -or, -and, -xor, -nor, -nand and -nxor operations are restricted to PBM inputs. They combine each pasted pixel with the corresponding base pixel rather than simply replacing it. For example:

$ pnmpaste -xor /path/to/mask.pbm 20 30 /path/to/base-mask.pbm > /path/to/mask-xor.pbm
$ pnmfile /path/to/mask-xor.pbm
/path/to/mask-xor.pbm: PBM raw, 320 by 200

In the Boolean rules, white is true and black is false. That is different from treating the stored PBM bits as ordinary arithmetic bits: PBM represents white with a zero bit. If the inputs are PGM or PPM, use the default replacement operation or a more general compositor such as pamcomp; do not assume the PBM Boolean options will convert them.

Netpbm 10.85 introduced -nand, -nor and -nxor. They are available in the installed 11.5.2 version, but a script intended for much older Netpbm installations should not rely on them without checking the target system.

6. Handle standard input and failures

Either input filename may be - for standard input, but not both. Omitting the base filename has the same meaning as using - for it:

$ pnmpaste /path/to/patch.pnm 100 120 < /path/to/base.pnm > /path/to/result.pnm
$ pnmfile /path/to/result.pnm

Keep the two streams unambiguous. Do not try to feed both images through one pipe, and do not combine a standard-input patch with an omitted base image. Use ordinary filenames when you are debugging a pipeline so each input can be inspected independently.

If part of the patch would cross an edge, the command fails. For example, a 2-pixel-wide patch at x coordinate 4 cannot fit in a 5-pixel-wide base:

$ pnmpaste /path/to/2x2-patch.pbm 4 3 /path/to/5x4-base.pbm > /tmp/rejected.pbm
pnmpaste: Extends over right edge by 1 pixels
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic varies with the violated edge, but a non-zero status is the meaningful signal. Recheck the dimensions, coordinates and input order. The output file may have been created or truncated by the shell even though the command failed, so treat it as unusable and write the next attempt to a different path.