adaspun 0.1.0__tar.gz

adaspun-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Added ADASPUN local research package scaffold.
+- Added native detector/depth/tracking/risk/QUBO modules.
+- Added robust V9 source-of-truth CLI bridge: adaspun-v9-robust.

adaspun-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+title: "ADASPUN: A Research Package for NeuroSentinel-4D++ ADAS Risk Perception"
+message: "If you use this software, please cite it."
+type: software
+authors:
+  - family-names: "T"
+    given-names: "Puneeth"
+version: "0.1.0"
+date-released: "2026-06-16"
+license: "TBD"

adaspun-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+Research License Placeholder
+
+Local research and academic experimentation only.
+Replace before public release.
+No warranty. Not certified for safety-critical deployment.

adaspun-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CITATION.cff
+include CHANGELOG.md
+recursive-include configs *.yaml *.yml *.json
+recursive-include examples *.yaml *.yml *.json *.md
+recursive-include tests *.py

adaspun-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: adaspun
+Version: 0.1.0
+Summary: Camera-based ADAS perception-to-risk calibration toolkit for monocular and stereo pipelines.
+Author: T, Puneeth
+Keywords: ADAS,computer vision,stereo vision,conformal prediction,risk calibration,QUBO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: opencv-python
+Requires-Dist: pyyaml
+Requires-Dist: tqdm
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Requires-Dist: pillow
+Provides-Extra: yolo
+Requires-Dist: ultralytics; extra == "yolo"
+Requires-Dist: torch; extra == "yolo"
+Provides-Extra: clip
+Requires-Dist: open_clip_torch; extra == "clip"
+Provides-Extra: quantum
+Requires-Dist: qiskit; extra == "quantum"
+Requires-Dist: qiskit-aer; extra == "quantum"
+Provides-Extra: crypto
+Requires-Dist: cryptography; extra == "crypto"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Dynamic: license-file
+
+# ADASPUN
+
+ADASPUN is a local research package for the NeuroSentinel-4D++ ADAS pipeline.
+
+Recommended paper/demo command:
+adaspun-v9-robust --cuda --copy-output D:\Puneeth_Adas\outputs\adaspun_phase7a_v9_robust\adaspun_v9_robust.mp4
+
+Development commands:
+adaspun-native-video
+adaspun-risk-smoke
+adaspun-qubo-smoke
+
+This package is currently for local research use. Public PyPI release requires removing hardcoded paths and finalizing licensing.

adaspun-0.1.0/README.md

@@ -0,0 +1,13 @@
+# ADASPUN
+
+ADASPUN is a local research package for the NeuroSentinel-4D++ ADAS pipeline.
+
+Recommended paper/demo command:
+adaspun-v9-robust --cuda --copy-output D:\Puneeth_Adas\outputs\adaspun_phase7a_v9_robust\adaspun_v9_robust.mp4
+
+Development commands:
+adaspun-native-video
+adaspun-risk-smoke
+adaspun-qubo-smoke
+
+This package is currently for local research use. Public PyPI release requires removing hardcoded paths and finalizing licensing.

adaspun-0.1.0/configs/kaggle_stereo_v9.yaml

