From 544795dbf2dc2bf0ee0a3adedc88f74ce84c87d7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 5 May 2026 21:46:57 +0000
Subject: [PATCH 1/3] docs: add rectangle visualization design document

Design spec for adding OBB estimation results to the 2D Canvas demo:
- LocalTracker (Hungarian matching + ExponentialSmoother per track)
- _match_clusters_to_estimates (linear_sum_assignment, gate 6.0m)
- _obb_to_dict JSON schema (cx, cy, theta, l, w, corners)
- Updated frame snapshot schema with clusters + obb fields
- Canvas 8-layer drawing order and legend spec
- 6 test cases for OBB structure validation

https://claude.ai/code/session_013sQREGvTmjgFT8cyRNmPUL
---
 docs/design/rectangle_visualization.md | 194 +++++++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 docs/design/rectangle_visualization.md

diff --git a/docs/design/rectangle_visualization.md b/docs/design/rectangle_visualization.md
new file mode 100644
index 0000000..ce07698
--- /dev/null
+++ b/docs/design/rectangle_visualization.md
@@ -0,0 +1,194 @@
+# 矩形推定結果の可視化設計
+
+**ステータス**: 承認済み  
+**対象ブランチ**: `claude/review-repository-status-1GXDH`
+
+---
+
+## 目的
+
+`demo.html` の 2D Canvas 可視化に、GGIW 楕円に加えて **OBB（推定矩形）** と
+**クラスタ点群の色分け** を追加する。
+
+現状は `run_once()` がフィルタ更新後にクラスタ情報を捨てており、
+`fit_rectangle()` を呼ぶ手がかりがない。
+本設計はこの欠落を解消し、フレームスナップショットに矩形推定を含める。
+
+---
+
+## アーキテクチャ概要
+
+```
+ LiDAR 点群
+     │
+     ▼
+ partition(pts, eps)           ← MeasurementCell のリストを保持する
+     │
+     ├──▶ filt.update(cells)   ← 既存処理（内部で仮説更新）
+     │
+     └──▶ ests = filt.extract_estimates()
+               │
+               ▼
+         クラスタ↔推定の対応 (最近傍マッチング)
+               │
+               ▼
+         fit_rectangle(cell.points)   ← OBBResult
+               │
+               ▼
+         LocalTracker.update(obb)     ← 軽量 ID 管理 + ExponentialSmoother
+               │
+               ▼
+         フレームスナップショットに obb フィールドを追加
+```
+
+---
+
+## コンポーネント詳細
+
+### 1. クラスタ↔推定の対応 (`_match_clusters_to_estimates`)
+
+- 入力: `cells: list[MeasurementCell]`, `ests: list[GGIWState]`
+- アルゴリズム: セントロイド間のユークリッド距離で線形割り当て（`scipy.optimize.linear_sum_assignment`）
+  - コスト行列サイズ: `(len(ests), len(cells))`
+  - ゲート距離: `6.0 m`（超えた場合は None を割り当て）
+- 出力: `list[MeasurementCell | None]`（ests と同じ長さ）
+
+**最近傍マッチングを使う理由**:  
+PMBM 内部の仮説割り当て（MAP 仮説）を外部に公開すると実装が複雑になる。
+可視化用途では近似的な対応で十分。
+
+### 2. 軽量トラック ID 管理 (`LocalTracker`)
+
+PMBM はトラックに永続 ID を付与しない。
+フレーム間でスムーザ状態を継続するために、ローカルで ID を管理する。
+
+```python
+class LocalTracker:
+    """フレーム間の推定位置をハンガリアン法でマッチし、
+    ローカル ID を維持しながら ExponentialSmoother を管理する。"""
+
+    gate_dist: float = 5.0          # 同一トラックとみなす最大距離 [m]
+    smoother_alpha: float = 0.4     # ExponentialSmoother の忘却係数
+
+    _smoothers: dict[int, ExponentialSmoother]
+    _positions: dict[int, np.ndarray]  # 前フレームの推定位置
+    _next_id: int
+```
+
+**ID 割り当てルール**:
+- 前フレームの推定位置と今フレームの推定位置をハンガリアン法でマッチ
+- コスト = ユークリッド距離、ゲート距離超過はコスト∞（新規扱い）
+- マッチした推定 → 既存 smoother を継続
+- マッチしなかった推定 → 新規 smoother を生成
+
+### 3. OBB スナップショット (`_obb_to_dict`)
+
+`OBBResult` を JSON シリアライズ可能な dict に変換する。
+
+```python
+{
+    "cx":      float,          # OBB 中心 x [m]
+    "cy":      float,          # OBB 中心 y [m]
+    "theta":   float,          # 長軸の角度 [rad]  ([-π/2, π/2))
+    "l":       float,          # 長辺 [m]
+    "w":       float,          # 短辺 [m]
+    "corners": [[x,y]*4]       # 反時計回り 4 頂点
+}
+```
+
+---
+
+## JSON スキーマ変更
+
+### フレームスナップショット（追加フィールド）
+
+```jsonc
+{
+  "fi": 5,
+  "missed": false,
+  "gt":   [{"x":…, "y":…, "yaw":…, "l":…, "w":…}],
+  "obs":  [[x, y], …],
+  "clusters": [                          // NEW: クラスタ点群
+    {
+      "centroid": [x, y],
+      "points":   [[x, y], …]
+    }
+  ],
+  "est": [
+    {
+      "x":…, "y":…, "vx":…, "vy":…,
+      "ext_a":…, "ext_b":…, "ext_theta":…,
+      "obb": {                           // NEW: 推定 OBB（null の場合あり）
+        "cx":…, "cy":…,
+        "theta":…, "l":…, "w":…,
+        "corners": [[x,y],[x,y],[x,y],[x,y]]
+      }
+    }
+  ]
+}
+```
+
+**`obb` が `null` になるケース**:
+- 対応クラスタの点数が 2 未満（`fit_rectangle` に必要な最低点数）
+- 推定に対応するクラスタが見つからない（ゲート距離超過）
+
+---
+
+## Canvas 描画の変更 (`demo.html`)
+
+### 描画レイヤー順序（下から上）
+
+| 順序 | 要素 | 色 |
+|------|------|----|
+| 1 | グリッド・軸 | `#2e3347` |
+| 2 | LiDAR 観測点（obs） | 黄 `#facc15` |
+| 3 | クラスタ識別色（clusters） | 推定ごとに色を変える |
+| 4 | GT 矩形 | 緑 `#4ade80` |
+| 5 | GGIW 楕円（extent） | 赤 `#f87171`（半透明） |
+| 6 | 推定 OBB 矩形 | 橙 `#fb923c` |
+| 7 | 速度ベクトル | 橙 `#fb923c` |
+| 8 | センサ原点マーカー | 青 `#60a5fa` |
+
+### 凡例追加
+
+```
+● センサ原点   ■ GT（緑）   ○ GGIW楕円（赤）   □ 推定OBB（橙）   · 観測点（黄）
+```
+
+---
+
+## 実装対象ファイル
+
+| ファイル | 変更種別 | 概要 |
+|---------|---------|------|
+| `src/tracking/evaluation/interactive.py` | 改修 | `LocalTracker` 追加、`_match_clusters_to_estimates()` 追加、`_obb_to_dict()` 追加、`run_once()` の `record_frames=True` パスで clusters・obb を記録 |
+| `docs/demo.html` | 改修 | クラスタ点群の色分け描画、OBB 矩形描画、凡例更新 |
+| `tests/tracking/test_interactive.py` | 追加 | フレームスナップショットの `clusters`・`obb` フィールド検証 |
+
+**変更しないファイル**:
+- `src/tracking/shape/rectangle_fitting.py` — API そのまま使用
+- `src/tracking/shape/smoothing.py` — `ExponentialSmoother` そのまま使用
+- `src/tracking/pmbm/pmbm_filter.py` — フィルタ内部には触れない
+
+---
+
+## テスト仕様
+
+| テスト名 | 検証内容 |
+|---------|---------|
+| `test_frame_clusters_present` | `frame["clusters"]` が存在し、各要素が `centroid`・`points` を持つ |
+| `test_frame_est_obb_structure` | 推定に `obb` キーがある（null または dict） |
+| `test_obb_corners_are_4_points` | `obb.corners` が 4 点の 2D 座標リスト |
+| `test_obb_dimensions_positive` | `obb.l > 0` かつ `obb.w > 0` |
+| `test_obb_center_near_cluster_centroid` | OBB 中心とクラスタ重心の距離 < 3 m |
+| `test_missed_frame_obb_is_null` | miss フレームのすべての est で `obb is null` |
+
+---
+
+## 制約・既知の限界
+
+- **部分観測**: 車両の片側しか見えない場合、OBB の長辺は実際より短くなる。
+  スムーザが緩和するが、完全には解消しない。
+- **クラスタ誤対応**: 2 台シナリオで車両が接近すると、
+  セントロイド最近傍マッチが誤る可能性がある。可視化用途なので許容する。
+- **初期フレーム**: 誕生直後のトラックはスムーザの学習が浅く、OBB が不安定。

