Niall’s virtual diary archives – Friday 3 July 2026

#!/usr/bin/env python3
"""make_timelapse.py — Aligned AV1/H.264/H.265 timelapse from DJI aerial JPEGs."""

from __future__ import annotations

import argparse
import math
import os
import subprocess
import sys
from concurrent.futures import ThreadPoolExecutor
from typing import NamedTuple

import cv2
import numpy as np


# ── Linearization (sRGB inverse EOTF) ─────────────────────────────────────


def srgb_to_linear(val: np.ndarray) -> np.ndarray:
    val = val.astype(np.float32) / 255.0
    lo = val <= 0.04045
    hi = ~lo
    out = np.empty_like(val, dtype=np.float32)
    out[lo] = val[lo] / 12.92
    out[hi] = ((val[hi] + 0.055) / 1.055) ** 2.4
    return out


def linear_to_srgb(val: np.ndarray) -> np.ndarray:
    lo = val <= 0.0031308
    hi = ~lo
    out = np.empty_like(val, dtype=np.float32)
    out[lo] = 12.92 * val[lo]
    out[hi] = 1.055 * (val[hi] ** (1.0 / 2.4)) - 0.055
    return np.clip(out * 255.0, 0, 255).astype(np.uint8)


# ── Data structures ────────────────────────────────────────────────────────


class FrameResult(NamedTuple):
    filename: str
    index: int  # 0-based source index
    M: np.ndarray | None  # 2x3 similarity matrix (src→ref), None if skipped
    inliers: int  # RANSAC inlier count
    total_matches: int
    skipped: bool
    skip_reason: str
    warp_bgr: np.ndarray | None  # uint8 BGR after warp
    valid_rect: tuple[int, int, int, int] | None  # (x0, y0, x1, y1) in ref space
    crop_rect: tuple[int, int, int, int] | None  # same


class TimelapseState:
    def __init__(self) -> None:
        self.last_output_bgr: np.ndarray | None = None


# ── ORB matching (uint8 BGR grayscale) ─────────────────────────────────────