@@ -0,0 +1,58 @@
+mode: stereo
+
+video:
+  left: "D:/Puneeth_Adas/videos/left.mp4"
+  right: "D:/Puneeth_Adas/videos/right.mp4"
+  output: "D:/Puneeth_Adas/output_adaspun_v9_package.mp4"
+  canvas_width: 1920
+  canvas_height: 720
+
+detectors:
+  primary: "D:/Puneeth_Adas/runs/idd_finetune/yolov8m_idd_stage2_unfreeze/weights/best.pt"
+  ensemble:
+    - "D:/Puneeth_Adas/runs/idd_finetune/yolov8s_idd_stage2_Ddrive_continue/weights/best.pt"
+    - "D:/Puneeth_Adas/runs/idd_finetune/yolov8x_idd_stage1_freeze10_512_batch4/weights/best.pt"
+  confidence: 0.25
+  iou: 0.50
+  fusion: "nms"
+
+depth:
+  mode: "stereo"
+  stereo_method: "sgbm"
+  fx: 721.5
+  baseline_m: 0.54
+  min_depth_m: 1.0
+  max_depth_m: 80.0
+  fallback: "mono_proxy"
+
+risk:
+  crc_threshold_file: "D:/Puneeth_Adas/outputs/experiments/neurosentinel_crc_auto_balanced_labels/crc_human_threshold.json"
+  lambda_star: 0.61
+  epsilon: 0.05
+  alert_fraction: 0.60
+  conformal_q: 6.8465
+  ego_lane_x_min: 0.40
+  ego_lane_x_max: 0.60
+
+qubo:
+  enabled: true
+  budget: 5
+  overlap_penalty: 0.30
+
+riskfield:
+  enabled: true
+  type: "ddpm"
+  model_path: "D:/Puneeth_Adas/outputs/experiments/neurosentinel_diffusion_risk_field_model/diffusion_risk_field_ddpm.pt"
+  timesteps: 100
+  sample_steps: 20
+
+ui:
+  style: "v9_clean"
+  show_distance_labels: true
+  show_bev: true
+  show_tpv: true
+  show_depth_panel: true
+
+audit:
+  enabled: false
+  output_jsonl: "D:/Puneeth_Adas/outputs/audit/adaspun_hash_chain.jsonl"

adaspun-0.1.0/configs/kaggle_stereo_v9_recall.yaml

@@ -0,0 +1,58 @@
+mode: stereo
+
+video:
+  left: "D:/Puneeth_Adas/videos/left.mp4"
+  right: "D:/Puneeth_Adas/videos/right.mp4"
+  output: "D:/Puneeth_Adas/output_adaspun_v9_package.mp4"
+  canvas_width: 1920
+  canvas_height: 720
+
+detectors:
+  primary: "D:/Puneeth_Adas/runs/idd_finetune/yolov8m_idd_stage2_unfreeze/weights/best.pt"
+  ensemble:
+    - "D:/Puneeth_Adas/runs/idd_finetune/yolov8s_idd_stage2_Ddrive_continue/weights/best.pt"
+    - "D:/Puneeth_Adas/runs/idd_finetune/yolov8x_idd_stage1_freeze10_512_batch4/weights/best.pt"
+  confidence: 0.15
+  iou: 0.50
+  fusion: "nms"
+
+depth:
+  mode: "stereo"
+  stereo_method: "sgbm"
+  fx: 721.5
+  baseline_m: 0.54
+  min_depth_m: 1.0
+  max_depth_m: 80.0
+  fallback: "mono_proxy"
+
+risk:
+  crc_threshold_file: "D:/Puneeth_Adas/outputs/experiments/neurosentinel_crc_auto_balanced_labels/crc_human_threshold.json"
+  lambda_star: 0.61
+  epsilon: 0.05
+  alert_fraction: 0.60
+  conformal_q: 6.8465
+  ego_lane_x_min: 0.40
+  ego_lane_x_max: 0.60
+
+qubo:
+  enabled: true
+  budget: 5
+  overlap_penalty: 0.30
+
+riskfield:
+  enabled: true
+  type: "ddpm"
+  model_path: "D:/Puneeth_Adas/outputs/experiments/neurosentinel_diffusion_risk_field_model/diffusion_risk_field_ddpm.pt"
+  timesteps: 100
+  sample_steps: 20
+
+ui:
+  style: "v9_clean"
+  show_distance_labels: true
+  show_bev: true
+  show_tpv: true
+  show_depth_panel: true
+
+audit:
+  enabled: false
+  output_jsonl: "D:/Puneeth_Adas/outputs/audit/adaspun_hash_chain.jsonl"

adaspun-0.1.0/examples/configs/local_kaggle_stereo_v9.example.yaml