From 7cfcfd68e8844f6cc23c22b5609228d8d52358c0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 5 May 2026 21:51:36 +0000
Subject: [PATCH 2/3] feat: add OBB rectangle visualization to 2D Canvas demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements docs/design/rectangle_visualization.md:

- interactive.py:
  - LocalTracker: Hungarian-based frame-to-frame ID management with
    per-track ExponentialSmoother (gate 5.0m, alpha 0.4)
  - _match_clusters_to_estimates(): linear_sum_assignment centroid
    matching with 6.0m gate
  - _obb_to_dict(): OBBResult → JSON-serializable dict (cx, cy, theta,
    l, w, corners)
  - run_once() record_frames=True path now includes clusters and obb
    in each frame snapshot

- demo.html:
  - Cluster-colored point rendering (6-color palette, falls back to
    yellow when no cluster data)
  - drawOBB() draws fitted OBB as orange rectangle using corner coords
  - Updated legend with OBB entry

- test_interactive.py:
  - TestOBBFrameSnapshot with 6 tests covering clusters structure,
    obb key presence, 4-corner constraint, positive dimensions,
    centre proximity, and missed-frame null guarantee

https://claude.ai/code/session_013sQREGvTmjgFT8cyRNmPUL
---
 docs/demo.html                         |  61 +++++++++-
 src/tracking/evaluation/interactive.py | 157 +++++++++++++++++++++++--
 tests/tracking/test_interactive.py     |  89 ++++++++++++++
 3 files changed, 294 insertions(+), 13 deletions(-)

