Rubber-sheet a Netpbm image with pamrubber control points

You will finish with a transformed Netpbm image whose pixels have been moved towards new control points, plus a repeatable command you can inspect or adapt. The examples use pamrubber from Netpbm 2:11.05.02-1.1build1, installed on this machine.

Allow about fifteen minutes. You need a readable PAM, PGM or another Netpbm image, enough knowledge of its width and height to choose points, and a writable working directory. The command does not edit its input. It writes the transformed image to standard output, so the shell redirection is part of every useful example.

1. Check the installed command

First confirm which executable will run and read the local manual. This is an ordinary, read-only check and does not need elevated privileges:

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

The command needs exactly one of -tri or -quad. It accepts control-point coordinates, followed by an optional input filename. If you omit the filename, it reads the image from standard input.

2. Understand the two coordinate lists

pamrubber takes one list of source points and one list of target points. Each point is an x y pair, and both lists must contain the same number of points. Coordinates refer to the input and output image respectively. The output keeps the input image's dimensions and format.

For example, the following four source points are the corners of a 4 by 4 image, in perimeter order. The target list pulls the top-right corner inwards:

source: 0 0   3 0   3 3   0 3
target: 0 0   2 0   3 3   0 3

There is no separate output-width or output-height option. With one point, pamrubber fills in the remaining geometry differently for each mode. With two points it uses those as opposite corners in quadrilateral mode. With three points it constructs a fourth point to make a parallelogram in that mode. These defaults are convenient for simple pulls, but explicit points are easier to review in a script.

3. Run a small triangle-mode transform

Triangle mode divides the image into corresponding triangular regions. This one-point example asks pamrubber to map the source point (0, 0) to target point (1, 1):

$ pamrubber -tri -randomseed=7 0 0 1 1 input.pam > output-tri.pam
$ pamfile output-tri.pam
output-tri.pam: PGM raw, 4 by 4  maxval 255

Replace input.pam with your file. The sample output line is from a small PGM input, so your format, dimensions and maxval may differ. The useful checks are a zero exit status, a non-empty destination, and a recognised Netpbm header.

-tri and -randomseed=7 are ordinary user commands. You do not need sudo. Keep the original input until you have inspected the result.

4. Use quadrilateral mode for four corners

Use -quad when your source and target are quadrilaterals, such as an image of a document whose corners need mapping. Put all source coordinates first, then all target coordinates:

$ pamrubber -quad -linear -randomseed=7 \
    0 0 3 0 3 3 0 3 \
    0 0 2 0 3 3 0 3 \
    input.pam > output-quad.pam
$ pamfile output-quad.pam
output-quad.pam: PGM raw, 4 by 4  maxval 255

The four points should describe the corners in matching perimeter order. Crossing the order can produce an invalid or surprising quadrilateral. Scale the example coordinates to your image: for an image WIDTH by HEIGHT, the last corner is normally WIDTH-1 HEIGHT-1, not WIDTH HEIGHT.

-linear selects bilinear interpolation of four source pixels. Without it, pamrubber uses nearest-neighbour interpolation. Bilinear interpolation usually makes geometric transformations look less blocky, while nearest-neighbour can be preferable when exact source values must be preserved.

5. Make runs reproducible

pamrubber randomises part of its output. By default it seeds the random number generator from the time of day, so two runs can differ even when the input and points are unchanged. Set -randomseed=N when you need a repeatable result:

$ pamrubber -tri -randomseed=7 0 0 1 1 input.pam > run-a.pam
$ pamrubber -tri -randomseed=7 0 0 1 1 input.pam > run-b.pam
$ cmp -- run-a.pam run-b.pam
$ echo $?
0

A zero status from cmp means the two files are byte-for-byte identical on this installation. Record the seed alongside the command if the output is an input to a test, build or review. Older Netpbm releases called this option -randseed; the installed manual documents -randomseed and says the old spelling remains accepted.

6. Add a diagnostic frame when checking geometry

-frame overlays the target image with the edges of the quadrilaterals or triangles used for the transformation. It is useful for checking point order, but the overlay changes the pixels, so do not use it for the final image:

$ pamrubber -quad -frame -randomseed=7 \
    0 0 3 0 3 3 0 3  0 0 3 0 3 3 0 3 \
    input.pam > frame-check.pam
$ pamfile frame-check.pam
frame-check.pam: PGM raw, 4 by 4  maxval 255

To get the same overlay on the source geometry, use identical source and target control points. Inspect the frame-check image with your normal image viewer, then rerun without -frame for the deliverable.

7. Protect an existing output

Shell redirection truncates its destination before pamrubber starts. Do not redirect straight over a valuable image. Write a temporary sibling, verify it, then replace the old file only when you are satisfied:

$ pamrubber -tri -randomseed=7 0 0 1 1 input.pam > output.pam.new
$ test -s output.pam.new
$ pamfile output.pam.new
$ mv -- output.pam.new output.pam

The final mv is the state-changing step and may replace output.pam. Make a backup first if the old file matters:

$ cp --preserve=all -- output.pam output.pam.bak

If pamrubber fails, do not move the incomplete file into place. Remove only the known temporary path after checking it, or leave it for diagnosis. To undo a completed replacement, restore the backup with mv -- output.pam.bak output.pam. Do not delete the backup until the new image has been checked.

8. Diagnose the common failures

If pamrubber says that you must specify -tri or -quad, add exactly one mode option. If it complains about control points, count the coordinates: every point needs two numbers, and the source and target lists need equal counts. In quad mode, check that the four points make corners in the same order rather than crossing lines.

A non-zero status from pamfile, an empty output or a corrupt-looking image means the transform is not verified. Check the input without changing it:

$ test -r input.pam && echo readable
$ pamfile input.pam
input.pam: PGM raw, 4 by 4  maxval 255

Remember that a successful exit status only says pamrubber completed its operation. It does not prove that your chosen points describe the intended geometry. Verify dimensions and inspect the image before distributing it.