CHANGELOG — libstereo_bolt delivery package
============================================

## 2026-07-02  v5 — flat-top endpoint + 0703 OBB model

Rebuilt on RK3588 from source eb96ff4 (branch qc/axis-dir-consensus).
C ABI unchanged (same 9 exported symbols) — no consumer recompile needed,
only replace lib/ + weights/ + config/.

Changes vs v4:
- Model: best_obb_1024_0703_20260702.rknn (0703 annotated finetune; far/oblique
  recall recovered — 0702 far scene 0-detect frames 131/167 -> ~0).
- config.rk3588.12mp.yaml: model_path -> 0703 rknn, imgsz 1024, task obb,
  measurement.top_morphology: "flat_top" (ellipse-center tip + tight foot band
  for black flat-top studs), 0621 calib (stereo_calib_20260621_202857).
- Ranging: physical-length consensus pairing repair + graded confidence.
  Board-verified on 0702 12MP: 8/8 bolts, status=ok, per-bolt 1.5-2.2m coherent.
- Board timing (12MP single frame, steady state): ~450-475ms total
  (yolo ~180ms, cmatch ~115ms, rectify ~90ms, measure+so+qc ~65ms, plane
  skipped in height_from_plane:false).
- NOTE: flat-top height ACCURACY still under validation (single-angle 10-frame
  board test median 150.6mm vs 160 nominal; needs multi-angle aggregation +
  on-site caliper zero-point before precision sign-off). Ranging + timing are
  production-ready; precise height functional but accuracy-pending.

## 2026-07-01  v4 — precise partial-output contract fix

Current delivery contents:
- Model: best_obb_1024.rknn (OBB, imgsz 1024, RKNN)
- Precise measurement and ranging share the same OBB model.
- Runtime libraries are bundled in lib/: libstereo_bolt.so, OpenCV 4.5.0, librknnrt.so.
- No target-board apt install is required for runtime OpenCV.

Behavior change:
- Precise measurement no longer exports left-only fallback heights as product
  results. If a bolt is detected in the left image but has no right detection
  / right ROI (`idx_R < 0`), it stays in the failure diagnostics only.
- `data.bolts[]` now contains only complete right-paired bolts that measured
  cleanly. This avoids misleading fake heights when the right YOLO detector
  misses part of the expected bolt set.
- C ABI is unchanged: function signatures and struct layouts are unchanged.

Performance / validation:
- RK3588, precision_153313_954, 7 full-resolution frames, expected=4:
  every frame correctly returns `success=0`, `reason=count_mismatch`,
  `L=4`, `R=2`, `pairs=4`, `data.n_bolts=2`. The two missing-right bolts are
  not exported as heights.
- RK3588, distance_153304_403, 21 binned frames:
  found=21/21, distance mean=1652.360 mm, min=1652.091, max=1652.582,
  elapsed mean=156.493 ms.
- Windows ctest: 23/23 pass, including the right-eye-missing fallback guard.

## 2026-07-01  v3 — stable OBB-axis ranging summary

Current delivery contents:
- Model: best_obb_1024.rknn (OBB, imgsz 1024, RKNN)
- Precise measurement and ranging share the same OBB model.
- Runtime libraries are bundled in lib/: libstereo_bolt.so, OpenCV 4.5.0, librknnrt.so.
- No target-board apt install is required for runtime OpenCV.

Algorithm:
- Ranging now uses left/right OBB-axis pairing before the NCC fallback.
- Even-count OBB candidates no longer average two different pair hypotheses.
  The summary distance chooses the center candidate with the more stable sampled
  axis disparity, removing the RK3588 1498/1652 mm jump.

Performance / validation:
- RK3588, distance_153304_403, 21 binned frames:
  found=21/21, distance mean=1652.360 mm, min=1652.091, max=1652.582,
  std=0.149 mm, elapsed mean=153.146 ms.
- Windows ctest: 22/22 pass.

## 2026-06-30  v2 — OBB model + plane skip optimization

Changes vs previous delivery (2026-06-24, v1):

### Model
- Previous package used an HBB detector at imgsz 960.
- Current package uses best_obb_1024.rknn (OBB, imgsz 1024, YOLOv8 oriented bbox).
- OBB model trained on mixed 5MP + 12MP data (2026-06-29)
- Auto-detection: library detects OBB vs HBB from RKNN output shape

### Config
- yolo.task: "auto" (auto-detect OBB/HBB from model output)
- yolo.imgsz: 960 -> 1024
- yolo.conf: 0.5 (unchanged)
- measurement.height_from_plane: false (height = top-to-foot along axis)
- working_distance.z_min_mm: 1200 -> 900
- working_distance.z_max_mm: 2800 -> 4000
- ranging.z_min_mm: 1300 -> 900
- ranging.z_max_mm: 3600 -> 4000

### Algorithm
- Plane computation skipped when height_from_plane=false
  (saves 300-550ms per frame on 8-bolt scenes)
- OBB auto-detection in RKNN backend
- OBB centerline rescue + peer height consensus clamp

### Calibration
- Unchanged: stereo_calib_20260621_202857_ascii.xml (baseline 482mm)

### C API
- ABI unchanged: c_api.h has zero changes
- All function signatures identical
- Struct layouts identical
- Drop-in .so replacement, no recompile needed for downstream

### Performance (RK3588 board, 8-bolt scene, height_from_plane=false)
- Precise: ~400ms/frame (was ~800ms with plane enabled)
- Ranging: superseded by v3 benchmark above

### Verified on
- RK3588 board (linaro): 0621 dataset 21 frames, 12/21 success
- 0627 dataset 10 frames: 10/10 success
- 0628 dataset 10 frames: 10/10 success
- Windows ctest at the time: 20/20 pass