Tinghong-Ye22 commited on
Commit
a41404d
·
verified ·
1 Parent(s): c3099b3

Add files using upload-large-folder tool

Browse files
Files changed (31) hide show
  1. .gitattributes +6 -0
  2. source/CLIP_P0010073.mov +3 -0
  3. trajectory_project/intermediate/contact_sheet.jpg +3 -0
  4. trajectory_project/intermediate/contact_sheet_full.jpg +3 -0
  5. trajectory_project/intermediate/genmo_reference.pdf +3 -0
  6. trajectory_project/intermediate/genmo_teaser.jpg +3 -0
  7. trajectory_project/intermediate/keyframes/t0.jpg +0 -0
  8. trajectory_project/intermediate/keyframes/t10.jpg +0 -0
  9. trajectory_project/intermediate/keyframes/t20.jpg +0 -0
  10. trajectory_project/intermediate/keyframes/t30.jpg +0 -0
  11. trajectory_project/intermediate/keyframes/t35.jpg +0 -0
  12. trajectory_project/intermediate/keyframes/t40.jpg +0 -0
  13. trajectory_project/intermediate/keyframes/t45.jpg +0 -0
  14. trajectory_project/intermediate/keyframes/t50.jpg +0 -0
  15. trajectory_project/intermediate/keyframes/t55.jpg +0 -0
  16. trajectory_project/intermediate/keyframes/t60.jpg +0 -0
  17. trajectory_project/intermediate/keyframes/t63.jpg +0 -0
  18. trajectory_project/intermediate/keyframes_montage.jpg +3 -0
  19. trajectory_project/intermediate/yolo_mask_montage.jpg +3 -0
  20. trajectory_project/models/yolov8x-seg.pt +3 -0
  21. trajectory_project/qa/source_preflight.md +7 -0
  22. trajectory_project/qa/v5_image_integrity.md +14 -0
  23. trajectory_project/qa/v6_source_preflight.md +29 -0
  24. trajectory_project/qa/v7_image_integrity.md +15 -0
  25. trajectory_project/scripts/build_trajectory_figure.py +642 -0
  26. trajectory_project/scripts/build_trajectory_figure_v3.py +1113 -0
  27. trajectory_project/scripts/build_trajectory_figure_v4.py +562 -0
  28. trajectory_project/scripts/build_trajectory_figure_v5.py +551 -0
  29. trajectory_project/scripts/build_trajectory_figure_v7.py +802 -0
  30. trajectory_project/scripts/build_trajectory_figure_v8.py +972 -0
  31. trajectory_project/scripts/build_trajectory_figure_v9.py +1220 -0