diff --git a/docs/demo.html b/docs/demo.html
index 77f84bd..a7daecd 100644
--- a/docs/demo.html
+++ b/docs/demo.html
@@ -101,6 +101,7 @@ <h1>EOT Simulator — 2D Visualization Demo</h1>
       <div class="legend-item"><div class="legend-rect" style="background:rgba(74,222,128,0.25);border:2px solid #4ade80;border-radius:2px"></div> GT (真値)</div>
       <div class="legend-item"><div class="legend-dot" style="background:rgba(250,204,21,0.7)"></div> LiDAR 観測点</div>
       <div class="legend-item"><div class="legend-ellipse" style="background:rgba(248,113,113,0.25);border:2px solid #f87171"></div> 推定 (GGIW extent)</div>
+      <div class="legend-item"><div class="legend-rect" style="background:rgba(251,146,60,0.2);border:2px solid #fb923c;border-radius:2px"></div> 推定 OBB</div>
       <div class="legend-item"><div style="width:14px;height:2px;background:#fb923c;display:inline-block"></div>&nbsp;速度ベクトル</div>
     </div>
 
@@ -109,6 +110,19 @@ <h1>EOT Simulator — 2D Visualization Demo</h1>
 </main>
 
 <script>
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+// Color palette for cluster point coloring — one color per cluster index
+const CLUSTER_COLORS = [
+  'rgba(250,204,21,0.85)',   // yellow
+  'rgba(96,165,250,0.85)',   // blue
+  'rgba(167,243,208,0.85)',  // mint
+  'rgba(249,168,212,0.85)',  // pink
+  'rgba(196,181,253,0.85)',  // violet
+  'rgba(253,186,116,0.85)',  // peach
+];
+
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -244,12 +258,25 @@ <h1>EOT Simulator — 2D Visualization Demo</h1>
   // Grid
   drawGrid(ctx, t, bounds, cw, ch);
 