@@ -0,0 +1,21 @@
+mode: stereo
+video:
+  left: D:/Puneeth_Adas/videos/left.mp4
+  right: D:/Puneeth_Adas/videos/right.mp4
+perception:
+  backend: yolo
+  fusion: nms
+  confidence: 0.15
+  iou: 0.55
+  max_det: 300
+depth:
+  fx: 721.5
+  baseline_m: 0.54
+  min_depth_m: 1.0
+  max_depth_m: 80.0
+risk:
+  lambda_star: 0.61
+  ego_lane_x_min: 0.40
+  ego_lane_x_max: 0.60
+qubo:
+  budget: 5

adaspun-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adaspun"
+version = "0.1.0"
+description = "Camera-based ADAS perception-to-risk calibration toolkit for monocular and stereo pipelines."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "T, Puneeth" }]
+keywords = ["ADAS", "computer vision", "stereo vision", "conformal prediction", "risk calibration", "QUBO"]
+dependencies = [
+  "numpy",
+  "pandas",
+  "opencv-python",
+  "pyyaml",
+  "tqdm",
+  "scipy",
+  "scikit-learn",
+  "matplotlib",
+  "pillow"
+]
+
+[project.optional-dependencies]
+yolo = ["ultralytics", "torch"]
+clip = ["open_clip_torch"]
+quantum = ["qiskit", "qiskit-aer"]
+crypto = ["cryptography"]
+dev = ["pytest", "ruff", "black"]
+
+[project.scripts]
+adaspun-video = "adaspun.cli.run_video:main"
+adaspun-make-stereo-video = "adaspun.cli.make_stereo_video:main"
+adaspun-calibrate = "adaspun.cli.calibrate:main"
+adaspun-qubo = "adaspun.cli.run_qubo:main"
+adaspun-clip-anomaly = "adaspun.cli.run_clip:main"
+adaspun-audit-verify = "adaspun.cli.audit_verify:main"
+adaspun-detect-frame = "adaspun.cli.detect_frame:main"
+adaspun-detect-depth-frame = "adaspun.cli.detect_depth_frame:main"
+adaspun-track-ttc-smoke = "adaspun.cli.track_ttc_smoke:main"
+adaspun-risk-smoke = "adaspun.cli.risk_smoke:main"
+adaspun-qubo-smoke = "adaspun.cli.qubo_smoke:main"
+adaspun-native-video = "adaspun.cli.native_video:main"
+adaspun-v9-robust = "adaspun.cli.v9_robust:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

adaspun-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adaspun-0.1.0/src/adaspun/__init__.py

@@ -0,0 +1,3 @@
+"""ADASPUN: camera-based ADAS perception-to-risk calibration toolkit."""
+
+__version__ = "0.1.0"

adaspun-0.1.0/src/adaspun/audit/hash_chain.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+
+class HashChainAuditLogger:
+    """Tamper-evident JSONL hash-chain logger for frame-level ADAS decisions."""
+
+    def __init__(self, output_jsonl: str | Path):
+        self.output_jsonl = Path(output_jsonl)
+        self.output_jsonl.parent.mkdir(parents=True, exist_ok=True)
+        self.previous_hash = "GENESIS"
+
+    def append(self, record: Dict[str, Any]) -> str:
+        payload = dict(record)
+        payload["previous_hash"] = self.previous_hash
+        canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+        current_hash = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+        payload["current_hash"] = current_hash
+        with self.output_jsonl.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(payload, sort_keys=True) + "
+")
+        self.previous_hash = current_hash
+        return current_hash

adaspun-0.1.0/src/adaspun/cli/audit_verify.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+import argparse
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="ADASPUN audit verification CLI scaffold.")
+    ap.add_argument("--config", required=False, help="Path to YAML config.")
+    ap.add_argument("--log", required=False, help="Path to audit log if applicable.")
+    args = ap.parse_args()
+    print("ADASPUN audit verification scaffold ready. Migrate project logic into this CLI.")
+    print(args)
+
+
+if __name__ == "__main__":
+    main()