def match_to_reference(
    ref_gray: np.ndarray,
    curr_gray: np.ndarray,
    fringe_mask: np.ndarray | None,
) -> tuple[np.ndarray | None, int, int]:
    """Return (M, inliers, total_good_matches). M=None if insufficient matches."""
    orb = cv2.ORB_create(nfeatures=2000, fastThreshold=5)
    bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)

    kp_ref, des_ref = orb.detectAndCompute(ref_gray, None)
    kp_curr, des_curr = orb.detectAndCompute(curr_gray, None)
    if des_ref is None or des_curr is None or len(kp_ref) < 4 or len(kp_curr) < 4:
        return None, 0, 0

    raw_matches = bf.knnMatch(des_ref, des_curr, k=2)
    good = []
    for pair in raw_matches:
        if len(pair) == 2:
            m, n = pair
            if m.distance < 0.75 * n.distance:
                good.append(m)

    if len(good) < 4:
        return None, len(good), len(good)

    src_pts = np.float32([kp_curr[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
    dst_pts = np.float32([kp_ref[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)

    if fringe_mask is not None:
        h, w = curr_gray.shape
        y0, y1 = int(0.30 * h), int(0.70 * h)
        x0, x1 = int(0.30 * w), int(0.70 * w)

        def in_fringe(pts: np.ndarray) -> np.ndarray:
            x = pts[:, 0, 0]
            y = pts[:, 0, 1]
            return ~((y0 <= y) & (y < y1) & (x0 <= x) & (x < x1))

        fringe_src = in_fringe(src_pts)
        fringe_dst = in_fringe(dst_pts)
        keep = fringe_src & fringe_dst
        src_pts = src_pts[keep]
        dst_pts = dst_pts[keep]

        if src_pts.shape[0] < 4:
            return None, 0, len(good)

    M, inlier_mask = cv2.estimateAffinePartial2D(
        src_pts,
        dst_pts,
        method=cv2.RANSAC,
        ransacReprojThreshold=1.0,
        maxIters=2000,
        confidence=0.99,
        refineIters=10,
    )
    if M is None:
        return None, src_pts.shape[0], len(good)
    inliers = int(inlier_mask.sum()) if inlier_mask is not None else src_pts.shape[0]
    return M, inliers, len(good)


def build_fringe_mask(h: int, w: int) -> np.ndarray | None:
    y0, y1 = int(0.30 * h), int(0.70 * h)
    x0, x1 = int(0.30 * w), int(0.70 * w)
    edge_pixels = (
        y0 * w
        + (h - y1) * w
        + y1 * x0
        + y1 * (w - x1)
    )
    if edge_pixels < 4000:
        return None
    mask = np.zeros((h, w), dtype=np.uint8)
    mask[:y0, :] = 255
    mask[y1:, :] = 255
    mask[y0:y1, :x0] = 255
    mask[y0:y1, x1:] = 255
    return mask


# ── Transform validation ────────────────────────────────────────────────────


def decompose_similarity(M: np.ndarray) -> tuple[float, float, float, float]:
    tx = float(M[0, 2])
    ty = float(M[1, 2])
    s = float(np.sqrt(M[0, 0] ** 2 + M[1, 0] ** 2))
    theta = float(np.degrees(np.arctan2(M[1, 0], M[0, 0])))
    return s, theta, tx, ty


def validate_transform(M: np.ndarray) -> str | None:
    s, theta, _, _ = decompose_similarity(M)
    if not (0.90 <= s <= 1.10):
        return f"scale={s:.4f} outside [0.90, 1.10]"
    if abs(theta) > 5.0:
        return f"rotation={theta:.2f}deg outside ±5°"
    return None


# ── Pass 0: pairwise scoring ────────────────────────────────────────────────


def score_pair(ref_gray: np.ndarray, curr_gray: np.ndarray, fringe_mask: np.ndarray | None) -> float:
    M, inliers, total = match_to_reference(ref_gray, curr_gray, fringe_mask)
    if M is None:
        return float("inf")
    cap_err = validate_transform(M)
    if cap_err:
        return float("inf")
    if inliers < 4:
        return float("inf")
    return 1.0 / (inliers + 1)


def _score_row(
    r: int,
    n: int,
    greys: list[np.ndarray | None],
    fringe_masks: list[np.ndarray | None],
) -> float:
    if greys[r] is None:
        return float("inf")
    total = 0.0
    for j in range(n):
        if j == r or greys[j] is None:
            continue
        total += score_pair(greys[r], greys[j], fringe_masks[j])
    return total


def select_reference_frame(
    files: list[str],
    greys: list[np.ndarray | None],
    fringe_masks: list[np.ndarray | None],
) -> int:
    print("Pass 0: pairwise scoring to select reference frame...", file=sys.stderr)

    n = len(files)
    total_scores: list[float] = [0.0] * n

    workers = min(os.cpu_count() or 1, n)
    with ThreadPoolExecutor(max_workers=workers) as executor:
        futures = {
            executor.submit(_score_row, r, n, greys, fringe_masks): r
            for r in range(n)
        }
        for future in futures:
            r = futures[future]
            total_scores[r] = future.result()

    ref_idx = int(np.argmin(total_scores))
    for i, sc in enumerate(total_scores):
        print(f"  {files[i]}: total_score={sc:.4f}", file=sys.stderr)
    print(f"Selected reference frame: {files[ref_idx]} (index {ref_idx})", file=sys.stderr)
    return ref_idx


# ── Valid-content rect via mask warp ───────────────────────────────────────


def valid_content_rect(M: np.ndarray, h_src: int, w_src: int, h_ref: int, w_ref: int) -> tuple[int, int, int, int]:
    mask_src = np.ones((h_src, w_src), dtype=np.uint8) * 255
    warped_mask = cv2.warpAffine(
        mask_src, M, (w_ref, h_ref), borderMode=cv2.BORDER_CONSTANT, borderValue=0
    )
    ys, xs = np.where(warped_mask > 0)
    if len(xs) == 0:
        return (0, 0, 0, 0)
    return int(xs.min()), int(ys.min()), int(xs.max() + 1), int(ys.max() + 1)


# ── Peripheral annulus mask ────────────────────────────────────────────────


def peripheral_mask(h: int, w: int) -> np.ndarray:
    y_top = int(math.ceil(0.10 * h))
    y_bot = int(math.floor(0.90 * h))
    x_left = int(math.ceil(0.10 * w))
    x_right = int(math.floor(0.90 * w))
    mask = np.zeros((h, w), dtype=bool)
    mask[:y_top, :] = True
    mask[y_bot:, :] = True
    mask[y_top:y_bot, :x_left] = True
    mask[y_top:y_bot, x_right:] = True
    return mask


# ── Brightness correction ──────────────────────────────────────────────────


def compute_gains(
    ref_linear: np.ndarray, frame_linear: np.ndarray, peri_mask: np.ndarray
) -> np.ndarray:
    gains = np.zeros(3, dtype=np.float32)
    for c in range(3):
        r = ref_linear[:, :, c][peri_mask].astype(np.float32)
        f = frame_linear[:, :, c][peri_mask].astype(np.float32)
        denom = (f ** 2).sum()
        if denom < 1e-12:
            gains[c] = 1.0
        else:
            gains[c] = (r * f).sum() / denom
    return gains


def apply_gains(frame: np.ndarray, gains: np.ndarray) -> np.ndarray:
    return frame * gains.astype(np.float32)


# ── Encoding ───────────────────────────────────────────────────────────────

AV1_ARGS = [
    "-c:v", "libsvtav1",
    "-crf", "18",
    "-preset", "5",
    "-pix_fmt", "yuv420p",
    "-color_primaries", "bt709",
    "-color_trc", "bt709",
    "-colorspace", "bt709",
    "-movflags", "+faststart",
]
H264_ARGS = [
    "-c:v", "libx264",
    "-crf", "15",
    "-pix_fmt", "yuv420p",
    "-color_primaries", "bt709",
    "-color_trc", "bt709",
    "-colorspace", "bt709",
]
H265_ARGS = [
    "-c:v", "libx265",
    "-crf", "16",
    "-pix_fmt", "yuv420p",
    "-color_primaries", "bt709",
    "-color_trc", "bt709",
    "-colorspace", "bt709",
]
CODEC_MAP = {"av1": AV1_ARGS, "h264": H264_ARGS, "h265": H265_ARGS}


def check_ffmpeg() -> None:
    try:
        subprocess.run(
            ["ffmpeg", "-version"],
            capture_output=True,
            check=True,
        )
    except (FileNotFoundError, subprocess.CalledProcessError):
        print(
            "ERROR: ffmpeg not found. Install with: brew install ffmpeg",
            file=sys.stderr,
        )
        sys.exit(1)


def check_av1_encoder(requested_av1: bool) -> str | None:
    try:
        result = subprocess.run(
            ["ffmpeg", "-encoders"],
            capture_output=True,
            text=True,
            check=True,
        )
    except (FileNotFoundError, subprocess.CalledProcessError):
        return None
    encoders = result.stdout.lower()
    if "libsvtav1" in encoders:
        return "libsvtav1"
    if requested_av1:
        print(
            "WARNING: libsvtav1 not found in ffmpeg build. "
            "Attempting libaom-av1 fallback (slower).",
            file=sys.stderr,
        )
        if "libaom-av1" in encoders:
            return "libaom-av1"
    return None


def build_ffmpeg_args(
    width: int, height: int, fps: int, output: str, encoder: str | None, codec: str
) -> list[str]:
    if encoder is None:
        print(
            "ERROR: No suitable AV1 encoder found in ffmpeg. "
            "Install with: brew install ffmpeg (includes libsvtav1).",
            file=sys.stderr,
        )
        sys.exit(1)

    args = [
        "ffmpeg",
        "-y",
        "-f", "rawvideo",
        "-pix_fmt", "bgr24",
        "-s", f"{width}x{height}",
        "-r", str(fps),
        "-i", "-",
    ]

    if codec == "av1":
        if encoder == "libsvtav1":
            args.extend(AV1_ARGS)
        else:
            args.extend(["-c:v", encoder, "-crf", "30", "-cpu-used", "4", "-pix_fmt", "yuv420p",
                         "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709"])
    else:
        args.extend(CODEC_MAP[codec])

    args.append(output)
    return args


def run_encoder(
    frames_iter, width: int, height: int, fps: int, output: str, encoder: str | None, codec: str
) -> bool:
    args = build_ffmpeg_args(width, height, fps, output, encoder, codec)
    proc = subprocess.Popen(
        args,
        stdin=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
    ok = True
    try:
        for bgr in frames_iter:
            try:
                proc.stdin.write(bgr.tobytes())
            except BrokenPipeError:
                stderr_text = proc.stderr.read().decode("utf-8", errors="replace")
                print(f"ERROR: ffmpeg pipe broken. stderr:\n{stderr_text}", file=sys.stderr)
                ok = False
                break
    finally:
        if proc.stdin and not proc.stdin.closed:
            proc.stdin.close()
        stderr_text = b""
        if proc.stderr:
            stderr_text = proc.stderr.read()
        ret = proc.wait()
        if ret != 0:
            print(
                f"ERROR: ffmpeg exited with code {ret}.\n"
                + stderr_text.decode("utf-8", errors="replace"),
                file=sys.stderr,
            )
            ok = False
    return ok


# ── Main pipeline ─────────────────────────────────────────────────────────


def process_sequence(
    input_dir: str,
    output: str,
    frames_per_image: int,
    fps: int,
    codec: str,
    encoder_choice: str | None = None,
    scale_factor: float | None = None,
) -> None:
    check_ffmpeg()
    requested_av1 = codec == "av1"
    encoder = encoder_choice if encoder_choice else check_av1_encoder(requested_av1)

    exts = {".jpg", ".jpeg", ".JPG", ".JPEG"}
    files = sorted(
        f for f in os.listdir(input_dir)
        if os.path.splitext(f)[1] in exts
    )
    if not files:
        print(f"ERROR: No JPEG files found in {input_dir}", file=sys.stderr)
        sys.exit(1)

    print(f"Found {len(files)} images.", file=sys.stderr)

    # Load all frames (needed for Pass 0 pairwise scoring)
    all_bgrs: list[np.ndarray | None] = []
    all_grays: list[np.ndarray | None] = []
    all_fringe: list[np.ndarray | None] = []
    h_ref, w_ref = 0, 0
    for fname in files:
        path = os.path.join(input_dir, fname)
        bgr = cv2.imread(path)
        if bgr is None:
            print(f"WARNING: Cannot load {fname}", file=sys.stderr)
            all_bgrs.append(None)
            all_grays.append(None)
            all_fringe.append(None)
            continue
        h, w = bgr.shape[:2]
        if h_ref == 0:
            h_ref, w_ref = h, w
        all_bgrs.append(bgr)
        all_grays.append(cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY))
        all_fringe.append(build_fringe_mask(h, w))

    if h_ref == 0:
        print("ERROR: Could not load any valid images.", file=sys.stderr)
        sys.exit(1)

    # ── Pass 0: select reference frame ─────────────────────────────────────
    ref_idx = select_reference_frame(files, all_grays, all_fringe)
    ref_bgr = all_bgrs[ref_idx]
    ref_gray = all_grays[ref_idx]
    assert ref_bgr is not None and ref_gray is not None

    # ── Pass 1: compute transforms to chosen reference ──────────────────────
    results: list[FrameResult] = []
    valid_rects: list[tuple[int, int, int, int]] = []

    for idx, fname in enumerate(files):
        src_bgr = all_bgrs[idx]
        curr_gray = all_grays[idx]

        if idx == ref_idx:
            full_rect = (0, 0, w_ref, h_ref)
            results.append(
                FrameResult(
                    filename=fname,
                    index=idx,
                    M=np.eye(2, 3, dtype=np.float32),
                    inliers=0,
                    total_matches=0,
                    skipped=False,
                    skip_reason="",
                    warp_bgr=ref_bgr,
                    valid_rect=full_rect,
                    crop_rect=None,
                )
            )
            valid_rects.append(full_rect)
            continue

        if src_bgr is None or curr_gray is None:
            msg = f"corrupt JPEG"
            print(f"WARNING: Skipping {fname}: {msg}", file=sys.stderr)
            results.append(
                FrameResult(
                    filename=fname,
                    index=idx,
                    M=None,
                    inliers=0,
                    total_matches=0,
                    skipped=True,
                    skip_reason=msg,
                    warp_bgr=None,
                    valid_rect=None,
                    crop_rect=None,
                )
            )
            valid_rects.append((0, 0, 0, 0))
            continue

        h_src, w_src = src_bgr.shape[:2]

        # Try fringe mask then full frame against chosen reference
        fringe_mask = build_fringe_mask(h_src, w_src)
        use_fringe = fringe_mask is not None
        M, inliers, total = match_to_reference(ref_gray, curr_gray, fringe_mask)

        if M is None and use_fringe:
            M, inliers, total = match_to_reference(ref_gray, curr_gray, None)

        skipped = False
        skip_reason = ""
        if M is None:
            skipped = True
            skip_reason = f"too few matches (got {total} good, 0 inliers)"
            print(
                f"WARNING: Skipping {fname}: {skip_reason}",
                file=sys.stderr,
            )
        else:
            cap_err = validate_transform(M)
            if cap_err:
                skipped = True
                skip_reason = f"transform cap exceeded: {cap_err}"
                print(
                    f"WARNING: Skipping {fname}: {skip_reason}",
                    file=sys.stderr,
                )
            else:
                if inliers < 6:
                    skipped = True
                    skip_reason = f"only {inliers} inliers (minimum 6 required)"
                    print(
                        f"WARNING: Skipping {fname}: {skip_reason}",
                        file=sys.stderr,
                    )
                elif inliers < 15:
                    print(
                        f"WARNING: {fname}: low inlier count {inliers} "
                        "(model may be unreliable)",
                        file=sys.stderr,
                    )

            # Warn (do not reject) on large absolute translation vs reference
            if not skipped and M is not None:
                _, _, tx, ty = decompose_similarity(M)
                if abs(tx) > 500.0 or abs(ty) > 500.0:
                    print(
                        f"WARNING: Frame {idx} ({fname}): large translation "
                        f"({tx:.1f}, {ty:.1f})px from reference — verify alignment",
                        file=sys.stderr,
                    )

        if skipped:
            results.append(
                FrameResult(
                    filename=fname,
                    index=idx,
                    M=None,
                    inliers=inliers,
                    total_matches=total,
                    skipped=True,
                    skip_reason=skip_reason,
                    warp_bgr=None,
                    valid_rect=None,
                    crop_rect=None,
                )
            )
            valid_rects.append((0, 0, 0, 0))
            continue

        # Warp to reference space
        warped = cv2.warpAffine(
            src_bgr, M, (w_ref, h_ref), borderMode=cv2.BORDER_REPLICATE
        )

        vcr = valid_content_rect(M, h_src, w_src, h_ref, w_ref)

        results.append(
            FrameResult(
                filename=fname,
                index=idx,
                M=M,
                inliers=inliers,
                total_matches=total,
                skipped=False,
                skip_reason="",
                warp_bgr=warped,
                valid_rect=vcr,
                crop_rect=None,
            )
        )
        valid_rects.append(vcr)

    # ── Compute final crop rect ─────────────────────────────────────────────
    x0 = max(r[0] for r in valid_rects)
    y0 = max(r[1] for r in valid_rects)
    x1 = min(r[2] for r in valid_rects)
    y1 = min(r[3] for r in valid_rects)

    crop_w = x1 - x0
    crop_h = y1 - y0

    pad_w = (2 - crop_w % 2) % 2
    pad_h = (2 - crop_h % 2) % 2
    x1 += pad_w
    y1 += pad_h
    crop_w += pad_w
    crop_h += pad_h

    if crop_w <= 0 or crop_h <= 0:
        print(
            f"ERROR: Crop dimensions are zero or negative ({crop_w}x{crop_h}). "
            f"Valid-content rects: {valid_rects}",
            file=sys.stderr,
        )
        sys.exit(1)

    ref_area = w_ref * h_ref
    crop_area = crop_w * crop_h
    if crop_area < 0.5 * ref_area:
        print(
            f"ERROR: Crop area ({crop_area} px = {crop_area/ref_area*100:.1f}% of reference) "
            f"is below 50% guard. Aborting.",
            file=sys.stderr,
        )
        sys.exit(1)

    print(
        f"Crop rect: x={x0}..{x1}, y={y0}..{y1}, size={crop_w}x{crop_h} "
        f"({crop_area/ref_area*100:.1f}% of reference)",
        file=sys.stderr,
    )

    for i, res in enumerate(results):
        if res.valid_rect is not None and not res.skipped:
            x0f, y0f, x1f, y1f = res.valid_rect
            cc = (
                max(x0f, x0),
                max(y0f, y0),
                min(x1f, x1),
                min(y1f, y1),
            )
            old = results[i]
            results[i] = old._replace(crop_rect=cc)

    # ── Pass 2: crop, brightness correct, generate output frames ─────────────
    state = TimelapseState()
    peri = peripheral_mask(crop_h, crop_w)

    out_w = crop_w if scale_factor is None else max(2, int(round(crop_w * scale_factor / 2)) * 2)
    out_h = crop_h if scale_factor is None else max(2, int(round(crop_h * scale_factor / 2)) * 2)

    ref_crop_bgr = results[ref_idx].warp_bgr[y0:y1, x0:x1]
    ref_linear = srgb_to_linear(ref_crop_bgr.astype(np.float32))

    def gen_output_frames():
        last_output = ref_crop_bgr
        for res in results:
            if res.skipped or res.warp_bgr is None:
                if state.last_output_bgr is None:
                    last_output = ref_crop_bgr
                    state.last_output_bgr = ref_crop_bgr
                out = (
                    state.last_output_bgr
                    if scale_factor is None
                    else cv2.resize(
                        state.last_output_bgr, (out_w, out_h), interpolation=cv2.INTER_AREA
                    )
                )
                for _ in range(frames_per_image):
                    yield out
                print(
                    f"WARNING: Frame {res.index} ({res.filename}): {res.skip_reason}. "
                    f"Substituting previous frame.",
                    file=sys.stderr,
                )
                continue

            crop_bgr = res.warp_bgr[y0:y1, x0:x1]

            if res.index == ref_idx:
                corrected_bgr = crop_bgr
            else:
                frame_linear = srgb_to_linear(crop_bgr.astype(np.float32))
                gains = compute_gains(ref_linear, frame_linear, peri)
                extreme = ((gains > 1.5) | (gains < 0.5)).any()
                if extreme:
                    print(
                        f"WARNING: Frame {res.index} ({res.filename}): "
                        f"extreme gains {gains.tolist()} — check exposure",
                        file=sys.stderr,
                    )
                corrected_linear = apply_gains(frame_linear, gains)
                corrected_bgr = linear_to_srgb(corrected_linear)

            clipped = np.count_nonzero(
                (corrected_bgr == 0) | (corrected_bgr == 255)
            )
            total_px = corrected_bgr.size
            if total_px > 0 and clipped > 0.01 * total_px:
                pct = clipped / total_px * 100
                print(
                    f"WARNING: Frame {res.index} ({res.filename}): "
                    f"{pct:.2f}% pixels clipped after correction",
                    file=sys.stderr,
                )

            state.last_output_bgr = corrected_bgr
            last_output = corrected_bgr

            out = (
                corrected_bgr
                if scale_factor is None
                else cv2.resize(
                    corrected_bgr, (out_w, out_h), interpolation=cv2.INTER_AREA
                )
            )
            for _ in range(frames_per_image):
                yield out

    ok = run_encoder(
        gen_output_frames(),
        width=out_w,
        height=out_h,
        fps=fps,
        output=output,
        encoder=encoder,
        codec=codec,
    )
    if ok:
        print(f"Done: {output} ({len(files)} sources × {frames_per_image} frames each)", file=sys.stderr)
    else:
        print(f"ERROR: Encoding failed. Output may be incomplete: {output}", file=sys.stderr)
        sys.exit(1)


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Generate an aligned AV1/H.264/H.265 timelapse from DJI aerial JPEGs."
    )
    parser.add_argument("--input", default="./input", help="Input JPEG directory")
    parser.add_argument("--output", default="./timelapse.mp4", help="Output video path")
    parser.add_argument(
        "--frames-per-image",
        type=int,
        default=30,
        help="Output frames per source image (default: 30)",
    )
    parser.add_argument(
        "--codec",
        choices=["av1", "h264", "h265"],
        default="av1",
        help="Output video codec (default: av1)",
    )
    parser.add_argument(
        "--fps",
        type=int,
        default=30,
        help="Output frame rate (default: 30)",
    )
    parser.add_argument(
        "--scale-factor",
        type=float,
        default=None,
        help="Output resolution as a fraction of input dimensions (default: no scaling)",
    )
    args = parser.parse_args()

    scale_factor = args.scale_factor

    if not os.path.isdir(args.input):
        print(f"ERROR: Input directory does not exist: {args.input}", file=sys.stderr)
        sys.exit(1)

    process_sequence(
        input_dir=args.input,
        output=args.output,
        frames_per_image=args.frames_per_image,
        fps=args.fps,
        codec=args.codec,
        scale_factor=scale_factor,
    )


if __name__ == "__main__":
    main()