tatmapper-app

Planar calibration protocol

Recommended user procedure

1. Put a U.S. quarter flat and fully visible in the placement plane.
2. Keep the camera as square to that plane as practical.
3. Capture or import the photo without resizing it outside TatMapper.
4. Choose U.S. Quarter — Recommended and align the four rim handles.
5. Confirm the observed size and review the camera-angle warnings.
6. Review physical design dimensions before export.

When four-corner planar perspective correction is needed, use the Placement Card backup:

1. Generate the profile-independent TM-CAL-1 Placement Card.
2. Print at Actual Size, disable Fit to Page, and physically measure it.
3. Put the card in the placement plane and capture/import the photo.
4. Place four handles on its inner-square corners.
5. Confirm its width/height and review the rectified working image.

The target method uses a projective homography to map the observed quadrilateral to the target’s known metric rectangle. See PRINTED_TARGET_PERSPECTIVE_MODEL.md.

The manual known-length fallback remains:

pixelDistance = distance(pointA, pointB)
pxPerMm = pixelDistance / knownDistanceMm
physicalLengthMm = imagePixelLength / pxPerMm

Software validation

• known distance must be positive and finite;
• endpoints must be at least 12 source-image pixels apart;
• a reference shorter than 12% of the image’s shorter side produces a precision warning;
• no invented scientific “confidence score” is shown;
• source is labelled by the actual selected method;
• calibration and all downstream geometry use the normalized source image.

Limitations

Four-corner target calibration corrects perspective for one plane. Lens distortion, reference thickness/damage, curvature, and off-plane artwork still change the real scale. The final printed rulers are required checks, not decoration.

See CALIBRATION_METHODS.md, COIN_CALIBRATION.md, and PLACEMENT_CARD.md.

Ground-truth fixture for QA

Use a flat, matte board with a traceable 100 mm reference, photograph it from a repeatable mount, calibrate at 100 mm, export a 100 mm software fixture, and measure the printed result with a reliable metric ruler or caliper. Record printer, paper, driver, scale setting, measured length, absolute error, and percentage error.