Warp Image Corners with pamhomography

You will map four points in an image to four new points, producing a perspective correction, skew, crop, flip or other quadrilateral warp in Netpbm format. Allow about fifteen minutes for a first transformation, plus time to choose and check the coordinates. The examples use Netpbm 11.5.2 from the installed netpbm package.

This is an ordinary user-level workflow. You need a readable PAM-compatible image, a writable output directory and the pamhomography command. Nothing here needs sudo. Keep the original image until you have inspected the result.

1. Check the installed command

Confirm the binary and package version before relying on an example. These commands only read local metadata:

$ command -v pamhomography
/usr/bin/pamhomography
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pamhomography --version 2>&1 | head -n 2
pamhomography: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamhomography: Built from source dated 2024-03-31 09:09:47

The manual allows a short unique prefix for options, either one or two hyphens, and either = or whitespace before a value. The examples use full option names and space-separated values so the mapping is easy to audit.

2. Understand the four-point mapping

pamhomography maps a source quadrilateral to a target quadrilateral. Each list contains four integer coordinate pairs, in corresponding order. Coordinates normally run clockwise around the shape, starting at its upper-left corner. The coordinate origin is the upper-left pixel of the image, and coordinates may be outside the image boundary.

With no -from option, the source is the complete input image. With no -to option, the target is also the complete input image. That default means a command with only -view can crop or add a border without changing the image's mapping.

Checkpoint: write down the four source points and four target points before typing the command. A swapped pair can produce a convincing but incorrect result, so do not treat a successful exit status as proof that the geometry is right.

3. Correct a photographed rectangle

Suppose the useful rectangular panel in photo.ppm has corners measured as (147,51), (316,105), (402,595) and (92,560). Map those points to a 441 by 640 rectangle. The output is written to a new file by shell redirection:

$ cat > panel.map <<'EOF'
(147, 51) (316, 105) (402, 595) (92, 560)
(0, 0) (440, 0) (440, 639) (0, 639)
EOF
$ pamhomography -mapfile panel.map photo.ppm > panel-rectified.ppm

The map file contains eight pairs: the first four are the source and the next four are their matching targets. Parentheses and commas are optional because every character other than digits, plus and minus signs is a separator. The output keeps the same Netpbm format as the input.

Verify the file before opening it in an editor or replacing anything:

$ file panel-rectified.ppm
panel-rectified.ppm: Netpbm image data, size 441 x 640, rawbits, pixmap
$ head -n 3 panel-rectified.ppm
P6
441 640
255

Your file wording can differ. Check that the output exists, has the intended dimensions and is non-empty, then inspect the image visually.

4. Use direct coordinates for a simple warp

For a whole-image transformation, -to is shorter than a map file. This maps a 441 by 640 image to a trapezoid, leaving the target view to fit the target quadrilateral:

$ pamhomography -to '50,0 390,0 440,200 0,200' photo.ppm > photo-trapezoid.ppm
$ file photo-trapezoid.ppm
photo-trapezoid.ppm: Netpbm image data, size 440 x 200, rawbits, pixmap

To flip left to right, reverse the corresponding top and bottom points:

$ pamhomography -to '440,0 0,0 0,639 440,639' photo.ppm > photo-flipped.ppm

This is a useful reminder that point order describes correspondence, not merely the outline direction. A counterclockwise target can be correct when it represents a reflection.

5. Control the visible output and fill colour

-view sets the upper-left and lower-right boundaries of the pixels visible in the output. -fill supplies the colour outside the target quadrilateral. The default fill is black, or transparent when the input has a transparency plane.

Scale a 441 by 640 image to 341 by 540 and add a tan border by choosing a wider view:

$ pamhomography \
    -to '0,0 340,0 340,539 0,539' \
    -view '-100,-100 440,639' \
    -fill tan \
    photo.ppm > photo-small-border.ppm
$ file photo-small-border.ppm
photo-small-border.ppm: Netpbm image data, size 541 x 740, rawbits, pixmap

Use the same source and target coordinates with -from and -to to extract a non-rectangular quadrilateral. Use -view alone when a rectangular crop is enough:

$ pamhomography -view '130,10 205,80' photo.ppm > photo-crop.ppm

Do not assume that a negative coordinate is an error. It is useful for borders and rotated shapes, but it can also create an unexpectedly large output. Check the dimensions every time.

6. Replace outputs without losing the old file

Shell redirection with > truncates an existing destination before pamhomography starts. During experimentation, write to a temporary name and promote it only after verification:

$ pamhomography -mapfile panel.map photo.ppm > panel-rectified.ppm.new
$ file panel-rectified.ppm.new
panel-rectified.ppm.new: Netpbm image data, size 441 x 640, rawbits, pixmap
$ mv panel-rectified.ppm.new panel-rectified.ppm

The final mv replaces the old output in the same directory. If the conversion fails, remove the incomplete .new file and rerun the command; the previous output is still available. Do not delete the source image or the old output until the new image has passed both the file check and visual inspection.

7. Diagnose the common failures

A malformed coordinate list is rejected before an image is produced. Each quadrilateral needs eight integers, and -view needs four. If you see an error such as failed to parse ... as a list of eight integers, count the x and y values, check the quotes and remove accidental shell expansion.

If the output is the wrong size, inspect -view first. If its dimensions are right but the subject is distorted, check the correspondence between each source point and target point, then check whether the points were entered clockwise as intended. A normal exit status only says that the transformation was calculated and written.

When an image viewer cannot open the result, use file and the first three header lines. The program preserves the input Netpbm format, so pass the output to a suitable Netpbm converter if your viewer does not support that format. Keep intermediate PPM files until the final conversion is confirmed.