Sync Space project with latest bat_tracker upstream

.gitignore

@@ -38,10 +38,5 @@ hf_downloads/
 # Keep project docs/configs tracked even with png ignored
 !README.md
 !config*.yaml
-!src_assets/*.png
 
 deliverables/
-src_assets/*.png
-
-deliverables/
-src_assets/*.png

README.md

@@ -13,8 +13,12 @@ pinned: false
 Proyecto Python para Linux orientado a CPU (con opcion CUDA cuando esta disponible) que procesa videos IR monocromos de cueva y genera:
 
 - `background.png`: fondo por mediana temporal
-- `valid_region/`: mascara vertical de zona valida por iluminacion horizontal
+- `valid_region/`: mascara vertical de zona valida estimada por perfil de iluminacion o profundidad
 - `tracks.csv`: trayectorias 2D por objeto
+- `track_candidates.csv`: evaluacion de todos los tracks candidatos con score y motivos de rechazo
+- `events.csv`: resumen por track con direccion, duracion, desplazamiento y estadisticas
+- `tracks.svg`: artefacto vectorial autocontenido con las trayectorias 2D en coordenadas originales
+- `tracks_render.json`: geometria normalizada por track para consumo externo
 - `tracks_overlay.png`: trayectorias sobre el fondo
 - `meta.json`: parametros y metricas de ejecucion
 
@@ -45,13 +49,13 @@ O sin `--config` para usar defaults.
 Tambien puede ejecutarse sin instalar entrypoint:
 
 ```bash
-python -m bat_tracker.cli --input /path/video.mp4 --output /path/out_dir --config /path/config.yaml
+python -m bat_tracker --input /path/video.mp4 --output /path/out_dir --config /path/config.yaml
 ```
 
 Generacion standalone de mascara vertical valida:
 
 ```bash
-python -m bat_tracker.valid_region \
+bat-valid-region \
   --input /path/out_dir/background.png \
   --output /path/out_dir/valid_region \
   --blur-kernel-size 151 \
@@ -59,17 +63,18 @@ python -m bat_tracker.valid_region \
   --safety-margin 10
 ```
 
-## Ejemplo de Resultados
+Alternativamente:
+
+```bash
+python -m bat_tracker.valid_region --input /path/out_dir/background.png --output /path/out_dir/valid_region
+```
 
-Aquí se muestran visualizaciones de las salidas generadas:
+## Ejemplo de Resultados
 
-**1. Máscara de Zona Válida (Método Híbrido):**
-*Filtra los laterales oscuros combinando profundidad en el centro y perfil de iluminación, reteniendo la zona útil.*
-![Valid Region](src_assets/valid_region_overlay.png)
+El pipeline genera visualizaciones de depuración y tracking como:
 
-**2. Tracking Final:**
-*Trayectorias 2D superpuestas sobre el fondo calculado.*
-![Tracks Overlay](src_assets/tracks_overlay.png)
+- `valid_region/overlay.png`: máscara de zona válida superpuesta sobre el fondo.
+- `tracks_overlay.png`: trayectorias 2D sobre el fondo calculado.
 
 ## Entradas
 
@@ -81,7 +86,6 @@ Ejemplos de configuracion incluidos:
 
 - `config.yaml.example` (base)
 - `config.out3_clean.yaml` (perfil limpio para escenas tipo out3 con menos ruido)
-- `config.universal.yaml` (perfil general para escenas variadas)
 
 ## Salidas
 
@@ -90,12 +94,20 @@ Se escriben en la carpeta indicada por `--output`:
 - `background.png`: fondo estimado por mediana temporal.
 - `valid_region/mask.png`: mascara binaria vertical (255 zona valida, 0 laterales invalidos).
 - `valid_region/overlay.png`: debug visual de banda valida sobre la imagen.
+- `valid_region/gate_overlay.png`: debug visual del gate real usado en tracking tras aplicar `valid_region_gate_dilate_px`.
 - `valid_region/profile.png`: debug de region valida (perfil horizontal en modo `horizontal_illumination_profile`; mapa de profundidad en modos `central_deep_layer`/`hybrid_deep_layer_profile`).
 - `tracks.csv`: trayectorias 2D por deteccion y frame.
+- `track_candidates.csv`: auditoria opcional de todos los tracks candidatos tras merge, con `accepted`, `score` y `reject_reasons`.
+- `events.csv`: resumen por track con inicio/fin, duracion, desplazamiento, recorrido, straightness y direccion.
+- `tracks.svg`: export vectorial autocontenido de todas las trayectorias en el sistema de coordenadas original del video, con el mismo color por `track_id` y las mismas etiquetas opcionales que `tracks_overlay.png`.
+- `tracks_render.json`: export JSON con `width`, `height`, puntos por track y metadatos minimos (`track_id`, `frame_start`, `frame_end`, `duration_sec`, `direction`, `point_start`, `point_end`).
+  - `direction` usa el vocabulario `entry`, `exit`, `inside`, `outside`, `unknown`.
 - `tracks_overlay.png`: trayectorias dibujadas sobre `background.png`.
+- `tracks_overlay_raw.png` y `tracks_overlay_smoothed.png` (opcionales): overlays adicionales cuando `output.trajectory_smoothing_enabled` esta activo.
 - `track_clips/` (opcional): clips de video por track (`track_0001_000120-000186.mp4`, etc.).
 - `meta.json`: metadatos del video, parametros efectivos y metricas de ejecucion.
-  - incluye bloque `valid_region` con `x_start`, `x_end`, `width` y `method`.
+  - incluye bloques `video`, `parameters`, `background`, `valid_region`, `metrics`, `execution`, `performance`, `outputs`, `trajectory_smoothing` y `postprocess`.
+  - `postprocess` resume tambien cuantos candidatos se aceptaron/rechazaron y las causas mas frecuentes.
 
 ## Formato de tracks.csv
 
@@ -103,6 +115,14 @@ Columnas exactas:
 
 `video_id,track_id,frame,time_sec,x,y,vx,vy,bbox_x1,bbox_y1,bbox_x2,bbox_y2,area`
 
+## Formato de events.csv
+
+Columnas exactas:
+
+`video_id,track_id,time_start_sec,time_end_sec,duration_sec,frame_start,frame_end,num_detections,x_start,y_start,x_end,y_end,displacement_px,path_length_px,straightness,mean_speed_px_sec,mean_area,start_in_valid_region,end_in_valid_region,direction`
+
+`direction` usa el vocabulario `entry`, `exit`, `inside`, `outside`, `unknown`.
+
 ## Pipeline implementado
 
 1. Lectura del video y metadatos.
@@ -111,10 +131,12 @@ Columnas exactas:
 4. Umbral binario (fijo u Otsu) + morfologia (open/close) + contornos.
 5. Filtrado de blobs por area minima/maxima.
 6. Tracking 2D frame a frame con asignacion greedy por distancia maxima y prediccion por velocidad para reducir cortes.
-7. Export de `tracks.csv` y render final `tracks_overlay.png` (color por track, primer punto mas grande).
-8. Si `valid_region.enabled`, calculo de banda vertical valida desde iluminacion horizontal y guardado en `valid_region/*`.
-9. Export de `meta.json` con parametros, metadatos y metricas.
+7. Merge automatico opcional de tracks fragmentados antes del filtrado final.
+8. Evaluacion centralizada de tracks candidatos (score + motivos de rechazo) y export de `tracks.csv`, `events.csv`, `tracks.svg`, `tracks_render.json` y render final `tracks_overlay.png`.
+9. Si `valid_region.enabled`, calculo de banda vertical valida desde iluminacion horizontal y guardado en `valid_region/*`.
+10. Export de `meta.json` con parametros, metadatos y metricas.
    - incluye `postprocess.auto_merges_applied` cuando `tracking.auto_merge_suggested` esta activo.
+   - incluye `trajectory_smoothing.enabled/window` y rutas extra de overlay cuando el suavizado esta activado.
 
 ## Configuracion
 
@@ -122,6 +144,9 @@ Usa `config.yaml.example` como base.
 
 - `background.sample_frames`: numero de frames para mediana temporal
 - `background.uniform_sampling`: muestreo uniforme en todo el video
+- `background.input_image`: si se define, reutiliza un fondo precomputado y omite la mediana temporal
+- `background.context_start_sec`: segundo inicial de la ventana usada para estimar `background.png`
+- `background.context_duration_sec`: duracion de esa ventana; `-1` usa el video entero
 - `detection.*`: parametros de blur, threshold, morfologia y area
   - `detection.threshold_mode`: `fixed` o `otsu`
   - `detection.otsu_offset`: ajuste fino sobre umbral Otsu (negativo = mas sensible)
@@ -143,6 +168,7 @@ Usa `config.yaml.example` como base.
   - `tracking.require_start_or_end_in_valid_region`: conserva solo tracks que empiezan o acaban dentro de la mascara valida
   - `tracking.valid_region_gate_dilate_px`: dilata la mascara valida en pixeles antes de aplicar el filtro inicio/fin
   - `tracking.auto_merge_suggested`: fusion automatica postproceso de tracks potencialmente duplicados
+  - `tracking.export_track_candidates`: escribe `track_candidates.csv` con todos los tracks evaluados, incluidos los rechazados
   - `tracking.merge_max_gap_frames` y `tracking.merge_max_endpoint_distance`: merge por handoff cercano (fin->inicio)
   - `tracking.merge_overlap_min_common_frames`: minimo de frames comunes para evaluar merge por solape
   - `tracking.merge_overlap_max_mean_distance`: distancia media maxima en frames comunes
@@ -153,6 +179,8 @@ Usa `config.yaml.example` como base.
   - `valid_region.apply_to_detection`: aplica mascara en deteccion por frame (si no, se usa solo para filtros de track)
   - `valid_region.hybrid_combine_mode`: `and`/`or` para combinar capa de profundidad + umbral por perfil
   - `valid_region.input_image`: si se define, usa esta imagen en vez de `background.png`
+  - `valid_region.input_mask`: si se define, reutiliza exactamente esta mascara y omite su estimacion
+  - `valid_region.context_start_sec` y `valid_region.context_duration_sec`: permiten estimar la mascara con una ventana temporal distinta a la del fondo de deteccion
   - `valid_region.blur_kernel_size` y `valid_region.profile_smooth_window`: deben ser impares
   - `valid_region.threshold_ratio`: fraccion del pico del perfil para definir region valida
   - `valid_region.safety_margin`: recorte adicional en pixeles por lado
@@ -160,15 +188,20 @@ Usa `config.yaml.example` como base.
   - `valid_region.depth_percentile/depth_morph_kernel/depth_min_area_ratio`: parametros del modo `central_deep_layer`
   - `valid_region.depth_layer_percentiles` + `valid_region.depth_layer_dilate_px`: expansion no uniforme por capas de profundidad (listas emparejadas)
   - `valid_region.bottom_contour_*`: refinado opcional del borde inferior ajustandolo al gradiente vertical de profundidad (`*_search_*` define ventana de busqueda, `*_smooth_window` suaviza la curva, `*_gradient_quantile` controla sensibilidad, `*_regularization`/`*_max_step_px` reducen muescas, `*_downward_bias` permite bajar cuando hay empate, `*_regularization_mix` mezcla ajuste local/global, `*_deepest_strong_ratio` favorece el borde fuerte mas profundo frente a crestas intermedias)
-- `output.*`: estilo del overlay
-  - `output.overlay_draw_track_labels`: dibuja el numero de `track_id` junto al inicio de cada track
-  - `output.overlay_draw_track_labels_at_end`: dibuja el numero de `track_id` al final del track
-  - `output.overlay_label_font_scale` y `output.overlay_label_thickness`: estilo de etiqueta
+- `output.*`: estilo del overlay y artefactos de salida
+  - `output.overlay_line_thickness`: grosor de linea en `tracks_overlay.png` y `tracks.svg`
+  - `output.overlay_start_radius`: radio del marcador del primer punto del track
+  - `output.overlay_alpha`: alpha del overlay raster `tracks_overlay.png`
+  - `output.overlay_draw_track_labels`: dibuja el numero de `track_id` junto al inicio de cada track en `tracks_overlay.png` y `tracks.svg`
+  - `output.overlay_draw_track_labels_at_end`: dibuja el numero de `track_id` al final del track en `tracks_overlay.png` y `tracks.svg`
+  - `output.overlay_label_font_scale` y `output.overlay_label_thickness`: estilo de etiqueta compartido por `tracks_overlay.png` y `tracks.svg`
   - `output.progress_enabled`: muestra trazas de avance global por consola durante todo el pipeline (etapas + frames)
   - `output.progress_step_percent`: porcentaje global entre trazas (1..100, por defecto `5`)
   - `output.export_track_clips`: exporta clips por track en una carpeta
   - `output.track_clips_subdir`: nombre de la carpeta de clips dentro del output
   - `output.track_clips_padding_frames`: frames extra antes/despues del rango del track
+  - `output.trajectory_smoothing_enabled`: genera una version suavizada de las trayectorias para overlays y `events.csv`
+  - `output.trajectory_smoothing_window`: ventana impar >= 3 usada en el suavizado
 - `execution.*`: seleccion de backend de computo
   - `execution.device`: `auto` (default), `cpu` o `cuda`
   - `execution.strict_parity`: cuando esta en `true`, compara mascara CPU/GPU y conserva la salida CPU para mantener resultados equivalentes al pipeline original
@@ -200,35 +233,6 @@ pytest
 
 Los tests cubren deteccion, tracking y export/render de salida.
 
-## Interfaz Web Para Hugging Face Spaces
-
-Se ha incluido una app Gradio en `app.py` pensada para un Space de Hugging Face.
-
-La interfaz permite:
-
-- subir el video de entrada
-- subir opcionalmente un YAML de configuracion
-- visualizar la imagen de region valida detectada
-- visualizar `tracks_overlay.png`
-- consultar `events.csv` como tabla
-- descargar `events.csv` y `tracks.csv`
-
-Ejecucion local:
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python3 app.py
-```
-
-Para desplegar en Hugging Face Spaces:
-
-1. crea un Space de tipo `Gradio`
-2. sube este repositorio o su contenido
-3. asegúrate de que `app.py` y `requirements.txt` queden en la raiz del Space
-4. Hugging Face instalará dependencias y lanzará la app automáticamente
-
 ## Agradecimientos / Referencias
 
 Parte de los parámetros y perfiles de uso incluidos en este proyecto se han inspirado en el enfoque y resultados de la herramienta **[ThruTracker](https://github.com/AaronJCorcoran/ThruTracker)** desarrollada por Aaron J. Corcoran. Recomendaos consultar su repositorio en GitHub.

bat_tracker/config.py

@@ -55,6 +55,7 @@ DEFAULT_CONFIG: Dict[str, Any] = {
         "merge_overlap_min_common_frames": 3,
         "merge_overlap_max_mean_distance": 60.0,
         "merge_overlap_min_direction_cosine": 0.8,
+        "export_track_candidates": False,
     },
     "valid_region": {
         "enabled": True,

bat_tracker/pipeline.py

@@ -21,7 +21,7 @@ from .config import load_config
 from .detection import build_detection_context
 from .detection import detect_foreground_blobs
 from .perf import PerformanceCollector
-from .render import render_tracks_overlay
+from .render import export_tracks_render_json, export_tracks_svg, render_tracks_overlay
 from .track_smoothing import smooth_track_points
 from .tracker import GreedyTracker, TrackPoint
 from .valid_region import load_image as load_valid_region_image
@@ -111,14 +111,56 @@ EVENTS_CSV_COLUMNS = [
     "direction",
 ]
 
+TRACK_CANDIDATES_CSV_COLUMNS = [
+    "video_id",
+    "track_id",
+    "accepted",
+    "reject_reasons",
+    "score",
+    "frame_start",
+    "frame_end",
+    "num_detections",
+    "duration_sec",
+    "x_start",
+    "y_start",
+    "x_end",
+    "y_end",
+    "displacement_px",
+    "path_length_px",
+    "straightness",
+    "mean_speed_px_sec",
+    "mean_area",
+    "start_in_valid_region",
+    "end_in_valid_region",
+    "direction",
+]
+
 
 def _classify_direction(start_inside: bool, end_inside: bool) -> str:
     if start_inside and end_inside:
         return "inside"
     if start_inside and not end_inside:
-        return "exits"
+        return "exit"
     if not start_inside and end_inside:
-        return "enters"
+        return "entry"
+    return "outside"
+
+
+def _infer_outside_direction_from_motion(
+    start: TrackPoint,
+    end: TrackPoint,
+    frame_shape: tuple[int, int] | None,
+) -> str:
+    if frame_shape is None:
+        return "outside"
+    height, width = frame_shape
+    dy = end.y - start.y
+    min_vertical_move = max(40.0, 0.15 * float(height))
+    top_band = 0.20 * float(height)
+    if dy <= -min_vertical_move and end.y <= top_band:
+        return "exit"
+    if dy >= min_vertical_move and start.y <= top_band:
+        return "entry"
     return "outside"
 
 
@@ -148,6 +190,8 @@ def _write_events_csv(
             s_in = _point_in_mask(start, valid_mask)
             e_in = _point_in_mask(end, valid_mask)
             direction = _classify_direction(s_in, e_in)
+            if direction == "outside":
+                direction = _infer_outside_direction_from_motion(start, end, valid_mask.shape[:2])
         else:
             s_in = None
             e_in = None
@@ -192,6 +236,14 @@ def _write_tracks_csv(path: Path, points: List[TrackPoint]) -> None:
             writer.writerow(row)
 
 
+def _write_track_candidates_csv(path: Path, rows: List[dict]) -> None:
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=TRACK_CANDIDATES_CSV_COLUMNS)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row)
+
+
 def _build_metrics(points: List[TrackPoint], frame_count: int) -> Dict:
     tracks_counter = Counter(p.track_id for p in points)
     tracks_lengths = list(tracks_counter.values())
@@ -367,7 +419,12 @@ def _filter_track_points(
     tracking_cfg: Dict,
     fps: float,
     valid_mask: np.ndarray | None = None,
-) -> List[TrackPoint]:
+) -> tuple[List[TrackPoint], List[dict]]:
+    def _ratio(value: float, threshold: float) -> float:
+        if threshold <= 0.0:
+            return 1.0
+        return min(1.0, max(0.0, value / threshold))
+
     min_track_length_cfg = int(tracking_cfg.get("min_track_length", 1))
     min_track_duration_sec = float(tracking_cfg.get("min_track_duration_sec", 0.0))
     min_track_length_from_sec = int(ceil(max(0.0, min_track_duration_sec) * max(1e-6, fps)))
@@ -377,39 +434,100 @@ def _filter_track_points(
     min_track_straightness = float(tracking_cfg.get("min_track_straightness", 0.0))
     require_start_or_end_in_valid_region = bool(tracking_cfg.get("require_start_or_end_in_valid_region", False))
     gate_mask = _build_valid_region_gate_mask(valid_mask, tracking_cfg)
+    strong_short_score_min = 0.9
 
     by_track: Dict[int, List[TrackPoint]] = defaultdict(list)
     for point in points:
         by_track[point.track_id].append(point)
 
     filtered: List[TrackPoint] = []
+    assessments: List[dict] = []
     for track_points in by_track.values():
         track_points = sorted(track_points, key=lambda p: p.frame)
-        if len(track_points) < min_track_length:
-            continue
-
         start = track_points[0]
         end = track_points[-1]
+        duration = end.time_sec - start.time_sec
         displacement = hypot(end.x - start.x, end.y - start.y)
-        if displacement < min_track_displacement:
-            continue
-
         path_length = _path_length(track_points)
+        straightness = (displacement / path_length) if path_length > 0 else 0.0
+        mean_speed = (path_length / duration) if duration > 0 else 0.0
+        avg_area = sum(p.area for p in track_points) / len(track_points)
+        score = mean(
+            [
+                _ratio(float(len(track_points)), float(min_track_length)),
+                _ratio(displacement, min_track_displacement),
+                _ratio(path_length, min_track_path_length),
+                _ratio(straightness, min_track_straightness) if min_track_straightness > 0.0 else 1.0,
+            ]
+        )
+        reject_reasons: list[str] = []
+        if len(track_points) < min_track_length:
+            reject_reasons.append("min_track_length")
+        if displacement < min_track_displacement:
+            reject_reasons.append("min_track_displacement")
         if path_length < min_track_path_length:
-            continue
-
+            reject_reasons.append("min_track_path_length")
         if min_track_straightness > 0.0 and path_length > 0.0:
-            straightness = displacement / path_length
             if straightness < min_track_straightness:
-                continue
+                reject_reasons.append("min_track_straightness")
 
+        s_in = None
+        e_in = None
+        direction = "unknown"
         if require_start_or_end_in_valid_region and gate_mask is not None:
-            if not (_point_in_mask(start, gate_mask) or _point_in_mask(end, gate_mask)):
-                continue
+            s_in = _point_in_mask(start, gate_mask)
+            e_in = _point_in_mask(end, gate_mask)
+            direction = _classify_direction(s_in, e_in)
+            if not (s_in or e_in):
+                reject_reasons.append("valid_region_gate")
+        elif valid_mask is not None:
+            s_in = _point_in_mask(start, valid_mask)
+            e_in = _point_in_mask(end, valid_mask)
+            direction = _classify_direction(s_in, e_in)
+            if direction == "outside":
+                direction = _infer_outside_direction_from_motion(start, end, valid_mask.shape[:2])
+
+        accepted = not reject_reasons
+        if not accepted:
+            reasons_set = set(reject_reasons)
+            if (
+                reasons_set.issubset({"min_track_length", "valid_region_gate"})
+                and len(track_points) >= min_track_length_from_sec
+                and score >= strong_short_score_min
+            ):
+                accepted = True
+                reject_reasons = []
+        assessments.append({
+            "video_id": start.video_id,
+            "track_id": start.track_id,
+            "accepted": accepted,
+            "reject_reasons": ";".join(reject_reasons),
+            "score": round(score, 4),
+            "frame_start": start.frame,
+            "frame_end": end.frame,
+            "num_detections": len(track_points),
+            "duration_sec": round(duration, 4),
+            "x_start": round(start.x, 2),
+            "y_start": round(start.y, 2),
+            "x_end": round(end.x, 2),
+            "y_end": round(end.y, 2),
+            "displacement_px": round(displacement, 2),
+            "path_length_px": round(path_length, 2),
+            "straightness": round(straightness, 4),
+            "mean_speed_px_sec": round(mean_speed, 2),
+            "mean_area": round(avg_area, 2),
+            "start_in_valid_region": s_in if s_in is not None else "",
+            "end_in_valid_region": e_in if e_in is not None else "",
+            "direction": direction,
+        })
+
+        if not accepted:
+            continue
 
         filtered.extend(track_points)
 
-    return filtered
+    assessments.sort(key=lambda row: int(row["track_id"]))
+    return filtered, assessments
 
 
 def _vector_cosine(v0: tuple[float, float], v1: tuple[float, float]) -> float | None:
@@ -564,16 +682,31 @@ def _auto_merge_track_points(points: List[TrackPoint], tracking_cfg: Dict) -> tu
             )
 
     merged_points = sorted(merged_points, key=lambda p: (p.track_id, p.frame))
-    deduped: List[TrackPoint] = []
-    seen = set()
+    by_track_frame: Dict[tuple[int, int], List[TrackPoint]] = defaultdict(list)
     for point in merged_points:
-        key = (point.track_id, point.frame, round(point.x, 3), round(point.y, 3))
-        if key in seen:
+        by_track_frame[(point.track_id, point.frame)].append(point)
+
+    consolidated: List[TrackPoint] = []
+    for key in sorted(by_track_frame.keys()):
+        candidates = by_track_frame[key]
+        if len(candidates) == 1:
+            consolidated.append(candidates[0])
             continue
-        seen.add(key)
-        deduped.append(point)
 
-    return deduped, merges_applied
+        # Keep one point per merged track/frame. Prefer the strongest blob and
+        # break ties deterministically to stabilize overlays and exports.
+        best = max(
+            candidates,
+            key=lambda p: (
+                p.area,
+                -abs(p.vx) - abs(p.vy),
+                -p.x,
+                -p.y,
+            ),
+        )
+        consolidated.append(best)
+
+    return consolidated, merges_applied
 
 
 def _export_track_clips(
@@ -840,14 +973,22 @@ def run_pipeline(
 
     progress.start_stage("postprocess")
     postprocess_started = perf_counter()
-    filtered_points = _filter_track_points(all_points, cfg["tracking"], meta.fps, valid_mask=valid_mask)
-    filtered_points, merges_applied = _auto_merge_track_points(filtered_points, cfg["tracking"])
+    merged_points, merges_applied = _auto_merge_track_points(all_points, cfg["tracking"])
+    filtered_points, track_assessments = _filter_track_points(
+        merged_points,
+        cfg["tracking"],
+        meta.fps,
+        valid_mask=valid_mask,
+    )
     perf.record("postprocess_stage", perf_counter() - postprocess_started, executions=1)
     progress.complete_stage("postprocess", detail="postprocess done")
 
     progress.start_stage("exports_core")
     tracks_csv_path = out_dir / "tracks.csv"
     _write_tracks_csv(tracks_csv_path, filtered_points)
+    track_candidates_csv_path = out_dir / "track_candidates.csv"
+    if bool(cfg["tracking"].get("export_track_candidates", False)):
+        _write_track_candidates_csv(track_candidates_csv_path, track_assessments)
 
     out_cfg_export = cfg.get("output", {})
     smoothing_on = bool(out_cfg_export.get("trajectory_smoothing_enabled", False))
@@ -859,6 +1000,31 @@ def run_pipeline(
     events_csv_path = out_dir / "events.csv"
     points_for_events = smoothed_points if smoothed_points is not None else filtered_points
     _write_events_csv(events_csv_path, points_for_events, valid_gate_mask)
+    tracks_svg_path = out_dir / "tracks.svg"
+    export_tracks_svg(
+        tracks_svg_path,
+        width=meta.width,
+        height=meta.height,
+        points=filtered_points,
+        line_thickness=int(cfg["output"]["overlay_line_thickness"]),
+        start_radius=int(cfg["output"]["overlay_start_radius"]),
+        alpha=float(cfg["output"].get("overlay_alpha", 1.0)),
+        draw_track_labels=bool(cfg["output"].get("overlay_draw_track_labels", False)),
+        draw_track_labels_at_end=bool(cfg["output"].get("overlay_draw_track_labels_at_end", False)),
+        label_font_scale=float(cfg["output"].get("overlay_label_font_scale", 0.5)),
+        label_thickness=int(cfg["output"].get("overlay_label_thickness", 1)),
+        valid_region_mask=valid_mask,
+        direction_mask=valid_gate_mask,
+    )
+    tracks_render_json_path = out_dir / "tracks_render.json"
+    export_tracks_render_json(
+        tracks_render_json_path,
+        width=meta.width,
+        height=meta.height,
+        points=filtered_points,
+        valid_region_mask=valid_mask,
+        direction_mask=valid_gate_mask,
+    )
 
     overlay_line_t = int(cfg["output"]["overlay_line_thickness"])
     overlay_start_r = int(cfg["output"]["overlay_start_radius"])
@@ -976,7 +1142,14 @@ def run_pipeline(
             "background_png": str(background_path.resolve()),
             "tracks_csv": str(tracks_csv_path.resolve()),
             "events_csv": str(events_csv_path.resolve()),
+            "tracks_svg": str(tracks_svg_path.resolve()),
+            "tracks_render_json": str(tracks_render_json_path.resolve()),
             "tracks_overlay_png": str(overlay_path.resolve()),
+            "track_candidates_csv": (
+                str(track_candidates_csv_path.resolve())
+                if bool(cfg["tracking"].get("export_track_candidates", False))
+                else ""
+            ),
             **overlay_smoothing_paths,
             "track_clips": track_clip_outputs,
             **valid_region_outputs,
@@ -984,6 +1157,17 @@ def run_pipeline(
         "postprocess": {
             "auto_merge_enabled": bool(cfg["tracking"].get("auto_merge_suggested", False)),
             "auto_merges_applied": merges_applied,
+            "track_candidates_total": len(track_assessments),
+            "track_candidates_kept": sum(1 for row in track_assessments if row["accepted"]),
+            "track_candidates_rejected": sum(1 for row in track_assessments if not row["accepted"]),
+            "track_candidates_top_rejections": dict(
+                Counter(
+                    reason
+                    for row in track_assessments
+                    for reason in str(row["reject_reasons"]).split(";")
+                    if reason
+                )
+            ),
         },
     }
 

bat_tracker/render.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import Dict, List, Sequence, Tuple
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Sequence, Tuple
+from xml.etree import ElementTree as ET
 
 import cv2
 import numpy as np
@@ -15,6 +18,311 @@ def track_color(track_id: int) -> Tuple[int, int, int]:
     return int(bgr[0]), int(bgr[1]), int(bgr[2])
 
 
+def _track_color_hex(track_id: int) -> str:
+    blue, green, red = track_color(track_id)
+    return f"#{red:02x}{green:02x}{blue:02x}"
+
+
+def _svg_number(value: float) -> str:
+    return format(float(value), ".15g")
+
+
+def _svg_stroke_width(line_thickness: int) -> str:
+    # OpenCV anti-aliased lines render visually thicker than an SVG stroke with
+    # the same numeric width. Apply a small compensation so the vector export
+    # better matches the PNG overlay.
+    return _svg_number(max(1.0, float(line_thickness) * 1.5))
+
+
+def _svg_label_font_size(label_font_scale: float) -> str:
+    # cv2.putText with FONT_HERSHEY_SIMPLEX renders larger than a same-number
+    # SVG font-size. This compensation keeps SVG labels visually aligned with
+    # the PNG overlay labels.
+    return _svg_number(max(0.3, float(label_font_scale)) * 28.0)
+
+
+def _point_in_mask_xy(x: float, y: float, mask: np.ndarray) -> bool:
+    xi = int(round(x))
+    yi = int(round(y))
+    if yi < 0 or yi >= mask.shape[0] or xi < 0 or xi >= mask.shape[1]:
+        return False
+    return bool(mask[yi, xi] > 0)
+
+
+def _classify_track_direction(start_inside: bool | None, end_inside: bool | None) -> str:
+    if start_inside is None or end_inside is None:
+        return "unknown"
+    if start_inside and end_inside:
+        return "inside"
+    if start_inside and not end_inside:
+        return "exit"
+    if not start_inside and end_inside:
+        return "entry"
+    return "outside"
+
+
+def _point_payload(point: TrackPoint) -> Dict[str, Any]:
+    return {
+        "x": float(point.x),
+        "y": float(point.y),
+        "frame": int(point.frame),
+        "time_sec": float(point.time_sec),
+    }
+
+
+def _mask_contours_payload(mask: np.ndarray) -> List[List[Dict[str, int]]]:
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    payload: List[List[Dict[str, int]]] = []
+    for contour in contours:
+        coords = contour.reshape(-1, 2)
+        payload.append([{"x": int(x), "y": int(y)} for x, y in coords])
+    return payload
+
+
+def build_tracks_render_payload(
+    width: int,
+    height: int,
+    points: Sequence[TrackPoint],
+    *,
+    valid_region_mask: np.ndarray | None = None,
+    direction_mask: np.ndarray | None = None,
+) -> Dict[str, Any]:
+    by_track: Dict[int, List[TrackPoint]] = defaultdict(list)
+    for point in points:
+        by_track[point.track_id].append(point)
+
+    payload: Dict[str, Any] = {
+        "width": int(width),
+        "height": int(height),
+        "tracks": [],
+    }
+
+    if valid_region_mask is not None:
+        payload["valid_region"] = {
+            "contours": _mask_contours_payload(valid_region_mask),
+        }
+
+    effective_direction_mask = direction_mask if direction_mask is not None else valid_region_mask
+    tracks_payload: List[Dict[str, Any]] = []
+    for track_id in sorted(by_track):
+        track_points = sorted(by_track[track_id], key=lambda p: p.frame)
+        start = track_points[0]
+        end = track_points[-1]
+        start_inside = None
+        end_inside = None
+        if effective_direction_mask is not None:
+            start_inside = _point_in_mask_xy(start.x, start.y, effective_direction_mask)
+            end_inside = _point_in_mask_xy(end.x, end.y, effective_direction_mask)
+
+        tracks_payload.append(
+            {
+                "track_id": int(track_id),
+                "color": _track_color_hex(track_id),
+                "frame_start": int(start.frame),
+                "frame_end": int(end.frame),
+                "duration_sec": float(end.time_sec - start.time_sec),
+                "direction": _classify_track_direction(start_inside, end_inside),
+                "point_start": _point_payload(start),
+                "point_end": _point_payload(end),
+                "points": [_point_payload(point) for point in track_points],
+            }
+        )
+
+    payload["tracks"] = tracks_payload
+    return payload
+
+
+def export_tracks_render_json(
+    path: str | Path,
+    width: int,
+    height: int,
+    points: Sequence[TrackPoint],
+    *,
+    valid_region_mask: np.ndarray | None = None,
+    direction_mask: np.ndarray | None = None,
+) -> Dict[str, Any]:
+    payload = build_tracks_render_payload(
+        width=width,
+        height=height,
+        points=points,
+        valid_region_mask=valid_region_mask,
+        direction_mask=direction_mask,
+    )
+    with Path(path).open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2)
+    return payload
+
+
+def export_tracks_svg(
+    path: str | Path,
+    width: int,
+    height: int,
+    points: Sequence[TrackPoint],
+    *,
+    line_thickness: int,
+    start_radius: int,
+    alpha: float = 1.0,
+    draw_track_labels: bool = False,
+    draw_track_labels_at_end: bool = False,
+    label_font_scale: float = 0.5,
+    label_thickness: int = 1,
+    valid_region_mask: np.ndarray | None = None,
+    direction_mask: np.ndarray | None = None,
+) -> Dict[str, Any]:
+    payload = build_tracks_render_payload(
+        width=width,
+        height=height,
+        points=points,
+        valid_region_mask=valid_region_mask,
+        direction_mask=direction_mask,
+    )
+
+    svg = ET.Element(
+        "svg",
+        {
+            "xmlns": "http://www.w3.org/2000/svg",
+            "viewBox": f"0 0 {int(width)} {int(height)}",
+            "width": str(int(width)),
+            "height": str(int(height)),
+            "role": "img",
+            "aria-label": "bat_tracker trajectories",
+        },
+    )
+    title = ET.SubElement(svg, "title")
+    title.text = "bat_tracker trajectories"
+    desc = ET.SubElement(svg, "desc")
+    desc.text = "Vector export of tracked trajectories in original video coordinates."
+    style = ET.SubElement(svg, "style")
+    style.text = (
+        ".track polyline { fill: none; stroke: var(--track-color); stroke-linecap: round; "
+        "stroke-linejoin: round; vector-effect: non-scaling-stroke; }\n"
+        ".track .track-start { fill: var(--track-color); }\n"
+        ".track .track-end { fill: var(--track-color); opacity: 0.9; }\n"
+        ".track text { fill: var(--track-color); stroke: #000; paint-order: stroke fill; "
+        "stroke-linejoin: round; dominant-baseline: alphabetic; }\n"
+        ".valid-region path { fill: rgba(0, 255, 0, 0.12); stroke: #00ffaa; stroke-width: 1.5; "
+        "vector-effect: non-scaling-stroke; }\n"
+    )
+
+    valid_region = payload.get("valid_region", {})
+    contours = valid_region.get("contours", []) if isinstance(valid_region, dict) else []
+    if contours:
+        valid_group = ET.SubElement(svg, "g", {"id": "valid-region", "class": "valid-region"})
+        valid_title = ET.SubElement(valid_group, "title")
+        valid_title.text = "Valid region"
+        for idx, contour in enumerate(contours):
+            if not contour:
+                continue
+            commands = [f"M {_svg_number(contour[0]['x'])} {_svg_number(contour[0]['y'])}"]
+            for point in contour[1:]:
+                commands.append(f"L {_svg_number(point['x'])} {_svg_number(point['y'])}")
+            commands.append("Z")
+            ET.SubElement(
+                valid_group,
+                "path",
+                {
+                    "id": f"valid-region-contour-{idx}",
+                    "d": " ".join(commands),
+                },
+            )
+
+    polyline_width = _svg_stroke_width(line_thickness)
+    start_radius_px = str(max(2, int(start_radius)))
+    end_radius_px = str(max(1, int(round(max(2, start_radius) * 0.6))))
+    group_opacity = _svg_number(max(0.0, min(1.0, alpha)))
+    label_offset = max(4, int(start_radius) + 2)
+    label_font_size = _svg_label_font_size(label_font_scale)
+    label_stroke_width = _svg_number(max(1, int(label_thickness)) + 2)
+    for track in payload["tracks"]:
+        track_id = int(track["track_id"])
+        group = ET.SubElement(
+            svg,
+            "g",
+            {
+                "id": f"track-{track_id}",
+                "class": "track",
+                "style": f"--track-color: {track['color']}",
+                "data-track-id": str(track_id),
+                "data-frame-start": str(track["frame_start"]),
+                "data-frame-end": str(track["frame_end"]),
+                "data-direction": str(track["direction"]),
+                "opacity": group_opacity,
+            },
+        )
+        group_title = ET.SubElement(group, "title")
+        group_title.text = (
+            f"Track {track_id} | frames {track['frame_start']}-{track['frame_end']} | "
+            f"duration {track['duration_sec']:.4f}s | direction {track['direction']}"
+        )
+
+        points_attr = " ".join(
+            f"{_svg_number(point['x'])},{_svg_number(point['y'])}" for point in track["points"]
+        )
+        ET.SubElement(
+            group,
+            "polyline",
+            {
+                "points": points_attr,
+                "stroke-width": polyline_width,
+            },
+        )
+
+        start = track["point_start"]
+        end = track["point_end"]
+        ET.SubElement(
+            group,
+            "circle",
+            {
+                "class": "track-start",
+                "cx": _svg_number(start["x"]),
+                "cy": _svg_number(start["y"]),
+                "r": start_radius_px,
+            },
+        )
+        ET.SubElement(
+            group,
+            "circle",
+            {
+                "class": "track-end",
+                "cx": _svg_number(end["x"]),
+                "cy": _svg_number(end["y"]),
+                "r": end_radius_px,
+            },
+        )
+        if draw_track_labels:
+            ET.SubElement(
+                group,
+                "text",
+                {
+                    "class": "track-label track-label-start",
+                    "x": _svg_number(start["x"] + label_offset),
+                    "y": _svg_number(start["y"] - label_offset),
+                    "font-size": label_font_size,
+                    "font-family": "sans-serif",
+                    "stroke-width": label_stroke_width,
+                },
+            ).text = str(track_id)
+        if draw_track_labels_at_end and track["points"]:
+            ET.SubElement(
+                group,
+                "text",
+                {
+                    "class": "track-label track-label-end",
+                    "x": _svg_number(end["x"] + label_offset),
+                    "y": _svg_number(end["y"] - label_offset),
+                    "font-size": label_font_size,
+                    "font-family": "sans-serif",
+                    "stroke-width": label_stroke_width,
+                },
+            ).text = str(track_id)
+
+    tree = ET.ElementTree(svg)
+    if hasattr(ET, "indent"):
+        ET.indent(tree, space="  ")
+    tree.write(Path(path), encoding="utf-8", xml_declaration=True)
+    return payload
+
+
 def render_tracks_overlay(
     background_gray: np.ndarray,
     points: Sequence[TrackPoint],

config.out3_clean.yaml

@@ -1,9 +1,9 @@
 background:
   sample_frames: 120
   uniform_sampling: true
+  input_image: ""
   context_start_sec: 0.0
   context_duration_sec: -1.0
-
 detection:
   blur_kernel: 9
   threshold_mode: fixed
@@ -24,32 +24,37 @@ detection:
   temporal_burst_window_frames: 10
   temporal_burst_trigger_frames: 3
   temporal_burst_cooldown_frames: 24
-
 tracking:
   max_distance: 120.0
   max_missed: 12
   min_track_length: 6
+  min_track_duration_sec: 0.1
   min_track_displacement: 20.0
   min_track_path_length: 28.0
   min_track_straightness: 0.08
-  min_track_duration_sec: 0.1
+  require_start_or_end_in_valid_region: true
+  valid_region_gate_dilate_px: 20
   auto_merge_suggested: true
   merge_max_gap_frames: 12
   merge_max_endpoint_distance: 100.0
   merge_overlap_min_common_frames: 3
   merge_overlap_max_mean_distance: 60.0
   merge_overlap_min_direction_cosine: 0.8
-  require_start_or_end_in_valid_region: true
-  valid_region_gate_dilate_px: 20
-
+  export_track_candidates: true
 valid_region:
   enabled: true
   method: hybrid_deep_layer_profile
   apply_to_detection: false
+  hybrid_combine_mode: and
+  input_image: ""
+  input_mask: ""
   context_start_sec: 0.0
   context_duration_sec: 75.0
-  hybrid_combine_mode: and
   blur_kernel_size: 151
+  profile_smooth_window: 31
+  threshold_ratio: 0.45
+  safety_margin: 10
+  min_region_width_ratio: 0.35
   depth_percentile: 85.0
   depth_morph_kernel: 9
   depth_min_area_ratio: 0.02
@@ -62,11 +67,10 @@ valid_region:
   bottom_contour_gradient_quantile: 52.0
   bottom_contour_regularization: 1.25
   bottom_contour_max_step_px: 8
-  bottom_contour_downward_bias: 0.20
-  bottom_contour_regularization_mix: 0.90
+  bottom_contour_downward_bias: 0.2
+  bottom_contour_regularization_mix: 0.9
   bottom_contour_deepest_strong_ratio: 0.62
   output_subdir: valid_region
-
 output:
   overlay_line_thickness: 2
   overlay_start_radius: 5
@@ -75,8 +79,10 @@ output:
   overlay_draw_track_labels_at_end: true
   overlay_label_font_scale: 0.5
   overlay_label_thickness: 1
+  progress_enabled: true
+  progress_step_percent: 1
   export_track_clips: false
   track_clips_subdir: track_clips
   track_clips_padding_frames: 5
-  progress_enabled: true
-  progress_step_percent: 1
+  trajectory_smoothing_enabled: false
+  trajectory_smoothing_window: 5

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bat_tracker"
-version = "1.1.1"
+version = "1.1.3"
 description = "CPU-first bat trajectory extraction from monochrome IR cave videos"
 readme = "README.md"
 requires-python = ">=3.10"

tests/test_track_exports.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+import cv2
+import numpy as np
+import yaml
+
+from bat_tracker.pipeline import run_pipeline
+from bat_tracker.render import export_tracks_render_json, export_tracks_svg
+
+
+SVG_NS = {"svg": "http://www.w3.org/2000/svg"}
+
+
+def _write_video(path: Path, frames: list[np.ndarray], fps: int = 10) -> None:
+    height, width = frames[0].shape
+    writer = cv2.VideoWriter(
+        str(path),
+        cv2.VideoWriter_fourcc(*"mp4v"),
+        float(fps),
+        (width, height),
+    )
+    assert writer.isOpened(), f"could not open writer for {path}"
+    for frame in frames:
+        writer.write(cv2.cvtColor(frame, cv2.COLOR_GRAY2BGR))
+    writer.release()
+
+
+def _read_tracks(path: Path) -> list[dict[str, str]]:
+    with path.open(newline="", encoding="utf-8") as handle:
+        return list(csv.DictReader(handle))
+
+
+def _base_config() -> dict:
+    return {
+        "background": {
+            "sample_frames": 12,
+            "uniform_sampling": True,
+        },
+        "detection": {
+            "blur_kernel": 1,
+            "threshold_mode": "fixed",
+            "diff_threshold": 10,
+            "morph_open": 1,
+            "morph_close": 1,
+            "min_area": 8,
+            "max_area": 5000,
+            "max_global_intensity_shift": -1.0,
+            "max_foreground_ratio": -1.0,
+            "max_detections_per_frame": 0,
+            "temporal_burst_min_detections": 0,
+            "temporal_burst_window_frames": 0,
+            "temporal_burst_trigger_frames": 0,
+            "temporal_burst_cooldown_frames": 0,
+        },
+        "tracking": {
+            "max_distance": 18,
+            "max_missed": 2,
+            "min_track_length": 1,
+            "min_track_displacement": 0.0,
+            "min_track_path_length": 0.0,
+            "min_track_straightness": 0.0,
+            "min_track_duration_sec": 0.0,
+            "auto_merge_suggested": False,
+            "require_start_or_end_in_valid_region": False,
+            "valid_region_gate_dilate_px": 0,
+        },
+        "valid_region": {
+            "enabled": False,
+        },
+        "output": {
+            "progress_enabled": False,
+            "overlay_line_thickness": 2,
+            "overlay_start_radius": 5,
+            "overlay_alpha": 1.0,
+            "overlay_draw_track_labels": True,
+            "overlay_draw_track_labels_at_end": True,
+            "overlay_label_font_scale": 0.5,
+            "overlay_label_thickness": 1,
+            "export_track_clips": False,
+        },
+    }
+
+
+def _make_single_track_video(tmp_path: Path) -> Path:
+    frames: list[np.ndarray] = []
+    for idx in range(10):
+        frame = np.zeros((48, 64), dtype=np.uint8)
+        if idx < 5:
+            x0 = 8 + idx * 5
+            cv2.rectangle(frame, (x0, 22), (x0 + 6, 28), 220, -1)
+        frames.append(frame)
+
+    video_path = tmp_path / "single_track.mp4"
+    _write_video(video_path, frames)
+    return video_path
+
+
+def test_pipeline_exports_svg_and_render_json_from_in_memory_tracks(tmp_path: Path) -> None:
+    video_path = _make_single_track_video(tmp_path)
+
+    mask = np.zeros((48, 64), dtype=np.uint8)
+    mask[:, 20:60] = 255
+    mask_path = tmp_path / "valid_mask.png"
+    cv2.imwrite(str(mask_path), mask)
+
+    cfg = _base_config()
+    cfg["valid_region"] = {
+        "enabled": True,
+        "input_mask": str(mask_path),
+        "apply_to_detection": False,
+    }
+    cfg_path = tmp_path / "cfg.yaml"
+    cfg_path.write_text(yaml.safe_dump(cfg), encoding="utf-8")
+
+    out_dir = tmp_path / "out"
+    meta = run_pipeline(str(video_path), str(out_dir), str(cfg_path))
+
+    tracks_rows = _read_tracks(out_dir / "tracks.csv")
+    assert tracks_rows
+
+    with (out_dir / "tracks_render.json").open(encoding="utf-8") as handle:
+        render_payload = json.load(handle)
+
+    assert render_payload["width"] == 64
+    assert render_payload["height"] == 48
+    assert len(render_payload["tracks"]) == 1
+    track_payload = render_payload["tracks"][0]
+    assert track_payload["track_id"] == 1
+    assert track_payload["direction"] == "entry"
+    assert track_payload["frame_start"] == 0
+    assert track_payload["frame_end"] == 4
+    assert track_payload["point_start"]["frame"] == 0
+    assert track_payload["point_end"]["frame"] == 4
+    assert "valid_region" in render_payload
+    assert render_payload["valid_region"]["contours"]
+
+    csv_points = [
+        {
+            "frame": int(row["frame"]),
+            "time_sec": float(row["time_sec"]),
+            "x": float(row["x"]),
+            "y": float(row["y"]),
+        }
+        for row in tracks_rows
+    ]
+    assert track_payload["points"] == csv_points
+
+    svg_root = ET.parse(out_dir / "tracks.svg").getroot()
+    assert svg_root.attrib["viewBox"] == "0 0 64 48"
+    valid_region_group = svg_root.find("svg:g[@id='valid-region']", SVG_NS)
+    assert valid_region_group is not None
+    track_group = svg_root.find("svg:g[@id='track-1']", SVG_NS)
+    assert track_group is not None
+    assert track_group.attrib["data-track-id"] == "1"
+    assert track_group.attrib["data-frame-start"] == "0"
+    assert track_group.attrib["data-frame-end"] == "4"
+    assert track_group.attrib["data-direction"] == "entry"
+    title = track_group.find("svg:title", SVG_NS)
+    assert title is not None
+    assert "Track 1" in (title.text or "")
+
+    polyline = track_group.find("svg:polyline", SVG_NS)
+    assert polyline is not None
+    expected_points = " ".join(f"{point['x']},{point['y']}" for point in csv_points)
+    assert polyline.attrib["points"] == expected_points
+
+    circles = track_group.findall("svg:circle", SVG_NS)
+    assert len(circles) == 2
+    labels = track_group.findall("svg:text", SVG_NS)
+    assert len(labels) == 2
+    assert {label.attrib["class"] for label in labels} == {
+        "track-label track-label-start",
+        "track-label track-label-end",
+    }
+    assert {label.text for label in labels} == {"1"}
+    assert meta["outputs"]["tracks_svg"] == str((out_dir / "tracks.svg").resolve())
+    assert meta["outputs"]["tracks_render_json"] == str((out_dir / "tracks_render.json").resolve())
+
+
+def test_svg_and_render_json_export_empty_tracks_as_valid_empty_documents(tmp_path: Path) -> None:
+    svg_path = tmp_path / "tracks.svg"
+    json_path = tmp_path / "tracks_render.json"
+
+    export_tracks_svg(svg_path, width=64, height=48, points=[], line_thickness=2, start_radius=5)
+    payload = export_tracks_render_json(json_path, width=64, height=48, points=[])
+
+    assert payload["tracks"] == []
+    with json_path.open(encoding="utf-8") as handle:
+        assert json.load(handle)["tracks"] == []
+
+    svg_root = ET.parse(svg_path).getroot()
+    assert svg_root.attrib["viewBox"] == "0 0 64 48"
+    assert svg_root.findall("svg:g[@class='track']", SVG_NS) == []