adaspun-0.1.0/src/adaspun/cli/calibrate.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+import argparse
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="ADASPUN C3RC calibration CLI scaffold.")
+    ap.add_argument("--config", required=False, help="Path to YAML config.")
+    ap.add_argument("--log", required=False, help="Path to audit log if applicable.")
+    args = ap.parse_args()
+    print("ADASPUN C3RC calibration scaffold ready. Migrate project logic into this CLI.")
+    print(args)
+
+
+if __name__ == "__main__":
+    main()

adaspun-0.1.0/src/adaspun/cli/detect_depth_frame.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import cv2
+import pandas as pd
+
+from adaspun.config import load_config
+from adaspun.perception.ensemble import DetectorEnsemble
+from adaspun.depth.sgbm import SGBMDepthEstimator
+from adaspun.depth.object_depth import extract_depths_for_detections
+from adaspun.visualization.depth_overlays import depth_to_heatmap, draw_detections_with_depth
+
+
+def _read_frame(video_path: str, frame_index: int):
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Could not open video: {video_path}")
+    cap.set(cv2.CAP_PROP_POS_FRAMES, int(frame_index))
+    ok, frame = cap.read()
+    cap.release()
+    if not ok:
+        raise RuntimeError(f"Could not read frame {frame_index} from {video_path}")
+    return frame
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="ADASPUN Phase-2 native detector + stereo object-depth smoke test.")
+    ap.add_argument("--config", required=True, help="Path to ADASPUN YAML config.")
+    ap.add_argument("--frame-index", type=int, default=25)
+    ap.add_argument("--output-dir", default="D:/Puneeth_Adas/outputs/adaspun_phase2_depth_smoke")
+    args = ap.parse_args()
+
+    cfg = load_config(args.config)
+    mode = cfg.get("mode", "stereo")
+    if mode != "stereo":
+        raise ValueError("Phase-2 smoke test expects mode: stereo with video.left and video.right.")
+
+    out_dir = Path(args.output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    video_cfg = cfg.get("video", {})
+    left_path = video_cfg.get("left")
+    right_path = video_cfg.get("right")
+    if not left_path or not right_path:
+        raise ValueError("Config must provide video.left and video.right for stereo depth smoke test.")
+
+    left = _read_frame(left_path, args.frame_index)
+    right = _read_frame(right_path, args.frame_index)
+    if right.shape[:2] != left.shape[:2]:
+        right = cv2.resize(right, (left.shape[1], left.shape[0]))
+
+    detector = DetectorEnsemble.from_config(cfg)
+    detections = detector.predict(left)
+
+    depth_cfg = cfg.get("depth", {})
+    estimator = SGBMDepthEstimator(
+        fx=float(depth_cfg.get("fx", 721.5)),
+        baseline_m=float(depth_cfg.get("baseline_m", 0.54)),
+        min_depth_m=float(depth_cfg.get("min_depth_m", 1.0)),
+        max_depth_m=float(depth_cfg.get("max_depth_m", 80.0)),
+    )
+    depth_map = estimator.compute(left, right)
+    depth_items = extract_depths_for_detections(
+        depth_map,
+        detections,
+        left.shape,
+        fallback=str(depth_cfg.get("fallback", "mono_proxy")),
+        min_depth_m=float(depth_cfg.get("min_depth_m", 1.0)),
+        max_depth_m=float(depth_cfg.get("max_depth_m", 80.0)),
+    )
+
+    annotated = draw_detections_with_depth(left, depth_items)
+    heat = depth_to_heatmap(depth_map, min_depth_m=float(depth_cfg.get("min_depth_m", 1.0)), max_depth_m=float(depth_cfg.get("max_depth_m", 80.0)))
+    blended = cv2.addWeighted(left, 0.55, heat, 0.45, 0)
+
+    out_annotated = out_dir / f"adaspun_depth_frame_{args.frame_index:06d}.jpg"
+    out_heat = out_dir / f"adaspun_depth_heatmap_{args.frame_index:06d}.jpg"
+    out_blend = out_dir / f"adaspun_depth_blend_{args.frame_index:06d}.jpg"
+    out_csv = out_dir / f"adaspun_depth_frame_{args.frame_index:06d}.csv"
+    out_json = out_dir / f"adaspun_depth_frame_{args.frame_index:06d}.json"
+
+    cv2.imwrite(str(out_annotated), annotated)
+    cv2.imwrite(str(out_heat), heat)
+    cv2.imwrite(str(out_blend), blended)
+
+    rows = []
+    for item in depth_items:
+        d = item.detection
+        rows.append({
+            "frame_index": args.frame_index,
+            "left_video": str(left_path),
+            "right_video": str(right_path),
+            "class_id": d.class_id,
+            "class_name": d.class_name,
+            "confidence": d.confidence,
+            "x1": d.bbox[0], "y1": d.bbox[1], "x2": d.bbox[2], "y2": d.bbox[3],
+            "source_model": d.source_model,
+            "distance_m": item.distance_m,
+            "depth_source": item.depth_source,
+            "stereo_valid": item.valid,
+            "valid_ratio": item.valid_ratio,
+            "depth_p25_m": item.depth_p25_m,
+            "depth_p50_m": item.depth_p50_m,
+            "depth_p75_m": item.depth_p75_m,
+        })
+    pd.DataFrame(rows).to_csv(out_csv, index=False)
+    out_json.write_text(json.dumps({"frame_index": args.frame_index, "objects": rows}, indent=2), encoding="utf-8")
+
+    stereo_valid_count = sum(1 for x in depth_items if x.depth_source == "stereo_sgbm")
+    fallback_count = sum(1 for x in depth_items if x.depth_source != "stereo_sgbm")
+
+    print("[ADASPUN] Phase-2 detector+depth smoke test complete")
+    print(f"[ADASPUN] Detections: {len(detections)}")
+    print(f"[ADASPUN] Stereo-valid object depths: {stereo_valid_count}")
+    print(f"[ADASPUN] Fallback object depths: {fallback_count}")
+    print(f"[ADASPUN] Annotated frame: {out_annotated}")
+    print(f"[ADASPUN] Depth heatmap: {out_heat}")
+    print(f"[ADASPUN] Depth blend: {out_blend}")
+    print(f"[ADASPUN] CSV: {out_csv}")
+    print(f"[ADASPUN] JSON: {out_json}")
+
+
+if __name__ == "__main__":
+    main()

adaspun-0.1.0/src/adaspun/cli/detect_frame.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import cv2
+import pandas as pd
+
+from adaspun.config import load_config
+from adaspun.perception.ensemble import DetectorEnsemble
+from adaspun.visualization.overlays import draw_detections
+
+
+def _open_frame_from_config(cfg: dict, frame_index: int):
+    mode = cfg.get("mode", "monocular")
+    video_cfg = cfg.get("video", {})
+    path = video_cfg.get("left") if mode == "stereo" else video_cfg.get("input")
+    if not path:
+        raise ValueError("Config must provide video.left for stereo or video.input for monocular.")
+    cap = cv2.VideoCapture(str(path))
+    if not cap.isOpened():
+        raise RuntimeError(f"Could not open video: {path}")
+    cap.set(cv2.CAP_PROP_POS_FRAMES, int(frame_index))
+    ok, frame = cap.read()
+    cap.release()
+    if not ok:
+        raise RuntimeError(f"Could not read frame {frame_index} from {path}")
+    return frame, Path(path)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="ADASPUN Phase-1 native detector ensemble one-frame smoke test.")
+    ap.add_argument("--config", required=True, help="Path to ADASPUN YAML config.")
+    ap.add_argument("--frame-index", type=int, default=25)
+    ap.add_argument("--output-dir", default="D:/Puneeth_Adas/outputs/adaspun_phase1_detector_smoke")
+    args = ap.parse_args()
+
+    cfg = load_config(args.config)
+    out_dir = Path(args.output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    frame, video_path = _open_frame_from_config(cfg, args.frame_index)
+    detector = DetectorEnsemble.from_config(cfg)
+    detections = detector.predict(frame)
+
+    annotated = draw_detections(frame, detections)
+    out_img = out_dir / f"adaspun_detector_frame_{args.frame_index:06d}.jpg"
+    out_json = out_dir / f"adaspun_detector_frame_{args.frame_index:06d}.json"
+    out_csv = out_dir / f"adaspun_detector_frame_{args.frame_index:06d}.csv"
+
+    cv2.imwrite(str(out_img), annotated)
+    rows = []
+    for d in detections:
+        rows.append({
+            "frame_index": args.frame_index,
+            "video": str(video_path),
+            "class_id": d.class_id,
+            "class_name": d.class_name,
+            "confidence": d.confidence,
+            "x1": d.bbox[0], "y1": d.bbox[1], "x2": d.bbox[2], "y2": d.bbox[3],
+            "source_model": d.source_model,
+        })
+    pd.DataFrame(rows).to_csv(out_csv, index=False)
+    out_json.write_text(json.dumps({"frame_index": args.frame_index, "video": str(video_path), "detections": rows}, indent=2), encoding="utf-8")
+
+    print("[ADASPUN] Phase-1 detector smoke test complete")
+    print(f"[ADASPUN] Detections: {len(detections)}")
+    print(f"[ADASPUN] Annotated frame: {out_img}")
+    print(f"[ADASPUN] CSV: {out_csv}")
+    print(f"[ADASPUN] JSON: {out_json}")
+
+
+if __name__ == "__main__":
+    main()

adaspun-0.1.0/src/adaspun/cli/make_stereo_video.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import re
+import cv2
+
+IMG_EXTS = {".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff"}
+
+
+def natural_key(p: Path):
+    return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", p.stem)]
+
+
+def list_images(d: Path):
+    return sorted([p for p in d.iterdir() if p.is_file() and p.suffix.lower() in IMG_EXTS], key=natural_key)
+
+
+def make_video(files, out_path: Path, fps: float):
+    first = cv2.imread(str(files[0]))
+    if first is None:
+        raise RuntimeError(f"Could not read {files[0]}")
+    h, w = first.shape[:2]
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    writer = cv2.VideoWriter(str(out_path), cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
+    for i, p in enumerate(files):
+        img = cv2.imread(str(p))
+        if img is None:
+            continue
+        if img.shape[:2] != (h, w):
+            img = cv2.resize(img, (w, h))
+        writer.write(img)
+        if (i + 1) % 100 == 0:
+            print(f"wrote {i+1}/{len(files)} to {out_path.name}")
+    writer.release()
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Create synchronized left/right videos from stereo image folders.")
+    ap.add_argument("--left-dir", required=True)
+    ap.add_argument("--right-dir", required=True)
+    ap.add_argument("--out-left", required=True)
+    ap.add_argument("--out-right", required=True)
+    ap.add_argument("--fps", type=float, default=10.0)
+    args = ap.parse_args()
+
+    lefts = list_images(Path(args.left_dir))
+    rights = list_images(Path(args.right_dir))
+    rb = {p.stem: p for p in rights}
+    pairs = [(l, rb[l.stem]) for l in lefts if l.stem in rb]
+    if not pairs:
+        n = min(len(lefts), len(rights))
+        pairs = list(zip(lefts[:n], rights[:n]))
+    print(f"paired frames: {len(pairs)}")
+    make_video([p[0] for p in pairs], Path(args.out_left), args.fps)
+    make_video([p[1] for p in pairs], Path(args.out_right), args.fps)
+
+
+if __name__ == "__main__":
+    main()