examples/sample_orb: fix coordinate un-scaling and outline width defects in training code

[kalwalt]

Note

Update (2026-08-24): The overshoot on the right side was confirmed to be caused by a bad printed target image (shrunk/squished aspect ratio, e.g., via A4 "Fit to Page" print settings), which is the same problem documented in webarkit/WebARKitLib-rs#240. Testing with the original "pinball" image displayed directly on a smartphone screen (at a 1:1 pixel aspect ratio) worked perfectly as expected. Thus, the overshoot is not caused by a "homography estimation error" or a code bug in jsfeatNext. The suggested changes in #134 (GMS) are not required to address this overshoot, though they may still improve overall tracking quality.

Summary

In examples/sample_orb_pinball.html the green quad drawn over the tracked marker follows the left, top and bottom edges of the physical target closely, but overshoots on the right. Reported from visual inspection, estimated at "up to ~10%, possibly less" — this is an eyeball figure, not a measurement.

Investigating it turned up two real defects in the example's training code. Both are genuine and worth fixing, but together they account for well under 1%, so they do not explain the observed overshoot. Filing everything found so the next person does not have to re-derive it.

Defect 1 — the outline is drawn one pixel narrower than the pattern frame

render_pattern_shape reconstructs the pattern size from the preview:

var shape_pts = tCorners(homo3x3.data, pattern_preview.cols * 2, pattern_preview.rows * 2);

and the preview is built by halving with >>:

pattern_preview = new jsfeat.matrix_t(new_width >> 1, new_height >> 1, ...);

For img/pinball.jpg (1637 × 2048):

step	value
sc0 = min(512/1637, 512/2048)	0.25
new_width, new_height	409, 512
pattern_preview	204 × 256
outline drawn at	408 × 512

409 >> 1 = 204, and 204 * 2 = 408. The homography's coordinate frame is lev0_img, which is 409 wide, so the right edge is drawn 1 px short — about 0.25%, and in the opposite direction to the reported overshoot.

The round-trip only survives even dimensions. Drawing from lev0_img.cols/rows (or storing the trained size explicitly) removes the issue entirely.

Defect 2 — level coordinates are un-scaled by the requested scale, not the achieved one

In the per-level loop the image is resized with a truncated target:

new_width  = (lev0_img.cols * sc) | 0;
new_height = (lev0_img.rows * sc) | 0;
imgproc.resample(lev0_img, lev_img, new_width, new_height);

but the detected keypoints are mapped back with the requested scale:

lev_corners[i].x *= 1. / sc;
lev_corners[i].y *= 1. / sc;

The achieved scale is new_width / lev0_img.cols, which after | 0 is not sc. Measured for this pattern (409 × 512, sc_inc = sqrt(2), 4 levels):

lev	requested sc	resized to	effective x	effective y	x error	y error
1	0.70711	289 × 362	0.70660	0.70703	+0.072%	+0.011%
2	0.50000	204 × 255	0.49878	0.49805	+0.245%	+0.392%
3	0.35355	144 × 181	0.35208	0.35352	+0.419%	+0.011%

Two things worth noting:

• The error is axis-asymmetric and non-monotonic, because it depends on how each dimension happens to truncate. 512 is a power of two and usually truncates cleanly; 409 is odd and does not.
• At level 2 the height loses a whole pixel: sc is accumulated as sc /= sc_inc, so after two divisions by sqrt(2) it holds 0.4999999999999999, not 0.5. (512 * 0.4999999999999999) | 0 is 255, not 256. Recomputing sc as Math.pow(sc_inc, -lev) — or deriving the un-scale factor from lev_img.cols / lev0_img.cols — avoids this.

These feed slightly wrong keypoint coordinates into the homography fit, so they degrade the estimate rather than shifting the outline directly.

What is probably causing the visible overshoot

Neither defect above reaches 1%, so the observed error is most likely homography estimation error, not a drawing bug.

In the reported session the ORB matches are heavily concentrated on the left and centre of the target — the bright, high-contrast pinball artwork — while the right portion is darker and more foreshortened, contributing very few correspondences. A homography fitted from correspondences clustered on one side extrapolates least accurately on the opposite side, which is exactly where the error appears.

Attempted diagnostic: hold the target flat and fronto-parallel and see whether the overshoot changes. Result inconclusive — no obvious change was observed, but holding a hand-held print flat enough for this to be decisive is difficult, so this neither confirms nor rules out the hypothesis.

If this is the cause, the effective fix is not in this example: it is #134 (GMS), which filters geometrically inconsistent matches before find_homography and directly targets a poor inlier distribution. That is the natural time to revisit this.

Suggested scope

• Draw the outline from the trained pattern dimensions rather than pattern_preview.cols * 2
• Un-scale level coordinates by the achieved scale (lev_img.cols / lev0_img.cols) instead of the requested sc
• Compute sc per level as a power rather than by repeated division, to stop float drift crossing an integer boundary
• Re-assess the residual overshoot once feat(gms): grid-based motion statistics match filter #134 lands, before assuming anything further is wrong here (Update: confirmed to be a printed aspect ratio issue, see update note at the top)

Notes

• Not a regression from warp_affine extrapolates just outside the top-left edge instead of using fill_value #119: the behaviour predates it, and the reporter confirmed no visible change in tracking quality after that fix.
• examples/sample_orb.html shares the same training code and is presumably affected identically.
• Low priority. Nothing here blocks the library itself — the defects are in example code, and the dominant term is most likely estimation quality rather than a bug.

[kalwalt]

An update on the tracking overshoot on the right edge:

This issue has the same root cause as the one identified and documented in webarkit/WebARKitLib-rs#240.

The overshoot is caused by the test target having been printed with a shrunk/squished aspect ratio (e.g., A4 "Fit to Page" print driver squishing), which shifts the physical image borders relative to the template homography. Testing the tracker with the reference "pinball" image displayed directly on a smartphone screen (at a 1:1 pixel aspect ratio) worked perfectly as expected.

Therefore, the discrepancy is not caused by a "homography estimation error" or a code bug in jsfeatNext. The suggested changes in #134 (GMS) are not required to fix this, though they may still improve the general tracking quality of the WebAR experience.

[kalwalt]

The issue title has been updated to focus on the minor training code bugs (Defect 1 and Defect 2) since the overshoot is confirmed to be an aspect ratio issue with the printed target image. We will keep this issue open to track and address these remaining defects in the example code.