feat(#44): skip feature detection while tracking (part B)

[kalwalt]

What

Part B of #44. Guard the per-frame feature detection (extractFeatures + descriptor matching via MatchFeatures) with if (!_isTracking). Once optical flow holds a lock, detection is skipped and the pose is maintained by optical flow + template matching. When the marker is lost (_isTracking cleared in runOpticalFlow / RunTemplateMatching), detection resumes on the next frame to re-acquire.

Why

Detection is the dominant per-frame cost. Running it every frame even while a lock is held is wasteful — optical flow already produces the pose. Part A (#52) cut the cost of each detection; part B removes most detections entirely.

Measured (Teblid webcam example, 640×480): ~10–15 fps detecting every frame → ~45 fps while tracking (≈3×). Re-acquisition latency is one frame after loss.

Why !_isTracking and not the ArtoolkitX counter

ArtoolkitX gates detection on _currentlyTrackedMarkers < _maxNumberOfMarkersToTrack. That doesn't translate directly here: _isDetected is reset to false at the top of every frame, and optical flow is skipped on the very first detection frame (_frameCount == 0), so the marker is detected but not yet tracking. A counter-based guard would then see _currentlyTrackedMarkers == _max on the next frame and skip both detection and optical flow (the OF/pose gate is _isDetected || _isTracking, both false) → permanent freeze. This is guaranteed in the static-image example, which feeds the same frame repeatedly. Gating on _isTracking re-detects until optical flow actually holds a lock, then skips.

State walk-through (single marker)

Frame	_isTracking in	Detection?	Result
0 (acquire)	false	yes	match → _isDetected=true; OF skipped (_frameCount==0)
1	false	yes	match; OF runs → _isTracking=true
2…N (hold)	true	no	OF + template maintain pose (the win)
loss	true→false	—	OF/template fail → _isTracking=false, _valid=false (#46)
N+1	false	yes	detection resumes

Unchanged

Optical-flow / template / solvePnP paths (gated on _isDetected || _isTracking), #46 tracking-loss, #38 centered origin, and part A's downsampling/rescale.

Testing

• Static (1920×1440, pyrLevel 1): acquires and holds — no freeze (the case the counter-guard would break).
• Webcam (640×480): acquire → marker LOST on removal → marker FOUND on re-show; steady-state fps ~10–15 → ~45.

Full design notes: docs/design-detection-guard.md in the webarkit-testing companion PR.

🤖 Generated with Claude Code