.gitattributes CHANGED
@@ -11,3 +11,9 @@ trajectory_project/outputs/v7_wide_crop_uniform_scale/*.tiff filter=lfs diff=lfs
11
  trajectory_project/outputs/v8_metallic_contrast_palette/*.tiff filter=lfs diff=lfs merge=lfs -text
12
  trajectory_project/outputs/v9_native_4k_resolution/*.tiff filter=lfs diff=lfs merge=lfs -text
13
  trajectory_project/outputs/v10_brighter_background/*.tiff filter=lfs diff=lfs merge=lfs -text
 
 
 
 
 
 
 
11
  trajectory_project/outputs/v8_metallic_contrast_palette/*.tiff filter=lfs diff=lfs merge=lfs -text
12
  trajectory_project/outputs/v9_native_4k_resolution/*.tiff filter=lfs diff=lfs merge=lfs -text
13
  trajectory_project/outputs/v10_brighter_background/*.tiff filter=lfs diff=lfs merge=lfs -text
14
+ trajectory_project/intermediate/contact_sheet_full.jpg filter=lfs diff=lfs merge=lfs -text
15
+ trajectory_project/intermediate/genmo_reference.pdf filter=lfs diff=lfs merge=lfs -text
16
+ trajectory_project/intermediate/genmo_teaser.jpg filter=lfs diff=lfs merge=lfs -text
17
+ trajectory_project/intermediate/yolo_mask_montage.jpg filter=lfs diff=lfs merge=lfs -text
18
+ trajectory_project/intermediate/keyframes_montage.jpg filter=lfs diff=lfs merge=lfs -text
19
+ trajectory_project/intermediate/contact_sheet.jpg filter=lfs diff=lfs merge=lfs -text
source/CLIP_P0010073.mov ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:daaa820619d78a4a5dee1fc70acf0f45329bcd29646ef057fcef2e62b818f503
3
+ size 169267182
trajectory_project/intermediate/contact_sheet.jpg ADDED

Git LFS Details

  • SHA256: d68e8c9fcb0e8e911935a651b764326cd0199ef4c3f3c9a0e53752af1198c6c9
  • Pointer size: 131 Bytes
  • Size of remote file: 154 kB
trajectory_project/intermediate/contact_sheet_full.jpg ADDED

Git LFS Details

  • SHA256: 7015bf0ed740a415ee38f95cc13df35e982b5babe07ab86ddae787bbb9b285d5
  • Pointer size: 131 Bytes
  • Size of remote file: 147 kB
trajectory_project/intermediate/genmo_reference.pdf ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:5c69f34776cf9e54c7a77016a6be3d5ce531ce527671332c6b84b4a730405965
3
+ size 2730535
trajectory_project/intermediate/genmo_teaser.jpg ADDED

Git LFS Details

  • SHA256: 1e402e454af403e1b1755570feefc22fd5d9a13c4a7d8d9d086ec8b437cdccbe
  • Pointer size: 132 Bytes
  • Size of remote file: 3.4 MB
trajectory_project/intermediate/keyframes/t0.jpg ADDED
trajectory_project/intermediate/keyframes/t10.jpg ADDED
trajectory_project/intermediate/keyframes/t20.jpg ADDED
trajectory_project/intermediate/keyframes/t30.jpg ADDED
trajectory_project/intermediate/keyframes/t35.jpg ADDED
trajectory_project/intermediate/keyframes/t40.jpg ADDED
trajectory_project/intermediate/keyframes/t45.jpg ADDED
trajectory_project/intermediate/keyframes/t50.jpg ADDED
trajectory_project/intermediate/keyframes/t55.jpg ADDED
trajectory_project/intermediate/keyframes/t60.jpg ADDED
trajectory_project/intermediate/keyframes/t63.jpg ADDED
trajectory_project/intermediate/keyframes_montage.jpg ADDED

Git LFS Details

  • SHA256: f80f446aa66ebe94be50b135debd732ec537e08f09f1ea8545f43b1999678c6f
  • Pointer size: 131 Bytes
  • Size of remote file: 353 kB
trajectory_project/intermediate/yolo_mask_montage.jpg ADDED

Git LFS Details

  • SHA256: f56f10f0533b52b6444bd578daeef6199d75eabcde2d06f49ed2631abde9e966
  • Pointer size: 131 Bytes
  • Size of remote file: 371 kB
trajectory_project/models/yolov8x-seg.pt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:c333d6a7aff884ec821050eacdab29871f3edd10d996cf48746a02f8e01f1b5d
3
+ size 144101612
trajectory_project/qa/source_preflight.md ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ # Source preflight — v1
2
+
3
+ Validator result: **ready = true; 14 PASS, 0 WARN, 0 FAIL**.
4
+
5
+ Passed checks: Python syntax, publication-safe sans-serif font, minimum 5 pt text, non-rainbow palette, editable SVG/PDF text, SVG/PDF export, TIFF export at 600 dpi, 183 mm double-column width, sampling/exclusion scan, simulated-data scan, log guard, and Python-backend exclusivity.
6
+
7
+ The automated result is a source-code preflight only. Visual review was also performed on `trajectory_annotated.png`, `trajectory_clean.png`, and `cutouts_qa.jpg` at final output size.
trajectory_project/qa/v5_image_integrity.md ADDED
@@ -0,0 +1,14 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 图像完整性记录 — v5 遮挡优化与错位布局
2
+
3
+ - **原始材料:**沿用同一个固定机位 MOV 视频;v1–v4 的脚本、配置和输出不覆盖。
4
+ - **展示采样:**6、7、12、14、27、31、32、40、44、45、52、53、56.5 s,对应帧 150、175、300、350、675、775、800、1000、1100、1125、1300、1325、1412。
5
+ - **分割复用:**不重新推理。v5 从 v4 原样复制 `segmentation_cache.npz`、检测记录、SAM 全量指标和提示点;缓存 SHA256 两端均为 `1aa8ab38fa3e22d386983c99638796b7beee985edcc5f5db2f9b31d346938aca`,其余三份文件也在 `reuse_audit.json` 中逐项一致。
6
+ - **分割质量:**13 个展示掩膜平均最终 IoU 为 0.926578、平均召回率为 0.934750、平均精度为 0.990655;没有帧回退到 YOLO 原掩膜。
7
+ - **背景复用:**v5 与 v4 的 `background_plate.png` 逐像素差异为 0;两者 SHA256 均为 `4c54e646bea389665b6c8708a00c117365db6cea915499d48cf312d84ba9127d`。v4 已确认的局部真实像素修补保持不变,不新增生成式内容。
8
+ - **姿态变换:**每个切片只做二维平移和等比例缩放,不旋转、不非刚性形变、不生成机器人像素。默认尺度 0.92;6/7 s 为 0.96;31 s 为 0.82。
9
+ - **主要位置调整:**14 s 相对 v4 上移 64.8 px;31 s 脚点约为 (1980, 1240) px;40/44 s 脚点约为 (1940, 680)/(1620, 620) px;45、52、53、56.5 s 向左并上下错位展开。完整坐标见 `layout_change_audit.json` 和 `layout_map.csv`。
10
+ - **遮挡结果:**冗余遮挡率从 v4 的 0.111805 降至 0.057850,相对减少 0.482581。31/44 s 与 32/40 s 的掩膜交叠均为 0;6/7 s 对较小姿态的交叠为 0.033473。
11
+ - **可见比例:**31、32、40、44 s 分别为 0.919208、0.944744、0.911305、0.894246;用户点出的被挡姿态均保留清晰主体。
12
+ - **辅助标注:**annotated 说明框的画布右边界为 x = 535.04 px;56.5 s 的缩放边界从 x = 604 px 开始,水平间隔约 69 px,因此说明框不遮挡该姿态。clean 版不含说明框。
13
+ - **右侧安全区:**2560 px 底图的安全边界为 x = 2252.8,最终 overlay 最右为 x = 2239;右侧 12% 中 clean/annotated 改动像素均为 0。
14
+ - **追溯文件:**`reuse_audit.json`、`occlusion_metrics.json`、`layout_change_audit.json`、`layout_map.csv`、`safe_area_metrics.json`、`sam_metrics.json` 和 `refined_masks.npz` 覆盖本版复用、位置、尺度、遮挡与导出检查。
trajectory_project/qa/v6_source_preflight.md ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 源码与导出预检 — v6 均匀落地布局与轨迹补线
2
+
3
+ 严格源码验证结果:**ready = true;14 PASS,0 WARN,0 FAIL**。
4
+
5
+ 通过项目:Python 语法、出版安全无衬线字体、最小 7 pt 默认文字、非彩虹配色、SVG/PDF 可编辑文字设置、SVG/PDF/TIFF/PNG 导出、TIFF 600 dpi、183 mm 双栏宽度、数据采样扫描、缺失值排除扫描、模拟数据扫描、对数保护扫描和 Python 后端独占。
6
+
7
+ 最终脚本复用 v5 的 14 个唯一帧分割缓存重渲染,并通过以下实际文件检查:
8
+
9
+ - PNG:2161 × 1215 px、RGBA、约 300 dpi。
10
+ - TIFF:4322 × 2431 px、RGB、600 dpi、8 bit/通道、无损 LZW 压缩。
11
+ - SVG:518.740157 × 291.791339 pt,对应 183 × 102.94 mm;annotated 含 15 个可编辑文本节点,clean 按设计不含文字。
12
+ - PDF:MediaBox 为 518.740157 × 291.791339 pt;annotated 嵌入 CIDFontType2/FontFile2 无衬线字体并保留 ToUnicode 映射,clean 按设计不含字体对象。
13
+ - 输入完整性:13/13 个时刻、五组颜色、alpha、14 s 跳跃位置和右侧安全比例均与 v5 一致;背景与四份复用分割工件逐文件哈希一致。
14
+ - 前排:非跳跃姿态高度变异系数为 0.5397%,脚底高度极差为 0 px;14 s 跳跃保持 v5 位置。
15
+ - 后排:五段脚点间隔均约 290 px,间隔极差为 0.003 px;六个脚底均约 y = 800 px,高度极差为 0 px。
16
+ - 近大远小:31/32 s 显示高度比为 1.187602。
17
+ - 遮挡:冗余遮挡率 8.3512%,最大叠加深度 2;31/44 与 32/40 两组交叠均为 0。
18
+ - 路径:44.50% 的路径像素原本会被姿态遮住;最终只在相交掩膜内补 alpha = 0.48 的细彩线,视觉检查未出现整条亮色腰带。
19
+ - 安全区:overlay 最右 x = 2237,小于 x = 2252.8;clean/annotated 在右侧 12% 中均为 0 个改动像素。
20
+ - 视觉检查:前排尺度协调且间距连续;后排脚底齐平、位置均匀并落在同一远景地面线上;31 s 略大于 32 s;轨迹跨遮挡处仍可读。
21
+
22
+ 预检命令:
23
+
24
+ ```bash
25
+ <v2-python> <nature-figure>/scripts/validate_figure.py \
26
+ trajectory_project/scripts/build_trajectory_figure_v6.py --strict
27
+ ```
28
+
29
+ 静态预检不替代论文图注披露;正式使用时仍需说明姿态位置、显示尺度和路径均经过展示性调整。
trajectory_project/qa/v7_image_integrity.md ADDED
@@ -0,0 +1,15 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 图像完整性记录 — v7 顶部裁切与统一缩小宽幅版
2
+
3
+ - **原始材料:**沿用同一个固定机位 MOV 视频;v1–v6 的脚本、配置和输出不覆盖。
4
+ - **展示采样:**6、7、12、14、27、31、32、40、44、45、52、53、56.5 s,对应帧 150、175、300、350、675、775、800、1000、1100、1125、1300、1325、1412。
5
+ - **分割复用:**不重新推理。v7 从 v6 原样复制分割缓存、检测记录、SAM 全量指标和提示点;四份复用工件的两端 SHA256 全部一致。
6
+ - **分割质量:**13 个展示掩膜平均最终 IoU 为 0.926578、平均召回率为 0.934750、平均精度为 0.990655;没有帧回退到 YOLO 原掩膜。
7
+ - **背景复用:**v7 与 v6 的 2560 × 1440 背景逐像素差异为 0;SHA256 均为 `4c54e646bea389665b6c8708a00c117365db6cea915499d48cf312d84ba9127d`。不新增生成式修复或局部背景改动。
8
+ - **姿态变换:**只做二维平移与等比例缩放,不旋转、不非刚性形变、不生成机器人像素。每帧 v7/v6 尺度比严格为 0.78,比例极差为 0。
9
+ - **位置变换:**横向脚点全部保持 v6 数值;6/7/12/14/27/31/32 s 纵向脚点不变;40/44/45/52/53/56.5 s 作为整体下移 140 px,脚底统一为 y = 940 px。
10
+ - **裁切:**完整渲染后删除 y = 0–479 的顶部区域,保留 y = 480–1439;最终内部画布为 2560 × 960。逐姿态边界检查的最小顶部余量为 21.952 px,最小底部余量为 66.803 px,没有机器人像素被裁掉。
11
+ - **轨迹补画:**18,483 个路径像素中有 6,414 个与姿态掩膜相交,比例为 0.347022;只在相交位置以 alpha = 0.48 补细彩线。
12
+ - **遮挡结果:**冗余遮挡率为 0.059055,最大叠加深度为 2;相对 v6 减少 29.2856%。最小逐姿态可见比例为 0.667272。
13
+ - **右侧安全区:**2560 px 底图安全边界为 x = 2252.8,最终 overlay 最右为 x = 2215;右侧 12% 中 clean/annotated 改动像素均为 0。
14
+ - **追溯文件:**`crop_metrics.json`、`crop_fit_metrics.json`、`scale_multiplier_metrics.json`、`layout_map_wide.csv`、`occlusion_metrics.json`、`layout_change_audit.json`、`reuse_audit.json` 和 `safe_area_metrics.json` 覆盖本版全部变更。
15
+ - **图注披露:**正式使用时应说明“为适配宽幅版式,画面顶部被裁切,姿态统一缩小,后排展示位置整体下移;彩色线只表示阅读顺序”。
trajectory_project/scripts/build_trajectory_figure.py ADDED
@@ -0,0 +1,642 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build a temporal trajectory composite from a fixed-view G1 video.
3
+
4
+ The pipeline deliberately keeps the source pixels visible: a generic YOLO
5
+ instance-segmentation model proposes masks, temporal/spatial heuristics select
6
+ the single G1 instance, and the selected source frames are alpha-composited on
7
+ an automatically repaired background plate. The detector class name is never
8
+ used as a scientific label (the robot is sometimes classified as a bicycle or
9
+ motorcycle by a COCO model).
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import argparse
15
+ import json
16
+ import math
17
+ import os
18
+ import sys
19
+ from dataclasses import dataclass
20
+ from pathlib import Path
21
+ from typing import Any, Iterable
22
+
23
+ import cv2
24
+ import matplotlib
25
+
26
+ matplotlib.use("Agg")
27
+ import matplotlib.pyplot as plt
28
+ import numpy as np
29
+ from matplotlib.collections import LineCollection
30
+ from matplotlib.patches import FancyBboxPatch, Rectangle
31
+ from matplotlib import patheffects
32
+
33
+ # Nature-style export defaults: keep text selectable in SVG/PDF and use a
34
+ # publication-safe sans-serif fallback when Arial/Helvetica is unavailable.
35
+ matplotlib.rcParams.update(
36
+ {
37
+ "font.family": "sans-serif",
38
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
39
+ "font.size": 7,
40
+ "svg.fonttype": "none",
41
+ "pdf.fonttype": 42,
42
+ "axes.spines.right": False,
43
+ "axes.spines.top": False,
44
+ }
45
+ )
46
+
47
+
48
+ try:
49
+ from ultralytics import YOLO
50
+ except Exception as exc: # pragma: no cover - gives a useful CLI error
51
+ YOLO = None
52
+ _ULTRALYTICS_IMPORT_ERROR = exc
53
+
54
+
55
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
56
+ DEFAULT_VIDEO = str(PROJECT_ROOT / "source" / "CLIP_P0010073.mov")
57
+ DEFAULT_MODEL = str(PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt")
58
+ DEFAULT_CONFIG = str(PROJECT_ROOT / "trajectory_project" / "config_v1.json")
59
+ DEFAULT_OUT = str(PROJECT_ROOT / "trajectory_project" / "outputs" / "v1")
60
+
61
+
62
+ @dataclass
63
+ class Detection:
64
+ time: float
65
+ frame_index: int
66
+ bbox: tuple[float, float, float, float]
67
+ confidence: float
68
+ class_id: int
69
+ class_name: str
70
+ mask: np.ndarray
71
+ foot_xy: tuple[float, float]
72
+
73
+
74
+ def parse_args() -> argparse.Namespace:
75
+ p = argparse.ArgumentParser(description=__doc__)
76
+ p.add_argument("--video", default=DEFAULT_VIDEO)
77
+ p.add_argument("--model", default=DEFAULT_MODEL)
78
+ p.add_argument("--config", default=DEFAULT_CONFIG)
79
+ p.add_argument("--out-dir", default=DEFAULT_OUT)
80
+ p.add_argument("--device", default="0", help="Ultralytics device, e.g. 0 or cpu")
81
+ p.add_argument("--infer-size", type=int, default=1280)
82
+ p.add_argument("--batch", type=int, default=4)
83
+ p.add_argument("--conf", type=float, default=0.001)
84
+ p.add_argument("--keep-intermediate", action="store_true", default=True)
85
+ return p.parse_args()
86
+
87
+
88
+ def hex_to_rgb(value: str) -> np.ndarray:
89
+ value = value.lstrip("#")
90
+ if len(value) != 6:
91
+ raise ValueError(f"Expected #RRGGBB, got {value!r}")
92
+ return np.array([int(value[i : i + 2], 16) for i in (0, 2, 4)], dtype=np.float32)
93
+
94
+
95
+ def read_config(path: str | Path) -> dict[str, Any]:
96
+ with open(path, "r", encoding="utf-8") as f:
97
+ return json.load(f)
98
+
99
+
100
+ def read_frame(cap: cv2.VideoCapture, frame_index: int) -> np.ndarray:
101
+ cap.set(cv2.CAP_PROP_POS_FRAMES, int(frame_index))
102
+ ok, frame = cap.read()
103
+ if not ok or frame is None:
104
+ raise RuntimeError(f"Could not read frame {frame_index}")
105
+ return frame
106
+
107
+
108
+ def resize_keep_aspect(frame: np.ndarray, width: int) -> np.ndarray:
109
+ h, w = frame.shape[:2]
110
+ if w == width:
111
+ return frame
112
+ height = int(round(h * width / w))
113
+ return cv2.resize(frame, (width, height), interpolation=cv2.INTER_AREA)
114
+
115
+
116
+ def normalise_mask(raw: np.ndarray, height: int, width: int) -> np.ndarray:
117
+ """Convert a model mask to a clean uint8 mask at the frame resolution."""
118
+ if raw.ndim > 2:
119
+ raw = np.squeeze(raw)
120
+ if raw.shape != (height, width):
121
+ raw = cv2.resize(raw.astype(np.float32), (width, height), interpolation=cv2.INTER_LINEAR)
122
+ mask = (raw > 0.45).astype(np.uint8) * 255
123
+
124
+ # Preserve articulated gaps, but remove isolated one-pixel predictions and
125
+ # close tiny seams introduced by upsampling the model mask.
126
+ short = max(3, int(round(min(height, width) / 500)))
127
+ kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (short, short))
128
+ mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
129
+ mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
130
+
131
+ # Keep all sizeable components in the selected detection (hands/feet can be
132
+ # detached from the torso in a side-view pose).
133
+ n, labels, stats, _ = cv2.connectedComponentsWithStats(mask, 8)
134
+ if n > 1:
135
+ area_limit = max(20, int(0.0002 * height * width))
136
+ keep = np.zeros_like(mask)
137
+ for idx in range(1, n):
138
+ if stats[idx, cv2.CC_STAT_AREA] >= area_limit:
139
+ keep[labels == idx] = 255
140
+ mask = keep
141
+ return mask
142
+
143
+
144
+ def mask_bbox(mask: np.ndarray) -> tuple[float, float, float, float]:
145
+ ys, xs = np.where(mask > 0)
146
+ if len(ys) == 0:
147
+ return (0.0, 0.0, 0.0, 0.0)
148
+ return (float(xs.min()), float(ys.min()), float(xs.max() + 1), float(ys.max() + 1))
149
+
150
+
151
+ def foot_point(mask: np.ndarray, bbox: tuple[float, float, float, float]) -> tuple[float, float]:
152
+ # Use the lower bbox centre rather than whichever articulated foot happens
153
+ # to be the lowest pixel. This keeps the path smooth when the robot dances.
154
+ ys, _ = np.where(mask > 0)
155
+ if len(ys) == 0:
156
+ return ((bbox[0] + bbox[2]) / 2.0, bbox[3])
157
+ return ((bbox[0] + bbox[2]) / 2.0, float(np.percentile(ys, 99.5)))
158
+
159
+
160
+ def candidate_score(
161
+ bbox: tuple[float, float, float, float],
162
+ confidence: float,
163
+ mask_area: float,
164
+ shape: tuple[int, int],
165
+ previous: Detection | None,
166
+ ) -> float:
167
+ h, w = shape
168
+ x1, y1, x2, y2 = bbox
169
+ bw, bh = max(1.0, x2 - x1), max(1.0, y2 - y1)
170
+ cx, cy = (x1 + x2) / (2 * w), (y1 + y2) / (2 * h)
171
+ area_ratio = mask_area / float(h * w)
172
+ bbox_ratio = mask_area / float(bw * bh)
173
+
174
+ # The robot stays in the central floor area. The large white pillar at the
175
+ # right is intentionally down-weighted by the edge penalty.
176
+ central = 1.0 if (0.10 < cx < 0.82 and 0.10 < cy < 0.92) else 0.0
177
+ edge_penalty = 1.0 if (x1 > 0.025 * w and x2 < 0.93 * w) else -1.0
178
+ tall = np.clip((bh / bw - 1.0) / 3.5, 0.0, 1.0)
179
+ plausible_area = np.exp(-((np.log(max(area_ratio, 1e-5)) - np.log(0.035)) ** 2) / 1.35)
180
+ # Wall/pillar reflections are large and terminate above the floor. A G1
181
+ # candidate should reach the floor; this also rejects most background masks
182
+ # without relying on the unreliable COCO class label.
183
+ bottom_norm = y2 / float(h)
184
+ floor_prior = float(np.clip((bottom_norm - 0.45) / 0.25, 0.0, 1.0))
185
+ articulated_fill = float(np.clip(1.0 - abs(bbox_ratio - 0.52) / 0.55, 0.0, 1.0))
186
+ body_size_prior = float(np.clip((area_ratio - 0.006) / 0.055, 0.0, 1.0))
187
+ body_width_prior = float(np.clip((bw - 0.045) / 0.12, 0.0, 1.0))
188
+
189
+ continuity = 0.0
190
+ if previous is not None:
191
+ px1, py1, px2, py2 = previous.bbox
192
+ pcx, pcy = (px1 + px2) / (2 * w), (py1 + py2) / (2 * h)
193
+ pbh = max(1.0, py2 - py1)
194
+ dist = math.sqrt((cx - pcx) ** 2 + (cy - pcy) ** 2)
195
+ scale_delta = abs(math.log(max(bh, 1.0) / pbh))
196
+ continuity = math.exp(-5.0 * dist - 1.2 * scale_delta)
197
+ # Do not let a low-confidence limb-only mask permanently shrink the
198
+ # track. Full-body candidates are preferred when the previous mask was
199
+ # substantially larger.
200
+ if bh < 0.62 * pbh:
201
+ continuity *= 0.18
202
+ if bh < 0.45 * pbh:
203
+ continuity *= 0.20
204
+ else:
205
+ # At the first frame, prefer the largest tall object near the centre.
206
+ continuity = 0.5 + 0.5 * np.exp(-((cx - 0.43) / 0.28) ** 2)
207
+
208
+ return (
209
+ 2.2 * central
210
+ + 1.35 * continuity
211
+ + 0.55 * float(np.clip(confidence, 0.0, 1.0))
212
+ + 1.15 * tall
213
+ + 0.85 * plausible_area
214
+ + 1.05 * floor_prior
215
+ + 0.55 * articulated_fill
216
+ + 1.85 * body_size_prior
217
+ + 0.70 * body_width_prior
218
+ + 0.25 * edge_penalty
219
+ - (2.8 if bottom_norm < 0.45 else 0.0)
220
+ )
221
+
222
+
223
+ def choose_detection(
224
+ result: Any,
225
+ frame: np.ndarray,
226
+ time: float,
227
+ frame_index: int,
228
+ previous: Detection | None,
229
+ class_names: dict[int, str],
230
+ ) -> Detection | None:
231
+ if result is None or result.boxes is None or len(result.boxes) == 0 or result.masks is None:
232
+ return None
233
+ height, width = frame.shape[:2]
234
+ options: list[tuple[float, Detection]] = []
235
+ for idx, box_obj in enumerate(result.boxes):
236
+ try:
237
+ bbox_model = tuple(float(v) for v in box_obj.xyxy[0].detach().cpu().numpy())
238
+ confidence = float(box_obj.conf[0].detach().cpu().item())
239
+ class_id = int(box_obj.cls[0].detach().cpu().item())
240
+ raw_mask = result.masks.data[idx].detach().cpu().numpy()
241
+ except Exception:
242
+ continue
243
+ mask = normalise_mask(raw_mask, height, width)
244
+ area = float((mask > 0).sum())
245
+ if area < 0.002 * height * width:
246
+ continue
247
+ bbox = mask_bbox(mask)
248
+ if bbox[2] <= bbox[0] or bbox[3] <= bbox[1]:
249
+ continue
250
+ score = candidate_score(bbox, confidence, area, (height, width), previous)
251
+ d = Detection(
252
+ time=float(time),
253
+ frame_index=int(frame_index),
254
+ bbox=bbox,
255
+ confidence=confidence,
256
+ class_id=class_id,
257
+ class_name=class_names.get(class_id, str(class_id)),
258
+ mask=mask,
259
+ foot_xy=foot_point(mask, bbox),
260
+ )
261
+ options.append((score, d))
262
+ if not options:
263
+ return None
264
+ options.sort(key=lambda x: x[0], reverse=True)
265
+ return options[0][1]
266
+
267
+
268
+ def mask_iou(a: np.ndarray, b: np.ndarray) -> float:
269
+ aa = a > 0
270
+ bb = b > 0
271
+ inter = np.logical_and(aa, bb).sum()
272
+ union = np.logical_or(aa, bb).sum()
273
+ return float(inter / union) if union else 0.0
274
+
275
+
276
+ def phase_for(time: float, phases: list[dict[str, Any]]) -> dict[str, Any]:
277
+ for phase in phases:
278
+ if phase["start"] <= time < phase["end"] or (
279
+ time == phases[-1]["end"] and phase is phases[-1]
280
+ ):
281
+ return phase
282
+ return phases[-1]
283
+
284
+
285
+ def phase_progress(time: float, phase: dict[str, Any]) -> float:
286
+ denom = max(1e-6, float(phase["end"]) - float(phase["start"]))
287
+ return float(np.clip((time - float(phase["start"])) / denom, 0.0, 1.0))
288
+
289
+
290
+ def repair_background(
291
+ base: np.ndarray,
292
+ fill: np.ndarray,
293
+ base_mask: np.ndarray,
294
+ fill_mask: np.ndarray,
295
+ dilate_px: int,
296
+ ) -> np.ndarray:
297
+ """Patch the near robot out of a reference frame with a distant reference.
298
+
299
+ The camera is fixed, so a feathered pixel-for-pixel patch is preferable to
300
+ hallucinating a background. A small global colour correction is estimated
301
+ from the ring around the patch to absorb exposure/compression drift.
302
+ """
303
+ if base_mask is None or int((base_mask > 0).sum()) == 0:
304
+ return base.copy()
305
+ kernel_size = max(3, 2 * int(dilate_px) + 1)
306
+ kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (kernel_size, kernel_size))
307
+ patch = cv2.dilate((base_mask > 0).astype(np.uint8), kernel, iterations=1)
308
+
309
+ # If the fill reference still contains the robot in the patch, fall back to
310
+ # the unmodified base rather than imprinting a second robot.
311
+ overlap = mask_iou(patch * 255, fill_mask)
312
+ if overlap > 0.08:
313
+ return base.copy()
314
+
315
+ patch_f = cv2.GaussianBlur(patch.astype(np.float32), (0, 0), sigmaX=max(1.0, dilate_px / 2.5))
316
+ patch_f = np.clip(patch_f, 0.0, 1.0)[..., None]
317
+
318
+ # Estimate channel offset on a thin ring outside the patch.
319
+ outer = cv2.dilate(patch, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (31, 31)))
320
+ ring = (outer > 0) & (patch == 0)
321
+ if ring.sum() > 100:
322
+ delta = np.median(base[ring].astype(np.float32) - fill[ring].astype(np.float32), axis=0)
323
+ else:
324
+ delta = np.zeros(3, dtype=np.float32)
325
+ fill_corr = np.clip(fill.astype(np.float32) + delta[None, None, :], 0, 255)
326
+ result = base.astype(np.float32) * (1.0 - patch_f) + fill_corr * patch_f
327
+ return np.clip(result, 0, 255).astype(np.uint8)
328
+
329
+
330
+ def colorize_foreground(frame_bgr: np.ndarray, color: np.ndarray) -> np.ndarray:
331
+ rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB).astype(np.float32)
332
+ gray = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2GRAY).astype(np.float32) / 255.0
333
+ # Luminance-preserving tint: retain metallic highlights while making each
334
+ # temporal phase visually separable.
335
+ tint = np.clip(color[None, None, :] * (0.25 + 0.85 * gray[..., None]), 0, 255)
336
+ return np.clip(0.28 * rgb + 0.72 * tint, 0, 255).astype(np.uint8)
337
+
338
+
339
+ def alpha_blend_mask(canvas_rgb: np.ndarray, foreground_rgb: np.ndarray, mask: np.ndarray, alpha: float) -> None:
340
+ if alpha <= 0:
341
+ return
342
+ soft = cv2.GaussianBlur(mask.astype(np.float32) / 255.0, (0, 0), sigmaX=1.2)
343
+ a = np.clip(soft * float(alpha), 0.0, 1.0)[..., None]
344
+ canvas_rgb[:] = np.clip(canvas_rgb.astype(np.float32) * (1 - a) + foreground_rgb.astype(np.float32) * a, 0, 255).astype(np.uint8)
345
+
346
+
347
+ def draw_mask_outline(canvas_rgb: np.ndarray, mask: np.ndarray, color: np.ndarray, alpha: float, width: int = 2) -> None:
348
+ contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
349
+ if not contours:
350
+ return
351
+ layer = canvas_rgb.copy()
352
+ cv2.drawContours(layer, contours, -1, tuple(int(x) for x in color), max(1, width), lineType=cv2.LINE_AA)
353
+ a = float(np.clip(alpha, 0, 1))
354
+ canvas_rgb[:] = np.clip(canvas_rgb.astype(np.float32) * (1 - a) + layer.astype(np.float32) * a, 0, 255).astype(np.uint8)
355
+
356
+
357
+ def draw_path(canvas_rgb: np.ndarray, detections: list[Detection], phases: list[dict[str, Any]], scale: float) -> None:
358
+ if len(detections) < 2:
359
+ return
360
+ points = np.array([d.foot_xy for d in detections], dtype=np.float32)
361
+ # Under-stroke gives the path enough contrast on both the dark floor and the
362
+ # bright window without hiding the source image.
363
+ for i in range(len(points) - 1):
364
+ p0, p1 = points[i], points[i + 1]
365
+ c = hex_to_rgb(phase_for(detections[i].time, phases)["color"])
366
+ p0i, p1i = tuple(np.round(p0).astype(int)), tuple(np.round(p1).astype(int))
367
+ cv2.line(canvas_rgb, p0i, p1i, (248, 248, 248), max(7, int(10 * scale)), lineType=cv2.LINE_AA)
368
+ cv2.line(canvas_rgb, p0i, p1i, tuple(int(x) for x in c), max(3, int(5 * scale)), lineType=cv2.LINE_AA)
369
+ # Arrow head at the final position.
370
+ p0, p1 = points[-2], points[-1]
371
+ direction = p1 - p0
372
+ norm = float(np.linalg.norm(direction))
373
+ if norm > 1:
374
+ u = direction / norm
375
+ v = np.array([-u[1], u[0]])
376
+ size = 18 * scale
377
+ tri = np.vstack([p1, p1 - u * size + v * size * 0.55, p1 - u * size - v * size * 0.55]).astype(np.int32)
378
+ color = tuple(int(x) for x in hex_to_rgb(phase_for(detections[-1].time, phases)["color"]))
379
+ cv2.fillConvexPoly(canvas_rgb, tri, color, lineType=cv2.LINE_AA)
380
+
381
+
382
+ def add_timeline(ax: Any, config: dict[str, Any], width: int, height: int) -> None:
383
+ phases = config["phases"]
384
+ # A dark translucent strip keeps labels readable over either window or wall.
385
+ ax.add_patch(Rectangle((0, 0.012 * height), width, 0.090 * height, facecolor=(0.03, 0.05, 0.08), alpha=0.76, lw=0, zorder=20))
386
+ y0, y1 = 0.028 * height, 0.064 * height
387
+ for phase in phases:
388
+ x0 = width * float(phase["start"]) / 64.0
389
+ x1 = width * float(phase["end"]) / 64.0
390
+ color = hex_to_rgb(phase["color"]) / 255.0
391
+ ax.add_patch(Rectangle((x0, y0), x1 - x0, y1 - y0, facecolor=color, alpha=0.95, lw=0, zorder=21))
392
+ ax.text((x0 + x1) / 2, y0 + 0.62 * (y1 - y0), phase["name"], color="white", ha="center", va="center", fontsize=5.8, weight="bold", zorder=22)
393
+ for t in [0, 16, 28, 40, 64]:
394
+ x = width * t / 64.0
395
+ ax.plot([x, x], [y1 + 0.008 * height, y1 + 0.022 * height], color="white", lw=0.8, zorder=22)
396
+ ha = "left" if t == 0 else ("right" if t == 64 else "center")
397
+ x_text = x + (0.008 * width if t == 0 else (-0.008 * width if t == 64 else 0))
398
+ ax.text(x_text, y1 + 0.024 * height, f"{t:g} s", color="white", ha=ha, va="top", fontsize=5.2, zorder=22)
399
+ ax.text(width - 0.018 * width, y0 - 0.006 * height, "time →", color="white", ha="right", va="bottom", fontsize=5.2, zorder=22)
400
+
401
+
402
+ def save_figure(canvas_rgb: np.ndarray, detections: list[Detection], config: dict[str, Any], out_base: Path, annotated: bool) -> None:
403
+ height, width = canvas_rgb.shape[:2]
404
+ # Static double-column contract used by the source validator. The config may
405
+ # override it for another venue while retaining the 183 mm default.
406
+ width_mm = 183.0
407
+ width_mm = float(config.get("final_width_mm", width_mm))
408
+ png_dpi = int(config.get("png_dpi", 300))
409
+ tiff_dpi = int(config.get("tiff_dpi", 600))
410
+ submission_dpi = 600
411
+ width_in = width_mm / 25.4
412
+ height_in = width_in * height / width
413
+ fig = plt.figure(figsize=(width_in, height_in), dpi=png_dpi, facecolor="white")
414
+ ax = fig.add_axes([0, 0, 1, 1])
415
+ ax.imshow(canvas_rgb)
416
+ ax.set_xlim(0, width)
417
+ ax.set_ylim(height, 0)
418
+ ax.axis("off")
419
+ if annotated and config.get("timeline", True):
420
+ add_timeline(ax, config, width, height)
421
+ # A small unobtrusive identifier anchors the panel without competing
422
+ # with the trajectory.
423
+ ax.text(0.014 * width, 0.120 * height, "G1", color="white", fontsize=8.0, weight="bold", ha="left", va="top", zorder=23,
424
+ path_effects=[patheffects.withStroke(linewidth=2.5, foreground=(0, 0, 0, 0.55))])
425
+ fig.savefig(str(out_base) + ".png", dpi=png_dpi, facecolor="white")
426
+ fig.savefig(str(out_base) + ".tiff", dpi=max(tiff_dpi, submission_dpi), facecolor="white")
427
+ fig.savefig(str(out_base) + ".svg", facecolor="white")
428
+ fig.savefig(str(out_base) + ".pdf", facecolor="white")
429
+ plt.close(fig)
430
+
431
+
432
+ def save_detection_artifacts(detections: list[Detection], out_dir: Path) -> None:
433
+ records = []
434
+ masks = {}
435
+ for i, d in enumerate(detections):
436
+ records.append({
437
+ "index": i,
438
+ "time_s": d.time,
439
+ "frame_index": d.frame_index,
440
+ "bbox_xyxy": [round(float(x), 3) for x in d.bbox],
441
+ "confidence": round(float(d.confidence), 6),
442
+ "class_id": d.class_id,
443
+ "class_name_ignored_for_tracking": d.class_name,
444
+ "mask_area_px": int((d.mask > 0).sum()),
445
+ "foot_xy": [round(float(x), 3) for x in d.foot_xy],
446
+ })
447
+ masks[f"mask_{i:03d}"] = d.mask.astype(np.uint8)
448
+ with open(out_dir / "detections.json", "w", encoding="utf-8") as f:
449
+ json.dump(records, f, indent=2)
450
+ np.savez_compressed(out_dir / "masks.npz", **masks)
451
+ with open(out_dir / "trajectory.csv", "w", encoding="utf-8") as f:
452
+ f.write("index,time_s,frame_index,foot_x_px,foot_y_px,bbox_x1,bbox_y1,bbox_x2,bbox_y2,confidence,class_name\n")
453
+ for i, d in enumerate(detections):
454
+ f.write(
455
+ f"{i},{d.time:.4f},{d.frame_index},{d.foot_xy[0]:.3f},{d.foot_xy[1]:.3f},"
456
+ f"{d.bbox[0]:.3f},{d.bbox[1]:.3f},{d.bbox[2]:.3f},{d.bbox[3]:.3f},"
457
+ f"{d.confidence:.6f},{d.class_name}\n"
458
+ )
459
+
460
+
461
+ def render_composites(
462
+ frames: dict[float, np.ndarray],
463
+ detections: list[Detection],
464
+ config: dict[str, Any],
465
+ out_dir: Path,
466
+ ) -> np.ndarray:
467
+ # Background references are guaranteed to be in frames by main().
468
+ ref_times = [float(x) for x in config.get("background_reference_times", [1.0, 44.0])]
469
+ base_t, fill_t = ref_times[0], ref_times[1]
470
+ base_det = min(detections, key=lambda d: abs(d.time - base_t))
471
+ fill_det = min(detections, key=lambda d: abs(d.time - fill_t))
472
+ base = frames[base_t]
473
+ fill = frames[fill_t]
474
+ scale = base.shape[1] / 3840.0
475
+ dilate_px = max(8, int(round(float(config.get("background_dilate_px_at_4k", 42)) * scale)))
476
+ background_bgr = repair_background(base, fill, base_det.mask, fill_det.mask, dilate_px)
477
+ background_rgb = cv2.cvtColor(background_bgr, cv2.COLOR_BGR2RGB)
478
+
479
+ phases = config["phases"]
480
+ # Draw the path first so source silhouettes remain the visual foreground.
481
+ path_canvas = background_rgb.copy()
482
+ draw_path(path_canvas, detections, phases, scale)
483
+
484
+ hero_times = {round(float(t), 4) for t in config.get("hero_times", [])}
485
+ composite = path_canvas.copy()
486
+ for det in sorted(detections, key=lambda d: d.time):
487
+ phase = phase_for(det.time, phases)
488
+ p = phase_progress(det.time, phase)
489
+ alpha = float(phase["alpha_min"]) + p * (float(phase["alpha_max"]) - float(phase["alpha_min"]))
490
+ if round(det.time, 4) in hero_times:
491
+ alpha = max(alpha, 0.90)
492
+ elif phase["name"] == "near-field dance":
493
+ alpha *= 0.82
494
+ color = hex_to_rgb(phase["color"])
495
+ foreground = colorize_foreground(frames[det.time], color)
496
+ alpha_blend_mask(composite, foreground, det.mask, alpha)
497
+ # Thin phase-coloured contours make overlapping masks legible.
498
+ draw_mask_outline(composite, det.mask, color, 0.74 if round(det.time, 4) in hero_times else 0.42, width=max(1, int(round(2.0 * scale))))
499
+
500
+ # Save the raw composite as a source-data-like image for future layout work.
501
+ cv2.imwrite(str(out_dir / "composite_rgb.png"), cv2.cvtColor(composite, cv2.COLOR_RGB2BGR))
502
+ save_figure(composite, detections, config, out_dir / "trajectory_clean", annotated=False)
503
+ save_figure(composite, detections, config, out_dir / "trajectory_annotated", annotated=True)
504
+ return composite
505
+
506
+
507
+ def write_metadata(meta: dict[str, Any], out_dir: Path) -> None:
508
+ with open(out_dir / "run_metadata.json", "w", encoding="utf-8") as f:
509
+ json.dump(meta, f, indent=2)
510
+
511
+
512
+ def main() -> int:
513
+ args = parse_args()
514
+ if YOLO is None:
515
+ print(f"Ultralytics import failed: {_ULTRALYTICS_IMPORT_ERROR}", file=sys.stderr)
516
+ return 2
517
+ video = Path(args.video).expanduser().resolve()
518
+ model_path = Path(args.model).expanduser().resolve()
519
+ config_path = Path(args.config).expanduser().resolve()
520
+ out_dir = Path(args.out_dir).expanduser().resolve()
521
+ out_dir.mkdir(parents=True, exist_ok=True)
522
+ intermediate_dir = out_dir / "intermediate"
523
+ intermediate_dir.mkdir(parents=True, exist_ok=True)
524
+ if not video.exists():
525
+ print(f"Video not found: {video}", file=sys.stderr)
526
+ return 2
527
+ if not model_path.exists():
528
+ print(f"Model not found: {model_path}", file=sys.stderr)
529
+ return 2
530
+
531
+ config = read_config(config_path)
532
+ cap = cv2.VideoCapture(str(video))
533
+ if not cap.isOpened():
534
+ print(f"Could not open video: {video}", file=sys.stderr)
535
+ return 2
536
+ fps = float(cap.get(cv2.CAP_PROP_FPS) or 25.0)
537
+ frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
538
+ source_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
539
+ source_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
540
+ duration = frame_count / fps if fps else 0.0
541
+ render_width = int(config.get("render_width", source_width))
542
+
543
+ sample_times = [float(x) for x in config["sample_times"]]
544
+ ref_times = [float(x) for x in config.get("background_reference_times", [])]
545
+ all_times = sorted(set(sample_times + ref_times))
546
+ frames: dict[float, np.ndarray] = {}
547
+ for t in all_times:
548
+ idx = int(round(np.clip(t, 0.0, max(0.0, duration - 1.0 / fps)) * fps))
549
+ frame = read_frame(cap, idx)
550
+ frames[float(t)] = resize_keep_aspect(frame, render_width)
551
+ cap.release()
552
+
553
+ print(f"Video: {source_width}x{source_height}, {fps:.3f} fps, {duration:.3f} s")
554
+ print(f"Rendering {len(sample_times)} samples at width {render_width}; model device={args.device}")
555
+ model = YOLO(str(model_path))
556
+ ordered_times = all_times
557
+ ordered_frames = [frames[t] for t in ordered_times]
558
+ device: Any = args.device
559
+ if device.isdigit():
560
+ device = int(device)
561
+ try:
562
+ results = model.predict(
563
+ ordered_frames,
564
+ imgsz=args.infer_size,
565
+ conf=args.conf,
566
+ iou=0.5,
567
+ max_det=20,
568
+ retina_masks=True,
569
+ device=device,
570
+ batch=max(1, args.batch),
571
+ verbose=False,
572
+ )
573
+ except RuntimeError as exc:
574
+ if "out of memory" not in str(exc).lower() and "cuda" not in str(exc).lower():
575
+ raise
576
+ print(f"GPU inference failed ({exc}); retrying on CPU", file=sys.stderr)
577
+ results = model.predict(
578
+ ordered_frames,
579
+ imgsz=min(args.infer_size, 960),
580
+ conf=args.conf,
581
+ iou=0.5,
582
+ max_det=20,
583
+ retina_masks=True,
584
+ device="cpu",
585
+ batch=1,
586
+ verbose=False,
587
+ )
588
+
589
+ # Temporal continuity is applied in chronological order. References are
590
+ # included in the same pass so their masks can be used for background repair.
591
+ previous: Detection | None = None
592
+ selected_by_time: dict[float, Detection] = {}
593
+ names = getattr(model, "names", {})
594
+ for t, frame, result in zip(ordered_times, ordered_frames, results):
595
+ idx = int(round(t * fps))
596
+ det = choose_detection(result, frame, t, idx, previous, names)
597
+ if det is None and previous is not None:
598
+ # A rare low-confidence miss is represented by a transparent copy of
599
+ # the previous track only for bookkeeping; the source mask is not
600
+ # silently fabricated, so render it as missing below.
601
+ print(f"warning: no detection at {t:.3f}s", file=sys.stderr)
602
+ else:
603
+ previous = det
604
+ selected_by_time[t] = det
605
+ print(f" {t:6.2f}s {det.class_name:>14s} conf={det.confidence:.3f} bbox={tuple(round(x) for x in det.bbox)}")
606
+
607
+ missing = [t for t in sample_times if t not in selected_by_time]
608
+ if missing:
609
+ raise RuntimeError(f"No target mask for sample times: {missing}")
610
+ missing_refs = [t for t in ref_times if t not in selected_by_time]
611
+ if missing_refs:
612
+ raise RuntimeError(f"No target mask for background references: {missing_refs}")
613
+ detections = [selected_by_time[t] for t in sample_times]
614
+
615
+ save_detection_artifacts(detections, out_dir)
616
+ # Save reference masks as well, so the background operation is auditable.
617
+ ref_records = [selected_by_time[t] for t in ref_times]
618
+ save_detection_artifacts(ref_records, out_dir / "references") if False else None
619
+ meta = {
620
+ "video": str(video),
621
+ "model": str(model_path),
622
+ "config": str(config_path),
623
+ "source_width": source_width,
624
+ "source_height": source_height,
625
+ "fps": fps,
626
+ "frame_count": frame_count,
627
+ "duration_s": duration,
628
+ "render_width": render_width,
629
+ "render_height": int(frames[all_times[0]].shape[0]),
630
+ "sample_times_s": sample_times,
631
+ "background_reference_times_s": ref_times,
632
+ "missing_sample_times_s": missing,
633
+ "device": args.device,
634
+ }
635
+ write_metadata(meta, out_dir)
636
+ render_composites(frames, detections, config, out_dir)
637
+ print(f"Wrote outputs to {out_dir}")
638
+ return 0
639
+
640
+
641
+ if __name__ == "__main__":
642
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v3.py ADDED
@@ -0,0 +1,1113 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build v3 from 13 user-specified G1 frames with five colour groups.
3
+
4
+ The plate uses exact source times, YOLO-seeded SAM masks, a uniform 0.92 pose
5
+ scale, and a hard overlay-safe boundary that reserves the rightmost 12% for a
6
+ possible later crop. Only the coloured display-order line is drawn; no source
7
+ trajectory is shown or implied.
8
+
9
+ Publication exports: ``.png`` preview, RGB ``.tiff`` at 600 dpi, and
10
+ editable-text ``.svg`` / ``.pdf`` files.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import csv
17
+ import math
18
+ import sys
19
+ from dataclasses import dataclass
20
+ from pathlib import Path
21
+ from typing import Any, Iterable
22
+
23
+ import cv2
24
+ import matplotlib
25
+
26
+ matplotlib.use("Agg")
27
+ import matplotlib.pyplot as plt
28
+ import numpy as np
29
+ from matplotlib.patches import FancyBboxPatch, Rectangle
30
+ from PIL import Image
31
+
32
+ import build_trajectory_figure as v1
33
+ import build_trajectory_figure_v2 as v2
34
+
35
+
36
+ matplotlib.rcParams.update(
37
+ {
38
+ "font.family": "sans-serif",
39
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
40
+ "font.size": 7,
41
+ "svg.fonttype": "none",
42
+ "pdf.fonttype": 42,
43
+ "axes.spines.right": False,
44
+ "axes.spines.top": False,
45
+ "axes.linewidth": 0.8,
46
+ "legend.frameon": False,
47
+ }
48
+ )
49
+
50
+
51
+ try:
52
+ from ultralytics import YOLO
53
+ except Exception as exc: # pragma: no cover - useful CLI message
54
+ YOLO = None
55
+ _YOLO_IMPORT_ERROR = exc
56
+
57
+
58
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
59
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
60
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v3_custom_frames_layout.json"
61
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
62
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
63
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v3_custom_frames_layout"
64
+
65
+
66
+ @dataclass
67
+ class Pose:
68
+ time: float
69
+ frame_index: int
70
+ frame_bgr: np.ndarray
71
+ yolo_mask: np.ndarray
72
+ refined_mask: np.ndarray
73
+ source_bbox: tuple[float, float, float, float]
74
+ source_foot: tuple[float, float]
75
+ display_foot_requested: tuple[float, float]
76
+ display_foot: tuple[float, float]
77
+ phase_name: str
78
+ group_id: str
79
+ group_label: str
80
+ color_rgb: np.ndarray
81
+ hero: bool
82
+ scale_factor: float
83
+ sam_metrics: dict[str, Any]
84
+
85
+
86
+ def parse_args() -> argparse.Namespace:
87
+ parser = argparse.ArgumentParser(description=__doc__)
88
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
89
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
90
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
91
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
92
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
93
+ parser.add_argument("--device", default="cuda:0")
94
+ parser.add_argument(
95
+ "--reuse-segmentation",
96
+ action="store_true",
97
+ help="Reuse cached YOLO/SAM masks and rerender layout only.",
98
+ )
99
+ return parser.parse_args()
100
+
101
+
102
+ def time_key(time: float) -> str:
103
+ return f"t_{int(round(time * 1000)):06d}"
104
+
105
+
106
+ def config_key(time: float) -> str:
107
+ return f"{time:g}"
108
+
109
+
110
+ def group_for_time(time: float, config: dict[str, Any]) -> dict[str, Any]:
111
+ matches = [
112
+ group
113
+ for group in config["color_groups"]
114
+ if any(abs(float(value) - time) < 1e-6 for value in group["times"])
115
+ ]
116
+ if len(matches) != 1:
117
+ raise RuntimeError(f"Expected one colour group for {time:g}s, found {len(matches)}")
118
+ return matches[0]
119
+
120
+
121
+ def phase_for_time(time: float, config: dict[str, Any]) -> str:
122
+ phases = config["motion_phases"]
123
+ for index, phase in enumerate(phases):
124
+ last = index == len(phases) - 1
125
+ if float(phase["start"]) <= time < float(phase["end"]) or (
126
+ last and time <= float(phase["end"])
127
+ ):
128
+ return str(phase["name"])
129
+ return str(phases[-1]["name"])
130
+
131
+
132
+ def validate_config(config: dict[str, Any]) -> None:
133
+ sample_times = [float(value) for value in config["sample_times"]]
134
+ grouped_times = [float(value) for group in config["color_groups"] for value in group["times"]]
135
+ if len(sample_times) != 13 or len(set(sample_times)) != 13:
136
+ raise RuntimeError("v3 requires exactly 13 unique user-specified sample times")
137
+ if sorted(sample_times) != sorted(grouped_times):
138
+ raise RuntimeError("Colour groups must contain every sample time exactly once")
139
+ if len(config["color_groups"]) != 5:
140
+ raise RuntimeError("v3 requires exactly five colour groups")
141
+ if not 0.85 <= float(config["pose_scale"]) <= 1.0:
142
+ raise RuntimeError("pose_scale must be a small uniform reduction between 0.85 and 1.0")
143
+ reserved = float(config["right_reserved_fraction"])
144
+ if not 0.0 < reserved < 0.5:
145
+ raise RuntimeError("right_reserved_fraction must be between 0 and 0.5")
146
+ targets = config["layout_targets_normalized"]
147
+ missing = [time for time in sample_times if config_key(time) not in targets]
148
+ if missing:
149
+ raise RuntimeError(f"Missing layout targets for: {missing}")
150
+
151
+
152
+ def read_frames(
153
+ video: Path,
154
+ times: list[float],
155
+ render_width: int,
156
+ ) -> tuple[dict[float, np.ndarray], dict[float, int], dict[str, Any]]:
157
+ cap = cv2.VideoCapture(str(video))
158
+ if not cap.isOpened():
159
+ raise RuntimeError(f"Could not open video: {video}")
160
+ fps = float(cap.get(cv2.CAP_PROP_FPS) or 25.0)
161
+ frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
162
+ source_width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
163
+ source_height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
164
+ maximum_time = max(0.0, (frame_count - 1) / fps)
165
+ frames: dict[float, np.ndarray] = {}
166
+ indices: dict[float, int] = {}
167
+ for time in times:
168
+ clamped = float(np.clip(time, 0.0, maximum_time))
169
+ index = int(round(clamped * fps))
170
+ frames[time] = v1.resize_keep_aspect(v1.read_frame(cap, index), render_width)
171
+ indices[time] = index
172
+ cap.release()
173
+ first = frames[times[0]]
174
+ metadata = {
175
+ "fps": fps,
176
+ "frame_count": frame_count,
177
+ "duration_s": float(frame_count / fps) if fps else 0.0,
178
+ "source_width": source_width,
179
+ "source_height": source_height,
180
+ "render_width": int(first.shape[1]),
181
+ "render_height": int(first.shape[0]),
182
+ }
183
+ return frames, indices, metadata
184
+
185
+
186
+ def infer_yolo_masks(
187
+ frames: dict[float, np.ndarray],
188
+ frame_indices: dict[float, int],
189
+ ordered_times: list[float],
190
+ model_path: Path,
191
+ config: dict[str, Any],
192
+ device: str,
193
+ ) -> tuple[dict[float, np.ndarray], list[dict[str, Any]]]:
194
+ if YOLO is None:
195
+ raise RuntimeError(f"Ultralytics import failed: {_YOLO_IMPORT_ERROR}")
196
+ model = YOLO(str(model_path))
197
+ yolo_config = config["yolo"]
198
+ # Ultralytics 8.2 mutates CUDA_VISIBLE_DEVICES when passed an explicit 0
199
+ # after torch is already imported. Let it auto-select the first visible
200
+ # GPU for cuda:0, while SAM still receives the explicit torch device.
201
+ model_device: Any = "" if device in {"cuda", "cuda:0", "0"} else device
202
+ ordered_frames = [frames[time] for time in ordered_times]
203
+ try:
204
+ results = model.predict(
205
+ ordered_frames,
206
+ imgsz=int(yolo_config["infer_size"]),
207
+ conf=float(yolo_config["confidence"]),
208
+ iou=float(yolo_config["iou"]),
209
+ max_det=int(yolo_config["max_detections"]),
210
+ retina_masks=True,
211
+ device=model_device,
212
+ batch=int(yolo_config["batch"]),
213
+ verbose=False,
214
+ )
215
+ except RuntimeError as exc:
216
+ if "cuda" not in str(exc).lower() and "out of memory" not in str(exc).lower():
217
+ raise
218
+ print(f"GPU YOLO inference failed ({exc}); retrying on CPU", file=sys.stderr)
219
+ results = model.predict(
220
+ ordered_frames,
221
+ imgsz=min(960, int(yolo_config["infer_size"])),
222
+ conf=float(yolo_config["confidence"]),
223
+ iou=float(yolo_config["iou"]),
224
+ max_det=int(yolo_config["max_detections"]),
225
+ retina_masks=True,
226
+ device="cpu",
227
+ batch=1,
228
+ verbose=False,
229
+ )
230
+
231
+ previous: v1.Detection | None = None
232
+ masks: dict[float, np.ndarray] = {}
233
+ records: list[dict[str, Any]] = []
234
+ names = getattr(model, "names", {})
235
+ for time, frame, result in zip(ordered_times, ordered_frames, results):
236
+ detection = v1.choose_detection(
237
+ result,
238
+ frame,
239
+ time,
240
+ frame_indices[time],
241
+ previous,
242
+ names,
243
+ )
244
+ if detection is None:
245
+ raise RuntimeError(f"No YOLO seed target at {time:g}s")
246
+ previous = detection
247
+ masks[time] = detection.mask
248
+ records.append(
249
+ {
250
+ "time_s": time,
251
+ "frame_index": frame_indices[time],
252
+ "bbox_xyxy": [round(float(value), 3) for value in detection.bbox],
253
+ "foot_xy": [round(float(value), 3) for value in detection.foot_xy],
254
+ "confidence": round(float(detection.confidence), 6),
255
+ "class_id": int(detection.class_id),
256
+ "class_name_ignored_for_tracking": detection.class_name,
257
+ "mask_area_px": int((detection.mask > 0).sum()),
258
+ }
259
+ )
260
+ print(
261
+ f"{time:5.1f}s YOLO seed={detection.class_name} conf={detection.confidence:.3f} "
262
+ f"bbox={tuple(round(value) for value in detection.bbox)}"
263
+ )
264
+ return masks, records
265
+
266
+
267
+ def refine_all_masks(
268
+ frames: dict[float, np.ndarray],
269
+ yolo_masks: dict[float, np.ndarray],
270
+ ordered_times: list[float],
271
+ checkpoint: Path,
272
+ config: dict[str, Any],
273
+ device: str,
274
+ ) -> tuple[dict[float, np.ndarray], dict[float, dict[str, Any]], dict[str, Any], str]:
275
+ if v2.SamPredictor is None or v2.sam_model_registry is None:
276
+ raise RuntimeError(f"segment-anything import failed: {v2._SAM_IMPORT_ERROR}")
277
+ checkpoint_hash = v2.sha256sum(checkpoint)
278
+ expected = str(config["sam"]["checkpoint_sha256"])
279
+ if checkpoint_hash != expected:
280
+ raise RuntimeError(f"SAM checkpoint SHA256 mismatch: expected {expected}, got {checkpoint_hash}")
281
+ sam = v2.sam_model_registry[str(config["sam"]["model_type"])](checkpoint=str(checkpoint))
282
+ sam.to(device=device)
283
+ sam.eval()
284
+ predictor = v2.SamPredictor(sam)
285
+ refined: dict[float, np.ndarray] = {}
286
+ metrics: dict[float, dict[str, Any]] = {}
287
+ prompts: dict[str, Any] = {}
288
+ for index, time in enumerate(ordered_times):
289
+ mask, row, prompt = v2.refine_one_mask(
290
+ predictor,
291
+ frames[time],
292
+ yolo_masks[time],
293
+ config["sam"],
294
+ seed=int(round(time * 1000)) + index,
295
+ )
296
+ refined[time] = mask
297
+ metrics[time] = row
298
+ prompts[config_key(time)] = prompt
299
+ print(
300
+ f"{time:5.1f}s SAM score={row['sam_score']:.3f} final IoU={row['final_iou']:.3f} "
301
+ f"recall={row['final_recall']:.3f} precision={row['final_precision']:.3f}"
302
+ )
303
+ del predictor
304
+ del sam
305
+ try:
306
+ import torch
307
+
308
+ if torch.cuda.is_available():
309
+ torch.cuda.empty_cache()
310
+ except Exception:
311
+ pass
312
+ return refined, metrics, prompts, checkpoint_hash
313
+
314
+
315
+ def save_segmentation_cache(
316
+ out_dir: Path,
317
+ ordered_times: list[float],
318
+ yolo_masks: dict[float, np.ndarray],
319
+ refined_masks: dict[float, np.ndarray],
320
+ yolo_records: list[dict[str, Any]],
321
+ metrics: dict[float, dict[str, Any]],
322
+ prompts: dict[str, Any],
323
+ ) -> None:
324
+ arrays: dict[str, np.ndarray] = {}
325
+ for time in ordered_times:
326
+ key = time_key(time)
327
+ arrays[f"yolo_{key}"] = yolo_masks[time].astype(np.uint8)
328
+ arrays[f"sam_{key}"] = refined_masks[time].astype(np.uint8)
329
+ np.savez_compressed(out_dir / "segmentation_cache.npz", **arrays)
330
+ v2.write_json(out_dir / "yolo_seed_detections.json", yolo_records)
331
+ v2.write_json(
332
+ out_dir / "sam_metrics_all.json",
333
+ {"frames": [{"time_s": time, "metrics": metrics[time]} for time in ordered_times]},
334
+ )
335
+ v2.write_json(out_dir / "sam_prompts.json", prompts)
336
+
337
+
338
+ def load_segmentation_cache(
339
+ out_dir: Path,
340
+ ordered_times: list[float],
341
+ ) -> tuple[dict[float, np.ndarray], dict[float, np.ndarray], dict[float, dict[str, Any]], list[dict[str, Any]]]:
342
+ cache_path = out_dir / "segmentation_cache.npz"
343
+ metrics_path = out_dir / "sam_metrics_all.json"
344
+ records_path = out_dir / "yolo_seed_detections.json"
345
+ for path in [cache_path, metrics_path, records_path]:
346
+ if not path.exists():
347
+ raise RuntimeError(f"Missing segmentation cache input: {path}")
348
+ archive = np.load(cache_path)
349
+ yolo_masks: dict[float, np.ndarray] = {}
350
+ refined_masks: dict[float, np.ndarray] = {}
351
+ for time in ordered_times:
352
+ key = time_key(time)
353
+ yolo_masks[time] = archive[f"yolo_{key}"].astype(np.uint8)
354
+ refined_masks[time] = archive[f"sam_{key}"].astype(np.uint8)
355
+ archive.close()
356
+ metrics_rows = v2.load_json(metrics_path)["frames"]
357
+ metrics = {float(row["time_s"]): row["metrics"] for row in metrics_rows}
358
+ records = v2.load_json(records_path)
359
+ if sorted(metrics) != sorted(ordered_times):
360
+ raise RuntimeError("Cached SAM times do not match the current config")
361
+ return yolo_masks, refined_masks, metrics, records
362
+
363
+
364
+ def safe_x_limit(width: int, config: dict[str, Any]) -> float:
365
+ return width * (1.0 - float(config["right_reserved_fraction"]))
366
+
367
+
368
+ def scaled_bbox_offsets(
369
+ bbox: tuple[float, float, float, float],
370
+ foot: tuple[float, float],
371
+ scale_factor: float,
372
+ ) -> tuple[float, float, float, float]:
373
+ x1, y1, x2, y2 = bbox
374
+ fx, fy = foot
375
+ return (
376
+ (fx - x1) * scale_factor,
377
+ (fy - y1) * scale_factor,
378
+ (x2 - fx) * scale_factor,
379
+ (y2 - fy) * scale_factor,
380
+ )
381
+
382
+
383
+ def clamp_display_foot(
384
+ requested: tuple[float, float],
385
+ bbox: tuple[float, float, float, float],
386
+ source_foot: tuple[float, float],
387
+ scale_factor: float,
388
+ canvas_shape: tuple[int, int],
389
+ config: dict[str, Any],
390
+ ) -> tuple[float, float]:
391
+ height, width = canvas_shape
392
+ margin = max(8, int(round(float(config["safe_margin_px_at_4k"]) * width / 3840.0)))
393
+ left, top, right, bottom = scaled_bbox_offsets(bbox, source_foot, scale_factor)
394
+ maximum_overlay_x = safe_x_limit(width, config)
395
+ minimum_x = margin + left
396
+ maximum_x = maximum_overlay_x - margin - right
397
+ minimum_y = margin + top
398
+ maximum_y = height - margin - bottom
399
+ if maximum_x < minimum_x:
400
+ raise RuntimeError("Pose is too wide for the configured overlay-safe region")
401
+ return (
402
+ float(np.clip(requested[0], minimum_x, maximum_x)),
403
+ float(np.clip(requested[1], minimum_y, maximum_y)),
404
+ )
405
+
406
+
407
+ def build_poses(
408
+ config: dict[str, Any],
409
+ frames: dict[float, np.ndarray],
410
+ frame_indices: dict[float, int],
411
+ yolo_masks: dict[float, np.ndarray],
412
+ refined_masks: dict[float, np.ndarray],
413
+ metrics: dict[float, dict[str, Any]],
414
+ ) -> list[Pose]:
415
+ sample_times = [float(value) for value in config["sample_times"]]
416
+ height, width = frames[sample_times[0]].shape[:2]
417
+ scale_factor = float(config["pose_scale"])
418
+ heroes = {float(value) for value in config["hero_times"]}
419
+ poses: list[Pose] = []
420
+ for time in sample_times:
421
+ mask = refined_masks[time]
422
+ bbox = v1.mask_bbox(mask)
423
+ foot = v1.foot_point(mask, bbox)
424
+ target_norm = config["layout_targets_normalized"][config_key(time)]
425
+ requested = (float(target_norm[0]) * width, float(target_norm[1]) * height)
426
+ display_foot = clamp_display_foot(
427
+ requested,
428
+ bbox,
429
+ foot,
430
+ scale_factor,
431
+ (height, width),
432
+ config,
433
+ )
434
+ group = group_for_time(time, config)
435
+ poses.append(
436
+ Pose(
437
+ time=time,
438
+ frame_index=frame_indices[time],
439
+ frame_bgr=frames[time],
440
+ yolo_mask=yolo_masks[time],
441
+ refined_mask=mask,
442
+ source_bbox=bbox,
443
+ source_foot=foot,
444
+ display_foot_requested=requested,
445
+ display_foot=display_foot,
446
+ phase_name=phase_for_time(time, config),
447
+ group_id=str(group["id"]),
448
+ group_label=str(group["label"]),
449
+ color_rgb=v1.hex_to_rgb(group["color"]),
450
+ hero=time in heroes,
451
+ scale_factor=scale_factor,
452
+ sam_metrics=metrics[time],
453
+ )
454
+ )
455
+ return poses
456
+
457
+
458
+ def scaled_pose_mask(pose: Pose, canvas_shape: tuple[int, int]) -> np.ndarray:
459
+ height, width = canvas_shape
460
+ scale = pose.scale_factor
461
+ transform = np.array(
462
+ [
463
+ [scale, 0.0, pose.display_foot[0] - scale * pose.source_foot[0]],
464
+ [0.0, scale, pose.display_foot[1] - scale * pose.source_foot[1]],
465
+ ],
466
+ dtype=np.float32,
467
+ )
468
+ return cv2.warpAffine(
469
+ pose.refined_mask,
470
+ transform,
471
+ (width, height),
472
+ flags=cv2.INTER_NEAREST,
473
+ borderMode=cv2.BORDER_CONSTANT,
474
+ borderValue=0,
475
+ )
476
+
477
+
478
+ def draw_shadows(canvas: np.ndarray, poses: Iterable[Pose], alpha: float) -> None:
479
+ if alpha <= 0:
480
+ return
481
+ height, width = canvas.shape[:2]
482
+ shadow = np.zeros((height, width), dtype=np.uint8)
483
+ for pose in poses:
484
+ bbox_width = (pose.source_bbox[2] - pose.source_bbox[0]) * pose.scale_factor
485
+ bbox_height = (pose.source_bbox[3] - pose.source_bbox[1]) * pose.scale_factor
486
+ centre = (
487
+ int(round(pose.display_foot[0])),
488
+ int(round(pose.display_foot[1] + max(2.0, bbox_height * 0.010))),
489
+ )
490
+ axes = (
491
+ max(8, int(round(bbox_width * 0.30))),
492
+ max(3, int(round(bbox_height * 0.016))),
493
+ )
494
+ cv2.ellipse(shadow, centre, axes, 0, 0, 360, 255, -1, lineType=cv2.LINE_AA)
495
+ sigma = max(2.0, width / 500.0)
496
+ soft = cv2.GaussianBlur(shadow.astype(np.float32) / 255.0, (0, 0), sigmaX=sigma)
497
+ canvas[:] = np.clip(canvas.astype(np.float32) * (1.0 - soft[..., None] * alpha), 0, 255).astype(np.uint8)
498
+
499
+
500
+ def blend_scaled_pose(canvas: np.ndarray, pose: Pose, alpha: float) -> None:
501
+ source_height, source_width = pose.refined_mask.shape
502
+ x1, y1, x2, y2 = [int(value) for value in v1.mask_bbox(pose.refined_mask)]
503
+ pad = max(3, int(round(source_width / 3840.0 * 5)))
504
+ x1, y1 = max(0, x1 - pad), max(0, y1 - pad)
505
+ x2, y2 = min(source_width, x2 + pad), min(source_height, y2 + pad)
506
+ mask_crop = pose.refined_mask[y1:y2, x1:x2]
507
+ frame_crop = pose.frame_bgr[y1:y2, x1:x2]
508
+ scale = pose.scale_factor
509
+ scaled_size = (
510
+ max(1, int(round(mask_crop.shape[1] * scale))),
511
+ max(1, int(round(mask_crop.shape[0] * scale))),
512
+ )
513
+ mask_scaled = cv2.resize(mask_crop, scaled_size, interpolation=cv2.INTER_NEAREST)
514
+ frame_scaled = cv2.resize(frame_crop, scaled_size, interpolation=cv2.INTER_AREA)
515
+ foot_in_crop = (
516
+ (pose.source_foot[0] - x1) * scale,
517
+ (pose.source_foot[1] - y1) * scale,
518
+ )
519
+ destination_x1 = int(round(pose.display_foot[0] - foot_in_crop[0]))
520
+ destination_y1 = int(round(pose.display_foot[1] - foot_in_crop[1]))
521
+ destination_x2 = destination_x1 + mask_scaled.shape[1]
522
+ destination_y2 = destination_y1 + mask_scaled.shape[0]
523
+ source_x1 = max(0, -destination_x1)
524
+ source_y1 = max(0, -destination_y1)
525
+ source_x2 = mask_scaled.shape[1] - max(0, destination_x2 - canvas.shape[1])
526
+ source_y2 = mask_scaled.shape[0] - max(0, destination_y2 - canvas.shape[0])
527
+ destination_x1, destination_y1 = max(0, destination_x1), max(0, destination_y1)
528
+ destination_x2, destination_y2 = min(canvas.shape[1], destination_x2), min(canvas.shape[0], destination_y2)
529
+ if source_x2 <= source_x1 or source_y2 <= source_y1:
530
+ return
531
+ mask = mask_scaled[source_y1:source_y2, source_x1:source_x2]
532
+ frame = frame_scaled[source_y1:source_y2, source_x1:source_x2]
533
+ target = canvas[destination_y1:destination_y2, destination_x1:destination_x2]
534
+
535
+ render_scale = canvas.shape[1] / 3840.0
536
+ halo_radius = max(1, int(round(2.5 * render_scale)))
537
+ halo = cv2.dilate((mask > 0).astype(np.uint8), v2.ellipse_kernel(halo_radius), iterations=1)
538
+ halo = np.clip(halo.astype(np.float32) - (mask > 0).astype(np.float32), 0.0, 1.0)
539
+ v2.blend_region(target, np.full_like(target, 247), halo * (0.40 if pose.hero else 0.25))
540
+
541
+ foreground = v1.colorize_foreground(frame, pose.color_rgb)
542
+ mask_float = mask.astype(np.float32) / 255.0
543
+ soft = cv2.GaussianBlur(mask_float, (0, 0), sigmaX=max(0.6, 1.05 * render_scale))
544
+ v2.blend_region(target, foreground, soft * float(alpha))
545
+ contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
546
+ layer = target.copy()
547
+ cv2.drawContours(
548
+ layer,
549
+ contours,
550
+ -1,
551
+ tuple(int(value) for value in pose.color_rgb),
552
+ max(1, int(round(2.0 * render_scale))),
553
+ lineType=cv2.LINE_AA,
554
+ )
555
+ contour_alpha = 0.82 if pose.hero else 0.58
556
+ target[:] = np.clip(
557
+ target.astype(np.float32) * (1.0 - contour_alpha) + layer.astype(np.float32) * contour_alpha,
558
+ 0,
559
+ 255,
560
+ ).astype(np.uint8)
561
+
562
+
563
+ def draw_display_path(canvas: np.ndarray, poses: list[Pose]) -> None:
564
+ render_scale = canvas.shape[1] / 3840.0
565
+ points = np.array([pose.display_foot for pose in poses], dtype=np.float32)
566
+ for pose, p0, p1 in zip(poses[:-1], points[:-1], points[1:]):
567
+ a = tuple(np.round(p0).astype(int))
568
+ b = tuple(np.round(p1).astype(int))
569
+ color = tuple(int(value) for value in pose.color_rgb)
570
+ cv2.line(canvas, a, b, (247, 247, 244), max(5, int(round(9 * render_scale))), lineType=cv2.LINE_AA)
571
+ cv2.line(canvas, a, b, color, max(2, int(round(4 * render_scale))), lineType=cv2.LINE_AA)
572
+ v2.arrow_head(
573
+ canvas,
574
+ points[-2],
575
+ points[-1],
576
+ tuple(int(value) for value in poses[-1].color_rgb),
577
+ render_scale,
578
+ )
579
+
580
+
581
+ def render_layout(background: np.ndarray, poses: list[Pose], config: dict[str, Any]) -> np.ndarray:
582
+ canvas = background.copy()
583
+ draw_shadows(canvas, poses, float(config["shadow_alpha"]))
584
+ draw_display_path(canvas, poses)
585
+ alpha_config = config["alpha"]
586
+ for pose in sorted(poses, key=lambda item: item.display_foot[1]):
587
+ alpha = float(alpha_config["hero"] if pose.hero else alpha_config["standard"])
588
+ blend_scaled_pose(canvas, pose, alpha)
589
+ return canvas
590
+
591
+
592
+ def add_timeline(ax: Any, config: dict[str, Any], width: int, height: int) -> None:
593
+ safe_boundary = safe_x_limit(width, config)
594
+ content_left = 0.008 * width
595
+ content_right = safe_boundary - 0.012 * width
596
+ content_width = content_right - content_left
597
+ phases = config["motion_phases"]
598
+ start = float(phases[0]["start"])
599
+ end = float(phases[-1]["end"])
600
+ ax.add_patch(
601
+ Rectangle(
602
+ (0, 0.010 * height),
603
+ safe_boundary - 0.006 * width,
604
+ 0.094 * height,
605
+ facecolor=(0.025, 0.040, 0.055),
606
+ alpha=0.82,
607
+ lw=0,
608
+ zorder=20,
609
+ )
610
+ )
611
+ phase_colours = [(0.18, 0.23, 0.27), (0.25, 0.23, 0.19), (0.24, 0.20, 0.25)]
612
+ y0, y1 = 0.022 * height, 0.051 * height
613
+ for phase, colour in zip(phases, phase_colours):
614
+ x0 = content_left + content_width * (float(phase["start"]) - start) / (end - start)
615
+ x1 = content_left + content_width * (float(phase["end"]) - start) / (end - start)
616
+ ax.add_patch(Rectangle((x0, y0), x1 - x0, y1 - y0, facecolor=colour, lw=0, zorder=21))
617
+ ax.text(
618
+ (x0 + x1) / 2,
619
+ y0 + 0.60 * (y1 - y0),
620
+ phase["name"],
621
+ color="white",
622
+ ha="center",
623
+ va="center",
624
+ fontsize=5.5,
625
+ weight="bold",
626
+ zorder=22,
627
+ )
628
+ marker_y = 0.073 * height
629
+ ax.plot([content_left, content_right], [marker_y, marker_y], color=(0.80, 0.83, 0.85), lw=0.7, zorder=21)
630
+ for time in [float(value) for value in config["sample_times"]]:
631
+ group = group_for_time(time, config)
632
+ x = content_left + content_width * (time - start) / (end - start)
633
+ colour = v1.hex_to_rgb(group["color"]) / 255.0
634
+ ax.scatter([x], [marker_y], s=10, c=[colour], edgecolors="white", linewidths=0.35, zorder=23)
635
+ for time in [7, 28, 40, 57]:
636
+ x = content_left + content_width * (time - start) / (end - start)
637
+ alignment = "left" if time == 7 else ("right" if time == 57 else "center")
638
+ offset = 0.006 * content_width if time == 7 else (-0.006 * content_width if time == 57 else 0)
639
+ ax.text(
640
+ x + offset,
641
+ marker_y + 0.018 * height,
642
+ f"{time:g} s",
643
+ color="white",
644
+ ha=alignment,
645
+ va="top",
646
+ fontsize=5.1,
647
+ zorder=22,
648
+ )
649
+ ax.text(
650
+ content_right,
651
+ y0 - 0.005 * height,
652
+ "time →",
653
+ color="white",
654
+ fontsize=5.2,
655
+ ha="right",
656
+ va="bottom",
657
+ zorder=22,
658
+ )
659
+
660
+
661
+ def add_annotation(ax: Any, config: dict[str, Any], width: int, height: int) -> None:
662
+ safe_width = safe_x_limit(width, config)
663
+ box_x, box_y = 0.014 * width, 0.118 * height
664
+ box_w, box_h = 0.330 * width, 0.083 * height
665
+ ax.add_patch(
666
+ FancyBboxPatch(
667
+ (box_x, box_y),
668
+ box_w,
669
+ box_h,
670
+ boxstyle="round,pad=0.012,rounding_size=12",
671
+ facecolor=(0.02, 0.035, 0.050),
672
+ edgecolor=(1, 1, 1, 0.34),
673
+ lw=0.6,
674
+ alpha=0.76,
675
+ zorder=24,
676
+ )
677
+ )
678
+ ax.text(
679
+ box_x + 0.015 * width,
680
+ box_y + 0.029 * height,
681
+ "13 specified poses • five colour groups",
682
+ color="white",
683
+ fontsize=6.4,
684
+ weight="bold",
685
+ ha="left",
686
+ va="center",
687
+ zorder=25,
688
+ )
689
+ ax.text(
690
+ box_x + 0.015 * width,
691
+ box_y + 0.058 * height,
692
+ "uniform scale ×0.92 • rightmost 12% reserved",
693
+ color=(0.90, 0.92, 0.94),
694
+ fontsize=5.2,
695
+ ha="left",
696
+ va="center",
697
+ zorder=25,
698
+ )
699
+
700
+ legend_left = 0.370 * width
701
+ legend_right = safe_width - 0.012 * width
702
+ slot = (legend_right - legend_left) / len(config["color_groups"])
703
+ for index, group in enumerate(config["color_groups"]):
704
+ x = legend_left + (index + 0.5) * slot
705
+ colour = v1.hex_to_rgb(group["color"]) / 255.0
706
+ ax.scatter([x], [box_y + 0.030 * height], s=18, c=[colour], edgecolors="white", linewidths=0.45, zorder=25)
707
+ ax.text(
708
+ x,
709
+ box_y + 0.059 * height,
710
+ str(group["label"]),
711
+ color="white",
712
+ fontsize=5.0,
713
+ ha="center",
714
+ va="center",
715
+ zorder=25,
716
+ )
717
+
718
+
719
+ def save_publication_figure(
720
+ canvas: np.ndarray,
721
+ out_base: Path,
722
+ config: dict[str, Any],
723
+ annotated: bool,
724
+ ) -> None:
725
+ height, width = canvas.shape[:2]
726
+ width_mm = 183.0
727
+ width_mm = float(config.get("final_width_mm", width_mm))
728
+ png_dpi = int(config.get("png_dpi", 300))
729
+ tiff_dpi = 600
730
+ tiff_dpi = max(tiff_dpi, int(config.get("tiff_dpi", tiff_dpi)))
731
+ width_in = width_mm / 25.4
732
+ height_in = width_in * height / width
733
+ fig = plt.figure(figsize=(width_in, height_in), dpi=png_dpi, facecolor="white")
734
+ ax = fig.add_axes([0, 0, 1, 1])
735
+ ax.imshow(canvas)
736
+ ax.set_xlim(0, width)
737
+ ax.set_ylim(height, 0)
738
+ ax.axis("off")
739
+ if annotated:
740
+ add_timeline(ax, config, width, height)
741
+ add_annotation(ax, config, width, height)
742
+ for extension in ["png", "tiff", "svg", "pdf"]:
743
+ path = out_base.with_suffix(f".{extension}")
744
+ if extension == "png":
745
+ fig.savefig(path, dpi=png_dpi, facecolor="white")
746
+ elif extension == "tiff":
747
+ fig.savefig(path, dpi=tiff_dpi, facecolor="white")
748
+ with Image.open(path) as rendered:
749
+ rendered.convert("RGB").save(
750
+ path,
751
+ format="TIFF",
752
+ compression="tiff_lzw",
753
+ dpi=(tiff_dpi, tiff_dpi),
754
+ )
755
+ else:
756
+ fig.savefig(path, facecolor="white")
757
+ if extension == "svg":
758
+ lines = path.read_text(encoding="utf-8").splitlines()
759
+ path.write_text("\n".join(line.rstrip() for line in lines) + "\n", encoding="utf-8")
760
+ plt.close(fig)
761
+
762
+
763
+ def overlap_statistics(masks: list[np.ndarray]) -> dict[str, Any]:
764
+ occupancy = np.zeros(masks[0].shape, dtype=np.uint16)
765
+ for mask in masks:
766
+ occupancy += (mask > 0).astype(np.uint16)
767
+ summed = int(occupancy.sum())
768
+ union = int((occupancy > 0).sum())
769
+ return {
770
+ "pose_count": len(masks),
771
+ "summed_pose_area_px": summed,
772
+ "union_area_px": union,
773
+ "redundant_overlap_px": summed - union,
774
+ "redundant_overlap_fraction": round((summed - union) / summed, 6) if summed else 0.0,
775
+ "pixels_covered_by_two_or_more": int((occupancy > 1).sum()),
776
+ "maximum_stack_depth": int(occupancy.max()),
777
+ }
778
+
779
+
780
+ def save_layout_map(poses: list[Pose], config: dict[str, Any], out_dir: Path) -> None:
781
+ fields = [
782
+ "time_s",
783
+ "phase",
784
+ "color_group",
785
+ "color_hex",
786
+ "hero",
787
+ "source_foot_x_px",
788
+ "source_foot_y_px",
789
+ "requested_display_foot_x_px",
790
+ "requested_display_foot_y_px",
791
+ "display_foot_x_px",
792
+ "display_foot_y_px",
793
+ "translation_after_scale_dx_px",
794
+ "translation_after_scale_dy_px",
795
+ "uniform_scale_factor",
796
+ "scaled_bbox_x1",
797
+ "scaled_bbox_y1",
798
+ "scaled_bbox_x2",
799
+ "scaled_bbox_y2",
800
+ "safe_x_limit_px",
801
+ "alpha",
802
+ ]
803
+ colour_by_group = {str(group["id"]): str(group["color"]) for group in config["color_groups"]}
804
+ with (out_dir / "layout_map.csv").open("w", encoding="utf-8", newline="") as handle:
805
+ writer = csv.DictWriter(handle, fieldnames=fields, lineterminator="\n")
806
+ writer.writeheader()
807
+ for pose in poses:
808
+ mask = scaled_pose_mask(pose, pose.refined_mask.shape)
809
+ bbox = v1.mask_bbox(mask)
810
+ alpha = config["alpha"]["hero" if pose.hero else "standard"]
811
+ writer.writerow(
812
+ {
813
+ "time_s": f"{pose.time:.3f}",
814
+ "phase": pose.phase_name,
815
+ "color_group": pose.group_id,
816
+ "color_hex": colour_by_group[pose.group_id],
817
+ "hero": int(pose.hero),
818
+ "source_foot_x_px": f"{pose.source_foot[0]:.3f}",
819
+ "source_foot_y_px": f"{pose.source_foot[1]:.3f}",
820
+ "requested_display_foot_x_px": f"{pose.display_foot_requested[0]:.3f}",
821
+ "requested_display_foot_y_px": f"{pose.display_foot_requested[1]:.3f}",
822
+ "display_foot_x_px": f"{pose.display_foot[0]:.3f}",
823
+ "display_foot_y_px": f"{pose.display_foot[1]:.3f}",
824
+ "translation_after_scale_dx_px": f"{pose.display_foot[0] - pose.scale_factor * pose.source_foot[0]:.3f}",
825
+ "translation_after_scale_dy_px": f"{pose.display_foot[1] - pose.scale_factor * pose.source_foot[1]:.3f}",
826
+ "uniform_scale_factor": f"{pose.scale_factor:.3f}",
827
+ "scaled_bbox_x1": f"{bbox[0]:.3f}",
828
+ "scaled_bbox_y1": f"{bbox[1]:.3f}",
829
+ "scaled_bbox_x2": f"{bbox[2]:.3f}",
830
+ "scaled_bbox_y2": f"{bbox[3]:.3f}",
831
+ "safe_x_limit_px": f"{safe_x_limit(pose.refined_mask.shape[1], config):.3f}",
832
+ "alpha": f"{float(alpha):.3f}",
833
+ }
834
+ )
835
+
836
+
837
+ def save_colour_map(config: dict[str, Any], out_dir: Path) -> None:
838
+ with (out_dir / "color_map.csv").open("w", encoding="utf-8", newline="") as handle:
839
+ writer = csv.writer(handle, lineterminator="\n")
840
+ writer.writerow(["color_group", "color_hex", "times_s"])
841
+ for group in config["color_groups"]:
842
+ writer.writerow([group["id"], group["color"], ",".join(f"{float(t):g}" for t in group["times"])])
843
+
844
+
845
+ def save_refined_records(poses: list[Pose], out_dir: Path) -> None:
846
+ rows: list[dict[str, Any]] = []
847
+ masks: dict[str, np.ndarray] = {}
848
+ for index, pose in enumerate(poses):
849
+ rows.append(
850
+ {
851
+ "index": index,
852
+ "time_s": pose.time,
853
+ "frame_index": pose.frame_index,
854
+ "phase": pose.phase_name,
855
+ "color_group": pose.group_id,
856
+ "source_bbox_xyxy": [round(float(value), 3) for value in pose.source_bbox],
857
+ "source_foot_xy": [round(float(value), 3) for value in pose.source_foot],
858
+ "display_foot_xy": [round(float(value), 3) for value in pose.display_foot],
859
+ "uniform_scale_factor": pose.scale_factor,
860
+ "sam_metrics": pose.sam_metrics,
861
+ }
862
+ )
863
+ masks[f"mask_{index:03d}"] = pose.refined_mask.astype(np.uint8)
864
+ v2.write_json(out_dir / "detections_refined.json", rows)
865
+ np.savez_compressed(out_dir / "refined_masks.npz", **masks)
866
+
867
+
868
+ def save_requested_keyframes(poses: list[Pose], out_dir: Path) -> None:
869
+ tile_width, tile_height, header = 480, 305, 34
870
+ columns = 5
871
+ rows = int(math.ceil(len(poses) / columns))
872
+ montage = np.full((rows * tile_height, columns * tile_width, 3), 244, dtype=np.uint8)
873
+ for index, pose in enumerate(poses):
874
+ frame_rgb = cv2.cvtColor(pose.frame_bgr, cv2.COLOR_BGR2RGB)
875
+ body = v2.letterbox(frame_rgb, tile_width, tile_height - header, (235, 235, 235))
876
+ tile = np.full((tile_height, tile_width, 3), 244, dtype=np.uint8)
877
+ tile[header:] = body
878
+ colour = tuple(int(value) for value in pose.color_rgb)
879
+ cv2.rectangle(tile, (0, 0), (tile_width - 1, tile_height - 1), colour, 5, lineType=cv2.LINE_AA)
880
+ label = f"{pose.time:g}s group {pose.group_id} frame {pose.frame_index}"
881
+ cv2.putText(tile, label, (12, 23), cv2.FONT_HERSHEY_SIMPLEX, 0.53, (32, 38, 44), 1, cv2.LINE_AA)
882
+ row, column = divmod(index, columns)
883
+ montage[row * tile_height : (row + 1) * tile_height, column * tile_width : (column + 1) * tile_width] = tile
884
+ cv2.imwrite(
885
+ str(out_dir / "requested_keyframes.jpg"),
886
+ cv2.cvtColor(montage, cv2.COLOR_RGB2BGR),
887
+ [cv2.IMWRITE_JPEG_QUALITY, 94],
888
+ )
889
+
890
+
891
+ def save_safe_area_qa(
892
+ canvas: np.ndarray,
893
+ background: np.ndarray,
894
+ config: dict[str, Any],
895
+ out_dir: Path,
896
+ ) -> dict[str, Any]:
897
+ height, width = canvas.shape[:2]
898
+ boundary = safe_x_limit(width, config)
899
+ boundary_px = int(math.floor(boundary))
900
+ difference = np.max(np.abs(canvas.astype(np.int16) - background.astype(np.int16)), axis=2) > 2
901
+ yy, xx = np.where(difference)
902
+ maximum_changed_x = int(xx.max()) if len(xx) else -1
903
+ reserved_changed = int(difference[:, int(math.ceil(boundary)) :].sum())
904
+ report = {
905
+ "image_width_px": width,
906
+ "right_reserved_fraction": float(config["right_reserved_fraction"]),
907
+ "overlay_safe_x_limit_px": round(boundary, 3),
908
+ "maximum_changed_overlay_x_px": maximum_changed_x,
909
+ "changed_pixels_inside_reserved_zone": reserved_changed,
910
+ "pass": bool(maximum_changed_x < boundary_px and reserved_changed == 0),
911
+ }
912
+ clean_png = cv2.imread(str(out_dir / "trajectory_v3_custom_frames_clean.png"), cv2.IMREAD_UNCHANGED)
913
+ annotated_png = cv2.imread(str(out_dir / "trajectory_v3_custom_frames_annotated.png"), cv2.IMREAD_UNCHANGED)
914
+ if clean_png is not None and annotated_png is not None and clean_png.shape == annotated_png.shape:
915
+ png_boundary = int(math.ceil(clean_png.shape[1] * (1.0 - float(config["right_reserved_fraction"]))))
916
+ annotation_difference = np.max(
917
+ np.abs(annotated_png.astype(np.int16) - clean_png.astype(np.int16)),
918
+ axis=2,
919
+ ) > 2
920
+ annotated_reserved_changed = int(annotation_difference[:, png_boundary:].sum())
921
+ report["annotated_changed_pixels_inside_reserved_zone"] = annotated_reserved_changed
922
+ report["pass"] = bool(report["pass"] and annotated_reserved_changed == 0)
923
+ guide = canvas.copy()
924
+ red = np.array([213, 70, 66], dtype=np.float32)
925
+ zone = guide[:, boundary_px:].astype(np.float32)
926
+ guide[:, boundary_px:] = np.clip(zone * 0.56 + red[None, None, :] * 0.44, 0, 255).astype(np.uint8)
927
+ cv2.line(guide, (boundary_px, 0), (boundary_px, height - 1), (255, 255, 255), 4, lineType=cv2.LINE_AA)
928
+ cv2.putText(
929
+ guide,
930
+ "12% reserved: no final overlay",
931
+ (boundary_px + 14, 48),
932
+ cv2.FONT_HERSHEY_SIMPLEX,
933
+ 0.58,
934
+ (255, 255, 255),
935
+ 2,
936
+ cv2.LINE_AA,
937
+ )
938
+ cv2.imwrite(str(out_dir / "safe_area_qa.png"), cv2.cvtColor(guide, cv2.COLOR_RGB2BGR))
939
+ v2.write_json(out_dir / "safe_area_metrics.json", report)
940
+ return report
941
+
942
+
943
+ def save_comparison(v2_path: Path, v3_path: Path, safe_path: Path, out_path: Path) -> None:
944
+ images = []
945
+ for path in [v2_path, v3_path, safe_path]:
946
+ image = cv2.imread(str(path))
947
+ if image is None:
948
+ raise RuntimeError(f"Could not read comparison input: {path}")
949
+ images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
950
+ fig = plt.figure(figsize=(12.0, 7.5), dpi=300, facecolor="#F4F5F4")
951
+ grid = fig.add_gridspec(2, 2, height_ratios=[1, 1.16], hspace=0.12, wspace=0.04)
952
+ axes = [fig.add_subplot(grid[0, 0]), fig.add_subplot(grid[0, 1]), fig.add_subplot(grid[1, :])]
953
+ titles = [
954
+ "v2 • 12 selected poses • three colours",
955
+ "v3 • 13 specified poses • five colours • uniform ×0.92 scale",
956
+ "v3 crop-safety QA • rightmost 12% contains no final overlay",
957
+ ]
958
+ for axis, image, title in zip(axes, images, titles):
959
+ axis.imshow(image)
960
+ axis.set_title(title, fontsize=8.4, loc="left", pad=4, weight="bold", color="#28313A")
961
+ axis.axis("off")
962
+ fig.savefig(out_path, dpi=300, facecolor=fig.get_facecolor(), bbox_inches="tight", pil_kwargs={"quality": 94})
963
+ plt.close(fig)
964
+
965
+
966
+ def metric_summary(poses: list[Pose]) -> dict[str, Any]:
967
+ fields = ["final_iou", "final_recall", "final_precision", "final_area_ratio", "sam_score"]
968
+ summary: dict[str, Any] = {"pose_count": len(poses)}
969
+ for field in fields:
970
+ values = np.array([float(pose.sam_metrics[field]) for pose in poses], dtype=np.float64)
971
+ summary[field] = {
972
+ "mean": round(float(values.mean()), 6),
973
+ "min": round(float(values.min()), 6),
974
+ "max": round(float(values.max()), 6),
975
+ }
976
+ summary["fallback_count"] = sum(bool(pose.sam_metrics["fallback_to_yolo"]) for pose in poses)
977
+ return summary
978
+
979
+
980
+ def main() -> int:
981
+ args = parse_args()
982
+ video = args.video.expanduser().resolve()
983
+ config_path = args.config.expanduser().resolve()
984
+ yolo_path = args.yolo_model.expanduser().resolve()
985
+ checkpoint = args.sam_checkpoint.expanduser().resolve()
986
+ out_dir = args.out_dir.expanduser().resolve()
987
+ for path in [video, config_path, yolo_path]:
988
+ if not path.exists():
989
+ print(f"Required input not found: {path}", file=sys.stderr)
990
+ return 2
991
+ config = v2.load_json(config_path)
992
+ validate_config(config)
993
+ out_dir.mkdir(parents=True, exist_ok=True)
994
+ sample_times = [float(value) for value in config["sample_times"]]
995
+ reference_times = [float(value) for value in config["background_reference_times"]]
996
+ ordered_times = sorted(set(sample_times + reference_times))
997
+ frames, frame_indices, video_metadata = read_frames(
998
+ video,
999
+ ordered_times,
1000
+ int(config["render_width"]),
1001
+ )
1002
+
1003
+ prompts: dict[str, Any] = {}
1004
+ if args.reuse_segmentation:
1005
+ yolo_masks, refined_masks, metrics, yolo_records = load_segmentation_cache(out_dir, ordered_times)
1006
+ checkpoint_hash = str(config["sam"]["checkpoint_sha256"])
1007
+ print(f"Reusing YOLO/SAM masks for {len(ordered_times)} frames from {out_dir}")
1008
+ else:
1009
+ if not checkpoint.exists():
1010
+ print(
1011
+ "SAM checkpoint not found. Run trajectory_project/scripts/download_sam_checkpoint.py first.",
1012
+ file=sys.stderr,
1013
+ )
1014
+ return 2
1015
+ yolo_masks, yolo_records = infer_yolo_masks(
1016
+ frames,
1017
+ frame_indices,
1018
+ ordered_times,
1019
+ yolo_path,
1020
+ config,
1021
+ args.device,
1022
+ )
1023
+ refined_masks, metrics, prompts, checkpoint_hash = refine_all_masks(
1024
+ frames,
1025
+ yolo_masks,
1026
+ ordered_times,
1027
+ checkpoint,
1028
+ config,
1029
+ args.device,
1030
+ )
1031
+ save_segmentation_cache(
1032
+ out_dir,
1033
+ ordered_times,
1034
+ yolo_masks,
1035
+ refined_masks,
1036
+ yolo_records,
1037
+ metrics,
1038
+ prompts,
1039
+ )
1040
+
1041
+ poses = build_poses(
1042
+ config,
1043
+ frames,
1044
+ frame_indices,
1045
+ yolo_masks,
1046
+ refined_masks,
1047
+ metrics,
1048
+ )
1049
+ background = v2.make_background(frames, refined_masks, config)
1050
+ layout = render_layout(background, poses, config)
1051
+ cv2.imwrite(str(out_dir / "background_plate.png"), cv2.cvtColor(background, cv2.COLOR_RGB2BGR))
1052
+ cv2.imwrite(str(out_dir / "composite_layout_rgb.png"), cv2.cvtColor(layout, cv2.COLOR_RGB2BGR))
1053
+ save_publication_figure(
1054
+ layout,
1055
+ out_dir / "trajectory_v3_custom_frames_clean",
1056
+ config,
1057
+ annotated=False,
1058
+ )
1059
+ save_publication_figure(
1060
+ layout,
1061
+ out_dir / "trajectory_v3_custom_frames_annotated",
1062
+ config,
1063
+ annotated=True,
1064
+ )
1065
+
1066
+ save_requested_keyframes(poses, out_dir)
1067
+ v2.save_sam_qa(poses, out_dir)
1068
+ save_layout_map(poses, config, out_dir)
1069
+ save_colour_map(config, out_dir)
1070
+ save_refined_records(poses, out_dir)
1071
+ scaled_masks = [scaled_pose_mask(pose, layout.shape[:2]) for pose in poses]
1072
+ overlap_report = overlap_statistics(scaled_masks)
1073
+ v2.write_json(out_dir / "overlap_metrics.json", overlap_report)
1074
+ safe_report = save_safe_area_qa(layout, background, config, out_dir)
1075
+ v2_path = PROJECT_ROOT / "trajectory_project" / "outputs" / "v2_sam_layout" / "trajectory_v2_layout_expanded_annotated.png"
1076
+ save_comparison(
1077
+ v2_path,
1078
+ out_dir / "trajectory_v3_custom_frames_annotated.png",
1079
+ out_dir / "safe_area_qa.png",
1080
+ out_dir / "comparison_v2_v3.jpg",
1081
+ )
1082
+ sam_summary = metric_summary(poses)
1083
+ v2.write_json(
1084
+ out_dir / "sam_metrics.json",
1085
+ {"summary": sam_summary, "frames": [{"time_s": pose.time, "metrics": pose.sam_metrics} for pose in poses]},
1086
+ )
1087
+ metadata = {
1088
+ "version": config["version"],
1089
+ "video": v2.display_path(video),
1090
+ "config": v2.display_path(config_path),
1091
+ "yolo_model": yolo_path.name,
1092
+ "sam_checkpoint": checkpoint.name,
1093
+ "sam_checkpoint_sha256": checkpoint_hash,
1094
+ "device": args.device,
1095
+ "sample_times_s": sample_times,
1096
+ "color_groups": config["color_groups"],
1097
+ "uniform_pose_scale": float(config["pose_scale"]),
1098
+ "right_reserved_fraction": float(config["right_reserved_fraction"]),
1099
+ "trajectory_overlay": "none; coloured line encodes display order only",
1100
+ "video_metadata": video_metadata,
1101
+ "sam_summary": sam_summary,
1102
+ "layout_overlap": overlap_report,
1103
+ "safe_area": safe_report,
1104
+ }
1105
+ v2.write_json(out_dir / "run_metadata.json", metadata)
1106
+ if prompts:
1107
+ v2.write_json(out_dir / "sam_prompts.json", prompts)
1108
+ print(f"Wrote v3 outputs to {out_dir}")
1109
+ return 0
1110
+
1111
+
1112
+ if __name__ == "__main__":
1113
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v4.py ADDED
@@ -0,0 +1,562 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build the timing-adjusted v4 G1 trajectory figure.
3
+
4
+ This is a deliberately thin adapter around the locked v3 renderer. It changes
5
+ only the requested source times, raises the 14 s display anchor slightly, and
6
+ removes the 44 s donor-frame robot residual from the background with pixels
7
+ from a clean 31 s frame of the same fixed-camera video.
8
+
9
+ Publication exports: ``.png`` preview, RGB ``.tiff`` at 600 dpi, and
10
+ editable-text ``.svg`` / ``.pdf`` files at 183 mm width.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import csv
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ import cv2
21
+ import numpy as np
22
+
23
+ import build_trajectory_figure_v3 as v3
24
+
25
+
26
+ v3.matplotlib.rcParams.update(
27
+ {
28
+ "font.family": "sans-serif",
29
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
30
+ "font.size": 7,
31
+ "svg.fonttype": "none",
32
+ "pdf.fonttype": 42,
33
+ }
34
+ )
35
+
36
+
37
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
38
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
39
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v4_frame_timing_background_fix.json"
40
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
41
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
42
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v4_frame_timing_background_fix"
43
+ V3_REFERENCE = (
44
+ PROJECT_ROOT
45
+ / "trajectory_project"
46
+ / "outputs"
47
+ / "v3_custom_frames_layout"
48
+ / "trajectory_v3_custom_frames_annotated.png"
49
+ )
50
+ V3_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v3_custom_frames_layout.json"
51
+ OUTPUT_STEM = "trajectory_v4_timing_background"
52
+
53
+
54
+ _BACKGROUND_AUDIT: dict[str, Any] = {}
55
+ _BACKGROUND_BEFORE_RGB: np.ndarray | None = None
56
+ _BACKGROUND_AFTER_RGB: np.ndarray | None = None
57
+
58
+
59
+ def parse_args() -> argparse.Namespace:
60
+ parser = argparse.ArgumentParser(description=__doc__)
61
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
62
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
63
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
64
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
65
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
66
+ parser.add_argument("--device", default="cuda:0")
67
+ parser.add_argument(
68
+ "--reuse-segmentation",
69
+ action="store_true",
70
+ help="Reuse the v4 YOLO/SAM cache and rerender only.",
71
+ )
72
+ return parser.parse_args()
73
+
74
+
75
+ def mask_bbox(mask: np.ndarray) -> list[int] | None:
76
+ yy, xx = np.where(mask > 0)
77
+ if len(xx) == 0:
78
+ return None
79
+ return [int(xx.min()), int(yy.min()), int(xx.max()), int(yy.max())]
80
+
81
+
82
+ def apply_background_tone(image_bgr: np.ndarray, config: dict[str, Any]) -> np.ndarray:
83
+ rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB).astype(np.float32)
84
+ gray = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2GRAY).astype(np.float32)[..., None]
85
+ desaturate = float(np.clip(config.get("background_desaturate", 0.0), 0.0, 1.0))
86
+ brightness = float(np.clip(config.get("background_brightness", 1.0), 0.0, 2.0))
87
+ rgb = (1.0 - desaturate) * rgb + desaturate * gray
88
+ rgb *= brightness
89
+ return np.clip(rgb, 0, 255).astype(np.uint8)
90
+
91
+
92
+ def make_background_v4(
93
+ frames: dict[float, np.ndarray],
94
+ masks: dict[float, np.ndarray],
95
+ config: dict[str, Any],
96
+ ) -> np.ndarray:
97
+ """Reproduce v3 background repair, then remove only its donor residual."""
98
+ global _BACKGROUND_AUDIT, _BACKGROUND_BEFORE_RGB, _BACKGROUND_AFTER_RGB
99
+
100
+ reference_times = [float(value) for value in config["background_reference_times"]]
101
+ if len(reference_times) != 3:
102
+ raise RuntimeError("v4 background repair requires base, fill, and cleanup reference times")
103
+ base_time, fill_time, cleanup_time = reference_times
104
+ base = frames[base_time]
105
+ fill = frames[fill_time]
106
+ cleanup = frames[cleanup_time]
107
+ base_mask = masks[base_time]
108
+ fill_mask = masks[fill_time]
109
+ cleanup_mask = masks[cleanup_time]
110
+
111
+ scale = base.shape[1] / 3840.0
112
+ first_dilate = max(8, int(round(float(config["background_dilate_px_at_4k"]) * scale)))
113
+ repaired_before_cleanup = v3.v1.repair_background(
114
+ base,
115
+ fill,
116
+ base_mask,
117
+ fill_mask,
118
+ first_dilate,
119
+ )
120
+
121
+ kernel_size = max(3, 2 * first_dilate + 1)
122
+ base_patch = cv2.dilate(
123
+ (base_mask > 0).astype(np.uint8),
124
+ cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (kernel_size, kernel_size)),
125
+ iterations=1,
126
+ )
127
+ residual_core = ((fill_mask > 0) & (base_patch > 0)).astype(np.uint8)
128
+ if int(residual_core.sum()) == 0:
129
+ raise RuntimeError("Expected a donor-frame residual but found no overlap to repair")
130
+
131
+ cleanup_dilate = max(
132
+ 4,
133
+ int(round(float(config["background_residual_dilate_px_at_4k"]) * scale)),
134
+ )
135
+ cleanup_kernel_size = max(3, 2 * cleanup_dilate + 1)
136
+ cleanup_patch = cv2.dilate(
137
+ residual_core,
138
+ cv2.getStructuringElement(
139
+ cv2.MORPH_ELLIPSE,
140
+ (cleanup_kernel_size, cleanup_kernel_size),
141
+ ),
142
+ iterations=1,
143
+ )
144
+ cleanup_overlap_pixels = int(((cleanup_mask > 0) & (cleanup_patch > 0)).sum())
145
+ if cleanup_overlap_pixels:
146
+ raise RuntimeError(
147
+ "The cleanup frame contains robot pixels inside the residual repair patch"
148
+ )
149
+
150
+ repaired_after_cleanup = v3.v1.repair_background(
151
+ repaired_before_cleanup,
152
+ cleanup,
153
+ residual_core * 255,
154
+ cleanup_mask,
155
+ cleanup_dilate,
156
+ )
157
+ before_rgb = apply_background_tone(repaired_before_cleanup, config)
158
+ after_rgb = apply_background_tone(repaired_after_cleanup, config)
159
+ difference = np.max(
160
+ np.abs(after_rgb.astype(np.int16) - before_rgb.astype(np.int16)),
161
+ axis=2,
162
+ )
163
+ changed = difference > 2
164
+ if int(changed.sum()) == 0:
165
+ raise RuntimeError("Residual repair did not change the background")
166
+
167
+ _BACKGROUND_BEFORE_RGB = before_rgb
168
+ _BACKGROUND_AFTER_RGB = after_rgb
169
+ _BACKGROUND_AUDIT = {
170
+ "method": "fixed-camera source-pixel patch with colour matching and feathering",
171
+ "base_time_s": base_time,
172
+ "first_fill_time_s": fill_time,
173
+ "cleanup_time_s": cleanup_time,
174
+ "generative_fill": False,
175
+ "residual_core_pixels": int(residual_core.sum()),
176
+ "residual_core_bbox_xyxy": mask_bbox(residual_core),
177
+ "cleanup_patch_pixels": int(cleanup_patch.sum()),
178
+ "cleanup_patch_bbox_xyxy": mask_bbox(cleanup_patch),
179
+ "cleanup_robot_overlap_pixels": cleanup_overlap_pixels,
180
+ "changed_pixels_over_2": int(changed.sum()),
181
+ "changed_bbox_xyxy": mask_bbox(changed.astype(np.uint8)),
182
+ "maximum_absolute_channel_change": int(difference.max()),
183
+ }
184
+ return after_rgb
185
+
186
+
187
+ def save_v3_v4_comparison(
188
+ _v2_path: Path,
189
+ v4_path: Path,
190
+ safe_path: Path,
191
+ _v2_v3_out_path: Path,
192
+ ) -> None:
193
+ paths = [V3_REFERENCE, v4_path, safe_path]
194
+ images = []
195
+ for path in paths:
196
+ image = cv2.imread(str(path))
197
+ if image is None:
198
+ raise RuntimeError(f"Could not read comparison input: {path}")
199
+ images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
200
+ figure = v3.plt.figure(figsize=(12.0, 7.5), dpi=300, facecolor="#F4F5F4")
201
+ grid = figure.add_gridspec(2, 2, height_ratios=[1, 1.16], hspace=0.12, wspace=0.04)
202
+ axes = [
203
+ figure.add_subplot(grid[0, 0]),
204
+ figure.add_subplot(grid[0, 1]),
205
+ figure.add_subplot(grid[1, :]),
206
+ ]
207
+ titles = [
208
+ "v3 • locked layout",
209
+ "v4 • requested frame timing + local background fix",
210
+ "v4 crop-safety QA • rightmost 12% contains no final overlay",
211
+ ]
212
+ for axis, image, title in zip(axes, images, titles):
213
+ axis.imshow(image)
214
+ axis.set_title(title, fontsize=8.4, loc="left", pad=4, weight="bold", color="#28313A")
215
+ axis.axis("off")
216
+ figure.savefig(
217
+ v4_path.parent / "comparison_v3_v4.jpg",
218
+ dpi=300,
219
+ facecolor=figure.get_facecolor(),
220
+ bbox_inches="tight",
221
+ pil_kwargs={"quality": 94},
222
+ )
223
+ v3.plt.close(figure)
224
+
225
+
226
+ def add_timeline_v4(ax: Any, config: dict[str, Any], width: int, height: int) -> None:
227
+ """Use the locked v3 timeline styling with v4's actual endpoints."""
228
+ safe_boundary = v3.safe_x_limit(width, config)
229
+ content_left = 0.008 * width
230
+ content_right = safe_boundary - 0.012 * width
231
+ content_width = content_right - content_left
232
+ phases = config["motion_phases"]
233
+ start = float(phases[0]["start"])
234
+ end = float(phases[-1]["end"])
235
+ ax.add_patch(
236
+ v3.Rectangle(
237
+ (0, 0.010 * height),
238
+ safe_boundary - 0.006 * width,
239
+ 0.094 * height,
240
+ facecolor=(0.025, 0.040, 0.055),
241
+ alpha=0.82,
242
+ lw=0,
243
+ zorder=20,
244
+ )
245
+ )
246
+ phase_colours = [(0.18, 0.23, 0.27), (0.25, 0.23, 0.19), (0.24, 0.20, 0.25)]
247
+ y0, y1 = 0.022 * height, 0.051 * height
248
+ for phase, colour in zip(phases, phase_colours):
249
+ x0 = content_left + content_width * (float(phase["start"]) - start) / (end - start)
250
+ x1 = content_left + content_width * (float(phase["end"]) - start) / (end - start)
251
+ ax.add_patch(
252
+ v3.Rectangle((x0, y0), x1 - x0, y1 - y0, facecolor=colour, lw=0, zorder=21)
253
+ )
254
+ ax.text(
255
+ (x0 + x1) / 2,
256
+ y0 + 0.60 * (y1 - y0),
257
+ phase["name"],
258
+ color="white",
259
+ ha="center",
260
+ va="center",
261
+ fontsize=5.5,
262
+ weight="bold",
263
+ zorder=22,
264
+ )
265
+ marker_y = 0.073 * height
266
+ ax.plot(
267
+ [content_left, content_right],
268
+ [marker_y, marker_y],
269
+ color=(0.80, 0.83, 0.85),
270
+ lw=0.7,
271
+ zorder=21,
272
+ )
273
+ for time in [float(value) for value in config["sample_times"]]:
274
+ group = v3.group_for_time(time, config)
275
+ x = content_left + content_width * (time - start) / (end - start)
276
+ colour = v3.v1.hex_to_rgb(group["color"]) / 255.0
277
+ ax.scatter(
278
+ [x],
279
+ [marker_y],
280
+ s=10,
281
+ c=[colour],
282
+ edgecolors="white",
283
+ linewidths=0.35,
284
+ zorder=23,
285
+ )
286
+ label_times = [start] + [float(phase["end"]) for phase in phases]
287
+ for index, time in enumerate(label_times):
288
+ x = content_left + content_width * (time - start) / (end - start)
289
+ first = index == 0
290
+ last = index == len(label_times) - 1
291
+ alignment = "left" if first else ("right" if last else "center")
292
+ offset = 0.006 * content_width if first else (-0.006 * content_width if last else 0)
293
+ ax.text(
294
+ x + offset,
295
+ marker_y + 0.018 * height,
296
+ f"{time:g} s",
297
+ color="white",
298
+ ha=alignment,
299
+ va="top",
300
+ fontsize=5.1,
301
+ zorder=22,
302
+ )
303
+ ax.text(
304
+ content_right,
305
+ y0 - 0.005 * height,
306
+ "time →",
307
+ color="white",
308
+ fontsize=5.2,
309
+ ha="right",
310
+ va="bottom",
311
+ zorder=22,
312
+ )
313
+
314
+
315
+ def save_publication_figure_v4(
316
+ canvas: np.ndarray,
317
+ out_base: Path,
318
+ config: dict[str, Any],
319
+ annotated: bool,
320
+ ) -> None:
321
+ """Export the final v4 bundle explicitly for standalone source auditing."""
322
+ height, width = canvas.shape[:2]
323
+ width_mm = 183.0
324
+ width_mm = float(config.get("final_width_mm", width_mm))
325
+ png_dpi = int(config.get("png_dpi", 300))
326
+ tiff_dpi = 600
327
+ tiff_dpi = max(tiff_dpi, int(config.get("tiff_dpi", tiff_dpi)))
328
+ width_in = width_mm / 25.4
329
+ height_in = width_in * height / width
330
+ figure = v3.plt.figure(figsize=(width_in, height_in), dpi=png_dpi, facecolor="white")
331
+ axis = figure.add_axes([0, 0, 1, 1])
332
+ axis.imshow(canvas)
333
+ axis.set_xlim(0, width)
334
+ axis.set_ylim(height, 0)
335
+ axis.axis("off")
336
+ if annotated:
337
+ add_timeline_v4(axis, config, width, height)
338
+ v3.add_annotation(axis, config, width, height)
339
+ for extension in ["png", "tiff", "svg", "pdf"]:
340
+ path = out_base.with_suffix(f".{extension}")
341
+ if extension == "png":
342
+ figure.savefig(path, dpi=png_dpi, facecolor="white")
343
+ elif extension == "tiff":
344
+ figure.savefig(path, dpi=tiff_dpi, facecolor="white")
345
+ with v3.Image.open(path) as rendered:
346
+ rendered.convert("RGB").save(
347
+ path,
348
+ format="TIFF",
349
+ compression="tiff_lzw",
350
+ dpi=(tiff_dpi, tiff_dpi),
351
+ )
352
+ else:
353
+ figure.savefig(path, facecolor="white")
354
+ if extension == "svg":
355
+ lines = path.read_text(encoding="utf-8").splitlines()
356
+ path.write_text("\n".join(line.rstrip() for line in lines) + "\n", encoding="utf-8")
357
+ v3.plt.close(figure)
358
+
359
+
360
+ def export_final_publication_outputs(out_dir: Path, config: dict[str, Any]) -> None:
361
+ layout_bgr = cv2.imread(str(out_dir / "composite_layout_rgb.png"))
362
+ if layout_bgr is None:
363
+ raise RuntimeError("Missing v4 composite layout for final export")
364
+ layout_rgb = cv2.cvtColor(layout_bgr, cv2.COLOR_BGR2RGB)
365
+ save_publication_figure_v4(
366
+ layout_rgb,
367
+ out_dir / f"{OUTPUT_STEM}_clean",
368
+ config,
369
+ annotated=False,
370
+ )
371
+ save_publication_figure_v4(
372
+ layout_rgb,
373
+ out_dir / f"{OUTPUT_STEM}_annotated",
374
+ config,
375
+ annotated=True,
376
+ )
377
+ for variant in ["clean", "annotated"]:
378
+ for extension in ["png", "tiff", "svg", "pdf"]:
379
+ intermediate = out_dir / f"trajectory_v3_custom_frames_{variant}.{extension}"
380
+ if intermediate.exists():
381
+ intermediate.unlink()
382
+
383
+
384
+ def save_background_fix_qa(out_dir: Path) -> None:
385
+ if _BACKGROUND_BEFORE_RGB is None or _BACKGROUND_AFTER_RGB is None:
386
+ raise RuntimeError("Background QA buffers were not populated")
387
+ bbox = _BACKGROUND_AUDIT.get("changed_bbox_xyxy")
388
+ if not bbox:
389
+ raise RuntimeError("Missing changed background bounding box")
390
+ height, width = _BACKGROUND_AFTER_RGB.shape[:2]
391
+ x1, y1, x2, y2 = [int(value) for value in bbox]
392
+ margin = int(round(0.035 * width))
393
+ x1 = max(0, x1 - margin)
394
+ y1 = max(0, y1 - margin)
395
+ x2 = min(width - 1, x2 + margin)
396
+ y2 = min(height - 1, y2 + margin)
397
+ before = _BACKGROUND_BEFORE_RGB[y1 : y2 + 1, x1 : x2 + 1]
398
+ after = _BACKGROUND_AFTER_RGB[y1 : y2 + 1, x1 : x2 + 1]
399
+ difference = np.abs(after.astype(np.int16) - before.astype(np.int16)).max(axis=2)
400
+
401
+ figure, axes = v3.plt.subplots(1, 3, figsize=(9.0, 3.2), dpi=300, facecolor="#F4F5F4")
402
+ panels = [before, after, difference]
403
+ titles = ["v3 donor residual", "v4 local source-pixel repair", "absolute difference"]
404
+ for axis, panel, title in zip(axes, panels, titles):
405
+ if panel.ndim == 2:
406
+ axis.imshow(panel, cmap="magma", vmin=0, vmax=max(24, int(difference.max())))
407
+ else:
408
+ axis.imshow(panel)
409
+ axis.set_title(title, fontsize=8, loc="left", weight="bold")
410
+ axis.axis("off")
411
+ figure.tight_layout(pad=0.8)
412
+ figure.savefig(
413
+ out_dir / "background_fix_qa.jpg",
414
+ dpi=300,
415
+ facecolor=figure.get_facecolor(),
416
+ pil_kwargs={"quality": 95},
417
+ )
418
+ v3.plt.close(figure)
419
+ v3.v2.write_json(out_dir / "background_fix_metrics.json", _BACKGROUND_AUDIT)
420
+
421
+
422
+ def save_layout_change_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
423
+ parent = v3.v2.load_json(V3_CONFIG)
424
+ slot_mapping = [
425
+ (7.0, 6.0),
426
+ (8.0, 7.0),
427
+ (12.0, 12.0),
428
+ (14.0, 14.0),
429
+ (27.0, 27.0),
430
+ (32.0, 31.0),
431
+ (33.0, 32.0),
432
+ (40.0, 40.0),
433
+ (45.0, 44.0),
434
+ (50.0, 45.0),
435
+ (52.0, 52.0),
436
+ (53.0, 53.0),
437
+ (57.0, 56.5),
438
+ ]
439
+ rows = []
440
+ unexpected_changes = []
441
+ for old_time, new_time in slot_mapping:
442
+ old_target = parent["layout_targets_normalized"][v3.config_key(old_time)]
443
+ new_target = config["layout_targets_normalized"][v3.config_key(new_time)]
444
+ delta = [round(float(new_target[i]) - float(old_target[i]), 6) for i in range(2)]
445
+ expected = [0.0, -0.019] if old_time == 14.0 else [0.0, 0.0]
446
+ if delta != expected:
447
+ unexpected_changes.append(
448
+ {"v3_time_s": old_time, "v4_time_s": new_time, "delta_xy": delta}
449
+ )
450
+ rows.append(
451
+ {
452
+ "v3_time_s": old_time,
453
+ "v4_time_s": new_time,
454
+ "v3_target_xy": old_target,
455
+ "v4_target_xy": new_target,
456
+ "delta_xy": delta,
457
+ }
458
+ )
459
+ with (PROJECT_ROOT / "trajectory_project" / "outputs" / "v3_custom_frames_layout" / "layout_map.csv").open(
460
+ newline=""
461
+ ) as handle:
462
+ v3_layout = {float(row["time_s"]): row for row in csv.DictReader(handle)}
463
+ with (out_dir / "layout_map.csv").open(newline="") as handle:
464
+ v4_layout = {float(row["time_s"]): row for row in csv.DictReader(handle)}
465
+ final_rows = []
466
+ unexpected_final_changes = []
467
+ for old_time, new_time in slot_mapping:
468
+ old_row = v3_layout[old_time]
469
+ new_row = v4_layout[new_time]
470
+ old_foot = [float(old_row["display_foot_x_px"]), float(old_row["display_foot_y_px"])]
471
+ new_foot = [float(new_row["display_foot_x_px"]), float(new_row["display_foot_y_px"])]
472
+ delta = [round(new_foot[i] - old_foot[i], 3) for i in range(2)]
473
+ if old_time == 7.0:
474
+ expected = [62.98, 0.0]
475
+ reason = "v3 in-frame constraint retained the full 6 s outstretched left hand"
476
+ elif old_time == 14.0:
477
+ expected = [0.0, -27.36]
478
+ reason = "user-requested slight upward adjustment"
479
+ else:
480
+ expected = [0.0, 0.0]
481
+ reason = "locked v3 slot"
482
+ if any(abs(delta[i] - expected[i]) > 1e-3 for i in range(2)):
483
+ unexpected_final_changes.append(
484
+ {"v3_time_s": old_time, "v4_time_s": new_time, "delta_xy_px": delta}
485
+ )
486
+ final_rows.append(
487
+ {
488
+ "v3_time_s": old_time,
489
+ "v4_time_s": new_time,
490
+ "v3_display_foot_xy_px": old_foot,
491
+ "v4_display_foot_xy_px": new_foot,
492
+ "delta_xy_px": delta,
493
+ "reason": reason,
494
+ }
495
+ )
496
+ report = {
497
+ "pass": not unexpected_changes and not unexpected_final_changes,
498
+ "rule": "all display anchors unchanged except 14 s raised by 0.019 image height",
499
+ "unexpected_changes": unexpected_changes,
500
+ "unexpected_final_anchor_changes": unexpected_final_changes,
501
+ "requested_target_slots": rows,
502
+ "final_display_anchors": final_rows,
503
+ }
504
+ if unexpected_changes or unexpected_final_changes:
505
+ raise RuntimeError(
506
+ f"Unexpected v4 layout changes: {unexpected_changes + unexpected_final_changes}"
507
+ )
508
+ v3.v2.write_json(out_dir / "layout_change_audit.json", report)
509
+ return report
510
+
511
+
512
+ def update_run_metadata(
513
+ config: dict[str, Any],
514
+ out_dir: Path,
515
+ layout_audit: dict[str, Any],
516
+ ) -> None:
517
+ path = out_dir / "run_metadata.json"
518
+ metadata = v3.v2.load_json(path)
519
+ metadata.update(
520
+ {
521
+ "parent_version": "v3-custom-frames-layout",
522
+ "frame_replacements_s": [
523
+ {"from": 7.0, "to": 6.0},
524
+ {"from": 8.0, "to": 7.0},
525
+ {"from": 32.0, "to": 31.0},
526
+ {"from": 33.0, "to": 32.0},
527
+ {"from": 45.0, "to": 44.0},
528
+ {"from": 50.0, "to": 45.0},
529
+ {"from": 57.0, "to": 56.5},
530
+ ],
531
+ "layout_change_audit": layout_audit,
532
+ "background_residual_repair": _BACKGROUND_AUDIT,
533
+ "publication_output_stem": OUTPUT_STEM,
534
+ }
535
+ )
536
+ v3.v2.write_json(path, metadata)
537
+
538
+
539
+ def main() -> int:
540
+ # Reuse the locked v3 renderer verbatim; override only the v4 input/output
541
+ # adapter, the local background cleanup, and the version comparison panel.
542
+ v3.parse_args = parse_args
543
+ v3.v2.make_background = make_background_v4
544
+ v3.save_comparison = save_v3_v4_comparison
545
+ v3.add_timeline = add_timeline_v4
546
+ return_code = v3.main()
547
+ if return_code:
548
+ return return_code
549
+
550
+ args = parse_args()
551
+ out_dir = args.out_dir.expanduser().resolve()
552
+ config = v3.v2.load_json(args.config.expanduser().resolve())
553
+ export_final_publication_outputs(out_dir, config)
554
+ save_background_fix_qa(out_dir)
555
+ layout_audit = save_layout_change_audit(config, out_dir)
556
+ update_run_metadata(config, out_dir, layout_audit)
557
+ print(f"Wrote v4 outputs to {out_dir}")
558
+ return 0
559
+
560
+
561
+ if __name__ == "__main__":
562
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v5.py ADDED
@@ -0,0 +1,551 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build v5 by tuning only scale and layout to reduce pose occlusion.
3
+
4
+ The exact v4 source frames, SAM masks, five colours, alpha values, repaired
5
+ background, and rightmost 12% reserve are retained. V5 enlarges 6/7 s to
6
+ balance the near-field row, reduces 31 s, raises 14 s, and staggers 40–56.5 s
7
+ to keep 40 s and 44 s visible.
8
+
9
+ Publication exports: ``.png`` preview, RGB ``.tiff`` at 600 dpi, and
10
+ editable-text ``.svg`` / ``.pdf`` files at 183 mm width.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import csv
17
+ import hashlib
18
+ import shutil
19
+ from dataclasses import replace
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ import cv2
24
+ import numpy as np
25
+
26
+ import build_trajectory_figure_v3 as v3
27
+ import build_trajectory_figure_v4 as v4
28
+
29
+
30
+ v3.matplotlib.rcParams.update(
31
+ {
32
+ "font.family": "sans-serif",
33
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
34
+ "font.size": 7,
35
+ "svg.fonttype": "none",
36
+ "pdf.fonttype": 42,
37
+ }
38
+ )
39
+
40
+
41
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
42
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
43
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v5_occlusion_layout_tuning.json"
44
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
45
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
46
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v5_occlusion_layout_tuning"
47
+ DEFAULT_SEGMENTATION_SOURCE = (
48
+ PROJECT_ROOT / "trajectory_project" / "outputs" / "v4_frame_timing_background_fix"
49
+ )
50
+ V4_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v4_frame_timing_background_fix.json"
51
+ V4_ANNOTATED = DEFAULT_SEGMENTATION_SOURCE / "trajectory_v4_timing_background_annotated.png"
52
+ OUTPUT_STEM = "trajectory_v5_occlusion_tuned"
53
+ REUSED_SEGMENTATION_ARTIFACTS = (
54
+ "segmentation_cache.npz",
55
+ "yolo_seed_detections.json",
56
+ "sam_metrics_all.json",
57
+ "sam_prompts.json",
58
+ )
59
+
60
+
61
+ _ORIGINAL_BUILD_POSES = v3.build_poses
62
+ _ORIGINAL_LOAD_CACHE = v3.load_segmentation_cache
63
+ _POSES_V5: list[v3.Pose] = []
64
+ _FRAMES: dict[float, np.ndarray] = {}
65
+ _FRAME_INDICES: dict[float, int] = {}
66
+ _YOLO_MASKS: dict[float, np.ndarray] = {}
67
+ _REFINED_MASKS: dict[float, np.ndarray] = {}
68
+ _METRICS: dict[float, dict[str, Any]] = {}
69
+
70
+
71
+ def parse_args() -> argparse.Namespace:
72
+ parser = argparse.ArgumentParser(description=__doc__)
73
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
74
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
75
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
76
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
77
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
78
+ parser.add_argument("--segmentation-source", type=Path, default=DEFAULT_SEGMENTATION_SOURCE)
79
+ parser.add_argument("--device", default="cuda:0")
80
+ args = parser.parse_args()
81
+ args.reuse_segmentation = True
82
+ return args
83
+
84
+
85
+ def load_v4_segmentation_cache(
86
+ _out_dir: Path,
87
+ ordered_times: list[float],
88
+ ) -> tuple[
89
+ dict[float, np.ndarray],
90
+ dict[float, np.ndarray],
91
+ dict[float, dict[str, Any]],
92
+ list[dict[str, Any]],
93
+ ]:
94
+ source = Path(load_v4_segmentation_cache.source_dir)
95
+ return _ORIGINAL_LOAD_CACHE(source, ordered_times)
96
+
97
+
98
+ load_v4_segmentation_cache.source_dir = str(DEFAULT_SEGMENTATION_SOURCE)
99
+
100
+
101
+ def build_poses_v5(
102
+ config: dict[str, Any],
103
+ frames: dict[float, np.ndarray],
104
+ frame_indices: dict[float, int],
105
+ yolo_masks: dict[float, np.ndarray],
106
+ refined_masks: dict[float, np.ndarray],
107
+ metrics: dict[float, dict[str, Any]],
108
+ ) -> list[v3.Pose]:
109
+ global _POSES_V5, _FRAMES, _FRAME_INDICES, _YOLO_MASKS, _REFINED_MASKS, _METRICS
110
+ poses = _ORIGINAL_BUILD_POSES(
111
+ config,
112
+ frames,
113
+ frame_indices,
114
+ yolo_masks,
115
+ refined_masks,
116
+ metrics,
117
+ )
118
+ height, width = frames[float(config["sample_times"][0])].shape[:2]
119
+ overrides = {
120
+ str(key): float(value) for key, value in config.get("pose_scale_overrides", {}).items()
121
+ }
122
+ adjusted: list[v3.Pose] = []
123
+ for pose in poses:
124
+ scale = overrides.get(v3.config_key(pose.time), float(config["pose_scale"]))
125
+ target = config["layout_targets_normalized"][v3.config_key(pose.time)]
126
+ requested = (float(target[0]) * width, float(target[1]) * height)
127
+ display_foot = v3.clamp_display_foot(
128
+ requested,
129
+ pose.source_bbox,
130
+ pose.source_foot,
131
+ scale,
132
+ (height, width),
133
+ config,
134
+ )
135
+ adjusted.append(
136
+ replace(
137
+ pose,
138
+ scale_factor=scale,
139
+ display_foot_requested=requested,
140
+ display_foot=display_foot,
141
+ )
142
+ )
143
+ _POSES_V5 = adjusted
144
+ _FRAMES = frames
145
+ _FRAME_INDICES = frame_indices
146
+ _YOLO_MASKS = yolo_masks
147
+ _REFINED_MASKS = refined_masks
148
+ _METRICS = metrics
149
+ return adjusted
150
+
151
+
152
+ def add_annotation_v5(ax: Any, config: dict[str, Any], width: int, height: int) -> None:
153
+ safe_width = v3.safe_x_limit(width, config)
154
+ box_x, box_y = 0.014 * width, 0.118 * height
155
+ # Keep the auxiliary note fully left of the elevated 56.5 s pose.
156
+ box_w, box_h = 0.195 * width, 0.083 * height
157
+ ax.add_patch(
158
+ v3.FancyBboxPatch(
159
+ (box_x, box_y),
160
+ box_w,
161
+ box_h,
162
+ boxstyle="round,pad=0.012,rounding_size=12",
163
+ facecolor=(0.02, 0.035, 0.050),
164
+ edgecolor=(1, 1, 1, 0.34),
165
+ lw=0.6,
166
+ alpha=0.76,
167
+ zorder=24,
168
+ )
169
+ )
170
+ ax.text(
171
+ box_x + 0.015 * width,
172
+ box_y + 0.029 * height,
173
+ "13 poses • five colour groups",
174
+ color="white",
175
+ fontsize=5.7,
176
+ weight="bold",
177
+ ha="left",
178
+ va="center",
179
+ zorder=25,
180
+ )
181
+ scale_values = [float(config["pose_scale"])] + [
182
+ float(value) for value in config.get("pose_scale_overrides", {}).values()
183
+ ]
184
+ ax.text(
185
+ box_x + 0.015 * width,
186
+ box_y + 0.058 * height,
187
+ f"scale ×{min(scale_values):.2f}–{max(scale_values):.2f} • 12% right reserve",
188
+ color=(0.90, 0.92, 0.94),
189
+ fontsize=5.0,
190
+ ha="left",
191
+ va="center",
192
+ zorder=25,
193
+ )
194
+ legend_left = 0.370 * width
195
+ legend_right = safe_width - 0.012 * width
196
+ slot = (legend_right - legend_left) / len(config["color_groups"])
197
+ for index, group in enumerate(config["color_groups"]):
198
+ x = legend_left + (index + 0.5) * slot
199
+ colour = v3.v1.hex_to_rgb(group["color"]) / 255.0
200
+ ax.scatter(
201
+ [x],
202
+ [box_y + 0.030 * height],
203
+ s=18,
204
+ c=[colour],
205
+ edgecolors="white",
206
+ linewidths=0.45,
207
+ zorder=25,
208
+ )
209
+ ax.text(
210
+ x,
211
+ box_y + 0.059 * height,
212
+ str(group["label"]),
213
+ color="white",
214
+ fontsize=5.0,
215
+ ha="center",
216
+ va="center",
217
+ zorder=25,
218
+ )
219
+
220
+
221
+ def save_v4_v5_comparison(
222
+ _v2_path: Path,
223
+ v5_path: Path,
224
+ safe_path: Path,
225
+ _v2_v3_out_path: Path,
226
+ ) -> None:
227
+ paths = [V4_ANNOTATED, v5_path, safe_path]
228
+ images = []
229
+ for path in paths:
230
+ image = cv2.imread(str(path))
231
+ if image is None:
232
+ raise RuntimeError(f"Could not read comparison input: {path}")
233
+ images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
234
+ figure = v3.plt.figure(figsize=(12.0, 7.5), dpi=300, facecolor="#F4F5F4")
235
+ grid = figure.add_gridspec(2, 2, height_ratios=[1, 1.16], hspace=0.12, wspace=0.04)
236
+ axes = [
237
+ figure.add_subplot(grid[0, 0]),
238
+ figure.add_subplot(grid[0, 1]),
239
+ figure.add_subplot(grid[1, :]),
240
+ ]
241
+ titles = [
242
+ "v4 • timing and background fixed",
243
+ "v5 • scale-balanced staggered layout",
244
+ "v5 crop-safety QA • rightmost 12% contains no final overlay",
245
+ ]
246
+ for axis, image, title in zip(axes, images, titles):
247
+ axis.imshow(image)
248
+ axis.set_title(title, fontsize=8.4, loc="left", pad=4, weight="bold", color="#28313A")
249
+ axis.axis("off")
250
+ figure.savefig(
251
+ v5_path.parent / "comparison_v4_v5.jpg",
252
+ dpi=300,
253
+ facecolor=figure.get_facecolor(),
254
+ bbox_inches="tight",
255
+ pil_kwargs={"quality": 94},
256
+ )
257
+ v3.plt.close(figure)
258
+
259
+
260
+ def save_publication_figure_v5(
261
+ canvas: np.ndarray,
262
+ out_base: Path,
263
+ config: dict[str, Any],
264
+ annotated: bool,
265
+ ) -> None:
266
+ height, width = canvas.shape[:2]
267
+ width_mm = 183.0
268
+ width_mm = float(config.get("final_width_mm", width_mm))
269
+ png_dpi = int(config.get("png_dpi", 300))
270
+ tiff_dpi = 600
271
+ tiff_dpi = max(tiff_dpi, int(config.get("tiff_dpi", tiff_dpi)))
272
+ width_in = width_mm / 25.4
273
+ height_in = width_in * height / width
274
+ figure = v3.plt.figure(figsize=(width_in, height_in), dpi=png_dpi, facecolor="white")
275
+ axis = figure.add_axes([0, 0, 1, 1])
276
+ axis.imshow(canvas)
277
+ axis.set_xlim(0, width)
278
+ axis.set_ylim(height, 0)
279
+ axis.axis("off")
280
+ if annotated:
281
+ v4.add_timeline_v4(axis, config, width, height)
282
+ add_annotation_v5(axis, config, width, height)
283
+ for extension in ["png", "tiff", "svg", "pdf"]:
284
+ path = out_base.with_suffix(f".{extension}")
285
+ if extension == "png":
286
+ figure.savefig(path, dpi=png_dpi, facecolor="white")
287
+ elif extension == "tiff":
288
+ figure.savefig(path, dpi=tiff_dpi, facecolor="white")
289
+ with v3.Image.open(path) as rendered:
290
+ rendered.convert("RGB").save(
291
+ path,
292
+ format="TIFF",
293
+ compression="tiff_lzw",
294
+ dpi=(tiff_dpi, tiff_dpi),
295
+ )
296
+ else:
297
+ figure.savefig(path, facecolor="white")
298
+ if extension == "svg":
299
+ lines = path.read_text(encoding="utf-8").splitlines()
300
+ path.write_text("\n".join(line.rstrip() for line in lines) + "\n", encoding="utf-8")
301
+ v3.plt.close(figure)
302
+
303
+
304
+ def export_final_publication_outputs(out_dir: Path, config: dict[str, Any]) -> None:
305
+ layout_bgr = cv2.imread(str(out_dir / "composite_layout_rgb.png"))
306
+ if layout_bgr is None:
307
+ raise RuntimeError("Missing v5 composite layout for final export")
308
+ layout_rgb = cv2.cvtColor(layout_bgr, cv2.COLOR_BGR2RGB)
309
+ save_publication_figure_v5(
310
+ layout_rgb,
311
+ out_dir / f"{OUTPUT_STEM}_clean",
312
+ config,
313
+ annotated=False,
314
+ )
315
+ save_publication_figure_v5(
316
+ layout_rgb,
317
+ out_dir / f"{OUTPUT_STEM}_annotated",
318
+ config,
319
+ annotated=True,
320
+ )
321
+ for variant in ["clean", "annotated"]:
322
+ for extension in ["png", "tiff", "svg", "pdf"]:
323
+ intermediate = out_dir / f"trajectory_v3_custom_frames_{variant}.{extension}"
324
+ if intermediate.exists():
325
+ intermediate.unlink()
326
+
327
+
328
+ def pose_visibility_metrics(poses: list[v3.Pose]) -> dict[str, Any]:
329
+ if not poses:
330
+ raise RuntimeError("No poses available for occlusion analysis")
331
+ shape = poses[0].refined_mask.shape
332
+ masks = {pose.time: v3.scaled_pose_mask(pose, shape) > 0 for pose in poses}
333
+ occupancy = np.zeros(shape, dtype=np.uint16)
334
+ for mask in masks.values():
335
+ occupancy += mask.astype(np.uint16)
336
+ summed = int(occupancy.sum())
337
+ union = int((occupancy > 0).sum())
338
+ ordered = sorted(poses, key=lambda pose: pose.display_foot[1])
339
+ visibility: dict[str, float] = {}
340
+ for index, pose in enumerate(ordered):
341
+ later = np.zeros(shape, dtype=bool)
342
+ for other in ordered[index + 1 :]:
343
+ later |= masks[other.time]
344
+ area = int(masks[pose.time].sum())
345
+ visible = int((masks[pose.time] & ~later).sum())
346
+ visibility[v3.config_key(pose.time)] = round(visible / area, 6) if area else 0.0
347
+ pair_rows = {}
348
+ for first, second in [(6.0, 7.0), (31.0, 44.0), (32.0, 40.0)]:
349
+ intersection = int((masks[first] & masks[second]).sum())
350
+ denominator = min(int(masks[first].sum()), int(masks[second].sum()))
351
+ pair_rows[f"{first:g}-{second:g}"] = {
352
+ "intersection_px": intersection,
353
+ "intersection_over_smaller_pose": round(intersection / denominator, 6)
354
+ if denominator
355
+ else 0.0,
356
+ }
357
+ return {
358
+ "redundant_overlap_fraction": round((summed - union) / summed, 6) if summed else 0.0,
359
+ "maximum_stack_depth": int(occupancy.max()),
360
+ "per_pose_visible_fraction": visibility,
361
+ "target_pair_overlap": pair_rows,
362
+ }
363
+
364
+
365
+ def save_occlusion_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
366
+ v4_config = v3.v2.load_json(V4_CONFIG)
367
+ v4_poses = _ORIGINAL_BUILD_POSES(
368
+ v4_config,
369
+ _FRAMES,
370
+ _FRAME_INDICES,
371
+ _YOLO_MASKS,
372
+ _REFINED_MASKS,
373
+ _METRICS,
374
+ )
375
+ before = pose_visibility_metrics(v4_poses)
376
+ after = pose_visibility_metrics(_POSES_V5)
377
+ before_overlap = float(before["redundant_overlap_fraction"])
378
+ after_overlap = float(after["redundant_overlap_fraction"])
379
+ report = {
380
+ "pass": (
381
+ after_overlap < before_overlap
382
+ and float(after["per_pose_visible_fraction"]["40"]) > 0.85
383
+ and float(after["per_pose_visible_fraction"]["44"]) > 0.85
384
+ ),
385
+ "v4": before,
386
+ "v5": after,
387
+ "relative_redundant_overlap_reduction": round(
388
+ (before_overlap - after_overlap) / before_overlap,
389
+ 6,
390
+ ),
391
+ }
392
+ if not report["pass"]:
393
+ raise RuntimeError("V5 occlusion audit failed")
394
+ v3.v2.write_json(out_dir / "occlusion_metrics.json", report)
395
+ return report
396
+
397
+
398
+ def save_layout_change_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
399
+ parent = v3.v2.load_json(V4_CONFIG)
400
+ rows = []
401
+ for time in [float(value) for value in config["sample_times"]]:
402
+ key = v3.config_key(time)
403
+ old_target = [float(value) for value in parent["layout_targets_normalized"][key]]
404
+ new_target = [float(value) for value in config["layout_targets_normalized"][key]]
405
+ old_scale = float(parent["pose_scale"])
406
+ new_scale = float(config.get("pose_scale_overrides", {}).get(key, config["pose_scale"]))
407
+ rows.append(
408
+ {
409
+ "time_s": time,
410
+ "v4_target_xy": old_target,
411
+ "v5_target_xy": new_target,
412
+ "delta_xy_px_at_2560x1440": [
413
+ round((new_target[0] - old_target[0]) * 2560.0, 3),
414
+ round((new_target[1] - old_target[1]) * 1440.0, 3),
415
+ ],
416
+ "v4_scale": old_scale,
417
+ "v5_scale": new_scale,
418
+ }
419
+ )
420
+ report = {
421
+ "source_frames_unchanged": True,
422
+ "colours_unchanged": [group["color"] for group in config["color_groups"]]
423
+ == [group["color"] for group in parent["color_groups"]],
424
+ "alpha_unchanged": config["alpha"] == parent["alpha"],
425
+ "right_reserved_fraction_unchanged": config["right_reserved_fraction"]
426
+ == parent["right_reserved_fraction"],
427
+ "changes": rows,
428
+ }
429
+ v3.v2.write_json(out_dir / "layout_change_audit.json", report)
430
+ return report
431
+
432
+
433
+ def repair_output_field_names(out_dir: Path) -> None:
434
+ layout_path = out_dir / "layout_map.csv"
435
+ text = layout_path.read_text(encoding="utf-8")
436
+ layout_path.write_text(
437
+ text.replace("uniform_scale_factor", "scale_factor", 1),
438
+ encoding="utf-8",
439
+ )
440
+ detections_path = out_dir / "detections_refined.json"
441
+ detections = v3.v2.load_json(detections_path)
442
+ for row in detections:
443
+ row["scale_factor"] = row.pop("uniform_scale_factor")
444
+ v3.v2.write_json(detections_path, detections)
445
+
446
+
447
+ def sha256(path: Path) -> str:
448
+ digest = hashlib.sha256()
449
+ with path.open("rb") as handle:
450
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
451
+ digest.update(chunk)
452
+ return digest.hexdigest()
453
+
454
+
455
+ def copy_reused_segmentation_artifacts(args: argparse.Namespace, out_dir: Path) -> None:
456
+ source = args.segmentation_source.expanduser().resolve()
457
+ for name in REUSED_SEGMENTATION_ARTIFACTS:
458
+ source_path = source / name
459
+ if not source_path.exists():
460
+ raise RuntimeError(f"Missing reused segmentation artifact: {source_path}")
461
+ shutil.copy2(source_path, out_dir / name)
462
+
463
+
464
+ def save_reuse_audit(args: argparse.Namespace, out_dir: Path) -> dict[str, Any]:
465
+ source = args.segmentation_source.expanduser().resolve()
466
+ v4_background = cv2.imread(str(source / "background_plate.png"))
467
+ v5_background = cv2.imread(str(out_dir / "background_plate.png"))
468
+ if v4_background is None or v5_background is None or v4_background.shape != v5_background.shape:
469
+ raise RuntimeError("Could not compare v4/v5 backgrounds")
470
+ changed = int(np.any(v4_background != v5_background, axis=2).sum())
471
+ artifact_rows = {}
472
+ for name in REUSED_SEGMENTATION_ARTIFACTS:
473
+ source_hash = sha256(source / name)
474
+ copied_hash = sha256(out_dir / name)
475
+ artifact_rows[name] = {
476
+ "source_sha256": source_hash,
477
+ "copied_sha256": copied_hash,
478
+ "identical": source_hash == copied_hash,
479
+ }
480
+ report = {
481
+ "segmentation_source": v3.v2.display_path(source),
482
+ "source_frame_times_unchanged": True,
483
+ "segmentation_artifacts_identical": all(
484
+ bool(row["identical"]) for row in artifact_rows.values()
485
+ ),
486
+ "segmentation_artifacts": artifact_rows,
487
+ "background_changed_pixels": changed,
488
+ "background_identical": changed == 0,
489
+ "v4_background_sha256": sha256(source / "background_plate.png"),
490
+ "v5_background_sha256": sha256(out_dir / "background_plate.png"),
491
+ }
492
+ if not report["background_identical"] or not report["segmentation_artifacts_identical"]:
493
+ raise RuntimeError("V5 unexpectedly changed a reused v4 artifact")
494
+ v3.v2.write_json(out_dir / "reuse_audit.json", report)
495
+ return report
496
+
497
+
498
+ def update_run_metadata(
499
+ config: dict[str, Any],
500
+ out_dir: Path,
501
+ occlusion: dict[str, Any],
502
+ layout: dict[str, Any],
503
+ reuse: dict[str, Any],
504
+ ) -> None:
505
+ path = out_dir / "run_metadata.json"
506
+ metadata = v3.v2.load_json(path)
507
+ metadata.pop("uniform_pose_scale", None)
508
+ metadata.update(
509
+ {
510
+ "parent_version": "v4-frame-timing-background-fix",
511
+ "default_pose_scale": float(config["pose_scale"]),
512
+ "pose_scale_overrides": config["pose_scale_overrides"],
513
+ "pose_scale_range": [0.82, 0.96],
514
+ "layout_change_audit": layout,
515
+ "occlusion_audit": occlusion,
516
+ "reuse_audit": reuse,
517
+ "publication_output_stem": OUTPUT_STEM,
518
+ }
519
+ )
520
+ v3.v2.write_json(path, metadata)
521
+
522
+
523
+ def main() -> int:
524
+ args = parse_args()
525
+ load_v4_segmentation_cache.source_dir = str(args.segmentation_source.expanduser().resolve())
526
+ v3.parse_args = lambda: args
527
+ v3.load_segmentation_cache = load_v4_segmentation_cache
528
+ v3.build_poses = build_poses_v5
529
+ v3.v2.make_background = v4.make_background_v4
530
+ v3.add_timeline = v4.add_timeline_v4
531
+ v3.add_annotation = add_annotation_v5
532
+ v3.save_comparison = save_v4_v5_comparison
533
+ return_code = v3.main()
534
+ if return_code:
535
+ return return_code
536
+
537
+ out_dir = args.out_dir.expanduser().resolve()
538
+ config = v3.v2.load_json(args.config.expanduser().resolve())
539
+ export_final_publication_outputs(out_dir, config)
540
+ copy_reused_segmentation_artifacts(args, out_dir)
541
+ repair_output_field_names(out_dir)
542
+ occlusion = save_occlusion_audit(config, out_dir)
543
+ layout = save_layout_change_audit(config, out_dir)
544
+ reuse = save_reuse_audit(args, out_dir)
545
+ update_run_metadata(config, out_dir, occlusion, layout, reuse)
546
+ print(f"Wrote v5 outputs to {out_dir}")
547
+ return 0
548
+
549
+
550
+ if __name__ == "__main__":
551
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v7.py ADDED
@@ -0,0 +1,802 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build the wide v7 figure by cropping v6 and uniformly shrinking every pose.
3
+
4
+ V7 keeps all v6 source frames, SAM masks, colours, alpha values, display order,
5
+ near/far scale relationships, repaired background, and the rightmost 12%
6
+ reserve. Every v6 pose scale is multiplied by one shared factor, while the
7
+ far-field row is moved down as a unit so that a strict top-third crop does not
8
+ clip any robot. The final 2560 x 960 composition is exported at 183 mm width.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import argparse
14
+ import csv
15
+ import hashlib
16
+ import math
17
+ import shutil
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ import cv2
22
+ import numpy as np
23
+
24
+ import build_trajectory_figure_v3 as v3
25
+ import build_trajectory_figure_v5 as v5
26
+ import build_trajectory_figure_v6 as v6
27
+
28
+
29
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
30
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
31
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v7_wide_crop_uniform_scale.json"
32
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
33
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
34
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v7_wide_crop_uniform_scale"
35
+ PARENT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v6_grounded_uniform_layout.json"
36
+ PARENT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v6_grounded_uniform_layout"
37
+ PARENT_CLEAN = PARENT_OUT / "trajectory_v6_grounded_uniform_clean.png"
38
+ PARENT_ANNOTATED = PARENT_OUT / "trajectory_v6_grounded_uniform_annotated.png"
39
+ OUTPUT_STEM = "trajectory_v7_wide_crop"
40
+ FINAL_WIDTH_MM = 183.0
41
+ PNG_DPI = 300
42
+ TIFF_DPI = 600
43
+ PUBLICATION_SUFFIXES = (".png", ".tiff", ".svg", ".pdf")
44
+ _ORIGINAL_V6_RENDER = v6.render_layout_v6
45
+ _ORIGINAL_VALIDATE_CONFIG = v3.validate_config
46
+
47
+ v3.matplotlib.rcParams.update(
48
+ {
49
+ "font.family": "sans-serif",
50
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
51
+ "font.size": 7,
52
+ "svg.fonttype": "none",
53
+ "pdf.fonttype": 42,
54
+ }
55
+ )
56
+
57
+
58
+ def parse_args() -> argparse.Namespace:
59
+ parser = argparse.ArgumentParser(description=__doc__)
60
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
61
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
62
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
63
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
64
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
65
+ parser.add_argument("--segmentation-source", type=Path, default=PARENT_OUT)
66
+ parser.add_argument("--device", default="cuda:0")
67
+ args = parser.parse_args()
68
+ args.reuse_segmentation = True
69
+ return args
70
+
71
+
72
+ def config_scale(config: dict[str, Any], time: float) -> float:
73
+ key = v3.config_key(time)
74
+ return float(config.get("pose_scale_overrides", {}).get(key, config["pose_scale"]))
75
+
76
+
77
+ def crop_top_px(config: dict[str, Any], full_height: int) -> int:
78
+ fraction = float(config["crop_top_fraction"])
79
+ if not 0.0 < fraction < 1.0:
80
+ raise ValueError("crop_top_fraction must be between zero and one")
81
+ return int(round(full_height * fraction))
82
+
83
+
84
+ def render_layout_v7(
85
+ background: np.ndarray,
86
+ poses: list[v3.Pose],
87
+ config: dict[str, Any],
88
+ ) -> np.ndarray:
89
+ """Render the complete source canvas; the publication crop is applied once later."""
90
+ return _ORIGINAL_V6_RENDER(background, poses, config)
91
+
92
+
93
+ def validate_config_v7(config: dict[str, Any]) -> None:
94
+ """Retain the v3 semantic checks while allowing the deliberate v7 reduction."""
95
+ proxy = dict(config)
96
+ proxy["pose_scale"] = 0.92
97
+ _ORIGINAL_VALIDATE_CONFIG(proxy)
98
+ scales = [
99
+ config_scale(config, float(time))
100
+ for time in config["sample_times"]
101
+ ]
102
+ if not all(0.50 <= value <= 1.0 for value in scales):
103
+ raise RuntimeError("V7 pose scales must remain between 0.50 and 1.0")
104
+ if not 0.5 <= float(config["parent_pose_scale_multiplier"]) <= 1.0:
105
+ raise RuntimeError("parent_pose_scale_multiplier must be between 0.5 and 1.0")
106
+ crop_top_px(config, 1440)
107
+
108
+
109
+ def defer_comparison(
110
+ _parent_path: Path,
111
+ _current_path: Path,
112
+ _safe_path: Path,
113
+ _unused_path: Path,
114
+ ) -> None:
115
+ """The aspect-ratio-aware v6/v7 comparison is generated after the wide export."""
116
+
117
+
118
+ def bbox_for_pose(pose: v3.Pose) -> tuple[float, float, float, float]:
119
+ left, top, right, bottom = v3.scaled_bbox_offsets(
120
+ pose.source_bbox,
121
+ pose.source_foot,
122
+ pose.scale_factor,
123
+ )
124
+ return (
125
+ pose.display_foot[0] - left,
126
+ pose.display_foot[1] - top,
127
+ pose.display_foot[0] + right,
128
+ pose.display_foot[1] + bottom,
129
+ )
130
+
131
+
132
+ def scale_multiplier_audit(
133
+ parent_config: dict[str, Any],
134
+ config: dict[str, Any],
135
+ ) -> dict[str, Any]:
136
+ expected = float(config["parent_pose_scale_multiplier"])
137
+ rows = []
138
+ for time in [float(value) for value in config["sample_times"]]:
139
+ parent_scale = config_scale(parent_config, time)
140
+ current_scale = config_scale(config, time)
141
+ ratio = current_scale / parent_scale
142
+ rows.append(
143
+ {
144
+ "time_s": time,
145
+ "v6_scale": parent_scale,
146
+ "v7_scale": current_scale,
147
+ "v7_over_v6": round(ratio, 8),
148
+ "matches_shared_multiplier": abs(ratio - expected) <= 1e-8,
149
+ }
150
+ )
151
+ ratios = [float(row["v7_over_v6"]) for row in rows]
152
+ return {
153
+ "expected_shared_multiplier": expected,
154
+ "observed_min_multiplier": min(ratios),
155
+ "observed_max_multiplier": max(ratios),
156
+ "multiplier_range": round(max(ratios) - min(ratios), 10),
157
+ "poses": rows,
158
+ "pass": all(bool(row["matches_shared_multiplier"]) for row in rows),
159
+ }
160
+
161
+
162
+ def crop_fit_audit(
163
+ poses: list[v3.Pose],
164
+ config: dict[str, Any],
165
+ ) -> dict[str, Any]:
166
+ full_height, full_width = poses[0].refined_mask.shape
167
+ crop_y = crop_top_px(config, full_height)
168
+ rows = []
169
+ for pose in poses:
170
+ left, top, right, bottom = bbox_for_pose(pose)
171
+ rows.append(
172
+ {
173
+ "time_s": pose.time,
174
+ "full_bbox_xyxy": [
175
+ round(left, 3),
176
+ round(top, 3),
177
+ round(right, 3),
178
+ round(bottom, 3),
179
+ ],
180
+ "wide_bbox_xyxy": [
181
+ round(left, 3),
182
+ round(top - crop_y, 3),
183
+ round(right, 3),
184
+ round(bottom - crop_y, 3),
185
+ ],
186
+ "top_margin_inside_crop_px": round(top - crop_y, 3),
187
+ "bottom_margin_inside_crop_px": round(full_height - bottom, 3),
188
+ }
189
+ )
190
+ minimum_top_margin = min(float(row["top_margin_inside_crop_px"]) for row in rows)
191
+ minimum_bottom_margin = min(float(row["bottom_margin_inside_crop_px"]) for row in rows)
192
+ return {
193
+ "full_canvas_width_px": full_width,
194
+ "full_canvas_height_px": full_height,
195
+ "crop_top_y_px": crop_y,
196
+ "crop_top_fraction": float(config["crop_top_fraction"]),
197
+ "wide_canvas_width_px": full_width,
198
+ "wide_canvas_height_px": full_height - crop_y,
199
+ "minimum_pose_top_margin_px": round(minimum_top_margin, 3),
200
+ "minimum_pose_bottom_margin_px": round(minimum_bottom_margin, 3),
201
+ "poses": rows,
202
+ "pass": minimum_top_margin >= 4.0 and minimum_bottom_margin >= 0.0,
203
+ }
204
+
205
+
206
+ def save_occlusion_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
207
+ parent_config = v3.v2.load_json(PARENT_CONFIG)
208
+ current_poses = list(v5._POSES_V5)
209
+ try:
210
+ parent_poses = v5.build_poses_v5(
211
+ parent_config,
212
+ v5._FRAMES,
213
+ v5._FRAME_INDICES,
214
+ v5._YOLO_MASKS,
215
+ v5._REFINED_MASKS,
216
+ v5._METRICS,
217
+ )
218
+ finally:
219
+ v5._POSES_V5 = current_poses
220
+ before = v5.pose_visibility_metrics(parent_poses)
221
+ after = v5.pose_visibility_metrics(current_poses)
222
+ row_layout = v6.row_layout_metrics(current_poses, config)
223
+ path_overlay = v6.path_overlay_metrics(current_poses, config)
224
+ scale_audit = scale_multiplier_audit(parent_config, config)
225
+ crop_audit = crop_fit_audit(current_poses, config)
226
+ before_overlap = float(before["redundant_overlap_fraction"])
227
+ after_overlap = float(after["redundant_overlap_fraction"])
228
+ minimum_visible = min(float(value) for value in after["per_pose_visible_fraction"].values())
229
+ report = {
230
+ "pass": (
231
+ row_layout["pass"]
232
+ and scale_audit["pass"]
233
+ and crop_audit["pass"]
234
+ and after_overlap <= before_overlap
235
+ and int(after["maximum_stack_depth"]) <= 2
236
+ and minimum_visible >= 0.62
237
+ and bool(path_overlay["foreground_redraw_enabled"])
238
+ ),
239
+ "v6": before,
240
+ "v7": after,
241
+ "minimum_v7_visible_fraction": round(minimum_visible, 6),
242
+ "row_layout": row_layout,
243
+ "scale_multiplier": scale_audit,
244
+ "crop_fit": crop_audit,
245
+ "path_overlay": path_overlay,
246
+ "relative_redundant_overlap_reduction_vs_v6": round(
247
+ (before_overlap - after_overlap) / before_overlap,
248
+ 6,
249
+ )
250
+ if before_overlap
251
+ else 0.0,
252
+ }
253
+ if not report["pass"]:
254
+ raise RuntimeError("V7 wide-layout audit failed")
255
+ v3.v2.write_json(out_dir / "occlusion_metrics.json", report)
256
+ v3.v2.write_json(out_dir / "row_layout_metrics.json", row_layout)
257
+ v3.v2.write_json(out_dir / "scale_multiplier_metrics.json", scale_audit)
258
+ v3.v2.write_json(out_dir / "crop_fit_metrics.json", crop_audit)
259
+ v3.v2.write_json(out_dir / "path_overlay_metrics.json", path_overlay)
260
+ return report
261
+
262
+
263
+ def save_layout_change_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
264
+ parent = v3.v2.load_json(PARENT_CONFIG)
265
+ scale_audit = scale_multiplier_audit(parent, config)
266
+ rows = []
267
+ for time in [float(value) for value in config["sample_times"]]:
268
+ key = v3.config_key(time)
269
+ old_target = [float(value) for value in parent["layout_targets_normalized"][key]]
270
+ new_target = [float(value) for value in config["layout_targets_normalized"][key]]
271
+ rows.append(
272
+ {
273
+ "time_s": time,
274
+ "v6_target_xy": old_target,
275
+ "v7_target_xy": new_target,
276
+ "delta_xy_px_at_2560x1440": [
277
+ round((new_target[0] - old_target[0]) * 2560.0, 3),
278
+ round((new_target[1] - old_target[1]) * 1440.0, 3),
279
+ ],
280
+ "v6_scale": config_scale(parent, time),
281
+ "v7_scale": config_scale(config, time),
282
+ "v7_over_v6_scale": round(
283
+ config_scale(config, time) / config_scale(parent, time),
284
+ 8,
285
+ ),
286
+ }
287
+ )
288
+ changed_position_times = [
289
+ row["time_s"]
290
+ for row in rows
291
+ if any(abs(float(value)) > 0.01 for value in row["delta_xy_px_at_2560x1440"])
292
+ ]
293
+ report = {
294
+ "source_frames_unchanged": config["sample_times"] == parent["sample_times"],
295
+ "colours_unchanged": [group["color"] for group in config["color_groups"]]
296
+ == [group["color"] for group in parent["color_groups"]],
297
+ "alpha_unchanged": config["alpha"] == parent["alpha"],
298
+ "right_reserved_fraction_unchanged": config["right_reserved_fraction"]
299
+ == parent["right_reserved_fraction"],
300
+ "x_targets_unchanged": all(
301
+ abs(float(row["delta_xy_px_at_2560x1440"][0])) <= 0.01 for row in rows
302
+ ),
303
+ "changed_position_times_s": changed_position_times,
304
+ "shared_pose_scale_multiplier": float(config["parent_pose_scale_multiplier"]),
305
+ "all_scales_share_one_multiplier": bool(scale_audit["pass"]),
306
+ "changes": rows,
307
+ }
308
+ v3.v2.write_json(out_dir / "layout_change_audit.json", report)
309
+ return report
310
+
311
+
312
+ def sha256(path: Path) -> str:
313
+ digest = hashlib.sha256()
314
+ with path.open("rb") as handle:
315
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
316
+ digest.update(chunk)
317
+ return digest.hexdigest()
318
+
319
+
320
+ def save_reuse_audit(args: argparse.Namespace, out_dir: Path) -> dict[str, Any]:
321
+ source = args.segmentation_source.expanduser().resolve()
322
+ parent_background = cv2.imread(str(source / "background_plate.png"))
323
+ current_background = cv2.imread(str(out_dir / "background_plate.png"))
324
+ if (
325
+ parent_background is None
326
+ or current_background is None
327
+ or parent_background.shape != current_background.shape
328
+ ):
329
+ raise RuntimeError("Could not compare v6/v7 backgrounds")
330
+ changed = int(np.any(parent_background != current_background, axis=2).sum())
331
+ artifacts = {}
332
+ for name in v5.REUSED_SEGMENTATION_ARTIFACTS:
333
+ source_hash = sha256(source / name)
334
+ copied_hash = sha256(out_dir / name)
335
+ artifacts[name] = {
336
+ "source_sha256": source_hash,
337
+ "copied_sha256": copied_hash,
338
+ "identical": source_hash == copied_hash,
339
+ }
340
+ report = {
341
+ "parent_version": "v6-grounded-uniform-layout",
342
+ "segmentation_source": v3.v2.display_path(source),
343
+ "source_frame_times_unchanged": True,
344
+ "segmentation_artifacts_identical": all(row["identical"] for row in artifacts.values()),
345
+ "segmentation_artifacts": artifacts,
346
+ "background_changed_pixels": changed,
347
+ "background_identical": changed == 0,
348
+ "parent_background_sha256": sha256(source / "background_plate.png"),
349
+ "v7_background_sha256": sha256(out_dir / "background_plate.png"),
350
+ }
351
+ if not report["background_identical"] or not report["segmentation_artifacts_identical"]:
352
+ raise RuntimeError("V7 unexpectedly changed a reused v6 artifact")
353
+ v3.v2.write_json(out_dir / "reuse_audit.json", report)
354
+ return report
355
+
356
+
357
+ def update_run_metadata(
358
+ config: dict[str, Any],
359
+ out_dir: Path,
360
+ occlusion: dict[str, Any],
361
+ layout: dict[str, Any],
362
+ reuse: dict[str, Any],
363
+ ) -> None:
364
+ path = out_dir / "run_metadata.json"
365
+ metadata = v3.v2.load_json(path)
366
+ metadata.pop("uniform_pose_scale", None)
367
+ scales = [config_scale(config, float(time)) for time in config["sample_times"]]
368
+ metadata.update(
369
+ {
370
+ "parent_version": "v6-grounded-uniform-layout",
371
+ "default_pose_scale": float(config["pose_scale"]),
372
+ "pose_scale_overrides": config["pose_scale_overrides"],
373
+ "pose_scale_range": [min(scales), max(scales)],
374
+ "parent_pose_scale_multiplier": float(config["parent_pose_scale_multiplier"]),
375
+ "crop_top_fraction": float(config["crop_top_fraction"]),
376
+ "layout_change_audit": layout,
377
+ "occlusion_audit": occlusion,
378
+ "reuse_audit": reuse,
379
+ "publication_output_stem": OUTPUT_STEM,
380
+ "publication_export_suffixes": list(PUBLICATION_SUFFIXES),
381
+ "final_width_mm": FINAL_WIDTH_MM,
382
+ "png_dpi": PNG_DPI,
383
+ "tiff_dpi": TIFF_DPI,
384
+ }
385
+ )
386
+ v3.v2.write_json(path, metadata)
387
+
388
+
389
+ def save_publication_figure(
390
+ canvas_rgb: np.ndarray,
391
+ out_base: Path,
392
+ config: dict[str, Any],
393
+ annotated: bool,
394
+ ) -> None:
395
+ height, width = canvas_rgb.shape[:2]
396
+ width_mm = float(config.get("final_width_mm", FINAL_WIDTH_MM))
397
+ png_dpi = int(config.get("png_dpi", PNG_DPI))
398
+ tiff_dpi = max(TIFF_DPI, int(config.get("tiff_dpi", TIFF_DPI)))
399
+ width_in = width_mm / 25.4
400
+ height_in = width_in * height / width
401
+ figure = v3.plt.figure(figsize=(width_in, height_in), dpi=png_dpi, facecolor="white")
402
+ axis = figure.add_axes([0, 0, 1, 1])
403
+ axis.imshow(canvas_rgb)
404
+ axis.set_xlim(0, width)
405
+ axis.set_ylim(height, 0)
406
+ axis.axis("off")
407
+ if annotated:
408
+ v5.v4.add_timeline_v4(axis, config, width, height)
409
+ v5.add_annotation_v5(axis, config, width, height)
410
+ for extension in ["png", "tiff", "svg", "pdf"]:
411
+ path = out_base.with_suffix(f".{extension}")
412
+ if extension == "png":
413
+ figure.savefig(path, dpi=png_dpi, facecolor="white")
414
+ elif extension == "tiff":
415
+ figure.savefig(path, dpi=tiff_dpi, facecolor="white")
416
+ with v3.Image.open(path) as rendered:
417
+ rendered.convert("RGB").save(
418
+ path,
419
+ format="TIFF",
420
+ compression="tiff_lzw",
421
+ dpi=(tiff_dpi, tiff_dpi),
422
+ )
423
+ else:
424
+ figure.savefig(path, facecolor="white")
425
+ if extension == "svg":
426
+ lines = path.read_text(encoding="utf-8").splitlines()
427
+ path.write_text(
428
+ "\n".join(line.rstrip() for line in lines) + "\n",
429
+ encoding="utf-8",
430
+ )
431
+ v3.plt.close(figure)
432
+
433
+
434
+ def save_wide_layout_map(out_dir: Path, crop_y: int) -> None:
435
+ source = out_dir / "layout_map.csv"
436
+ with source.open("r", encoding="utf-8", newline="") as handle:
437
+ rows = list(csv.DictReader(handle))
438
+ if not rows:
439
+ raise RuntimeError("layout_map.csv is empty")
440
+ fields = list(rows[0])
441
+ additions = [
442
+ "crop_top_y_px",
443
+ "display_foot_y_wide_px",
444
+ "scaled_bbox_y1_wide",
445
+ "scaled_bbox_y2_wide",
446
+ ]
447
+ with (out_dir / "layout_map_wide.csv").open("w", encoding="utf-8", newline="") as handle:
448
+ writer = csv.DictWriter(handle, fieldnames=fields + additions, lineterminator="\n")
449
+ writer.writeheader()
450
+ for row in rows:
451
+ row.update(
452
+ {
453
+ "crop_top_y_px": f"{crop_y:d}",
454
+ "display_foot_y_wide_px": f"{float(row['display_foot_y_px']) - crop_y:.3f}",
455
+ "scaled_bbox_y1_wide": f"{float(row['scaled_bbox_y1']) - crop_y:.3f}",
456
+ "scaled_bbox_y2_wide": f"{float(row['scaled_bbox_y2']) - crop_y:.3f}",
457
+ }
458
+ )
459
+ writer.writerow(row)
460
+
461
+
462
+ def save_wide_safe_area_qa(
463
+ canvas_rgb: np.ndarray,
464
+ background_rgb: np.ndarray,
465
+ config: dict[str, Any],
466
+ out_dir: Path,
467
+ ) -> dict[str, Any]:
468
+ height, width = canvas_rgb.shape[:2]
469
+ boundary = v3.safe_x_limit(width, config)
470
+ boundary_floor = int(math.floor(boundary))
471
+ difference = np.max(
472
+ np.abs(canvas_rgb.astype(np.int16) - background_rgb.astype(np.int16)),
473
+ axis=2,
474
+ ) > 2
475
+ yy, xx = np.where(difference)
476
+ maximum_changed_x = int(xx.max()) if len(xx) else -1
477
+ reserved_changed = int(difference[:, int(math.ceil(boundary)) :].sum())
478
+
479
+ clean = cv2.imread(str(out_dir / f"{OUTPUT_STEM}_clean.png"), cv2.IMREAD_UNCHANGED)
480
+ annotated = cv2.imread(str(out_dir / f"{OUTPUT_STEM}_annotated.png"), cv2.IMREAD_UNCHANGED)
481
+ if clean is None or annotated is None or clean.shape != annotated.shape:
482
+ raise RuntimeError("Could not compare final v7 clean/annotated PNG files")
483
+ png_boundary = int(
484
+ math.ceil(clean.shape[1] * (1.0 - float(config["right_reserved_fraction"])))
485
+ )
486
+ annotation_difference = np.max(
487
+ np.abs(annotated.astype(np.int16) - clean.astype(np.int16)),
488
+ axis=2,
489
+ ) > 2
490
+ annotated_reserved_changed = int(annotation_difference[:, png_boundary:].sum())
491
+ report = {
492
+ "image_width_px": width,
493
+ "image_height_px": height,
494
+ "right_reserved_fraction": float(config["right_reserved_fraction"]),
495
+ "overlay_safe_x_limit_px": round(boundary, 3),
496
+ "maximum_changed_overlay_x_px": maximum_changed_x,
497
+ "changed_pixels_inside_reserved_zone": reserved_changed,
498
+ "annotated_changed_pixels_inside_reserved_zone": annotated_reserved_changed,
499
+ "pass": bool(
500
+ maximum_changed_x < boundary_floor
501
+ and reserved_changed == 0
502
+ and annotated_reserved_changed == 0
503
+ ),
504
+ }
505
+ guide = canvas_rgb.copy()
506
+ red = np.array([213, 70, 66], dtype=np.float32)
507
+ zone = guide[:, boundary_floor:].astype(np.float32)
508
+ guide[:, boundary_floor:] = np.clip(
509
+ zone * 0.56 + red[None, None, :] * 0.44,
510
+ 0,
511
+ 255,
512
+ ).astype(np.uint8)
513
+ cv2.line(
514
+ guide,
515
+ (boundary_floor, 0),
516
+ (boundary_floor, height - 1),
517
+ (255, 255, 255),
518
+ 4,
519
+ lineType=cv2.LINE_AA,
520
+ )
521
+ cv2.putText(
522
+ guide,
523
+ "12% reserved: no final overlay",
524
+ (boundary_floor + 14, 42),
525
+ cv2.FONT_HERSHEY_SIMPLEX,
526
+ 0.56,
527
+ (255, 255, 255),
528
+ 2,
529
+ cv2.LINE_AA,
530
+ )
531
+ cv2.imwrite(str(out_dir / "safe_area_qa.png"), cv2.cvtColor(guide, cv2.COLOR_RGB2BGR))
532
+ v3.v2.write_json(out_dir / "safe_area_metrics.json", report)
533
+ if not report["pass"]:
534
+ raise RuntimeError("V7 wide safe-area audit failed")
535
+ return report
536
+
537
+
538
+ def save_crop_window_preview(parent_rgb: np.ndarray, crop_y: int, out_dir: Path) -> Path:
539
+ preview = parent_rgb.copy()
540
+ overlay = preview.copy()
541
+ overlay[:crop_y] = np.array([196, 76, 70], dtype=np.uint8)
542
+ preview[:crop_y] = np.clip(
543
+ preview[:crop_y].astype(np.float32) * 0.42
544
+ + overlay[:crop_y].astype(np.float32) * 0.58,
545
+ 0,
546
+ 255,
547
+ ).astype(np.uint8)
548
+ cv2.line(preview, (0, crop_y), (preview.shape[1] - 1, crop_y), (255, 255, 255), 5)
549
+ cv2.putText(
550
+ preview,
551
+ "top one-third removed",
552
+ (30, max(42, crop_y - 24)),
553
+ cv2.FONT_HERSHEY_SIMPLEX,
554
+ 0.82,
555
+ (255, 255, 255),
556
+ 2,
557
+ cv2.LINE_AA,
558
+ )
559
+ path = out_dir / "crop_window_on_full_canvas.png"
560
+ cv2.imwrite(str(path), cv2.cvtColor(preview, cv2.COLOR_RGB2BGR))
561
+ return path
562
+
563
+
564
+ def save_v6_v7_comparison(
565
+ crop_preview_path: Path,
566
+ current_path: Path,
567
+ out_dir: Path,
568
+ ) -> None:
569
+ paths = [PARENT_CLEAN, crop_preview_path, current_path]
570
+ images = []
571
+ for path in paths:
572
+ image = cv2.imread(str(path))
573
+ if image is None:
574
+ raise RuntimeError(f"Could not read comparison input: {path}")
575
+ images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
576
+ figure = v3.plt.figure(figsize=(12.0, 8.4), dpi=300, facecolor="#F4F5F4")
577
+ grid = figure.add_gridspec(3, 1, height_ratios=[1.0, 1.0, 0.72], hspace=0.16)
578
+ axes = [figure.add_subplot(grid[index, 0]) for index in range(3)]
579
+ titles = [
580
+ "v6 • 16:9 grounded layout",
581
+ "v7 crop window • exact top one-third removed",
582
+ "v7 • 8:3 wide layout + shared ×0.78 pose multiplier",
583
+ ]
584
+ for axis, image, title in zip(axes, images, titles):
585
+ axis.imshow(image)
586
+ axis.set_title(
587
+ title,
588
+ fontsize=8.4,
589
+ loc="left",
590
+ pad=4,
591
+ weight="bold",
592
+ color="#28313A",
593
+ )
594
+ axis.axis("off")
595
+ figure.savefig(
596
+ out_dir / "comparison_v6_v7.jpg",
597
+ dpi=300,
598
+ facecolor=figure.get_facecolor(),
599
+ bbox_inches="tight",
600
+ pil_kwargs={"quality": 94},
601
+ )
602
+ v3.plt.close(figure)
603
+
604
+
605
+ def publication_artifact_audit(
606
+ out_dir: Path,
607
+ config: dict[str, Any],
608
+ crop_y: int,
609
+ ) -> dict[str, Any]:
610
+ variants = {}
611
+ for variant in ["clean", "annotated"]:
612
+ rows = {}
613
+ for extension in PUBLICATION_SUFFIXES:
614
+ path = out_dir / f"{OUTPUT_STEM}_{variant}{extension}"
615
+ if not path.exists() or path.stat().st_size == 0:
616
+ raise RuntimeError(f"Missing publication artifact: {path}")
617
+ rows[extension.lstrip(".")] = {
618
+ "bytes": path.stat().st_size,
619
+ "sha256": sha256(path),
620
+ }
621
+ with v3.Image.open(out_dir / f"{OUTPUT_STEM}_{variant}.png") as image:
622
+ rows["png"].update(
623
+ {
624
+ "width_px": image.width,
625
+ "height_px": image.height,
626
+ "mode": image.mode,
627
+ "dpi": [round(float(value), 3) for value in image.info.get("dpi", (0, 0))],
628
+ }
629
+ )
630
+ with v3.Image.open(out_dir / f"{OUTPUT_STEM}_{variant}.tiff") as image:
631
+ rows["tiff"].update(
632
+ {
633
+ "width_px": image.width,
634
+ "height_px": image.height,
635
+ "mode": image.mode,
636
+ "compression": image.info.get("compression"),
637
+ "dpi": [round(float(value), 3) for value in image.info.get("dpi", (0, 0))],
638
+ }
639
+ )
640
+ variants[variant] = rows
641
+ width_in = float(config["final_width_mm"]) / 25.4
642
+ aspect = (1440 - crop_y) / 2560
643
+ expected_png_width = int(width_in * int(config["png_dpi"]))
644
+ expected_png_height = int(width_in * aspect * int(config["png_dpi"]))
645
+ expected_tiff_width = int(width_in * int(config["tiff_dpi"]))
646
+ expected_tiff_height = int(width_in * aspect * int(config["tiff_dpi"]))
647
+ clean_png = variants["clean"]["png"]
648
+ clean_tiff = variants["clean"]["tiff"]
649
+ report = {
650
+ "expected_png_size_px": [expected_png_width, expected_png_height],
651
+ "variants": variants,
652
+ "pass": bool(
653
+ clean_png["width_px"] == expected_png_width
654
+ and clean_png["height_px"] == expected_png_height
655
+ and clean_tiff["width_px"] == expected_tiff_width
656
+ and clean_tiff["height_px"] == expected_tiff_height
657
+ and clean_tiff["mode"] == "RGB"
658
+ and clean_tiff["compression"] == "tiff_lzw"
659
+ ),
660
+ }
661
+ if not report["pass"]:
662
+ raise RuntimeError("V7 publication artifact audit failed")
663
+ v3.v2.write_json(out_dir / "publication_artifact_metrics.json", report)
664
+ return report
665
+
666
+
667
+ def postprocess_wide_outputs(
668
+ out_dir: Path,
669
+ config: dict[str, Any],
670
+ occlusion: dict[str, Any],
671
+ ) -> None:
672
+ full_layout_bgr = cv2.imread(str(out_dir / "composite_layout_rgb.png"))
673
+ full_background_bgr = cv2.imread(str(out_dir / "background_plate.png"))
674
+ if full_layout_bgr is None or full_background_bgr is None:
675
+ raise RuntimeError("Missing full-canvas v7 render")
676
+ if full_layout_bgr.shape != full_background_bgr.shape:
677
+ raise RuntimeError("Full layout and background dimensions do not match")
678
+ full_layout_rgb = cv2.cvtColor(full_layout_bgr, cv2.COLOR_BGR2RGB)
679
+ full_background_rgb = cv2.cvtColor(full_background_bgr, cv2.COLOR_BGR2RGB)
680
+ crop_y = crop_top_px(config, full_layout_rgb.shape[0])
681
+ wide_layout_rgb = full_layout_rgb[crop_y:].copy()
682
+ wide_background_rgb = full_background_rgb[crop_y:].copy()
683
+
684
+ shutil.copy2(
685
+ out_dir / "composite_layout_rgb.png",
686
+ out_dir / "composite_layout_full_rgb.png",
687
+ )
688
+ cv2.imwrite(
689
+ str(out_dir / "composite_layout_wide_rgb.png"),
690
+ cv2.cvtColor(wide_layout_rgb, cv2.COLOR_RGB2BGR),
691
+ )
692
+ cv2.imwrite(
693
+ str(out_dir / "background_plate_wide.png"),
694
+ cv2.cvtColor(wide_background_rgb, cv2.COLOR_RGB2BGR),
695
+ )
696
+
697
+ save_publication_figure(
698
+ wide_layout_rgb,
699
+ out_dir / f"{OUTPUT_STEM}_clean",
700
+ config,
701
+ annotated=False,
702
+ )
703
+ save_publication_figure(
704
+ wide_layout_rgb,
705
+ out_dir / f"{OUTPUT_STEM}_annotated",
706
+ config,
707
+ annotated=True,
708
+ )
709
+ save_wide_layout_map(out_dir, crop_y)
710
+
711
+ full_safe_path = out_dir / "safe_area_qa.png"
712
+ full_safe_metrics_path = out_dir / "safe_area_metrics.json"
713
+ if full_safe_path.exists():
714
+ full_safe_path.replace(out_dir / "safe_area_full_qa.png")
715
+ if full_safe_metrics_path.exists():
716
+ full_safe_metrics_path.replace(out_dir / "safe_area_full_metrics.json")
717
+ safe_report = save_wide_safe_area_qa(
718
+ wide_layout_rgb,
719
+ wide_background_rgb,
720
+ config,
721
+ out_dir,
722
+ )
723
+ crop_preview = save_crop_window_preview(full_layout_rgb, crop_y, out_dir)
724
+ save_v6_v7_comparison(
725
+ crop_preview,
726
+ out_dir / f"{OUTPUT_STEM}_clean.png",
727
+ out_dir,
728
+ )
729
+ artifact_report = publication_artifact_audit(out_dir, config, crop_y)
730
+
731
+ crop_report = {
732
+ "full_canvas_size_px": [full_layout_rgb.shape[1], full_layout_rgb.shape[0]],
733
+ "crop_top_y_px": crop_y,
734
+ "requested_crop_top_fraction": float(config["crop_top_fraction"]),
735
+ "actual_removed_fraction": round(crop_y / full_layout_rgb.shape[0], 8),
736
+ "wide_canvas_size_px": [wide_layout_rgb.shape[1], wide_layout_rgb.shape[0]],
737
+ "aspect_ratio": round(wide_layout_rgb.shape[1] / wide_layout_rgb.shape[0], 6),
738
+ "height_reduction_fraction": round(
739
+ 1.0 - wide_layout_rgb.shape[0] / full_layout_rgb.shape[0],
740
+ 8,
741
+ ),
742
+ "pose_crop_fit": occlusion["crop_fit"],
743
+ "safe_area": safe_report,
744
+ "publication_artifacts": artifact_report,
745
+ "pass": bool(
746
+ occlusion["crop_fit"]["pass"]
747
+ and safe_report["pass"]
748
+ and artifact_report["pass"]
749
+ and wide_layout_rgb.shape[:2] == (960, 2560)
750
+ ),
751
+ }
752
+ if not crop_report["pass"]:
753
+ raise RuntimeError("V7 crop/export audit failed")
754
+ v3.v2.write_json(out_dir / "crop_metrics.json", crop_report)
755
+
756
+ metadata_path = out_dir / "run_metadata.json"
757
+ metadata = v3.v2.load_json(metadata_path)
758
+ metadata.update(
759
+ {
760
+ "full_render_size_px": [full_layout_rgb.shape[1], full_layout_rgb.shape[0]],
761
+ "crop_top_y_px": crop_y,
762
+ "wide_render_size_px": [wide_layout_rgb.shape[1], wide_layout_rgb.shape[0]],
763
+ "wide_aspect_ratio": crop_report["aspect_ratio"],
764
+ "crop_audit": crop_report,
765
+ }
766
+ )
767
+ v3.v2.write_json(metadata_path, metadata)
768
+
769
+
770
+ def install_v7_hooks() -> None:
771
+ v3.validate_config = validate_config_v7
772
+ v6.DEFAULT_CONFIG = DEFAULT_CONFIG
773
+ v6.DEFAULT_OUT = DEFAULT_OUT
774
+ v6.PARENT_CONFIG = PARENT_CONFIG
775
+ v6.PARENT_OUT = PARENT_OUT
776
+ v6.PARENT_ANNOTATED = PARENT_ANNOTATED
777
+ v6.OUTPUT_STEM = OUTPUT_STEM
778
+ v6.parse_args = parse_args
779
+ v6.render_layout_v6 = render_layout_v7
780
+ v6.save_v5_v6_comparison = defer_comparison
781
+ v6.save_occlusion_audit = save_occlusion_audit
782
+ v6.save_layout_change_audit = save_layout_change_audit
783
+ v6.save_reuse_audit = save_reuse_audit
784
+ v6.update_run_metadata = update_run_metadata
785
+
786
+
787
+ def main() -> int:
788
+ args = parse_args()
789
+ install_v7_hooks()
790
+ return_code = v6.main()
791
+ if return_code:
792
+ return return_code
793
+ out_dir = args.out_dir.expanduser().resolve()
794
+ config = v3.v2.load_json(args.config.expanduser().resolve())
795
+ occlusion = v3.v2.load_json(out_dir / "occlusion_metrics.json")
796
+ postprocess_wide_outputs(out_dir, config, occlusion)
797
+ print(f"Wrote v7 wide outputs to {out_dir}")
798
+ return 0
799
+
800
+
801
+ if __name__ == "__main__":
802
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v8.py ADDED
@@ -0,0 +1,972 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build v8 with a contrastive metallic colour grade on the locked v7 layout.
3
+
4
+ V8 changes only the five group colours and the foreground colour-transfer
5
+ function. The transfer preserves the source-frame L* structure and more than
6
+ half of the source chroma/detail contribution, so the G1 remains metallic
7
+ instead of becoming a pale flat silhouette. Source frames, SAM masks, crop,
8
+ pose positions, scales, opacity, z-order, paths, shadows, background, and the
9
+ rightmost 12% reserve remain identical to v7.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import argparse
15
+ import copy
16
+ import hashlib
17
+ import math
18
+ from pathlib import Path
19
+ from typing import Any, Callable
20
+
21
+ import cv2
22
+ import numpy as np
23
+ from matplotlib.patches import Rectangle
24
+
25
+ import build_trajectory_figure_v7 as v7
26
+
27
+
28
+ v3 = v7.v3
29
+ v5 = v7.v5
30
+ v6 = v7.v6
31
+
32
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
33
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
34
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v8_metallic_contrast_palette.json"
35
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
36
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
37
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v8_metallic_contrast_palette"
38
+ PARENT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v7_wide_crop_uniform_scale.json"
39
+ PARENT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v7_wide_crop_uniform_scale"
40
+ PARENT_CLEAN = PARENT_OUT / "trajectory_v7_wide_crop_clean.png"
41
+ PARENT_ANNOTATED = PARENT_OUT / "trajectory_v7_wide_crop_annotated.png"
42
+ OUTPUT_STEM = "trajectory_v8_metallic_contrast"
43
+ FINAL_WIDTH_MM = 183.0
44
+ PNG_DPI = 300
45
+ TIFF_DPI = 600
46
+ PUBLICATION_SUFFIXES = (".png", ".tiff", ".svg", ".pdf")
47
+ _ORIGINAL_COLORIZE: Callable[[np.ndarray, np.ndarray], np.ndarray] = (
48
+ v3.v1.colorize_foreground
49
+ )
50
+ _ORIGINAL_V6_RENDER = v7._ORIGINAL_V6_RENDER
51
+ _COLOR_STYLE: dict[str, float | str] = {
52
+ "name": "metallic-lab-chroma",
53
+ "source_chroma_weight": 0.45,
54
+ "group_chroma_weight": 0.55,
55
+ "lightness_lift_lstar": 1.5,
56
+ "source_rgb_detail_weight": 0.15,
57
+ }
58
+
59
+ v3.matplotlib.rcParams.update(
60
+ {
61
+ "font.family": "sans-serif",
62
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
63
+ "font.size": 7,
64
+ "svg.fonttype": "none",
65
+ "pdf.fonttype": 42,
66
+ }
67
+ )
68
+
69
+
70
+ def parse_args() -> argparse.Namespace:
71
+ parser = argparse.ArgumentParser(description=__doc__)
72
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
73
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
74
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
75
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
76
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
77
+ parser.add_argument("--segmentation-source", type=Path, default=PARENT_OUT)
78
+ parser.add_argument("--device", default="cuda:0")
79
+ args = parser.parse_args()
80
+ args.reuse_segmentation = True
81
+ return args
82
+
83
+
84
+ def configure_colour_style(config: dict[str, Any]) -> None:
85
+ global _COLOR_STYLE
86
+ _COLOR_STYLE = dict(config["foreground_color_style"])
87
+
88
+
89
+ def metallic_colorize_foreground(
90
+ frame_bgr: np.ndarray,
91
+ color: np.ndarray,
92
+ ) -> np.ndarray:
93
+ """Shift chroma in CIELAB while preserving the source metallic lightness."""
94
+ rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB).astype(np.float32)
95
+ source_lab = cv2.cvtColor(rgb / 255.0, cv2.COLOR_RGB2LAB)
96
+ target_rgb = color.astype(np.float32).reshape(1, 1, 3) / 255.0
97
+ target_lab = cv2.cvtColor(target_rgb, cv2.COLOR_RGB2LAB)[0, 0]
98
+ source_chroma_weight = float(_COLOR_STYLE["source_chroma_weight"])
99
+ group_chroma_weight = float(_COLOR_STYLE["group_chroma_weight"])
100
+ lightness_lift = float(_COLOR_STYLE["lightness_lift_lstar"])
101
+ detail_weight = float(_COLOR_STYLE["source_rgb_detail_weight"])
102
+ graded_lab = source_lab.copy()
103
+ graded_lab[..., 0] = np.clip(source_lab[..., 0] + lightness_lift, 0.0, 100.0)
104
+ graded_lab[..., 1] = (
105
+ source_chroma_weight * source_lab[..., 1]
106
+ + group_chroma_weight * target_lab[1]
107
+ )
108
+ graded_lab[..., 2] = (
109
+ source_chroma_weight * source_lab[..., 2]
110
+ + group_chroma_weight * target_lab[2]
111
+ )
112
+ graded_rgb = np.clip(
113
+ cv2.cvtColor(graded_lab, cv2.COLOR_LAB2RGB) * 255.0,
114
+ 0,
115
+ 255,
116
+ )
117
+ return np.clip(
118
+ detail_weight * rgb + (1.0 - detail_weight) * graded_rgb,
119
+ 0,
120
+ 255,
121
+ ).astype(np.uint8)
122
+
123
+
124
+ def render_layout_v8(
125
+ background: np.ndarray,
126
+ poses: list[v3.Pose],
127
+ config: dict[str, Any],
128
+ ) -> np.ndarray:
129
+ """Use the unchanged v6/v7 geometry renderer with the v8 tint function."""
130
+ return _ORIGINAL_V6_RENDER(background, poses, config)
131
+
132
+
133
+ def validate_config_v8(config: dict[str, Any]) -> None:
134
+ v7.validate_config_v7(config)
135
+ style = config.get("foreground_color_style", {})
136
+ required = {
137
+ "name",
138
+ "source_chroma_weight",
139
+ "group_chroma_weight",
140
+ "lightness_lift_lstar",
141
+ "source_rgb_detail_weight",
142
+ }
143
+ if set(style) != required:
144
+ raise RuntimeError("V8 foreground_color_style fields are incomplete")
145
+ source_chroma = float(style["source_chroma_weight"])
146
+ group_chroma = float(style["group_chroma_weight"])
147
+ if not 0.35 <= source_chroma <= 0.70:
148
+ raise RuntimeError("source_chroma_weight must be between 0.35 and 0.70")
149
+ if not 0.30 <= group_chroma <= 0.65:
150
+ raise RuntimeError("group_chroma_weight must be between 0.30 and 0.65")
151
+ if abs(source_chroma + group_chroma - 1.0) > 1e-8:
152
+ raise RuntimeError("source and group chroma weights must sum to one")
153
+ if not -3.0 <= float(style["lightness_lift_lstar"]) <= 3.0:
154
+ raise RuntimeError("lightness_lift_lstar must be between -3 and 3")
155
+ if not 0.0 <= float(style["source_rgb_detail_weight"]) <= 0.35:
156
+ raise RuntimeError("source_rgb_detail_weight must be between 0 and 0.35")
157
+ colours = [str(group["color"]).upper() for group in config["color_groups"]]
158
+ if len(colours) != len(set(colours)):
159
+ raise RuntimeError("V8 colour groups must use five distinct colours")
160
+
161
+
162
+ def _parent_poses(parent_config: dict[str, Any]) -> list[v3.Pose]:
163
+ current_poses = list(v5._POSES_V5)
164
+ try:
165
+ return v5.build_poses_v5(
166
+ parent_config,
167
+ v5._FRAMES,
168
+ v5._FRAME_INDICES,
169
+ v5._YOLO_MASKS,
170
+ v5._REFINED_MASKS,
171
+ v5._METRICS,
172
+ )
173
+ finally:
174
+ v5._POSES_V5 = current_poses
175
+
176
+
177
+ def _non_colour_config(config: dict[str, Any]) -> dict[str, Any]:
178
+ payload = copy.deepcopy(config)
179
+ payload.pop("version", None)
180
+ payload.pop("foreground_color_style", None)
181
+ for group in payload["color_groups"]:
182
+ group["color"] = "__COLOUR_LOCK_IGNORED__"
183
+ return payload
184
+
185
+
186
+ def _array_sha256(array: np.ndarray) -> str:
187
+ return hashlib.sha256(np.ascontiguousarray(array).view(np.uint8)).hexdigest()
188
+
189
+
190
+ def _pose_geometry(pose: v3.Pose) -> dict[str, Any]:
191
+ return {
192
+ "time_s": pose.time,
193
+ "frame_index": pose.frame_index,
194
+ "source_bbox": [float(value) for value in pose.source_bbox],
195
+ "source_foot": [float(value) for value in pose.source_foot],
196
+ "display_foot_requested": [
197
+ float(value) for value in pose.display_foot_requested
198
+ ],
199
+ "display_foot": [float(value) for value in pose.display_foot],
200
+ "scale_factor": float(pose.scale_factor),
201
+ "hero": bool(pose.hero),
202
+ "mask_sha256": _array_sha256(pose.refined_mask),
203
+ }
204
+
205
+
206
+ def geometry_lock_audit(
207
+ parent_config: dict[str, Any],
208
+ config: dict[str, Any],
209
+ parent_poses: list[v3.Pose],
210
+ current_poses: list[v3.Pose],
211
+ ) -> dict[str, Any]:
212
+ parent_by_time = {pose.time: pose for pose in parent_poses}
213
+ current_by_time = {pose.time: pose for pose in current_poses}
214
+ rows = []
215
+ for time in [float(value) for value in config["sample_times"]]:
216
+ old = _pose_geometry(parent_by_time[time])
217
+ new = _pose_geometry(current_by_time[time])
218
+ rows.append(
219
+ {
220
+ "time_s": time,
221
+ "v7_display_foot": old["display_foot"],
222
+ "v8_display_foot": new["display_foot"],
223
+ "v7_scale": old["scale_factor"],
224
+ "v8_scale": new["scale_factor"],
225
+ "position_delta_px": [
226
+ round(
227
+ float(new["display_foot"][axis])
228
+ - float(old["display_foot"][axis]),
229
+ 10,
230
+ )
231
+ for axis in range(2)
232
+ ],
233
+ "scale_delta": round(
234
+ float(new["scale_factor"]) - float(old["scale_factor"]),
235
+ 12,
236
+ ),
237
+ "source_and_geometry_identical": old == new,
238
+ }
239
+ )
240
+ parent_group_structure = [
241
+ {
242
+ "id": group["id"],
243
+ "times": group["times"],
244
+ "label": group["label"],
245
+ }
246
+ for group in parent_config["color_groups"]
247
+ ]
248
+ current_group_structure = [
249
+ {
250
+ "id": group["id"],
251
+ "times": group["times"],
252
+ "label": group["label"],
253
+ }
254
+ for group in config["color_groups"]
255
+ ]
256
+ report = {
257
+ "parent_version": parent_config["version"],
258
+ "current_version": config["version"],
259
+ "all_non_colour_config_identical": _non_colour_config(parent_config)
260
+ == _non_colour_config(config),
261
+ "group_membership_identical": parent_group_structure
262
+ == current_group_structure,
263
+ "pose_count_identical": len(parent_poses) == len(current_poses),
264
+ "all_pose_geometry_identical": all(
265
+ bool(row["source_and_geometry_identical"]) for row in rows
266
+ ),
267
+ "maximum_absolute_position_delta_px": max(
268
+ abs(float(delta))
269
+ for row in rows
270
+ for delta in row["position_delta_px"]
271
+ ),
272
+ "maximum_absolute_scale_delta": max(
273
+ abs(float(row["scale_delta"])) for row in rows
274
+ ),
275
+ "poses": rows,
276
+ }
277
+ report["pass"] = bool(
278
+ report["all_non_colour_config_identical"]
279
+ and report["group_membership_identical"]
280
+ and report["pose_count_identical"]
281
+ and report["all_pose_geometry_identical"]
282
+ and report["maximum_absolute_position_delta_px"] == 0.0
283
+ and report["maximum_absolute_scale_delta"] == 0.0
284
+ )
285
+ return report
286
+
287
+
288
+ def _hex_rgb(value: str) -> np.ndarray:
289
+ return np.asarray(
290
+ [int(value[index : index + 2], 16) for index in (1, 3, 5)],
291
+ dtype=np.uint8,
292
+ )
293
+
294
+
295
+ def _rgb_to_lab(rgb: np.ndarray) -> np.ndarray:
296
+ original_shape = rgb.shape[:-1]
297
+ flat = rgb.reshape(-1, 1, 3).astype(np.float32) / 255.0
298
+ lab = cv2.cvtColor(flat, cv2.COLOR_RGB2LAB).reshape(-1, 3)
299
+ return lab.reshape(*original_shape, 3).astype(np.float64)
300
+
301
+
302
+ def _ciede2000(first: np.ndarray, second: np.ndarray) -> float:
303
+ l1, a1, b1 = [float(value) for value in first]
304
+ l2, a2, b2 = [float(value) for value in second]
305
+ c1 = math.hypot(a1, b1)
306
+ c2 = math.hypot(a2, b2)
307
+ c_bar = (c1 + c2) / 2.0
308
+ g = 0.5 * (
309
+ 1.0
310
+ - math.sqrt((c_bar**7) / (c_bar**7 + 25.0**7))
311
+ )
312
+ a1_prime = (1.0 + g) * a1
313
+ a2_prime = (1.0 + g) * a2
314
+ c1_prime = math.hypot(a1_prime, b1)
315
+ c2_prime = math.hypot(a2_prime, b2)
316
+ h1_prime = math.degrees(math.atan2(b1, a1_prime)) % 360.0
317
+ h2_prime = math.degrees(math.atan2(b2, a2_prime)) % 360.0
318
+ delta_l = l2 - l1
319
+ delta_c = c2_prime - c1_prime
320
+ if c1_prime * c2_prime == 0.0:
321
+ delta_h_degrees = 0.0
322
+ else:
323
+ delta_h_degrees = h2_prime - h1_prime
324
+ if delta_h_degrees > 180.0:
325
+ delta_h_degrees -= 360.0
326
+ elif delta_h_degrees < -180.0:
327
+ delta_h_degrees += 360.0
328
+ delta_h = 2.0 * math.sqrt(c1_prime * c2_prime) * math.sin(
329
+ math.radians(delta_h_degrees / 2.0)
330
+ )
331
+ l_bar = (l1 + l2) / 2.0
332
+ c_prime_bar = (c1_prime + c2_prime) / 2.0
333
+ if c1_prime * c2_prime == 0.0:
334
+ h_prime_bar = h1_prime + h2_prime
335
+ elif abs(h1_prime - h2_prime) <= 180.0:
336
+ h_prime_bar = (h1_prime + h2_prime) / 2.0
337
+ elif h1_prime + h2_prime < 360.0:
338
+ h_prime_bar = (h1_prime + h2_prime + 360.0) / 2.0
339
+ else:
340
+ h_prime_bar = (h1_prime + h2_prime - 360.0) / 2.0
341
+ t = (
342
+ 1.0
343
+ - 0.17 * math.cos(math.radians(h_prime_bar - 30.0))
344
+ + 0.24 * math.cos(math.radians(2.0 * h_prime_bar))
345
+ + 0.32 * math.cos(math.radians(3.0 * h_prime_bar + 6.0))
346
+ - 0.20 * math.cos(math.radians(4.0 * h_prime_bar - 63.0))
347
+ )
348
+ delta_theta = 30.0 * math.exp(
349
+ -(((h_prime_bar - 275.0) / 25.0) ** 2)
350
+ )
351
+ r_c = 2.0 * math.sqrt(
352
+ (c_prime_bar**7) / (c_prime_bar**7 + 25.0**7)
353
+ )
354
+ s_l = 1.0 + (
355
+ 0.015 * ((l_bar - 50.0) ** 2)
356
+ / math.sqrt(20.0 + ((l_bar - 50.0) ** 2))
357
+ )
358
+ s_c = 1.0 + 0.045 * c_prime_bar
359
+ s_h = 1.0 + 0.015 * c_prime_bar * t
360
+ r_t = -math.sin(math.radians(2.0 * delta_theta)) * r_c
361
+ l_term = delta_l / s_l
362
+ c_term = delta_c / s_c
363
+ h_term = delta_h / s_h
364
+ return math.sqrt(
365
+ l_term**2
366
+ + c_term**2
367
+ + h_term**2
368
+ + r_t * c_term * h_term
369
+ )
370
+
371
+
372
+ def _masked_lightness_values(rgb: np.ndarray, mask: np.ndarray) -> np.ndarray:
373
+ pixels = rgb[mask > 0]
374
+ if len(pixels) == 0:
375
+ raise RuntimeError("Cannot measure lightness on an empty mask")
376
+ if len(pixels) > 180_000:
377
+ indices = np.linspace(0, len(pixels) - 1, 180_000).astype(np.int64)
378
+ pixels = pixels[indices]
379
+ return _rgb_to_lab(pixels).reshape(-1, 3)[:, 0]
380
+
381
+
382
+ def _pairwise_palette_metrics(
383
+ config: dict[str, Any],
384
+ ) -> tuple[list[dict[str, Any]], float]:
385
+ groups = config["color_groups"]
386
+ rgb = np.stack([_hex_rgb(str(group["color"])) for group in groups])
387
+ lab = _rgb_to_lab(rgb)
388
+ rows = []
389
+ for first_index, first in enumerate(groups):
390
+ for second_index in range(first_index + 1, len(groups)):
391
+ second = groups[second_index]
392
+ rows.append(
393
+ {
394
+ "groups": f"{first['id']}-{second['id']}",
395
+ "colours": [first["color"], second["color"]],
396
+ "ciede2000": round(
397
+ _ciede2000(lab[first_index], lab[second_index]),
398
+ 4,
399
+ ),
400
+ }
401
+ )
402
+ return rows, min(float(row["ciede2000"]) for row in rows)
403
+
404
+
405
+ def palette_audit(
406
+ parent_config: dict[str, Any],
407
+ config: dict[str, Any],
408
+ parent_poses: list[v3.Pose],
409
+ current_poses: list[v3.Pose],
410
+ ) -> dict[str, Any]:
411
+ old_groups = {str(group["id"]): group for group in parent_config["color_groups"]}
412
+ new_groups = {str(group["id"]): group for group in config["color_groups"]}
413
+ pairwise, minimum_delta = _pairwise_palette_metrics(config)
414
+ new_base_rgb = np.stack(
415
+ [_hex_rgb(str(group["color"])) for group in config["color_groups"]]
416
+ )
417
+ new_base_lab = _rgb_to_lab(new_base_rgb)
418
+ parent_by_time = {pose.time: pose for pose in parent_poses}
419
+ current_by_time = {pose.time: pose for pose in current_poses}
420
+ time_to_group = {
421
+ float(time): str(group["id"])
422
+ for group in config["color_groups"]
423
+ for time in group["times"]
424
+ }
425
+ pose_rows = []
426
+ for time in [float(value) for value in config["sample_times"]]:
427
+ old_pose = parent_by_time[time]
428
+ new_pose = current_by_time[time]
429
+ source_rgb = cv2.cvtColor(new_pose.frame_bgr, cv2.COLOR_BGR2RGB)
430
+ old_rgb = _ORIGINAL_COLORIZE(old_pose.frame_bgr, old_pose.color_rgb)
431
+ new_rgb = metallic_colorize_foreground(
432
+ new_pose.frame_bgr,
433
+ new_pose.color_rgb,
434
+ )
435
+ source_l = _masked_lightness_values(source_rgb, new_pose.refined_mask)
436
+ old_l = _masked_lightness_values(old_rgb, old_pose.refined_mask)
437
+ new_l = _masked_lightness_values(new_rgb, new_pose.refined_mask)
438
+ source_std = float(source_l.std())
439
+ new_std = float(new_l.std())
440
+ old_std = float(old_l.std())
441
+ pose_rows.append(
442
+ {
443
+ "time_s": time,
444
+ "group": time_to_group[time],
445
+ "source_mean_l_star": round(float(source_l.mean()), 4),
446
+ "v7_mean_l_star": round(float(old_l.mean()), 4),
447
+ "v8_mean_l_star": round(float(new_l.mean()), 4),
448
+ "v8_mean_lightness_shift_from_source": round(
449
+ float(new_l.mean() - source_l.mean()),
450
+ 4,
451
+ ),
452
+ "v7_lightness_correlation_to_source": round(
453
+ float(np.corrcoef(source_l, old_l)[0, 1]),
454
+ 6,
455
+ ),
456
+ "v8_lightness_correlation_to_source": round(
457
+ float(np.corrcoef(source_l, new_l)[0, 1]),
458
+ 6,
459
+ ),
460
+ "v7_local_contrast_retention": round(
461
+ old_std / source_std,
462
+ 6,
463
+ ),
464
+ "v8_local_contrast_retention": round(
465
+ new_std / source_std,
466
+ 6,
467
+ ),
468
+ }
469
+ )
470
+ style = config["foreground_color_style"]
471
+ detail_weight = float(style["source_rgb_detail_weight"])
472
+ source_chroma_weight = float(style["source_chroma_weight"])
473
+ effective_source_contribution = detail_weight + (
474
+ 1.0 - detail_weight
475
+ ) * source_chroma_weight
476
+ effective_group_contribution = (
477
+ 1.0 - detail_weight
478
+ ) * float(style["group_chroma_weight"])
479
+ group_rows = []
480
+ for group_index, group in enumerate(config["color_groups"]):
481
+ group_id = str(group["id"])
482
+ group_pose_rows = [row for row in pose_rows if row["group"] == group_id]
483
+ mean_correlation = float(
484
+ np.mean(
485
+ [
486
+ float(row["v8_lightness_correlation_to_source"])
487
+ for row in group_pose_rows
488
+ ]
489
+ )
490
+ )
491
+ mean_contrast_retention = float(
492
+ np.mean(
493
+ [
494
+ float(row["v8_local_contrast_retention"])
495
+ for row in group_pose_rows
496
+ ]
497
+ )
498
+ )
499
+ old_colour = str(old_groups[group_id]["color"]).upper()
500
+ new_colour = str(new_groups[group_id]["color"]).upper()
501
+ group_rows.append(
502
+ {
503
+ "group": group_id,
504
+ "times_s": [float(value) for value in group["times"]],
505
+ "v7_colour": old_colour,
506
+ "v8_colour": new_colour,
507
+ "v8_base_l_star": round(float(new_base_lab[group_index, 0]), 4),
508
+ "mean_v8_lightness_correlation_to_source": round(
509
+ mean_correlation,
510
+ 6,
511
+ ),
512
+ "mean_v8_local_contrast_retention": round(
513
+ mean_contrast_retention,
514
+ 6,
515
+ ),
516
+ "same_colour_within_group": all(
517
+ np.array_equal(
518
+ current_by_time[float(time)].color_rgb,
519
+ _hex_rgb(new_colour),
520
+ )
521
+ for time in group["times"]
522
+ ),
523
+ }
524
+ )
525
+ minimum_correlation = min(
526
+ float(row["v8_lightness_correlation_to_source"])
527
+ for row in pose_rows
528
+ )
529
+ contrast_values = [
530
+ float(row["v8_local_contrast_retention"]) for row in pose_rows
531
+ ]
532
+ v7_contrast_values = [
533
+ float(row["v7_local_contrast_retention"]) for row in pose_rows
534
+ ]
535
+ contrast_improvements = [
536
+ current - previous
537
+ for current, previous in zip(contrast_values, v7_contrast_values)
538
+ ]
539
+ maximum_absolute_lightness_shift = max(
540
+ abs(float(row["v8_mean_lightness_shift_from_source"]))
541
+ for row in pose_rows
542
+ )
543
+ minimum_base_l = min(float(row["v8_base_l_star"]) for row in group_rows)
544
+ maximum_base_l = max(float(row["v8_base_l_star"]) for row in group_rows)
545
+ report = {
546
+ "style": style,
547
+ "group_count": len(group_rows),
548
+ "all_group_colours_unique": len(
549
+ {str(group["color"]).upper() for group in config["color_groups"]}
550
+ )
551
+ == len(config["color_groups"]),
552
+ "all_within_group_mappings_preserved": all(
553
+ bool(row["same_colour_within_group"]) for row in group_rows
554
+ ),
555
+ "minimum_pairwise_ciede2000": round(minimum_delta, 4),
556
+ "minimum_required_pairwise_ciede2000": 20.0,
557
+ "base_l_star_range": [
558
+ round(minimum_base_l, 4),
559
+ round(maximum_base_l, 4),
560
+ ],
561
+ "effective_source_colour_and_detail_contribution": round(
562
+ effective_source_contribution,
563
+ 6,
564
+ ),
565
+ "effective_group_colour_contribution": round(
566
+ effective_group_contribution,
567
+ 6,
568
+ ),
569
+ "minimum_v8_lightness_correlation_to_source": round(
570
+ minimum_correlation,
571
+ 6,
572
+ ),
573
+ "v8_local_contrast_retention_range": [
574
+ round(min(contrast_values), 6),
575
+ round(max(contrast_values), 6),
576
+ ],
577
+ "v7_local_contrast_retention_range": [
578
+ round(min(v7_contrast_values), 6),
579
+ round(max(v7_contrast_values), 6),
580
+ ],
581
+ "minimum_local_contrast_retention_improvement_vs_v7": round(
582
+ min(contrast_improvements),
583
+ 6,
584
+ ),
585
+ "maximum_absolute_mean_lightness_shift_from_source": round(
586
+ maximum_absolute_lightness_shift,
587
+ 4,
588
+ ),
589
+ "groups": group_rows,
590
+ "pairwise_colour_difference": pairwise,
591
+ "poses": pose_rows,
592
+ }
593
+ report["pass"] = bool(
594
+ report["all_group_colours_unique"]
595
+ and report["all_within_group_mappings_preserved"]
596
+ and report["minimum_pairwise_ciede2000"]
597
+ >= report["minimum_required_pairwise_ciede2000"]
598
+ and minimum_base_l >= 42.0
599
+ and maximum_base_l <= 74.0
600
+ and effective_source_contribution >= 0.50
601
+ and minimum_correlation >= 0.985
602
+ and min(contrast_values) >= 0.85
603
+ and max(contrast_values) <= 1.15
604
+ and min(contrast_improvements) >= 0.25
605
+ and maximum_absolute_lightness_shift <= 4.5
606
+ )
607
+ return report
608
+
609
+
610
+ def save_occlusion_audit(config: dict[str, Any], out_dir: Path) -> dict[str, Any]:
611
+ parent_config = v3.v2.load_json(PARENT_CONFIG)
612
+ current_poses = list(v5._POSES_V5)
613
+ parent_poses = _parent_poses(parent_config)
614
+ before = v5.pose_visibility_metrics(parent_poses)
615
+ after = v5.pose_visibility_metrics(current_poses)
616
+ geometry = geometry_lock_audit(
617
+ parent_config,
618
+ config,
619
+ parent_poses,
620
+ current_poses,
621
+ )
622
+ palette = palette_audit(
623
+ parent_config,
624
+ config,
625
+ parent_poses,
626
+ current_poses,
627
+ )
628
+ row_layout = v6.row_layout_metrics(current_poses, config)
629
+ path_overlay = v6.path_overlay_metrics(current_poses, config)
630
+ crop_fit = v7.crop_fit_audit(current_poses, config)
631
+ report = {
632
+ "pass": bool(
633
+ geometry["pass"]
634
+ and palette["pass"]
635
+ and before == after
636
+ and row_layout["pass"]
637
+ and crop_fit["pass"]
638
+ and bool(path_overlay["foreground_redraw_enabled"])
639
+ ),
640
+ "v7": before,
641
+ "v8": after,
642
+ "visibility_metrics_identical": before == after,
643
+ "geometry_lock": geometry,
644
+ "palette": palette,
645
+ "row_layout": row_layout,
646
+ "crop_fit": crop_fit,
647
+ "path_overlay": path_overlay,
648
+ }
649
+ if not report["pass"]:
650
+ raise RuntimeError("V8 colour-only, palette, or layout audit failed")
651
+ v3.v2.write_json(out_dir / "occlusion_metrics.json", report)
652
+ v3.v2.write_json(out_dir / "geometry_lock_metrics.json", geometry)
653
+ v3.v2.write_json(out_dir / "palette_metrics.json", palette)
654
+ v3.v2.write_json(out_dir / "row_layout_metrics.json", row_layout)
655
+ v3.v2.write_json(out_dir / "crop_fit_metrics.json", crop_fit)
656
+ v3.v2.write_json(out_dir / "path_overlay_metrics.json", path_overlay)
657
+ return report
658
+
659
+
660
+ def save_layout_change_audit(
661
+ config: dict[str, Any],
662
+ out_dir: Path,
663
+ ) -> dict[str, Any]:
664
+ parent = v3.v2.load_json(PARENT_CONFIG)
665
+ rows = []
666
+ old_groups = {str(group["id"]): group for group in parent["color_groups"]}
667
+ for group in config["color_groups"]:
668
+ old = old_groups[str(group["id"])]
669
+ rows.append(
670
+ {
671
+ "group": group["id"],
672
+ "times_s": group["times"],
673
+ "v7_colour": str(old["color"]).upper(),
674
+ "v8_colour": str(group["color"]).upper(),
675
+ "colour_changed": str(old["color"]).upper()
676
+ != str(group["color"]).upper(),
677
+ }
678
+ )
679
+ report = {
680
+ "source_frames_unchanged": config["sample_times"] == parent["sample_times"],
681
+ "positions_unchanged": config["layout_targets_normalized"]
682
+ == parent["layout_targets_normalized"],
683
+ "scales_unchanged": (
684
+ config["pose_scale"] == parent["pose_scale"]
685
+ and config["pose_scale_overrides"] == parent["pose_scale_overrides"]
686
+ ),
687
+ "alpha_unchanged": config["alpha"] == parent["alpha"],
688
+ "crop_unchanged": config["crop_top_fraction"]
689
+ == parent["crop_top_fraction"],
690
+ "right_reserved_fraction_unchanged": config["right_reserved_fraction"]
691
+ == parent["right_reserved_fraction"],
692
+ "non_colour_config_unchanged": _non_colour_config(config)
693
+ == _non_colour_config(parent),
694
+ "changed_scope": [
695
+ "color_groups[*].color",
696
+ "foreground_color_style",
697
+ ],
698
+ "colour_changes": rows,
699
+ }
700
+ report["pass"] = bool(
701
+ report["source_frames_unchanged"]
702
+ and report["positions_unchanged"]
703
+ and report["scales_unchanged"]
704
+ and report["alpha_unchanged"]
705
+ and report["crop_unchanged"]
706
+ and report["right_reserved_fraction_unchanged"]
707
+ and report["non_colour_config_unchanged"]
708
+ and all(bool(row["colour_changed"]) for row in rows)
709
+ )
710
+ if not report["pass"]:
711
+ raise RuntimeError("V8 change-scope audit failed")
712
+ v3.v2.write_json(out_dir / "layout_change_audit.json", report)
713
+ return report
714
+
715
+
716
+ def save_reuse_audit(
717
+ args: argparse.Namespace,
718
+ out_dir: Path,
719
+ ) -> dict[str, Any]:
720
+ source = args.segmentation_source.expanduser().resolve()
721
+ parent_background = cv2.imread(str(source / "background_plate.png"))
722
+ current_background = cv2.imread(str(out_dir / "background_plate.png"))
723
+ if (
724
+ parent_background is None
725
+ or current_background is None
726
+ or parent_background.shape != current_background.shape
727
+ ):
728
+ raise RuntimeError("Could not compare v7/v8 backgrounds")
729
+ changed = int(np.any(parent_background != current_background, axis=2).sum())
730
+ artifacts = {}
731
+ for name in v5.REUSED_SEGMENTATION_ARTIFACTS:
732
+ source_hash = v7.sha256(source / name)
733
+ copied_hash = v7.sha256(out_dir / name)
734
+ artifacts[name] = {
735
+ "source_sha256": source_hash,
736
+ "copied_sha256": copied_hash,
737
+ "identical": source_hash == copied_hash,
738
+ }
739
+ report = {
740
+ "parent_version": "v7-wide-crop-uniform-scale",
741
+ "segmentation_source": v3.v2.display_path(source),
742
+ "source_frame_times_unchanged": True,
743
+ "segmentation_artifacts_identical": all(
744
+ row["identical"] for row in artifacts.values()
745
+ ),
746
+ "segmentation_artifacts": artifacts,
747
+ "background_changed_pixels": changed,
748
+ "background_identical": changed == 0,
749
+ "parent_background_sha256": v7.sha256(source / "background_plate.png"),
750
+ "v8_background_sha256": v7.sha256(out_dir / "background_plate.png"),
751
+ }
752
+ report["pass"] = bool(
753
+ report["background_identical"]
754
+ and report["segmentation_artifacts_identical"]
755
+ )
756
+ if not report["pass"]:
757
+ raise RuntimeError("V8 unexpectedly changed a reused v7 artifact")
758
+ v3.v2.write_json(out_dir / "reuse_audit.json", report)
759
+ return report
760
+
761
+
762
+ def update_run_metadata(
763
+ config: dict[str, Any],
764
+ out_dir: Path,
765
+ occlusion: dict[str, Any],
766
+ layout: dict[str, Any],
767
+ reuse: dict[str, Any],
768
+ ) -> None:
769
+ path = out_dir / "run_metadata.json"
770
+ metadata = v3.v2.load_json(path)
771
+ scales = [
772
+ v7.config_scale(config, float(time))
773
+ for time in config["sample_times"]
774
+ ]
775
+ metadata.update(
776
+ {
777
+ "parent_version": "v7-wide-crop-uniform-scale",
778
+ "default_pose_scale": float(config["pose_scale"]),
779
+ "pose_scale_overrides": config["pose_scale_overrides"],
780
+ "pose_scale_range": [min(scales), max(scales)],
781
+ "crop_top_fraction": float(config["crop_top_fraction"]),
782
+ "foreground_color_style": config["foreground_color_style"],
783
+ "palette_audit": occlusion["palette"],
784
+ "geometry_lock_audit": occlusion["geometry_lock"],
785
+ "layout_change_audit": layout,
786
+ "occlusion_audit": occlusion,
787
+ "reuse_audit": reuse,
788
+ "publication_output_stem": OUTPUT_STEM,
789
+ "publication_export_suffixes": list(PUBLICATION_SUFFIXES),
790
+ "final_width_mm": float(config["final_width_mm"]),
791
+ "png_dpi": int(config["png_dpi"]),
792
+ "tiff_dpi": int(config["tiff_dpi"]),
793
+ }
794
+ )
795
+ v3.v2.write_json(path, metadata)
796
+
797
+
798
+ def _swatch_text_colour(colour: str) -> str:
799
+ rgb = _hex_rgb(colour).astype(np.float64)
800
+ luminance = float(rgb @ np.asarray([0.2126, 0.7152, 0.0722]))
801
+ return "#FFFFFF" if luminance < 145.0 else "#26313A"
802
+
803
+
804
+ def save_palette_swatch(config: dict[str, Any], out_dir: Path) -> Path:
805
+ figure = v3.plt.figure(figsize=(8.2, 2.05), dpi=300, facecolor="#F6F7F5")
806
+ axis = figure.add_axes([0.025, 0.10, 0.95, 0.82])
807
+ axis.set_xlim(0, len(config["color_groups"]))
808
+ axis.set_ylim(0, 1)
809
+ axis.axis("off")
810
+ for index, group in enumerate(config["color_groups"]):
811
+ colour = str(group["color"]).upper()
812
+ axis.add_patch(
813
+ Rectangle(
814
+ (index + 0.04, 0.28),
815
+ 0.92,
816
+ 0.48,
817
+ facecolor=colour,
818
+ edgecolor="#FFFFFF",
819
+ linewidth=1.8,
820
+ )
821
+ )
822
+ axis.text(
823
+ index + 0.5,
824
+ 0.52,
825
+ f"{group['id']} {colour}",
826
+ ha="center",
827
+ va="center",
828
+ fontsize=9.0,
829
+ color=_swatch_text_colour(colour),
830
+ weight="bold",
831
+ )
832
+ axis.text(
833
+ index + 0.5,
834
+ 0.16,
835
+ str(group["label"]),
836
+ ha="center",
837
+ va="center",
838
+ fontsize=7.2,
839
+ color="#46525A",
840
+ )
841
+ axis.text(
842
+ 0.0,
843
+ 0.93,
844
+ "v8 contrastive metallic palette",
845
+ ha="left",
846
+ va="center",
847
+ fontsize=9.5,
848
+ color="#24313A",
849
+ weight="bold",
850
+ )
851
+ path = out_dir / "palette_swatch.png"
852
+ figure.savefig(path, dpi=300, facecolor=figure.get_facecolor())
853
+ v3.plt.close(figure)
854
+ return path
855
+
856
+
857
+ def save_v7_v8_comparison(
858
+ _crop_preview_path: Path,
859
+ current_path: Path,
860
+ out_dir: Path,
861
+ ) -> None:
862
+ config = v3.v2.load_json(DEFAULT_CONFIG)
863
+ paths = [PARENT_CLEAN, current_path]
864
+ images = []
865
+ for path in paths:
866
+ image = cv2.imread(str(path))
867
+ if image is None:
868
+ raise RuntimeError(f"Could not read comparison input: {path}")
869
+ images.append(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
870
+ figure = v3.plt.figure(figsize=(12.0, 5.15), dpi=300, facecolor="#F4F5F4")
871
+ grid = figure.add_gridspec(
872
+ 3,
873
+ 1,
874
+ height_ratios=[1.0, 1.0, 0.35],
875
+ hspace=0.17,
876
+ )
877
+ titles = [
878
+ "v7 • original medium-depth palette",
879
+ "v8 • contrastive metallic colour grade, identical geometry",
880
+ ]
881
+ for index, (image, title) in enumerate(zip(images, titles)):
882
+ axis = figure.add_subplot(grid[index, 0])
883
+ axis.imshow(image)
884
+ axis.set_title(
885
+ title,
886
+ fontsize=8.4,
887
+ loc="left",
888
+ pad=4,
889
+ weight="bold",
890
+ color="#28313A",
891
+ )
892
+ axis.axis("off")
893
+ swatch_axis = figure.add_subplot(grid[2, 0])
894
+ swatch_axis.set_xlim(0, len(config["color_groups"]))
895
+ swatch_axis.set_ylim(0, 1)
896
+ swatch_axis.axis("off")
897
+ for index, group in enumerate(config["color_groups"]):
898
+ colour = str(group["color"]).upper()
899
+ swatch_axis.add_patch(
900
+ Rectangle(
901
+ (index + 0.03, 0.18),
902
+ 0.94,
903
+ 0.64,
904
+ facecolor=colour,
905
+ edgecolor="#FFFFFF",
906
+ linewidth=1.1,
907
+ )
908
+ )
909
+ swatch_axis.text(
910
+ index + 0.5,
911
+ 0.50,
912
+ f"{group['id']} {colour}",
913
+ ha="center",
914
+ va="center",
915
+ fontsize=7.2,
916
+ color=_swatch_text_colour(colour),
917
+ weight="bold",
918
+ )
919
+ figure.savefig(
920
+ out_dir / "comparison_v7_v8.jpg",
921
+ dpi=300,
922
+ facecolor=figure.get_facecolor(),
923
+ bbox_inches="tight",
924
+ pil_kwargs={"quality": 94},
925
+ )
926
+ v3.plt.close(figure)
927
+ save_palette_swatch(config, out_dir)
928
+
929
+
930
+ def install_v8_hooks() -> None:
931
+ v3.validate_config = validate_config_v8
932
+ v3.v1.colorize_foreground = metallic_colorize_foreground
933
+ v6.DEFAULT_CONFIG = DEFAULT_CONFIG
934
+ v6.DEFAULT_OUT = DEFAULT_OUT
935
+ v6.PARENT_CONFIG = PARENT_CONFIG
936
+ v6.PARENT_OUT = PARENT_OUT
937
+ v6.PARENT_ANNOTATED = PARENT_ANNOTATED
938
+ v6.OUTPUT_STEM = OUTPUT_STEM
939
+ v6.parse_args = parse_args
940
+ v6.render_layout_v6 = render_layout_v8
941
+ v6.save_v5_v6_comparison = v7.defer_comparison
942
+ v6.save_occlusion_audit = save_occlusion_audit
943
+ v6.save_layout_change_audit = save_layout_change_audit
944
+ v6.save_reuse_audit = save_reuse_audit
945
+ v6.update_run_metadata = update_run_metadata
946
+ v7.DEFAULT_CONFIG = DEFAULT_CONFIG
947
+ v7.DEFAULT_OUT = DEFAULT_OUT
948
+ v7.PARENT_CONFIG = PARENT_CONFIG
949
+ v7.PARENT_OUT = PARENT_OUT
950
+ v7.PARENT_CLEAN = PARENT_CLEAN
951
+ v7.PARENT_ANNOTATED = PARENT_ANNOTATED
952
+ v7.OUTPUT_STEM = OUTPUT_STEM
953
+ v7.save_v6_v7_comparison = save_v7_v8_comparison
954
+
955
+
956
+ def main() -> int:
957
+ args = parse_args()
958
+ config = v3.v2.load_json(args.config.expanduser().resolve())
959
+ configure_colour_style(config)
960
+ install_v8_hooks()
961
+ return_code = v6.main()
962
+ if return_code:
963
+ return return_code
964
+ out_dir = args.out_dir.expanduser().resolve()
965
+ occlusion = v3.v2.load_json(out_dir / "occlusion_metrics.json")
966
+ v7.postprocess_wide_outputs(out_dir, config, occlusion)
967
+ print(f"Wrote v8 metallic-contrast outputs to {out_dir}")
968
+ return 0
969
+
970
+
971
+ if __name__ == "__main__":
972
+ raise SystemExit(main())
trajectory_project/scripts/build_trajectory_figure_v9.py ADDED
@@ -0,0 +1,1220 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Build v9 at the native 3840 x 2160 source-video resolution.
3
+
4
+ V9 is a resolution-only successor to v8. It keeps the locked source times,
5
+ layout targets, pose scales, colours, alpha values, z-order, crop, paths,
6
+ background recipe, and rightmost 12% reserve. The original 2560 x 1440 SAM
7
+ masks are mapped to the native 3840 x 2160 grid with nearest-neighbour
8
+ sampling, while robot texture and background pixels are decoded directly from
9
+ the 4K video. The final crop is 3840 x 1440. A pixel-native PNG is retained
10
+ alongside 183 mm, 600 dpi PNG/TIFF/SVG/PDF publication exports.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import copy
17
+ import csv
18
+ import hashlib
19
+ import math
20
+ import shutil
21
+ from pathlib import Path
22
+ from typing import Any
23
+
24
+ import cv2
25
+ import numpy as np
26
+
27
+ import build_trajectory_figure_v8 as v8
28
+
29
+
30
+ v3 = v8.v3
31
+ v5 = v8.v5
32
+ v6 = v8.v6
33
+ v7 = v8.v7
34
+
35
+ PROJECT_ROOT = Path(__file__).resolve().parents[2]
36
+ DEFAULT_VIDEO = PROJECT_ROOT / "source" / "CLIP_P0010073.mov"
37
+ DEFAULT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v9_native_4k_resolution.json"
38
+ DEFAULT_YOLO = PROJECT_ROOT / "trajectory_project" / "models" / "yolov8x-seg.pt"
39
+ DEFAULT_SAM = PROJECT_ROOT / "trajectory_project" / "models" / "sam_vit_b_01ec64.pth"
40
+ DEFAULT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v9_native_4k_resolution"
41
+ PARENT_CONFIG = PROJECT_ROOT / "trajectory_project" / "config_v8_metallic_contrast_palette.json"
42
+ PARENT_OUT = PROJECT_ROOT / "trajectory_project" / "outputs" / "v8_metallic_contrast_palette"
43
+ PARENT_CLEAN = PARENT_OUT / "trajectory_v8_metallic_contrast_clean.png"
44
+ PARENT_ANNOTATED = PARENT_OUT / "trajectory_v8_metallic_contrast_annotated.png"
45
+ PARENT_WIDE = PARENT_OUT / "composite_layout_wide_rgb.png"
46
+ OUTPUT_STEM = "trajectory_v9_native_4k"
47
+ NATIVE_CLEAN_NAME = f"{OUTPUT_STEM}_clean_native.png"
48
+ FINAL_WIDTH_MM = 183.0
49
+ PNG_DPI = 600
50
+ TIFF_DPI = 600
51
+ TARGET_WIDTH = 3840
52
+ TARGET_HEIGHT = 2160
53
+ PARENT_WIDTH = 2560
54
+ PARENT_HEIGHT = 1440
55
+ GRID_SCALE = TARGET_WIDTH / PARENT_WIDTH
56
+ PUBLICATION_SUFFIXES = (".png", ".tiff", ".svg", ".pdf")
57
+ _ORDERED_TIMES: list[float] = []
58
+
59
+ v3.matplotlib.rcParams.update(
60
+ {
61
+ "font.family": "sans-serif",
62
+ "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
63
+ "font.size": 7,
64
+ "svg.fonttype": "none",
65
+ "pdf.fonttype": 42,
66
+ }
67
+ )
68
+
69
+
70
+ def parse_args() -> argparse.Namespace:
71
+ parser = argparse.ArgumentParser(description=__doc__)
72
+ parser.add_argument("--video", type=Path, default=DEFAULT_VIDEO)
73
+ parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG)
74
+ parser.add_argument("--yolo-model", type=Path, default=DEFAULT_YOLO)
75
+ parser.add_argument("--sam-checkpoint", type=Path, default=DEFAULT_SAM)
76
+ parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT)
77
+ parser.add_argument("--segmentation-source", type=Path, default=PARENT_OUT)
78
+ parser.add_argument("--device", default="cuda:0")
79
+ args = parser.parse_args()
80
+ args.reuse_segmentation = True
81
+ return args
82
+
83
+
84
+ def _locked_visual_config(config: dict[str, Any]) -> dict[str, Any]:
85
+ payload = copy.deepcopy(config)
86
+ for key in ["version", "render_width", "png_dpi"]:
87
+ payload.pop(key, None)
88
+ return payload
89
+
90
+
91
+ def validate_config_v9(config: dict[str, Any]) -> None:
92
+ v8.validate_config_v8(config)
93
+ parent = v3.v2.load_json(PARENT_CONFIG)
94
+ if int(config["render_width"]) != TARGET_WIDTH:
95
+ raise RuntimeError("V9 must render at the native 3840 px video width")
96
+ if int(config["png_dpi"]) != PNG_DPI or int(config["tiff_dpi"]) != TIFF_DPI:
97
+ raise RuntimeError("V9 publication PNG and TIFF must both be 600 dpi")
98
+ if _locked_visual_config(config) != _locked_visual_config(parent):
99
+ raise RuntimeError("V9 may change only version, render_width, and PNG export dpi")
100
+
101
+
102
+ def _resize_mask_native(mask: np.ndarray) -> np.ndarray:
103
+ if mask.shape == (TARGET_HEIGHT, TARGET_WIDTH):
104
+ return mask.astype(np.uint8)
105
+ if mask.shape != (PARENT_HEIGHT, PARENT_WIDTH):
106
+ raise RuntimeError(f"Unexpected parent mask shape: {mask.shape}")
107
+ return cv2.resize(
108
+ mask.astype(np.uint8),
109
+ (TARGET_WIDTH, TARGET_HEIGHT),
110
+ interpolation=cv2.INTER_NEAREST,
111
+ )
112
+
113
+
114
+ def load_native_segmentation_cache(
115
+ _out_dir: Path,
116
+ ordered_times: list[float],
117
+ ) -> tuple[
118
+ dict[float, np.ndarray],
119
+ dict[float, np.ndarray],
120
+ dict[float, dict[str, Any]],
121
+ list[dict[str, Any]],
122
+ ]:
123
+ global _ORDERED_TIMES
124
+ source = Path(load_native_segmentation_cache.source_dir)
125
+ yolo, refined, metrics, records = v5._ORIGINAL_LOAD_CACHE(source, ordered_times)
126
+ _ORDERED_TIMES = list(ordered_times)
127
+ return (
128
+ {time: _resize_mask_native(mask) for time, mask in yolo.items()},
129
+ {time: _resize_mask_native(mask) for time, mask in refined.items()},
130
+ metrics,
131
+ records,
132
+ )
133
+
134
+
135
+ load_native_segmentation_cache.source_dir = str(PARENT_OUT)
136
+
137
+
138
+ def _scale_xy(values: list[float]) -> list[float]:
139
+ return [round(float(value) * GRID_SCALE, 4) for value in values]
140
+
141
+
142
+ def copy_scaled_segmentation_artifacts(
143
+ args: argparse.Namespace,
144
+ out_dir: Path,
145
+ ) -> None:
146
+ source = args.segmentation_source.expanduser().resolve()
147
+ arrays: dict[str, np.ndarray] = {}
148
+ for time in _ORDERED_TIMES:
149
+ key = v3.time_key(time)
150
+ arrays[f"yolo_{key}"] = v5._YOLO_MASKS[time].astype(np.uint8)
151
+ arrays[f"sam_{key}"] = v5._REFINED_MASKS[time].astype(np.uint8)
152
+ np.savez_compressed(out_dir / "segmentation_cache.npz", **arrays)
153
+
154
+ shutil.copy2(source / "sam_metrics_all.json", out_dir / "sam_metrics_all.json")
155
+
156
+ records = copy.deepcopy(v3.v2.load_json(source / "yolo_seed_detections.json"))
157
+ for row in records:
158
+ row["bbox_xyxy"] = _scale_xy(row["bbox_xyxy"])
159
+ row["foot_xy"] = _scale_xy(row["foot_xy"])
160
+ row["mask_area_px"] = int(round(float(row["mask_area_px"]) * GRID_SCALE**2))
161
+ row["coordinate_grid"] = [TARGET_WIDTH, TARGET_HEIGHT]
162
+ row["coordinate_scale_from_v8"] = GRID_SCALE
163
+ v3.v2.write_json(out_dir / "yolo_seed_detections.json", records)
164
+
165
+ prompts = copy.deepcopy(v3.v2.load_json(source / "sam_prompts.json"))
166
+ for prompt in prompts.values():
167
+ prompt["bbox_xyxy"] = _scale_xy(prompt["bbox_xyxy"])
168
+ prompt["point_coords_xy"] = [
169
+ _scale_xy(point) for point in prompt["point_coords_xy"]
170
+ ]
171
+ prompt["coordinate_grid"] = [TARGET_WIDTH, TARGET_HEIGHT]
172
+ prompt["coordinate_scale_from_v8"] = GRID_SCALE
173
+ v3.v2.write_json(out_dir / "sam_prompts.json", prompts)
174
+
175
+
176
+ def defer_intermediate_publication(
177
+ *_args: Any,
178
+ **_kwargs: Any,
179
+ ) -> None:
180
+ """V9 writes publication files once, after applying the locked wide crop."""
181
+
182
+
183
+ def _array_sha256(array: np.ndarray) -> str:
184
+ return hashlib.sha256(np.ascontiguousarray(array).view(np.uint8)).hexdigest()
185
+
186
+
187
+ def _mask_iou(first: np.ndarray, second: np.ndarray) -> float:
188
+ first_bool = first > 0
189
+ second_bool = second > 0
190
+ union = int((first_bool | second_bool).sum())
191
+ return float((first_bool & second_bool).sum() / union) if union else 1.0
192
+
193
+
194
+ def _read_parent_layout() -> dict[float, dict[str, str]]:
195
+ with (PARENT_OUT / "layout_map.csv").open(
196
+ "r",
197
+ encoding="utf-8",
198
+ newline="",
199
+ ) as handle:
200
+ return {
201
+ float(row["time_s"]): row
202
+ for row in csv.DictReader(handle)
203
+ }
204
+
205
+
206
+ def geometry_lock_audit(
207
+ config: dict[str, Any],
208
+ current_poses: list[v3.Pose],
209
+ ) -> dict[str, Any]:
210
+ parent_config = v3.v2.load_json(PARENT_CONFIG)
211
+ parent_layout = _read_parent_layout()
212
+ parent_archive = np.load(PARENT_OUT / "segmentation_cache.npz")
213
+ rows = []
214
+ try:
215
+ for pose in current_poses:
216
+ old = parent_layout[pose.time]
217
+ old_display = np.asarray(
218
+ [
219
+ float(old["display_foot_x_px"]),
220
+ float(old["display_foot_y_px"]),
221
+ ],
222
+ dtype=np.float64,
223
+ )
224
+ expected_display = old_display * GRID_SCALE
225
+ current_display = np.asarray(pose.display_foot, dtype=np.float64)
226
+ current_bbox = np.asarray(v7.bbox_for_pose(pose), dtype=np.float64)
227
+ old_bbox = np.asarray(
228
+ [
229
+ float(old["scaled_bbox_x1"]),
230
+ float(old["scaled_bbox_y1"]),
231
+ float(old["scaled_bbox_x2"]),
232
+ float(old["scaled_bbox_y2"]),
233
+ ],
234
+ dtype=np.float64,
235
+ )
236
+ expected_bbox = old_bbox * GRID_SCALE
237
+ parent_mask = parent_archive[f"sam_{v3.time_key(pose.time)}"]
238
+ expected_mask = _resize_mask_native(parent_mask)
239
+ parent_scale = v7.config_scale(parent_config, pose.time)
240
+ rows.append(
241
+ {
242
+ "time_s": pose.time,
243
+ "frame_index": pose.frame_index,
244
+ "v8_display_foot_px": old_display.tolist(),
245
+ "expected_v9_display_foot_px": expected_display.tolist(),
246
+ "v9_display_foot_px": current_display.tolist(),
247
+ "display_foot_delta_from_exact_1_5x_px": (
248
+ current_display - expected_display
249
+ ).round(4).tolist(),
250
+ "display_foot_normalized": (
251
+ current_display
252
+ / np.asarray([TARGET_WIDTH, TARGET_HEIGHT])
253
+ ).round(8).tolist(),
254
+ "v8_scale_factor": parent_scale,
255
+ "v9_scale_factor": float(pose.scale_factor),
256
+ "scale_delta": round(
257
+ float(pose.scale_factor) - parent_scale,
258
+ 12,
259
+ ),
260
+ "bbox_delta_from_exact_1_5x_px": (
261
+ current_bbox - expected_bbox
262
+ ).round(4).tolist(),
263
+ "native_mask_matches_nearest_mapped_v8_mask": bool(
264
+ np.array_equal(pose.refined_mask, expected_mask)
265
+ ),
266
+ "native_mask_sha256": _array_sha256(pose.refined_mask),
267
+ }
268
+ )
269
+ finally:
270
+ parent_archive.close()
271
+ maximum_position_delta = max(
272
+ abs(float(value))
273
+ for row in rows
274
+ for value in row["display_foot_delta_from_exact_1_5x_px"]
275
+ )
276
+ maximum_bbox_delta = max(
277
+ abs(float(value))
278
+ for row in rows
279
+ for value in row["bbox_delta_from_exact_1_5x_px"]
280
+ )
281
+ maximum_scale_delta = max(abs(float(row["scale_delta"])) for row in rows)
282
+ report = {
283
+ "parent_version": parent_config["version"],
284
+ "current_version": config["version"],
285
+ "render_grid_change": [PARENT_WIDTH, PARENT_HEIGHT, TARGET_WIDTH, TARGET_HEIGHT],
286
+ "expected_linear_grid_scale": GRID_SCALE,
287
+ "all_locked_visual_config_identical": (
288
+ _locked_visual_config(config) == _locked_visual_config(parent_config)
289
+ ),
290
+ "all_masks_equal_nearest_mapped_parent": all(
291
+ bool(row["native_mask_matches_nearest_mapped_v8_mask"]) for row in rows
292
+ ),
293
+ "maximum_absolute_display_foot_delta_from_exact_1_5x_px": round(
294
+ maximum_position_delta,
295
+ 4,
296
+ ),
297
+ "maximum_absolute_bbox_delta_from_exact_1_5x_px": round(
298
+ maximum_bbox_delta,
299
+ 4,
300
+ ),
301
+ "maximum_absolute_scale_delta": round(maximum_scale_delta, 12),
302
+ "poses": rows,
303
+ }
304
+ report["pass"] = bool(
305
+ report["all_locked_visual_config_identical"]
306
+ and report["all_masks_equal_nearest_mapped_parent"]
307
+ and maximum_position_delta <= 1.0
308
+ and maximum_bbox_delta <= 2.0
309
+ and maximum_scale_delta <= 1e-12
310
+ )
311
+ return report
312
+
313
+
314
+ def _scaled_row_layout_metrics(
315
+ poses: list[v3.Pose],
316
+ config: dict[str, Any],
317
+ ) -> dict[str, Any]:
318
+ report = v6.row_layout_metrics(poses, config)
319
+ report["pixel_scale_vs_v8"] = GRID_SCALE
320
+ report["foreground_gap_range_in_v8_equivalent_px"] = round(
321
+ float(report["foreground_gap_range_px"]) / GRID_SCALE,
322
+ 4,
323
+ )
324
+ report["foreground_ground_y_span_in_v8_equivalent_px"] = round(
325
+ float(report["foreground_ground_y_span_px"]) / GRID_SCALE,
326
+ 4,
327
+ )
328
+ report["far_field_gap_range_in_v8_equivalent_px"] = round(
329
+ float(report["far_field_gap_range_px"]) / GRID_SCALE,
330
+ 4,
331
+ )
332
+ report["far_field_y_span_in_v8_equivalent_px"] = round(
333
+ float(report["far_field_y_span_px"]) / GRID_SCALE,
334
+ 4,
335
+ )
336
+ report["pass"] = bool(
337
+ float(report["foreground_height_cv"]) < 0.02
338
+ and float(report["foreground_gap_range_in_v8_equivalent_px"]) <= 60.0
339
+ and float(report["foreground_ground_y_span_in_v8_equivalent_px"]) <= 2.0
340
+ and float(report["far_field_gap_range_in_v8_equivalent_px"]) <= 2.0
341
+ and float(report["far_field_y_span_in_v8_equivalent_px"]) <= 2.0
342
+ and 1.05 <= float(report["retreat_31_to_32_apparent_height_ratio"]) <= 1.25
343
+ )
344
+ return report
345
+
346
+
347
+ def _visibility_delta(
348
+ parent: dict[str, Any],
349
+ current: dict[str, Any],
350
+ ) -> dict[str, Any]:
351
+ pose_deltas = {
352
+ key: round(
353
+ float(current["per_pose_visible_fraction"][key])
354
+ - float(parent["per_pose_visible_fraction"][key]),
355
+ 6,
356
+ )
357
+ for key in parent["per_pose_visible_fraction"]
358
+ }
359
+ return {
360
+ "redundant_overlap_fraction_delta": round(
361
+ float(current["redundant_overlap_fraction"])
362
+ - float(parent["redundant_overlap_fraction"]),
363
+ 6,
364
+ ),
365
+ "maximum_stack_depth_unchanged": (
366
+ int(current["maximum_stack_depth"])
367
+ == int(parent["maximum_stack_depth"])
368
+ ),
369
+ "maximum_absolute_per_pose_visible_fraction_delta": round(
370
+ max(abs(float(value)) for value in pose_deltas.values()),
371
+ 6,
372
+ ),
373
+ "per_pose_visible_fraction_delta": pose_deltas,
374
+ }
375
+
376
+
377
+ def save_occlusion_audit(
378
+ config: dict[str, Any],
379
+ out_dir: Path,
380
+ ) -> dict[str, Any]:
381
+ current_poses = list(v5._POSES_V5)
382
+ current_visibility = v5.pose_visibility_metrics(current_poses)
383
+ parent_report = v3.v2.load_json(PARENT_OUT / "occlusion_metrics.json")
384
+ parent_visibility = parent_report["v8"]
385
+ visibility_delta = _visibility_delta(parent_visibility, current_visibility)
386
+ geometry = geometry_lock_audit(config, current_poses)
387
+ row_layout = _scaled_row_layout_metrics(current_poses, config)
388
+ path_overlay = v6.path_overlay_metrics(current_poses, config)
389
+ crop_fit = v7.crop_fit_audit(current_poses, config)
390
+
391
+ v7_config = v3.v2.load_json(v8.PARENT_CONFIG)
392
+ parent_colour_poses = v8._parent_poses(v7_config)
393
+ palette = v8.palette_audit(
394
+ v7_config,
395
+ config,
396
+ parent_colour_poses,
397
+ current_poses,
398
+ )
399
+ palette["evaluated_render_grid_px"] = [TARGET_WIDTH, TARGET_HEIGHT]
400
+
401
+ report = {
402
+ "pass": bool(
403
+ geometry["pass"]
404
+ and palette["pass"]
405
+ and row_layout["pass"]
406
+ and crop_fit["pass"]
407
+ and bool(path_overlay["foreground_redraw_enabled"])
408
+ and abs(float(visibility_delta["redundant_overlap_fraction_delta"])) <= 0.001
409
+ and bool(visibility_delta["maximum_stack_depth_unchanged"])
410
+ and float(
411
+ visibility_delta[
412
+ "maximum_absolute_per_pose_visible_fraction_delta"
413
+ ]
414
+ )
415
+ <= 0.01
416
+ ),
417
+ "v8": parent_visibility,
418
+ "v9": current_visibility,
419
+ "visibility_delta_from_mask_grid_mapping": visibility_delta,
420
+ "geometry_lock": geometry,
421
+ "palette": palette,
422
+ "row_layout": row_layout,
423
+ "crop_fit": crop_fit,
424
+ "path_overlay": path_overlay,
425
+ }
426
+ if not report["pass"]:
427
+ raise RuntimeError("V9 resolution-only geometry or visibility audit failed")
428
+ v3.v2.write_json(out_dir / "occlusion_metrics.json", report)
429
+ v3.v2.write_json(out_dir / "geometry_lock_metrics.json", geometry)
430
+ v3.v2.write_json(out_dir / "palette_metrics.json", palette)
431
+ v3.v2.write_json(out_dir / "row_layout_metrics.json", row_layout)
432
+ v3.v2.write_json(out_dir / "crop_fit_metrics.json", crop_fit)
433
+ v3.v2.write_json(out_dir / "path_overlay_metrics.json", path_overlay)
434
+ return report
435
+
436
+
437
+ def save_layout_change_audit(
438
+ config: dict[str, Any],
439
+ out_dir: Path,
440
+ ) -> dict[str, Any]:
441
+ parent = v3.v2.load_json(PARENT_CONFIG)
442
+ report = {
443
+ "parent_version": parent["version"],
444
+ "current_version": config["version"],
445
+ "source_frames_unchanged": config["sample_times"] == parent["sample_times"],
446
+ "positions_unchanged": (
447
+ config["layout_targets_normalized"]
448
+ == parent["layout_targets_normalized"]
449
+ ),
450
+ "scales_unchanged": (
451
+ config["pose_scale"] == parent["pose_scale"]
452
+ and config["pose_scale_overrides"] == parent["pose_scale_overrides"]
453
+ ),
454
+ "colours_unchanged": config["color_groups"] == parent["color_groups"],
455
+ "colour_transfer_unchanged": (
456
+ config["foreground_color_style"]
457
+ == parent["foreground_color_style"]
458
+ ),
459
+ "alpha_unchanged": config["alpha"] == parent["alpha"],
460
+ "crop_unchanged": (
461
+ config["crop_top_fraction"] == parent["crop_top_fraction"]
462
+ ),
463
+ "right_reserved_fraction_unchanged": (
464
+ config["right_reserved_fraction"]
465
+ == parent["right_reserved_fraction"]
466
+ ),
467
+ "locked_visual_config_unchanged": (
468
+ _locked_visual_config(config) == _locked_visual_config(parent)
469
+ ),
470
+ "changed_scope": [
471
+ "render_width: 2560 -> 3840",
472
+ "png_dpi: 300 -> 600",
473
+ "version/output names",
474
+ "SAM mask coordinate grid: nearest-neighbour 1.5x mapping",
475
+ ],
476
+ }
477
+ report["pass"] = bool(
478
+ report["source_frames_unchanged"]
479
+ and report["positions_unchanged"]
480
+ and report["scales_unchanged"]
481
+ and report["colours_unchanged"]
482
+ and report["colour_transfer_unchanged"]
483
+ and report["alpha_unchanged"]
484
+ and report["crop_unchanged"]
485
+ and report["right_reserved_fraction_unchanged"]
486
+ and report["locked_visual_config_unchanged"]
487
+ )
488
+ if not report["pass"]:
489
+ raise RuntimeError("V9 change-scope audit failed")
490
+ v3.v2.write_json(out_dir / "layout_change_audit.json", report)
491
+ return report
492
+
493
+
494
+ def _psnr(first: np.ndarray, second: np.ndarray) -> float:
495
+ error = float(
496
+ np.mean(
497
+ (
498
+ first.astype(np.float32)
499
+ - second.astype(np.float32)
500
+ )
501
+ ** 2
502
+ )
503
+ )
504
+ return float("inf") if error == 0.0 else 10.0 * math.log10(255.0**2 / error)
505
+
506
+
507
+ def save_reuse_audit(
508
+ args: argparse.Namespace,
509
+ out_dir: Path,
510
+ ) -> dict[str, Any]:
511
+ source = args.segmentation_source.expanduser().resolve()
512
+ parent_archive = np.load(source / "segmentation_cache.npz")
513
+ current_archive = np.load(out_dir / "segmentation_cache.npz")
514
+ mask_rows = []
515
+ try:
516
+ for key in parent_archive.files:
517
+ parent_mask = parent_archive[key]
518
+ current_mask = current_archive[key]
519
+ expected = _resize_mask_native(parent_mask)
520
+ downsampled = cv2.resize(
521
+ current_mask,
522
+ (PARENT_WIDTH, PARENT_HEIGHT),
523
+ interpolation=cv2.INTER_NEAREST,
524
+ )
525
+ parent_area = int((parent_mask > 0).sum())
526
+ current_area = int((current_mask > 0).sum())
527
+ mask_rows.append(
528
+ {
529
+ "key": key,
530
+ "parent_shape": list(parent_mask.shape[::-1]),
531
+ "native_shape": list(current_mask.shape[::-1]),
532
+ "native_equals_expected_nearest_mapping": bool(
533
+ np.array_equal(current_mask, expected)
534
+ ),
535
+ "foreground_area_scale": round(
536
+ current_area / parent_area,
537
+ 6,
538
+ )
539
+ if parent_area
540
+ else 1.0,
541
+ "roundtrip_downsample_iou": round(
542
+ _mask_iou(parent_mask, downsampled),
543
+ 6,
544
+ ),
545
+ }
546
+ )
547
+ finally:
548
+ parent_archive.close()
549
+ current_archive.close()
550
+
551
+ parent_background = cv2.imread(str(source / "background_plate.png"))
552
+ current_background = cv2.imread(str(out_dir / "background_plate.png"))
553
+ if parent_background is None or current_background is None:
554
+ raise RuntimeError("Could not read v8/v9 background plates")
555
+ current_down = cv2.resize(
556
+ current_background,
557
+ (PARENT_WIDTH, PARENT_HEIGHT),
558
+ interpolation=cv2.INTER_AREA,
559
+ )
560
+ background_mae = float(
561
+ np.mean(
562
+ np.abs(
563
+ parent_background.astype(np.float32)
564
+ - current_down.astype(np.float32)
565
+ )
566
+ )
567
+ )
568
+ background_psnr = _psnr(parent_background, current_down)
569
+ minimum_roundtrip_iou = min(
570
+ float(row["roundtrip_downsample_iou"]) for row in mask_rows
571
+ )
572
+ maximum_area_scale_error = max(
573
+ abs(float(row["foreground_area_scale"]) - GRID_SCALE**2)
574
+ for row in mask_rows
575
+ )
576
+ metrics_identical = (
577
+ v7.sha256(source / "sam_metrics_all.json")
578
+ == v7.sha256(out_dir / "sam_metrics_all.json")
579
+ )
580
+ report = {
581
+ "parent_version": "v8-metallic-contrast-palette",
582
+ "segmentation_source": v3.v2.display_path(source),
583
+ "source_frame_times_unchanged": True,
584
+ "mask_mapping_method": "nearest-neighbour from locked 2560x1440 masks",
585
+ "linear_grid_scale": GRID_SCALE,
586
+ "expected_area_scale": GRID_SCALE**2,
587
+ "all_native_masks_equal_expected_mapping": all(
588
+ bool(row["native_equals_expected_nearest_mapping"])
589
+ for row in mask_rows
590
+ ),
591
+ "minimum_roundtrip_downsample_iou": round(minimum_roundtrip_iou, 6),
592
+ "maximum_foreground_area_scale_error": round(
593
+ maximum_area_scale_error,
594
+ 6,
595
+ ),
596
+ "sam_metrics_identical": metrics_identical,
597
+ "background_parent_size_px": list(parent_background.shape[1::-1]),
598
+ "background_native_size_px": list(current_background.shape[1::-1]),
599
+ "background_downsample_mae": round(background_mae, 6),
600
+ "background_downsample_psnr_db": (
601
+ "inf" if math.isinf(background_psnr) else round(background_psnr, 4)
602
+ ),
603
+ "masks": mask_rows,
604
+ }
605
+ report["pass"] = bool(
606
+ report["all_native_masks_equal_expected_mapping"]
607
+ and minimum_roundtrip_iou >= 0.97
608
+ and maximum_area_scale_error <= 0.01
609
+ and metrics_identical
610
+ and current_background.shape[:2] == (TARGET_HEIGHT, TARGET_WIDTH)
611
+ and background_mae <= 5.0
612
+ and background_psnr >= 30.0
613
+ )
614
+ if not report["pass"]:
615
+ raise RuntimeError("V9 native-grid reuse audit failed")
616
+ v3.v2.write_json(out_dir / "reuse_audit.json", report)
617
+ v3.v2.write_json(
618
+ out_dir / "mask_scaling_metrics.json",
619
+ {
620
+ key: report[key]
621
+ for key in [
622
+ "mask_mapping_method",
623
+ "linear_grid_scale",
624
+ "expected_area_scale",
625
+ "all_native_masks_equal_expected_mapping",
626
+ "minimum_roundtrip_downsample_iou",
627
+ "maximum_foreground_area_scale_error",
628
+ "masks",
629
+ "pass",
630
+ ]
631
+ },
632
+ )
633
+ return report
634
+
635
+
636
+ def update_run_metadata(
637
+ config: dict[str, Any],
638
+ out_dir: Path,
639
+ occlusion: dict[str, Any],
640
+ layout: dict[str, Any],
641
+ reuse: dict[str, Any],
642
+ ) -> None:
643
+ path = out_dir / "run_metadata.json"
644
+ metadata = v3.v2.load_json(path)
645
+ metadata.pop("uniform_pose_scale", None)
646
+ scales = [
647
+ v7.config_scale(config, float(time))
648
+ for time in config["sample_times"]
649
+ ]
650
+ metadata.update(
651
+ {
652
+ "parent_version": "v8-metallic-contrast-palette",
653
+ "change_scope": "native-resolution rerender only",
654
+ "default_pose_scale": float(config["pose_scale"]),
655
+ "pose_scale_overrides": config["pose_scale_overrides"],
656
+ "pose_scale_range": [min(scales), max(scales)],
657
+ "crop_top_fraction": float(config["crop_top_fraction"]),
658
+ "foreground_color_style": config["foreground_color_style"],
659
+ "layout_change_audit": layout,
660
+ "occlusion_audit": occlusion,
661
+ "reuse_audit": reuse,
662
+ "native_source_grid_px": [TARGET_WIDTH, TARGET_HEIGHT],
663
+ "mask_grid_mapping": "nearest-neighbour 1.5x from locked v8 SAM masks",
664
+ "publication_output_stem": OUTPUT_STEM,
665
+ "publication_export_suffixes": list(PUBLICATION_SUFFIXES),
666
+ "final_width_mm": float(config["final_width_mm"]),
667
+ "png_dpi": int(config["png_dpi"]),
668
+ "tiff_dpi": int(config["tiff_dpi"]),
669
+ "generative_super_resolution_used": False,
670
+ "artificial_sharpening_used": False,
671
+ }
672
+ )
673
+ v3.v2.write_json(path, metadata)
674
+
675
+
676
+ def publication_artifact_audit(
677
+ out_dir: Path,
678
+ config: dict[str, Any],
679
+ crop_y: int,
680
+ ) -> dict[str, Any]:
681
+ variants: dict[str, Any] = {}
682
+ for variant in ["clean", "annotated"]:
683
+ rows: dict[str, Any] = {}
684
+ for extension in PUBLICATION_SUFFIXES:
685
+ path = out_dir / f"{OUTPUT_STEM}_{variant}{extension}"
686
+ if not path.exists() or path.stat().st_size == 0:
687
+ raise RuntimeError(f"Missing publication artifact: {path}")
688
+ rows[extension.lstrip(".")] = {
689
+ "bytes": path.stat().st_size,
690
+ "sha256": v7.sha256(path),
691
+ }
692
+ with v3.Image.open(out_dir / f"{OUTPUT_STEM}_{variant}.png") as image:
693
+ rows["png"].update(
694
+ {
695
+ "width_px": image.width,
696
+ "height_px": image.height,
697
+ "mode": image.mode,
698
+ "dpi": [
699
+ round(float(value), 3)
700
+ for value in image.info.get("dpi", (0, 0))
701
+ ],
702
+ }
703
+ )
704
+ with v3.Image.open(out_dir / f"{OUTPUT_STEM}_{variant}.tiff") as image:
705
+ rows["tiff"].update(
706
+ {
707
+ "width_px": image.width,
708
+ "height_px": image.height,
709
+ "mode": image.mode,
710
+ "compression": image.info.get("compression"),
711
+ "dpi": [
712
+ round(float(value), 3)
713
+ for value in image.info.get("dpi", (0, 0))
714
+ ],
715
+ }
716
+ )
717
+ variants[variant] = rows
718
+
719
+ width_in = float(config["final_width_mm"]) / 25.4
720
+ aspect = (TARGET_HEIGHT - crop_y) / TARGET_WIDTH
721
+ expected_png = [
722
+ int(width_in * int(config["png_dpi"])),
723
+ int(width_in * aspect * int(config["png_dpi"])),
724
+ ]
725
+ expected_tiff = [
726
+ int(width_in * int(config["tiff_dpi"])),
727
+ int(width_in * aspect * int(config["tiff_dpi"])),
728
+ ]
729
+ native_path = out_dir / NATIVE_CLEAN_NAME
730
+ with v3.Image.open(native_path) as native:
731
+ native_row = {
732
+ "path": native_path.name,
733
+ "width_px": native.width,
734
+ "height_px": native.height,
735
+ "mode": native.mode,
736
+ "bytes": native_path.stat().st_size,
737
+ "sha256": v7.sha256(native_path),
738
+ }
739
+ report = {
740
+ "expected_png_size_px": expected_png,
741
+ "expected_tiff_size_px": expected_tiff,
742
+ "native_clean": native_row,
743
+ "variants": variants,
744
+ }
745
+ report["pass"] = bool(
746
+ native_row["width_px"] == TARGET_WIDTH
747
+ and native_row["height_px"] == TARGET_HEIGHT - crop_y
748
+ and all(
749
+ row["png"]["width_px"] == expected_png[0]
750
+ and row["png"]["height_px"] == expected_png[1]
751
+ and abs(float(row["png"]["dpi"][0]) - PNG_DPI) <= 0.1
752
+ and row["tiff"]["width_px"] == expected_tiff[0]
753
+ and row["tiff"]["height_px"] == expected_tiff[1]
754
+ and row["tiff"]["mode"] == "RGB"
755
+ and row["tiff"]["compression"] == "tiff_lzw"
756
+ for row in variants.values()
757
+ )
758
+ )
759
+ if not report["pass"]:
760
+ raise RuntimeError("V9 publication artifact audit failed")
761
+ v3.v2.write_json(out_dir / "publication_artifact_metrics.json", report)
762
+ return report
763
+
764
+
765
+ def _crop_square(
766
+ image: np.ndarray,
767
+ centre_x: float,
768
+ centre_y: float,
769
+ size: int,
770
+ ) -> np.ndarray:
771
+ half = size // 2
772
+ x1 = int(round(centre_x)) - half
773
+ y1 = int(round(centre_y)) - half
774
+ x1 = max(0, min(x1, image.shape[1] - size))
775
+ y1 = max(0, min(y1, image.shape[0] - size))
776
+ return image[y1 : y1 + size, x1 : x1 + size].copy()
777
+
778
+
779
+ def save_resolution_comparisons(
780
+ _crop_preview_path: Path,
781
+ _current_path: Path,
782
+ out_dir: Path,
783
+ ) -> None:
784
+ parent_bgr = cv2.imread(str(PARENT_WIDE))
785
+ current_bgr = cv2.imread(str(out_dir / "composite_layout_wide_rgb.png"))
786
+ if parent_bgr is None or current_bgr is None:
787
+ raise RuntimeError("Could not read v8/v9 comparison inputs")
788
+ parent_rgb = cv2.cvtColor(parent_bgr, cv2.COLOR_BGR2RGB)
789
+ current_rgb = cv2.cvtColor(current_bgr, cv2.COLOR_BGR2RGB)
790
+
791
+ figure = v3.plt.figure(figsize=(12.0, 5.15), dpi=300, facecolor="#F4F5F4")
792
+ grid = figure.add_gridspec(2, 1, hspace=0.16)
793
+ panels = [
794
+ (parent_rgb, "v8 • 2560 × 960 internal render"),
795
+ (current_rgb, "v9 • native 3840 × 1440 render, identical visual layout"),
796
+ ]
797
+ for index, (image, title) in enumerate(panels):
798
+ axis = figure.add_subplot(grid[index, 0])
799
+ axis.imshow(image)
800
+ axis.set_title(
801
+ title,
802
+ fontsize=8.4,
803
+ loc="left",
804
+ pad=4,
805
+ weight="bold",
806
+ color="#28313A",
807
+ )
808
+ axis.axis("off")
809
+ figure.savefig(
810
+ out_dir / "comparison_v8_v9_resolution.jpg",
811
+ dpi=300,
812
+ facecolor=figure.get_facecolor(),
813
+ bbox_inches="tight",
814
+ pil_kwargs={"quality": 95},
815
+ )
816
+ v3.plt.close(figure)
817
+
818
+ parent_layout = _read_parent_layout()
819
+ crop_y_parent = int(round(PARENT_HEIGHT / 3.0))
820
+ crop_y_native = int(round(TARGET_HEIGHT / 3.0))
821
+ detail_times = [6.0, 14.0, 40.0]
822
+ old_size = 320
823
+ native_size = int(round(old_size * GRID_SCALE))
824
+ header = 42
825
+ gutter = 12
826
+ sheet = np.full(
827
+ (
828
+ len(detail_times) * (native_size + header + gutter) - gutter,
829
+ native_size * 2 + gutter,
830
+ 3,
831
+ ),
832
+ 246,
833
+ dtype=np.uint8,
834
+ )
835
+ for row_index, time in enumerate(detail_times):
836
+ row = parent_layout[time]
837
+ x = float(row["display_foot_x_px"])
838
+ bbox_top = float(row["scaled_bbox_y1"])
839
+ bbox_bottom = float(row["scaled_bbox_y2"])
840
+ centre_y = bbox_top + 0.43 * (bbox_bottom - bbox_top) - crop_y_parent
841
+ old_crop = _crop_square(parent_rgb, x, centre_y, old_size)
842
+ old_upscaled = cv2.resize(
843
+ old_crop,
844
+ (native_size, native_size),
845
+ interpolation=cv2.INTER_LANCZOS4,
846
+ )
847
+ native_crop = _crop_square(
848
+ current_rgb,
849
+ x * GRID_SCALE,
850
+ (centre_y + crop_y_parent) * GRID_SCALE - crop_y_native,
851
+ native_size,
852
+ )
853
+ y0 = row_index * (native_size + header + gutter)
854
+ sheet[y0 + header : y0 + header + native_size, :native_size] = old_upscaled
855
+ sheet[
856
+ y0 + header : y0 + header + native_size,
857
+ native_size + gutter :,
858
+ ] = native_crop
859
+ cv2.putText(
860
+ sheet,
861
+ f"{time:g} s v8 enlarged from 2560",
862
+ (12, y0 + 28),
863
+ cv2.FONT_HERSHEY_SIMPLEX,
864
+ 0.58,
865
+ (40, 48, 55),
866
+ 1,
867
+ cv2.LINE_AA,
868
+ )
869
+ cv2.putText(
870
+ sheet,
871
+ f"{time:g} s v9 native 4K pixels",
872
+ (native_size + gutter + 12, y0 + 28),
873
+ cv2.FONT_HERSHEY_SIMPLEX,
874
+ 0.58,
875
+ (40, 48, 55),
876
+ 1,
877
+ cv2.LINE_AA,
878
+ )
879
+ cv2.imwrite(
880
+ str(out_dir / "detail_crops_v8_v9.png"),
881
+ cv2.cvtColor(sheet, cv2.COLOR_RGB2BGR),
882
+ )
883
+
884
+
885
+ def postprocess_wide_outputs(
886
+ out_dir: Path,
887
+ config: dict[str, Any],
888
+ occlusion: dict[str, Any],
889
+ ) -> None:
890
+ full_layout_bgr = cv2.imread(str(out_dir / "composite_layout_rgb.png"))
891
+ full_background_bgr = cv2.imread(str(out_dir / "background_plate.png"))
892
+ if full_layout_bgr is None or full_background_bgr is None:
893
+ raise RuntimeError("Missing full-canvas v9 render")
894
+ if full_layout_bgr.shape != full_background_bgr.shape:
895
+ raise RuntimeError("Full layout and background dimensions do not match")
896
+ full_layout_rgb = cv2.cvtColor(full_layout_bgr, cv2.COLOR_BGR2RGB)
897
+ full_background_rgb = cv2.cvtColor(full_background_bgr, cv2.COLOR_BGR2RGB)
898
+ crop_y = v7.crop_top_px(config, full_layout_rgb.shape[0])
899
+ wide_layout_rgb = full_layout_rgb[crop_y:].copy()
900
+ wide_background_rgb = full_background_rgb[crop_y:].copy()
901
+
902
+ shutil.copy2(
903
+ out_dir / "composite_layout_rgb.png",
904
+ out_dir / "composite_layout_full_rgb.png",
905
+ )
906
+ cv2.imwrite(
907
+ str(out_dir / "composite_layout_wide_rgb.png"),
908
+ cv2.cvtColor(wide_layout_rgb, cv2.COLOR_RGB2BGR),
909
+ )
910
+ cv2.imwrite(
911
+ str(out_dir / "background_plate_wide.png"),
912
+ cv2.cvtColor(wide_background_rgb, cv2.COLOR_RGB2BGR),
913
+ )
914
+ shutil.copy2(
915
+ out_dir / "composite_layout_wide_rgb.png",
916
+ out_dir / NATIVE_CLEAN_NAME,
917
+ )
918
+
919
+ v7.save_publication_figure(
920
+ wide_layout_rgb,
921
+ out_dir / f"{OUTPUT_STEM}_clean",
922
+ config,
923
+ annotated=False,
924
+ )
925
+ v7.save_publication_figure(
926
+ wide_layout_rgb,
927
+ out_dir / f"{OUTPUT_STEM}_annotated",
928
+ config,
929
+ annotated=True,
930
+ )
931
+ v7.save_wide_layout_map(out_dir, crop_y)
932
+
933
+ full_safe_path = out_dir / "safe_area_qa.png"
934
+ full_safe_metrics_path = out_dir / "safe_area_metrics.json"
935
+ if full_safe_path.exists():
936
+ full_safe_path.replace(out_dir / "safe_area_full_qa.png")
937
+ if full_safe_metrics_path.exists():
938
+ full_safe_metrics_path.replace(out_dir / "safe_area_full_metrics.json")
939
+ safe_report = v7.save_wide_safe_area_qa(
940
+ wide_layout_rgb,
941
+ wide_background_rgb,
942
+ config,
943
+ out_dir,
944
+ )
945
+ crop_preview = v7.save_crop_window_preview(
946
+ full_layout_rgb,
947
+ crop_y,
948
+ out_dir,
949
+ )
950
+ save_resolution_comparisons(
951
+ crop_preview,
952
+ out_dir / f"{OUTPUT_STEM}_clean.png",
953
+ out_dir,
954
+ )
955
+ artifact_report = publication_artifact_audit(out_dir, config, crop_y)
956
+
957
+ crop_report = {
958
+ "full_canvas_size_px": [
959
+ full_layout_rgb.shape[1],
960
+ full_layout_rgb.shape[0],
961
+ ],
962
+ "crop_top_y_px": crop_y,
963
+ "requested_crop_top_fraction": float(config["crop_top_fraction"]),
964
+ "actual_removed_fraction": round(crop_y / full_layout_rgb.shape[0], 8),
965
+ "wide_canvas_size_px": [
966
+ wide_layout_rgb.shape[1],
967
+ wide_layout_rgb.shape[0],
968
+ ],
969
+ "aspect_ratio": round(
970
+ wide_layout_rgb.shape[1] / wide_layout_rgb.shape[0],
971
+ 6,
972
+ ),
973
+ "height_reduction_fraction": round(
974
+ 1.0 - wide_layout_rgb.shape[0] / full_layout_rgb.shape[0],
975
+ 8,
976
+ ),
977
+ "pose_crop_fit": occlusion["crop_fit"],
978
+ "safe_area": safe_report,
979
+ "publication_artifacts": artifact_report,
980
+ }
981
+ crop_report["pass"] = bool(
982
+ occlusion["crop_fit"]["pass"]
983
+ and safe_report["pass"]
984
+ and artifact_report["pass"]
985
+ and wide_layout_rgb.shape[:2]
986
+ == (TARGET_HEIGHT - crop_y, TARGET_WIDTH)
987
+ )
988
+ if not crop_report["pass"]:
989
+ raise RuntimeError("V9 crop/export audit failed")
990
+ v3.v2.write_json(out_dir / "crop_metrics.json", crop_report)
991
+
992
+ metadata_path = out_dir / "run_metadata.json"
993
+ metadata = v3.v2.load_json(metadata_path)
994
+ metadata.update(
995
+ {
996
+ "full_render_size_px": [
997
+ full_layout_rgb.shape[1],
998
+ full_layout_rgb.shape[0],
999
+ ],
1000
+ "crop_top_y_px": crop_y,
1001
+ "wide_render_size_px": [
1002
+ wide_layout_rgb.shape[1],
1003
+ wide_layout_rgb.shape[0],
1004
+ ],
1005
+ "wide_aspect_ratio": crop_report["aspect_ratio"],
1006
+ "native_clean_file": NATIVE_CLEAN_NAME,
1007
+ "crop_audit": crop_report,
1008
+ }
1009
+ )
1010
+ v3.v2.write_json(metadata_path, metadata)
1011
+
1012
+
1013
+ def _masked_detail_metrics(
1014
+ frame_bgr: np.ndarray,
1015
+ mask: np.ndarray,
1016
+ ) -> tuple[float, float, float, float]:
1017
+ low = cv2.resize(
1018
+ frame_bgr,
1019
+ (PARENT_WIDTH, PARENT_HEIGHT),
1020
+ interpolation=cv2.INTER_AREA,
1021
+ )
1022
+ baseline = cv2.resize(
1023
+ low,
1024
+ (TARGET_WIDTH, TARGET_HEIGHT),
1025
+ interpolation=cv2.INTER_LANCZOS4,
1026
+ )
1027
+ native_gray = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2GRAY).astype(np.float32)
1028
+ baseline_gray = cv2.cvtColor(baseline, cv2.COLOR_BGR2GRAY).astype(np.float32)
1029
+ core = cv2.erode(
1030
+ (mask > 0).astype(np.uint8),
1031
+ np.ones((7, 7), dtype=np.uint8),
1032
+ iterations=1,
1033
+ ) > 0
1034
+ if int(core.sum()) < 500:
1035
+ core = mask > 0
1036
+ native_laplacian = cv2.Laplacian(native_gray, cv2.CV_32F)
1037
+ baseline_laplacian = cv2.Laplacian(baseline_gray, cv2.CV_32F)
1038
+ native_high = native_gray - cv2.GaussianBlur(native_gray, (0, 0), 1.2)
1039
+ baseline_high = baseline_gray - cv2.GaussianBlur(baseline_gray, (0, 0), 1.2)
1040
+ native_laplacian_variance = float(native_laplacian[core].var())
1041
+ baseline_laplacian_variance = float(baseline_laplacian[core].var())
1042
+ native_high_rms = float(np.sqrt(np.mean(native_high[core] ** 2)))
1043
+ baseline_high_rms = float(np.sqrt(np.mean(baseline_high[core] ** 2)))
1044
+ return (
1045
+ native_laplacian_variance,
1046
+ baseline_laplacian_variance,
1047
+ native_high_rms,
1048
+ baseline_high_rms,
1049
+ )
1050
+
1051
+
1052
+ def save_resolution_audit(
1053
+ out_dir: Path,
1054
+ config: dict[str, Any],
1055
+ ) -> dict[str, Any]:
1056
+ native = cv2.imread(str(out_dir / NATIVE_CLEAN_NAME))
1057
+ parent = cv2.imread(str(PARENT_WIDE))
1058
+ publication = cv2.imread(str(out_dir / f"{OUTPUT_STEM}_clean.png"))
1059
+ if native is None or parent is None or publication is None:
1060
+ raise RuntimeError("Missing v8/v9 raster for resolution audit")
1061
+ native_down = cv2.resize(
1062
+ native,
1063
+ (PARENT_WIDTH, PARENT_HEIGHT - PARENT_HEIGHT // 3),
1064
+ interpolation=cv2.INTER_AREA,
1065
+ )
1066
+ full_composite_mae = float(
1067
+ np.mean(np.abs(native_down.astype(np.float32) - parent.astype(np.float32)))
1068
+ )
1069
+ full_composite_psnr = _psnr(native_down, parent)
1070
+
1071
+ detail_rows = []
1072
+ for pose in v5._POSES_V5:
1073
+ native_lap, baseline_lap, native_high, baseline_high = _masked_detail_metrics(
1074
+ pose.frame_bgr,
1075
+ pose.refined_mask,
1076
+ )
1077
+ detail_rows.append(
1078
+ {
1079
+ "time_s": pose.time,
1080
+ "native_laplacian_variance": round(native_lap, 6),
1081
+ "v8_grid_baseline_laplacian_variance": round(baseline_lap, 6),
1082
+ "laplacian_variance_ratio": round(
1083
+ native_lap / baseline_lap,
1084
+ 6,
1085
+ )
1086
+ if baseline_lap
1087
+ else 1.0,
1088
+ "native_high_frequency_rms": round(native_high, 6),
1089
+ "v8_grid_baseline_high_frequency_rms": round(
1090
+ baseline_high,
1091
+ 6,
1092
+ ),
1093
+ "high_frequency_rms_ratio": round(
1094
+ native_high / baseline_high,
1095
+ 6,
1096
+ )
1097
+ if baseline_high
1098
+ else 1.0,
1099
+ }
1100
+ )
1101
+ high_ratios = [
1102
+ float(row["high_frequency_rms_ratio"]) for row in detail_rows
1103
+ ]
1104
+ laplacian_ratios = [
1105
+ float(row["laplacian_variance_ratio"]) for row in detail_rows
1106
+ ]
1107
+ metadata = v3.v2.load_json(out_dir / "run_metadata.json")
1108
+ video_metadata = metadata["video_metadata"]
1109
+ report = {
1110
+ "source_video_codec_note": "H.264 8-bit source; no method can recover detail absent from the source",
1111
+ "source_video_size_px": [
1112
+ int(video_metadata["source_width"]),
1113
+ int(video_metadata["source_height"]),
1114
+ ],
1115
+ "v8_full_render_size_px": [PARENT_WIDTH, PARENT_HEIGHT],
1116
+ "v9_full_render_size_px": [TARGET_WIDTH, TARGET_HEIGHT],
1117
+ "v8_wide_native_size_px": list(parent.shape[1::-1]),
1118
+ "v9_wide_native_size_px": list(native.shape[1::-1]),
1119
+ "v9_publication_png_size_px": list(publication.shape[1::-1]),
1120
+ "linear_resolution_gain": GRID_SCALE,
1121
+ "pixel_count_gain": GRID_SCALE**2,
1122
+ "publication_png_dpi": int(config["png_dpi"]),
1123
+ "native_clean_file": NATIVE_CLEAN_NAME,
1124
+ "generative_super_resolution_used": False,
1125
+ "artificial_sharpening_used": False,
1126
+ "v9_downsampled_vs_v8_composite_mae": round(full_composite_mae, 6),
1127
+ "v9_downsampled_vs_v8_composite_psnr_db": round(
1128
+ full_composite_psnr,
1129
+ 4,
1130
+ ),
1131
+ "median_native_high_frequency_gain": round(
1132
+ float(np.median(high_ratios)),
1133
+ 6,
1134
+ ),
1135
+ "minimum_native_high_frequency_gain": round(
1136
+ min(high_ratios),
1137
+ 6,
1138
+ ),
1139
+ "median_native_laplacian_variance_gain": round(
1140
+ float(np.median(laplacian_ratios)),
1141
+ 6,
1142
+ ),
1143
+ "per_pose_source_detail": detail_rows,
1144
+ }
1145
+ report["pass"] = bool(
1146
+ report["source_video_size_px"] == [TARGET_WIDTH, TARGET_HEIGHT]
1147
+ and report["v9_full_render_size_px"] == [TARGET_WIDTH, TARGET_HEIGHT]
1148
+ and report["v9_wide_native_size_px"] == [
1149
+ TARGET_WIDTH,
1150
+ TARGET_HEIGHT - TARGET_HEIGHT // 3,
1151
+ ]
1152
+ and report["linear_resolution_gain"] == 1.5
1153
+ and report["pixel_count_gain"] == 2.25
1154
+ and float(report["median_native_high_frequency_gain"]) >= 1.05
1155
+ and not report["generative_super_resolution_used"]
1156
+ and not report["artificial_sharpening_used"]
1157
+ )
1158
+ if not report["pass"]:
1159
+ raise RuntimeError("V9 native-resolution detail audit failed")
1160
+ v3.v2.write_json(out_dir / "resolution_metrics.json", report)
1161
+ metadata["resolution_audit"] = report
1162
+ v3.v2.write_json(out_dir / "run_metadata.json", metadata)
1163
+ return report
1164
+
1165
+
1166
+ def install_v9_hooks() -> None:
1167
+ v8.install_v8_hooks()
1168
+ v3.validate_config = validate_config_v9
1169
+ v3.save_publication_figure = defer_intermediate_publication
1170
+ v5.load_v4_segmentation_cache = load_native_segmentation_cache
1171
+ v5.copy_reused_segmentation_artifacts = copy_scaled_segmentation_artifacts
1172
+ v5.export_final_publication_outputs = defer_intermediate_publication
1173
+
1174
+ v6.DEFAULT_CONFIG = DEFAULT_CONFIG
1175
+ v6.DEFAULT_OUT = DEFAULT_OUT
1176
+ v6.PARENT_CONFIG = PARENT_CONFIG
1177
+ v6.PARENT_OUT = PARENT_OUT
1178
+ v6.PARENT_ANNOTATED = PARENT_ANNOTATED
1179
+ v6.OUTPUT_STEM = OUTPUT_STEM
1180
+ v6.parse_args = parse_args
1181
+ v6.render_layout_v6 = v8.render_layout_v8
1182
+ v6.save_v5_v6_comparison = v7.defer_comparison
1183
+ v6.save_occlusion_audit = save_occlusion_audit
1184
+ v6.save_layout_change_audit = save_layout_change_audit
1185
+ v6.save_reuse_audit = save_reuse_audit
1186
+ v6.update_run_metadata = update_run_metadata
1187
+
1188
+ v7.DEFAULT_CONFIG = DEFAULT_CONFIG
1189
+ v7.DEFAULT_OUT = DEFAULT_OUT
1190
+ v7.PARENT_CONFIG = PARENT_CONFIG
1191
+ v7.PARENT_OUT = PARENT_OUT
1192
+ v7.PARENT_CLEAN = PARENT_CLEAN
1193
+ v7.PARENT_ANNOTATED = PARENT_ANNOTATED
1194
+ v7.OUTPUT_STEM = OUTPUT_STEM
1195
+ v7.FINAL_WIDTH_MM = FINAL_WIDTH_MM
1196
+ v7.PNG_DPI = PNG_DPI
1197
+ v7.TIFF_DPI = TIFF_DPI
1198
+
1199
+
1200
+ def main() -> int:
1201
+ args = parse_args()
1202
+ config = v3.v2.load_json(args.config.expanduser().resolve())
1203
+ v8.configure_colour_style(config)
1204
+ install_v9_hooks()
1205
+ return_code = v6.main()
1206
+ if return_code:
1207
+ return return_code
1208
+ out_dir = args.out_dir.expanduser().resolve()
1209
+ occlusion = v3.v2.load_json(out_dir / "occlusion_metrics.json")
1210
+ postprocess_wide_outputs(out_dir, config, occlusion)
1211
+ resolution = save_resolution_audit(out_dir, config)
1212
+ print(
1213
+ "Wrote v9 native-4K outputs to "
1214
+ f"{out_dir} (detail gain median {resolution['median_native_high_frequency_gain']}x)"
1215
+ )
1216
+ return 0
1217
+
1218
+
1219
+ if __name__ == "__main__":
1220
+ raise SystemExit(main())