Correct a Skewed Flat Image with pamperspective

You will turn a photographed rectangle, such as a poster or document, into a rectangular Netpbm image by giving pamperspective the four corners visible in the source. The command writes an image to standard output, so the workflow also shows how to avoid destroying an existing result while you tune the coordinates.

Allow about fifteen minutes for a first correction. You need the netpbm package, a readable Netpbm image, and the pixel coordinates of its four target corners. The installed command used for this guide is Netpbm 11.05.02. This is an image transformation only: it does not alter the input file and does not require sudo.

1. Check the installed command

Confirm the binary and package version before relying on option details. These are ordinary read-only commands:

$ command -v pamperspective
/usr/bin/pamperspective
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The manual describes pamperspective as a reverse scanline renderer. It reads one Netpbm image and produces another image, normally from an input file or standard input to standard output. It does not infer the corners from the picture, and it does not crop by detecting a document border.

Checkpoint: if command -v finds nothing, stop here and install Netpbm through your normal package-management process. Do not work around a missing binary by guessing a different program's option syntax.

2. Record the four corners

Measure the quadrilateral in the input image as eight coordinates, in this order:

1. upper-left x and y
2. upper-right x and y
3. lower-left x and y
4. lower-right x and y

With the default coordinate interpretation, pamperspective uses a lattice measured in pixels: (0,0) is the upper-left corner of the first pixel and (width,height) is the lower-right corner of the last pixel. For a 1600 by 1200 source, a plausible measured quadrilateral might therefore be (210,145), (1390,190), (175,1050), and (1435,1015).

The words upper and lower refer to the output rectangle, not necessarily to the order in which a camera captured the image. Keep the corners in a consistent clockwise or counter-clockwise order. Crossing the points can produce a flipped or unusable result.

Point-and-click tools often measure pixel centres rather than pixel boundaries. For those measurements, use --input_system=pixel and choose the matching --input_unit. Do not mix a centre-based measurement with the default lattice interpretation: a one-pixel shift at every edge can be visible on a small document.

3. Render a first rectangle

Use the eight positional coordinates followed by the input path. Save to a new file while you are testing:

$ pamperspective \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > corrected-first.ppm

The default output is the selected parallelogram sheared to a rectangle. The output size is calculated from the requested detail unless you set it explicitly. The default --detail=1 aims to keep adjacent output pixels from moving across more than one input pixel, so the result can be larger or smaller than you expect.

Check the file immediately:

$ file corrected-first.ppm
corrected-first.ppm: Netpbm image data, size = 1234 x 945, rawbits, pixmap
$ test -s corrected-first.ppm && echo 'non-empty output'
non-empty output

The dimensions in file will depend on your corners and the installed image. A successful command proves that an output was written, not that the corners were measured correctly. Open the image or pass it to an installed Netpbm viewer or converter before replacing the source.

4. Choose output size and interpolation

For a predictable destination size, set both dimensions. These values are output pixels, not input dimensions:

$ pamperspective \
    --width=1200 --height=900 \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > corrected-1200x900.ppm
$ file corrected-1200x900.ppm
corrected-1200x900.ppm: Netpbm image data, size = 1200 x 900, rawbits, pixmap

Use --interpolation=nearest for the default nearest-input-pixel choice. It preserves source pixels but can look jagged after enlargement. Use --interpolation=linear for bilinear interpolation from surrounding pixels, which is often less harsh for a photograph:

$ pamperspective --width=1200 --height=900 \
    --interpolation=linear \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > corrected-linear.ppm

Do not add --proportion=fixed unless you also understand its effect. With that setting, --ratio asks the program to increase one dimension after detail-based sizing so that width divided by height equals the requested ratio. When you specify both width and height, those explicit dimensions are the clearer choice.

5. Preserve an existing result while tuning

Shell redirection with > truncates its destination before pamperspective starts. That is irreversible if the only copy is there. Render to a temporary name and replace the old result only after inspection:

$ pamperspective \
    --width=1200 --height=900 --interpolation=linear \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > corrected.ppm.new
$ file corrected.ppm.new
$ mv corrected.ppm.new corrected.ppm

The mv command changes the destination name only after the renderer has completed and the temporary file has been checked. If rendering fails, leave the old output in place and inspect the error. Recovery is simply to remove the incomplete corrected.ppm.new and rerun the command; do not remove the original until the replacement is verified.

6. Handle margins and oversized output carefully

By default, the visible output is the transformed frame. --margin=0.1 adds a border measured as a fraction of the frame, while the individual top, bottom, left and right margin options can override that common value:

$ pamperspective --margin=0.05 \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > corrected-with-border.ppm

--include can request that extra input points remain visible, but quote its semicolons so the shell does not treat them as command separators:

$ pamperspective \
    --input_system=lattice --input_unit=pixel \
    '--include=[210,145;1390,190;175,1050;1435,1015]' \
    210 145 1390 190 175 1050 1435 1015 \
    /path/to/source.ppm > included.ppm

Do not use --include indiscriminately around a perspective image. Points near a visible horizon can describe an enormous distance in the reconstructed plane, producing a very large output and high memory use. Start with the frame, add a small margin, and inspect the dimensions before requesting more.

7. Diagnose the common failures

A file-open error normally means the path is wrong or unreadable. Check without changing anything:

$ ls -l /path/to/source.ppm
$ test -r /path/to/source.ppm && echo readable

If the command exits successfully but the rectangle is skewed, revisit the corner order and the coordinate system first. If edges look one pixel out, establish whether your measurement tool reports pixel centres and set --input_system=pixel appropriately. If the result is unexpectedly huge, remove --include and margins, then set explicit --width and --height.

Input and output are Netpbm images in the command's image pipeline. A PPM file is not automatically converted to PNG or JPEG by pamperspective; use a separate converter after checking the result. Keep the original image until the transformed file has the expected geometry and quality.