6a703c314d
Incomplete: step 1 (fixture markers + track_truth.json), step 6 (frontend wiring), step 8 (tests) not done; suite not yet run. Salvaged from interrupted prior session. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
73 lines
3.9 KiB
Python
73 lines
3.9 KiB
Python
"""Track solving (spec M20, lane H) — STUB with the frozen contract in the docstring.
|
|
|
|
foundation3 ships the stub; lane H fills :func:`run_solve` (and adds
|
|
``backend/tests/test_tracker_solve.py``). This is pure orchestration over the FROZEN
|
|
geometry primitives — it must NEVER inline pose math (read ``resolve.py`` first; it is the
|
|
exact per-timestep pattern), and it writes through the ``db`` track helpers only.
|
|
|
|
================================================================================
|
|
FROZEN CONTRACTS (plan/30-phase6.md — copy, do not reinterpret)
|
|
================================================================================
|
|
|
|
Input — ``config.DETECTIONS_JSON`` (contract #3, written by ``tracker_detect.run_detect``)::
|
|
|
|
{"videos": {"<video_id>": [{"t_video_s", "marker_key", "cx", "cy", "area", "conf"}]},
|
|
"generated_by": "festival4d.tracker_detect"}
|
|
|
|
``cx``/``cy`` are normalized 0..1; multiply by the video's width/height for pixel coords.
|
|
|
|
Output — the ``tracks`` / ``track_points`` tables (contract #2), via ``db`` helpers::
|
|
|
|
tracks(id, marker_key, label, color, created_at)
|
|
track_points(id, track_id, t_global_s, x, y, z, quality, views) # ordered by t_global_s
|
|
# coordinates in Three.js scene space; views = cameras used (1 ⇒ ground-plane fallback)
|
|
|
|
Algorithm (spec M20 — the parts that bite):
|
|
1. Load detections; group by ``marker_key``.
|
|
2. **Time alignment is the whole game** (pitfall #1): a detection is found at ``t_video``;
|
|
association happens at ``t_global``. Convert with the FROZEN
|
|
``config.t_global_from_video(t_video, offset_ms, drift_ppm)`` ONLY — never re-derive it.
|
|
3. Per time bucket (**≈0.25 s** of ``t_global``), collect same-``marker_key`` detections
|
|
across cameras at matching ``t_global``:
|
|
- **2+ views → triangulate** through ``geometry`` primitives exactly as ``resolve.py``
|
|
does (``geometry.ray_from_pixel`` per view + ``geometry.triangulate_rays``, or a
|
|
multi-ray least squares built on them). Record ``views`` and a ``quality`` derived
|
|
from the residual/gap.
|
|
- **1 view → ray ∩ ground plane** (contract #5): the synthetic ground is ``y = 0``;
|
|
real projects estimate the 5th-percentile-y horizontal plane of the point cloud and
|
|
record it in the result dict. Such points get ``views = 1`` and ``quality ≤ 0.5``.
|
|
4. Smooth each track (moving average or Catmull-Rom — your call; **document which**).
|
|
5. Solid color for hue markers, palette color for code markers.
|
|
6. Write via ``db.add_track`` + ``db.set_track_points``. **Re-solve replaces that marker's
|
|
track** (idempotent — never stack duplicates on repeated runs).
|
|
7. Degradation: no detections → zero tracks + a note; never crash.
|
|
|
|
``POST /api/tracks/solve`` and ``python -m festival4d track`` both run detect→solve
|
|
end-to-end once this and ``tracker_detect`` are filled.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
|
|
log = logging.getLogger("festival4d.tracker_solve")
|
|
|
|
# Poses are keyed every ~0.5 s; bucket association at 0.25 s (spec M20). Kept here so lane H
|
|
# and any test reference one number.
|
|
BUCKET_S: float = 0.25
|
|
GROUND_PLANE_Y: float = 0.0 # synthetic fixture ground (contract #5, scene space)
|
|
SINGLE_VIEW_MAX_QUALITY: float = 0.5 # ground-plane fallback quality cap (contract #5)
|
|
|
|
|
|
def run_solve() -> dict:
|
|
"""Solve detections into 3D friend tracks (spec M20, see module docstring).
|
|
|
|
Lane H implements the full detect-output → ``tracks``/``track_points`` pipeline described
|
|
above. Returns a summary dict (tracks written, per-track point counts + coverage, the
|
|
ground-plane used, and any degradation note). Idempotent: re-running replaces each
|
|
marker's track rather than stacking duplicates.
|
|
"""
|
|
raise NotImplementedError(
|
|
"track solving not implemented yet (lane H / M20) — fill tracker_solve.run_solve"
|
|
)
|