-  // Observation points
-  for (const [ox, oy] of frame.obs) {
-    ctx.beginPath();
-    ctx.arc(t.wx(ox), t.wy(oy), 3, 0, 2 * Math.PI);
-    ctx.fillStyle = 'rgba(250,204,21,0.75)';
-    ctx.fill();
+  // Observation points (fallback when no cluster data)
+  if (!frame.clusters || frame.clusters.length === 0) {
+    for (const [ox, oy] of frame.obs) {
+      ctx.beginPath();
+      ctx.arc(t.wx(ox), t.wy(oy), 3, 0, 2 * Math.PI);
+      ctx.fillStyle = 'rgba(250,204,21,0.75)';
+      ctx.fill();
+    }
+  } else {
+    // Cluster-colored points — color cycles per cluster index
+    for (let ci = 0; ci < frame.clusters.length; ci++) {
+      const col = CLUSTER_COLORS[ci % CLUSTER_COLORS.length];
+      for (const [px, py] of frame.clusters[ci].points) {
+        ctx.beginPath();
+        ctx.arc(t.wx(px), t.wy(py), 3, 0, 2 * Math.PI);
+        ctx.fillStyle = col;
+        ctx.fill();
+      }
+    }
   }
 
   // GT rectangles
@@ -266,6 +293,13 @@ <h1>EOT Simulator — 2D Visualization Demo</h1>
   for (const e of frame.est) {
     drawEllipse(ctx, t, e.x, e.y, e.ext_a, e.ext_b, e.ext_theta,
                 'rgba(248,113,113,0.2)', '#f87171', 2);
+  }
+
+  // Estimated OBB rectangles (drawn on top of ellipses)
+  for (const e of frame.est) {
+    if (e.obb) {
+      drawOBB(ctx, t, e.obb);
+    }
     // Velocity arrow (scale: 1 s ahead)
     drawArrow(ctx, t, e.x, e.y, e.x + e.vx, e.y + e.vy, '#fb923c', 2);
     // Position dot
@@ -374,6 +408,21 @@ <h1>EOT Simulator — 2D Visualization Demo</h1>
   ctx.restore();
 }
 
+function drawOBB(ctx, t, obb) {
+  const corners = obb.corners;
+  ctx.beginPath();
+  ctx.moveTo(t.wx(corners[0][0]), t.wy(corners[0][1]));
+  for (let i = 1; i < corners.length; i++) {
+    ctx.lineTo(t.wx(corners[i][0]), t.wy(corners[i][1]));
+  }
+  ctx.closePath();
+  ctx.fillStyle = 'rgba(251,146,60,0.15)';
+  ctx.fill();
+  ctx.strokeStyle = '#fb923c';
+  ctx.lineWidth = 2;
+  ctx.stroke();
+}
+
 function drawSensor(ctx, sx, sy) {
   const r = 7;
   ctx.strokeStyle = '#60a5fa';
diff --git a/src/tracking/evaluation/interactive.py b/src/tracking/evaluation/interactive.py
index f4fcb98..9bdbb44 100644
--- a/src/tracking/evaluation/interactive.py
+++ b/src/tracking/evaluation/interactive.py
@@ -15,11 +15,15 @@
 matplotlib.use("agg")
 import matplotlib.pyplot as plt
 import numpy as np
+from scipy.optimize import linear_sum_assignment
 
 from src.simulator import LidarSimulator, VehicleSimulator
 from src.tracking.evaluation.association import associate
 from src.tracking.evaluation.metrics import gospa as gospa_metric
+from src.tracking.measurement.partition import partition
 from src.tracking.pmbm.pmbm_filter import BirthModel, PMBMFilter
+from src.tracking.shape.rectangle_fitting import OBBResult, fit_rectangle
+from src.tracking.shape.smoothing import ExponentialSmoother
 
 
 # ---------------------------------------------------------------------------
@@ -69,6 +73,121 @@ def _ggiw_to_ellipse(state) -> dict:
     }
 
 
+def _obb_to_dict(obb: OBBResult) -> dict:
+    """OBBResult → JSON シリアライズ可能な dict。"""
+    return {
+        "cx":      float(obb.center[0]),
+        "cy":      float(obb.center[1]),
+        "theta":   float(obb.theta),
+        "l":       float(obb.length),
+        "w":       float(obb.width),
+        "corners": obb.corners().tolist(),
+    }
+
+
+def _match_clusters_to_estimates(cells, ests) -> list:
+    """クラスタと推定をセントロイド距離で最近傍マッチング (ゲート 6.0 m)。
+
+    Returns:
+        ests と同じ長さのリスト。対応クラスタなしの場合は None。
+    """
+    if not ests or not cells:
+        return [None] * len(ests)
+
+    gate = 6.0
+    est_pos = np.array([s.position for s in ests])          # (n_est, 2)
+    cell_ctr = np.array([c.centroid for c in cells])         # (n_cell, 2)
+
+    # コスト行列 (n_est, n_cell)
+    diff = est_pos[:, None, :] - cell_ctr[None, :, :]        # (n_est, n_cell, 2)
+    cost = np.linalg.norm(diff, axis=2)
+
+    gated = np.where(cost < gate, cost, 1e9)
+    row_ind, col_ind = linear_sum_assignment(gated)
+
+    matched: list = [None] * len(ests)
+    for ri, ci in zip(row_ind, col_ind):
+        if cost[ri, ci] < gate:
+            matched[ri] = cells[ci]
+    return matched
+
+
+class LocalTracker:
+    """フレーム間でローカル ID と ExponentialSmoother を管理するトラッカー。
+
+    PMBM はトラックに永続 ID を付与しないため、推定位置のハンガリアン法マッチで
+    フレーム間同一性を近似し、スムーザ状態を継続する。
+    """
+
+    def __init__(self, gate_dist: float = 5.0, smoother_alpha: float = 0.4) -> None:
+        self._gate_dist = gate_dist
+        self._smoother_alpha = smoother_alpha
+        self._smoothers: dict[int, ExponentialSmoother] = {}
+        self._positions: dict[int, np.ndarray] = {}
+        self._next_id = 0
+
+    def update(self, ests: list, matched_cells: list) -> list:
+        """推定リストとマッチ済みクラスタからスムーズ OBB を計算する。
+
+        Returns:
+            ests と同じ長さのリスト (OBBResult | None)。
+        """
+        if not ests:
+            self._positions = {}
+            return []
+
+        curr_pos = np.array([s.position for s in ests])  # (n, 2)
+
+        # 前フレーム推定との Hungarian マッチング
+        est_to_id: dict[int, int] = {}
+        if self._positions:
+            prev_ids = list(self._positions.keys())
+            prev_pos = np.array([self._positions[pid] for pid in prev_ids])
+
+            n_prev, n_curr = len(prev_ids), len(ests)
+            cost = np.full((n_prev, n_curr), 1e9)
+            for i, pp in enumerate(prev_pos):
+                dists = np.linalg.norm(curr_pos - pp, axis=1)
+                mask = dists < self._gate_dist
+                cost[i, mask] = dists[mask]
+
+            row_ind, col_ind = linear_sum_assignment(cost)
+            for ri, ci in zip(row_ind, col_ind):
+                if cost[ri, ci] < self._gate_dist:
+                    est_to_id[ci] = prev_ids[ri]
+
+        # 未マッチ推定に新規 ID を割り当て
+        for j in range(len(ests)):
+            if j not in est_to_id:
+                est_to_id[j] = self._next_id
+                self._next_id += 1
+
+        # 消滅したトラックのスムーザを削除
+        active_ids = set(est_to_id.values())
+        for tid in list(self._smoothers.keys()):
+            if tid not in active_ids:
+                del self._smoothers[tid]
+
+        # OBB フィッティング + スムージング
+        result: list = []
+        new_positions: dict[int, np.ndarray] = {}
+        for j, (est, cell) in enumerate(zip(ests, matched_cells)):
+            tid = est_to_id[j]
+            new_positions[tid] = curr_pos[j]
+            if tid not in self._smoothers:
+                self._smoothers[tid] = ExponentialSmoother(alpha=self._smoother_alpha)
+
+            if cell is not None and len(cell.points) >= 2:
+                raw_obb = fit_rectangle(cell.points)
+                smoothed = self._smoothers[tid].update(raw_obb)
+                result.append(smoothed)
+            else:
+                result.append(None)
+
+        self._positions = new_positions
+        return result
+
+
 def run_once(
     sc_cfg: dict,
     filt: PMBMFilter,
@@ -98,6 +217,7 @@ def run_once(
     id_sw_vals: list[float] = []
     prev_asgn: dict[int, int] = {}
     snapshots: list[dict] | None = [] if record_frames else None
+    tracker = LocalTracker() if record_frames else None
 
     for fi in range(sc_cfg["n_frames"]):
         for v in vehicles:
@@ -132,14 +252,37 @@ def run_once(
         prev_asgn = curr_asgn
 
         if record_frames:
+            assert tracker is not None
+            # クラスタ取得 (OBB フィッティング用; フィルタ内部の partition と独立)
+            if ox:
+                pts = np.column_stack([ox, oy])
+                cells = partition(pts, eps=2.0)
+            else:
+                cells = []
+
+            matched_cells = _match_clusters_to_estimates(cells, ests)
+            obbs = tracker.update(ests, matched_cells)
+
+            clusters_data = [
+                {
+                    "centroid": c.centroid.tolist(),
+                    "points":   c.points.tolist(),
+                }
+                for c in cells
+            ]
+
             snapshots.append({
-                "fi":   fi,
-                "missed": fi in miss_frames,
-                "gt":  [{"x": float(v.x), "y": float(v.y),
-                          "yaw": float(v.yaw), "l": float(v.L), "w": float(v.W)}
-                         for v in vehicles],
-                "obs": [[float(x), float(y)] for x, y in zip(ox, oy)],
-                "est": [_ggiw_to_ellipse(s) for s in ests],
+                "fi":       fi,
+                "missed":   fi in miss_frames,
+                "gt":       [{"x": float(v.x), "y": float(v.y),
+                               "yaw": float(v.yaw), "l": float(v.L), "w": float(v.W)}
+                              for v in vehicles],
+                "obs":      [[float(x), float(y)] for x, y in zip(ox, oy)],
+                "clusters": clusters_data,
+                "est":      [
+                    {**_ggiw_to_ellipse(s), "obb": _obb_to_dict(o) if o is not None else None}
+                    for s, o in zip(ests, obbs)
+                ],
             })
 
     return {
diff --git a/tests/tracking/test_interactive.py b/tests/tracking/test_interactive.py
index b324575..f0335bb 100644
--- a/tests/tracking/test_interactive.py
+++ b/tests/tracking/test_interactive.py
@@ -243,3 +243,92 @@ def test_run_once_record_frames_true_returns_list(self):
         r = run_once(cfg, _make_filter(), seed=0, record_frames=True)
         assert isinstance(r["snapshots"], list)
         assert len(r["snapshots"]) == cfg["n_frames"]
+
+
+# ---------------------------------------------------------------------------
+# OBB / cluster frame snapshot tests (design: rectangle_visualization.md)
+# ---------------------------------------------------------------------------
+
+def _frames_with_obb() -> list[dict]:
+    """Run single_approach for 8 frames with record_frames=True; return snapshots."""
+    cfg = dict(SCENARIOS["single_approach"])
+    cfg["n_frames"] = 8
+    r = run_once(cfg, _make_filter(), seed=0, record_frames=True)
+    return r["snapshots"]
+
+
+class TestOBBFrameSnapshot:
+    def test_frame_clusters_present(self):
+        """Every frame snapshot has 'clusters'; non-missed frames with obs have entries."""
+        frames = _frames_with_obb()
+        for frame in frames:
+            assert "clusters" in frame
+            for cl in frame["clusters"]:
+                assert "centroid" in cl
+                assert "points" in cl
+                assert len(cl["centroid"]) == 2
+                assert len(cl["points"]) > 0
+
+    def test_frame_est_obb_structure(self):
+        """Every estimate in every frame has an 'obb' key (None or dict)."""
+        frames = _frames_with_obb()
+        for frame in frames:
+            for e in frame["est"]:
+                assert "obb" in e
+                # obb is either None or a dict with the required keys
+                if e["obb"] is not None:
+                    assert {"cx", "cy", "theta", "l", "w", "corners"} <= e["obb"].keys()
+
+    def test_obb_corners_are_4_points(self):
+        """When obb is not None, corners contains exactly 4 2-D points."""
+        frames = _frames_with_obb()
+        found = False
+        for frame in frames:
+            for e in frame["est"]:
+                if e["obb"] is not None:
+                    corners = e["obb"]["corners"]
+                    assert len(corners) == 4
+                    for pt in corners:
+                        assert len(pt) == 2
+                        assert all(np.isfinite(v) for v in pt)
+                    found = True
+        assert found, "No frame had a non-None OBB — increase n_frames or check filter"
+
+    def test_obb_dimensions_positive(self):
+        """OBB length and width must both be positive."""
+        frames = _frames_with_obb()
+        for frame in frames:
+            for e in frame["est"]:
+                if e["obb"] is not None:
+                    assert e["obb"]["l"] > 0
+                    assert e["obb"]["w"] > 0
+
+    def test_obb_center_near_cluster_centroid(self):
+        """OBB centre must be within 3 m of the matched cluster centroid."""
+        frames = _frames_with_obb()
+        for frame in frames:
+            for e in frame["est"]:
+                if e["obb"] is None:
+                    continue
+                cx, cy = e["obb"]["cx"], e["obb"]["cy"]
+                # Find closest cluster centroid
+                if not frame["clusters"]:
+                    continue
+                min_dist = min(
+                    math.hypot(cx - cl["centroid"][0], cy - cl["centroid"][1])
+                    for cl in frame["clusters"]
+                )
+                assert min_dist < 3.0, f"OBB centre too far from any cluster: {min_dist:.2f} m"
+
+    def test_missed_frame_obb_is_null(self):
+        """In missed frames all estimates must have obb=None."""
+        cfg = dict(SCENARIOS["missed_recovery"])
+        cfg["n_frames"] = 15
+        r = run_once(cfg, _make_filter(), seed=0, record_frames=True)
+        miss_set = set(SCENARIOS["missed_recovery"]["miss_frames"])
+        for frame in r["snapshots"]:
+            if frame["fi"] in miss_set:
+                for e in frame["est"]:
+                    assert e["obb"] is None, (
+                        f"frame {frame['fi']}: expected obb=null, got {e['obb']}"
+                    )

From de517b0caff42d56e5b3eb3c7177e57d93727556 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 6 May 2026 04:26:00 +0000
Subject: [PATCH 3/3] ci: generate demo frame data in Pages build

generate_demo.py was not called in the CI pipeline, so demo.html had
no docs/data/demo_*.json to fetch. Add a build step that runs
generate_demo.py --all before uploading the Pages artifact.

https://claude.ai/code/session_013sQREGvTmjgFT8cyRNmPUL
---
 .github/workflows/pages.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 7e02215..85027c0 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -48,6 +48,10 @@ jobs:
       - name: Generate reports (tests + evaluation)
         run: uv run python scripts/generate_report.py --n-mc 30
 
+      # --- Generate demo frame data for demo.html ---
+      - name: Generate demo frame data
+        run: uv run python scripts/generate_demo.py --all --n-mc 5
+
       # --- Upload artifact for deployment ---
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3