Fix AR pose/localization on >640x480 frames: keypoint scale bug, projection X-sign, marker handedness

[kalwalt]

Summary

Fixes AR pose/localization for the OCVT planar tracker on frames larger than featureImageMinSize (640x480) — the case exercised by the webarkit-testing static-image Teblid example at 2000x1500. What presented as a single "mirror" was three orthogonal bugs, headlined by a feature-detection scale bug that masked the others:

1. Keypoint scale-factor double-application — root cause (Feature keypoints double-scaled for frames larger than featureImageMinSize (marker mis-localized at ~2x position) #43)
2. Projection X-focal sign (Asymmetric -2*f_x/screenWidth in cameraProjectionMatrix — origin of X-mirror unclear #35)
3. Marker-frame handedness (Restore CV->GL column negation in updateTrackable (D*R*D) to fix 3D pose orientation #42)

Plus a behavior-preserving refactor removing the now-dead scale machinery (#44).

Details

1. Scale-factor double-application (WebARKitTracker.cpp) — Fixes #43

Detection runs on the full-resolution frame (the pyrDown block in resetTracking() is disabled), but MatchFeatures still multiplied matched keypoints by _featureDetectScaleFactor (derived from the pyramid level):

Frame	pyrLevel	factor	effect
640x480 (webcam)	0	1.0	OK — why it stayed hidden
2000x1500	1	2.0	every keypoint doubled

Doubled keypoints → marker localized at ~2x position → exploded homography → wrong solvePnP translation. Evidence: matched centroid ref(1034,908) → frame(1816,1250) = exactly 2×(908,625). Fix: force the factor to identity while detection is full-res.

2. Projection X-focal sign (WebARKitGL.cpp) — Refs #35

cameraProjectionMatrix used -2*f_x/w, mirroring screen-X. The modelview already applies the CV→GL Y,Z row negation (arglCameraViewRHf), so the projection must be plain pinhole with both focals positive (+2*f_x/w). Verified by projecting the tracked origin to NDC. gtests updated ([0] → +1.7851850084276433).

3. Marker handedness — DRD (WebARKitPattern.cpp) — Refs #42

Negate the Y,Z rotation columns of trans (matching ArtoolkitX ARTrackable2d::updateWithTwoDResults). With the downstream row negation this yields D*R*D — a right-handed frame (X=right, Y=up, Z=toward viewer). The translation column is untouched, so position is unchanged.

4. Refactor (WebARKitTracker.cpp) — Refs #44

Remove the dead _featureDetectPyrLevel/_featureDetectScaleFactor members, the commented pyrDown/detection-guard block, and the no-op rescales. Restoring downsampled detection + the guard for performance is tracked in #44.

Risk / behavior

• Feature keypoints double-scaled for frames larger than featureImageMinSize (marker mis-localized at ~2x position) #43 corrects localization for >640x480 frames (was broken); 640x480 webcams unaffected (factor was already 1.0).
• Restore CV->GL column negation in updateTrackable (D*R*D) to fix 3D pose orientation #42 changes orientation only — position provably unchanged (translation column never negated).
• The refactor is behavior-preserving (removed code was ×1/÷1 or commented).

Testing

• gtests updated for the projection sign.
• Verified end-to-end via the static-image Teblid example (2000x1500): marker correctly localized, cube/axes anchored on the marker, right-handed (red→right, green→up, blue→toward viewer).

Review checklist

• 640x480 live-camera tracking unaffected (factor was 1.0 there)
• No other consumer relied on the negative-X projection
• createFeatureMask bbox now used directly (see Restore downsampled feature detection + single-marker detection guard for performance (reconcile with ArtoolkitX OCVT) #44 caveat if downsampling is restored)

Companion example/build PR: webarkit/webarkit-testing (linked below).

🤖 Generated with Claude Code

[kalwalt]

Companion example + build PR: webarkit/webarkit-testing#35