Stitch Two Overlapping PNM Photos with pnmstitch

pnmstitch takes two overlapping, side-by-side PNM photographs and merges them into one wider panorama. The examples use pnmstitch from Netpbm 11.5.2, Debian package 2:11.05.02-1.1build1.

Allow about fifteen minutes, plus time to convert camera images to PNM if they are not already in that format. You need two readable PNM files, a shell, and enough free space for the output. The photographs must overlap substantially: pnmstitch is for panoramic alignment, not for bolting two unrelated images together.

1. Check the installed program

Confirm which binary is in use and record the Netpbm version. Both are ordinary, read-only commands needing no elevated privileges:

$ command -v pnmstitch
/usr/bin/pnmstitch
$ pnmstitch --version
pnmstitch: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmstitch: Built from source dated 2024-03-31 09:09:47

The version output includes build details and may run a line or two longer on your machine. If the command is missing, install Netpbm through your normal package-management process rather than dropping a binary into a system directory.

2. Check the input format and pair

pnmstitch expects the left image first and the right image second. It works on PNM files, so convert JPEG, PNG or another camera format with a separate tool before this step. Keep the original photographs until the finished result has been checked.

$ file /path/to/left.ppm /path/to/right.ppm
/path/to/left.ppm:  Netpbm image data, size = 4000 x 3000, rawbits, pixmap
/path/to/right.ppm: Netpbm image data, size = 4000 x 3000, rawbits, pixmap
$ test -r /path/to/left.ppm && test -r /path/to/right.ppm && echo 'both inputs are readable'
both inputs are readable

The wording from file varies between versions. What matters is that both paths exist, both are readable, and both identify as compatible PNM images. The left photograph should genuinely be the left-hand view; do not swap the arguments just because the right file happens to be bigger.

3. Write a stitched PNM safely

Use the three-argument form to name the output explicitly:

$ pnmstitch /path/to/left.ppm /path/to/right.ppm /path/to/panorama.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0

The command shifts and stretches the right image to match the left. A zero exit status only means the program finished; it does not prove the seam looks good. The output is PNM regardless of the extension your source files used.

Add -verbose to see the diagnostics:

$ pnmstitch -verbose /path/to/left.ppm /path/to/right.ppm /path/to/panorama.ppm
Selected BiLinearSliver stitcher algorithm
...diagnostic lines...
$ file /path/to/panorama.ppm
/path/to/panorama.ppm: Netpbm image data, size = 7990 x 3000, rawbits, pixmap

Verbose text describes the alignment work and goes to standard error; its numbers depend on the images and the installed build, so treat the dimensions above as an example, not a default you can rely on.

4. Verify the result before replacing anything

Check that the destination is non-empty and that an image tool recognises it:

$ test -s /path/to/panorama.ppm && echo 'output is non-empty'
output is non-empty
$ file /path/to/panorama.ppm
/path/to/panorama.ppm: Netpbm image data, size = 7990 x 3000, rawbits, pixmap

Open the image in a trusted viewer, or convert it with another Netpbm utility such as pnmtopng if that is installed. Look for a continuous seam, missing areas, and unexpected black borders. pnmstitch commonly leaves extra material around the transformed images, so cropping the result with pamcut afterwards is often appropriate; treat that crop as a separate operation writing to a new file while you are still testing.

If the panorama is not rectangular enough for your use, keep it as evidence while you pick crop coordinates. Do not delete the source images to save space before the seam and crop have been checked.

5. Choose the alignment controls only when needed

The default stitcher is RotateSliver. The other documented choices are BiLinearSliver and LinearSliver. Start with the default and change one setting at a time when the automatic result is poor:

$ pnmstitch -stitcher=BiLinearSliver /path/to/left.ppm /path/to/right.ppm /path/to/panorama-bilinear.ppm

-width, -height, -xrightpos and -yrightpos constrain where the images are joined. For LinearSliver, the two position values identify the point in the right image that corresponds to the top-right corner of the left image. These are geometry constraints, not resize controls; use them only once you have measured the pair and can explain the coordinate you are supplying.

The manual also lists LineAtATime and HorizontalCrop for -filter, with no further detail given. Avoid adding this option to a working command without testing the result. Option names can be abbreviated to a unique prefix, and two hyphens are accepted, but full option names read clearer in scripts.

Common traps

If the images merely touch at their edges with no overlapping scene, pnmstitch is the wrong command: use pamcat to concatenate them instead. For a vertical arrangement, the documented workflow combines pamflip with pnmstitch as needed; pnmstitch itself only handles side-by-side panoramas.

• One input filename given? pnmstitch reads the left image from standard input and treats the argument as the right image.
• No input filenames at all? It expects a multi-image file on standard input, left image followed by right.
• No output filename? The result goes to standard output; capture it deliberately rather than letting binary PNM data scroll through your terminal.

$ pnmstitch /path/to/left.ppm /path/to/right.ppm > /path/to/panorama.ppm
$ file /path/to/panorama.ppm

A failed run using redirection can leave a partial destination behind. Write to a new temporary destination, verify it, then move it into place only once you are satisfied:

$ pnmstitch /path/to/left.ppm /path/to/right.ppm /path/to/panorama.ppm.new
$ test -s /path/to/panorama.ppm.new && file /path/to/panorama.ppm.new
$ mv /path/to/panorama.ppm.new /path/to/panorama.ppm

That final mv is the only state-changing step in this recovery pattern. If verification fails, leave the original panorama alone and remove the untrusted .new file only after confirming its exact path.