# ╔══════════════════════════════════════════════════════════════════╗
# ║ Rig Conductor — reduce ║
# ║ « crop the recording to the arenas » ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║ Frame-exact re-encode of the Motif store to the arena box, ║
# ║ re-timed to the real camera rate. ║
# ╚══════════════════════════════════════════════════════════════════╝
"""Crop a Motif recording to the arenas ('reduce') to save disk space.
Runs after the cut: every chunk ``NNNNNN.mp4`` of the Motif image store is
re-encoded to the bounding box of all arenas plus a padding, frame for frame
(``-fps_mode passthrough``), so the ``NNNNNN.npz`` frame timestamps stay valid.
A chunk is replaced only after its cropped copy decodes to the same number of
frames. With ``gray`` the colour is dropped too (``format=gray``, still stored
as yuv420p: on a mono camera that changes nothing; a gray pix_fmt file came out
38 % larger in the 2026-11-11 test). ``metadata.yaml`` gets the new
``imgshape`` (the original is kept as
``metadata.full.yaml``) and ``reduced.json`` records the crop offset, so
full-frame coordinates map to the reduced video as ``(x - x0, y - y0)``.
"""
from __future__ import annotations
import json
import shutil
import subprocess
import time
from collections.abc import Callable
from pathlib import Path
import yaml
from rigconductor import ConductorError
from rigconductor.constants import (
FPS_SNAP_TOL,
PROGRESS_EVERY_S,
REDUCE_ALIGN_PX,
REDUCE_CRF,
REDUCE_PADDING_PX,
)
REDUCED_JSON = "reduced.json"
[docs]
def reduce_box(
circles: list[tuple[float, float, float]],
pad: float,
width: int,
height: int,
align: int = REDUCE_ALIGN_PX,
) -> tuple[int, int, int, int]:
"""(x, y, w, h) covering every circle + ``pad`` px, grown to multiples of
``align`` and clamped to the frame."""
if not circles:
raise ConductorError("no arenas to crop to")
x0 = min(cx - r for cx, _, r in circles) - pad
y0 = min(cy - r for _, cy, r in circles) - pad
x1 = max(cx + r for cx, _, r in circles) + pad
y1 = max(cy + r for _, cy, r in circles) + pad
return _box(_aligned(x0, x1, width, align), _aligned(y0, y1, height, align))
def _aligned(lo: float, hi: float, limit: int, align: int) -> tuple[int, int]:
"""Start (even) and size (multiple of ``align``) along one axis covering
[lo, hi], kept inside [0, limit]."""
import math
start = max(0, math.floor(lo))
start -= start % 2
end = min(limit, math.ceil(hi))
size = min(limit - limit % 2, -(-(end - start) // align) * align)
if start + size > limit: # grow towards the other side instead
start = max(0, limit - size)
start -= start % 2
return start, size
def _box(xs: tuple[int, int], ys: tuple[int, int]) -> tuple[int, int, int, int]:
return xs[0], ys[0], xs[1], ys[1]
[docs]
def recorded_fps(rec_dir: Path) -> float | None:
"""Real camera rate: Motif frame timestamps, snapped to the set
``acquisitionframerate`` when within 1 % (jitter like 69.001 gives time bases
MPEG-4 cannot store); else the timestamp rate to 2 decimals, else metadata.
Same rule as ThermoKourt's ``recorded_fps``."""
import numpy as np
measured = None
for npz in sorted(Path(rec_dir).glob("[0-9]" * 6 + ".npz")):
try:
with np.load(npz, allow_pickle=True) as z:
t = np.asarray(z["frame_time"], dtype=float)
if t.size > 10 and np.median(np.diff(t)) > 0:
measured = 1.0 / float(np.median(np.diff(t)))
break
except Exception: # noqa: BLE001 - fall back to metadata
pass
meta = Path(rec_dir) / "metadata.yaml"
nominal = None
if meta.is_file():
v = (yaml.safe_load(meta.read_text(encoding="utf-8")) or {}).get("acquisitionframerate")
nominal = float(v) if v else None
if measured and nominal and abs(measured / nominal - 1) <= FPS_SNAP_TOL:
return nominal
return round(measured, 2) if measured else nominal
def _header_frames(video: Path) -> int:
"""Frame count from the container header (instant; 0 if unknown)."""
r = subprocess.run(
[
"ffprobe",
"-v",
"error",
"-select_streams",
"v:0",
"-show_entries",
"stream=nb_frames",
"-of",
"csv=p=0",
str(video),
],
capture_output=True,
text=True,
)
try:
return int(r.stdout.strip())
except ValueError:
return 0
def _run_ffmpeg_progress(cmd: list[str], on_frame: Callable[[int], None]):
"""Run ffmpeg with ``-progress pipe:1``; ``on_frame(n)`` gets the frame count
as it encodes. Returns (returncode, stderr text)."""
import tempfile
with tempfile.TemporaryFile(mode="w+") as err:
proc = subprocess.Popen(
[*cmd[:-1], "-progress", "pipe:1", "-nostats", cmd[-1]],
stdout=subprocess.PIPE,
stderr=err,
text=True,
)
for line in proc.stdout:
value = line.split("=", 1)[1].strip() if line.startswith("frame=") else ""
if value.isdigit():
on_frame(int(value))
rc = proc.wait()
err.seek(0)
return rc, err.read()
def is_reduced(rec_dir: Path) -> dict | None:
p = Path(rec_dir) / REDUCED_JSON
return json.loads(p.read_text(encoding="utf-8")) if p.is_file() else None
def _frames(path: Path) -> int:
r = subprocess.run(
[
"ffprobe",
"-v",
"error",
"-select_streams",
"v:0",
"-count_packets",
"-show_entries",
"stream=nb_read_packets,width,height",
"-of",
"json",
str(path),
],
capture_output=True,
text=True,
)
if r.returncode != 0:
raise ConductorError(f"ffprobe failed on {path.name}: {r.stderr.strip()[-200:]}")
return int(json.loads(r.stdout)["streams"][0]["nb_read_packets"])
[docs]
def reduce_recording(
rec_dir: Path,
circles: list[tuple[float, float, float]],
padding_px: float = REDUCE_PADDING_PX,
crf: int = REDUCE_CRF,
keep_full: bool = False,
gray: bool = False,
log: Callable[[str], None] = print,
) -> dict:
"""Crop every chunk of the Motif store in ``rec_dir``; returns the reduced.json dict."""
rec_dir = Path(rec_dir)
done = is_reduced(rec_dir)
if done:
log(f"reduce: already cropped to {done['w']}×{done['h']}")
return done
meta_p = rec_dir / "metadata.yaml"
meta = yaml.safe_load(meta_p.read_text(encoding="utf-8"))
h_full, w_full = (int(v) for v in meta["__store"]["imgshape"][:2])
x, y, w, h = reduce_box(circles, padding_px, w_full, h_full)
chunks = sorted(p for p in rec_dir.glob("[0-9]" * 6 + ".mp4"))
if not chunks:
raise ConductorError(f"no Motif video chunks in {rec_dir}")
before = sum(c.stat().st_size for c in chunks)
log(
f"reduce: {w_full}×{h_full} → {w}×{h} at ({x}, {y}), padding {padding_px:g} px, "
f"{len(chunks)} chunk(s), {before / 1e6:.0f} MB"
)
fps = recorded_fps(rec_dir)
rate = ["-r", f"{fps:g}"] if fps else [] # input option: re-time at the real rate
full_dir = rec_dir / "full_frame"
after = 0
frames = [_header_frames(c) for c in chunks]
total = sum(frames) or 1
done_before = 0
last = [0.0]
def report(n: int, chunk_name: str):
now = time.monotonic()
if now - last[0] >= PROGRESS_EVERY_S:
frac = min(1.0, (done_before + n) / total)
log(f"@progress reduce {frac:.4f} {chunk_name}: frame {n} of {total}")
last[0] = now
for k, c in enumerate(chunks):
tmp = c.with_name(c.stem + ".reduced.mp4")
cmd = [
"ffmpeg",
"-nostdin",
"-hide_banner",
"-loglevel",
"error",
"-y",
*rate,
"-i",
str(c),
"-vf",
f"crop={w}:{h}:{x}:{y}" + (",format=gray" if gray else ""),
"-fps_mode",
"passthrough",
"-c:v",
"libx264",
"-preset",
"veryfast",
"-crf",
str(crf),
"-pix_fmt",
"yuv420p",
"-an",
str(tmp),
]
rc, err = _run_ffmpeg_progress(cmd, lambda n, name=c.name: report(n, name))
if rc != 0 and "fps_mode" in err: # ffmpeg < 5.1
i = cmd.index("-fps_mode")
cmd[i : i + 2] = ["-vsync", "passthrough"]
rc, err = _run_ffmpeg_progress(cmd, lambda n, name=c.name: report(n, name))
if rc != 0:
tmp.unlink(missing_ok=True)
raise ConductorError(f"reduce: ffmpeg failed on {c.name}: {err.strip()[-300:]}")
done_before += frames[k]
log(
f"@progress reduce {min(1.0, done_before / total):.4f} checking {c.name} frame by frame"
)
n_in, n_out = _frames(c), _frames(tmp)
if n_in != n_out:
tmp.unlink(missing_ok=True)
raise ConductorError(
f"reduce: {c.name} has {n_in} frames but the crop has {n_out}; original kept"
)
if keep_full:
full_dir.mkdir(exist_ok=True)
shutil.move(str(c), full_dir / c.name)
tmp.replace(c)
after += c.stat().st_size
log(f"reduce: {c.name} ok ({n_out} frames)")
if not (rec_dir / "metadata.full.yaml").exists():
shutil.copy2(meta_p, rec_dir / "metadata.full.yaml")
meta["__store"]["imgshape"] = [h, w, *meta["__store"]["imgshape"][2:]]
meta["conductor_reduced"] = {"x": x, "y": y, "w": w, "h": h, "padding_px": padding_px}
meta_p.write_text(yaml.safe_dump(meta, sort_keys=False), encoding="utf-8")
info = {
"x": x,
"y": y,
"w": w,
"h": h,
"full_width": w_full,
"full_height": h_full,
"padding_px": padding_px,
"gray": bool(gray),
"fps": fps,
"crf": crf,
"bytes_before": before,
"bytes_after": after,
"full_frame_kept": bool(keep_full),
}
(rec_dir / REDUCED_JSON).write_text(json.dumps(info, indent=2), encoding="utf-8")
log(
f"reduce: {before / 1e6:.0f} MB → {after / 1e6:.0f} MB "
f"({100 * (1 - after / before):.0f} % saved)"
+ (f"; full-frame originals kept in {full_dir}" if keep_full else "")
)
return info