openscvx 0.4.1.dev171__tar.gz → 0.4.1.dev172__tar.gz

{openscvx-0.4.1.dev171 → openscvx-0.4.1.dev172}/.gitignore

@@ -27,6 +27,9 @@ solver/*
 # Images
 *.eps
 
+# Animation renders
+examples/animations/mp4/
+
 # Numpy files
 *.npy
 

{openscvx-0.4.1.dev171/openscvx.egg-info → openscvx-0.4.1.dev172}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscvx
-Version: 0.4.1.dev171
+Version: 0.4.1.dev172
 Summary: A general Python-based successive convexification implementation which uses a JAX backend.
 Author-email: Chris Hayner and Griffin Norris <haynec@uw.edu>
 License: Apache Software License

openscvx-0.4.1.dev172/examples/animations/7_dof_arm.py

@@ -0,0 +1,225 @@
+"""Cinematic offline render of the 7-DOF arm pick-and-place example.
+
+The trajectory optimization problem itself lives in
+``examples/arm/7_dof_arm.py``; this file imports that ``problem`` and the
+robot parameters, solves it, builds a viser scene with arm links / joint
+frames / EE trail, and drives it frame-by-frame while piping raw RGB into
+ffmpeg to produce an mp4.
+
+Run it with::
+
+    python examples/animations/7_dof_arm.py
+
+The script prints a viser URL and waits. Open the URL in a browser — as soon
+as the client connects, the render begins. Requires ``ffmpeg`` on ``PATH``;
+``openscvx`` does not depend on it.
+
+Only one camera mode is provided — ``"overview"`` — a static elevated camera
+that frames the full pick-and-place workspace.
+
+Tweak ``OUTPUT_PATH`` / ``WIDTH`` / ``HEIGHT`` / ``FPS`` below for different
+output variants.
+"""
+
+import importlib
+import os
+import sys
+
+import numpy as np
+
+# Add the project root so `examples.*` imports resolve.
+current_dir = os.path.dirname(os.path.abspath(__file__))
+grandparent_dir = os.path.dirname(os.path.dirname(current_dir))
+sys.path.append(grandparent_dir)
+
+from examples.animations._camera import overview_pose
+from examples.animations._render import render_animation_to_video
+from examples.plotting_viser import AnimatedServerHandle
+from openscvx.plotting.viser import (
+    add_animated_trail,
+    add_ellipsoid_obstacles,
+    add_ghost_trajectory,
+    add_position_marker,
+    add_target_markers,
+    compute_velocity_colors,
+    create_server,
+)
+
+# Import the arm example by path (filename starts with a digit).
+_arm_spec = importlib.util.spec_from_file_location(
+    "arm_7dof", os.path.join(grandparent_dir, "examples", "arm", "7_dof_arm_collision.py")
+)
+_arm_mod = importlib.util.module_from_spec(_arm_spec)
+_arm_spec.loader.exec_module(_arm_mod)
+
+problem = _arm_mod.problem
+d1 = _arm_mod.d1
+a2 = _arm_mod.a2
+a3 = _arm_mod.a3
+a4 = _arm_mod.a4
+joint_names = _arm_mod.joint_names
+waypoint_names = _arm_mod.waypoint_names
+waypoint_positions = _arm_mod.waypoint_positions
+obstacle_center = _arm_mod.obstacle_center
+obstacle_radius = _arm_mod.obstacle_radius
+
+# Keypoint home positions (derived from link lengths — defined in __main__ of
+# the arm example, so we replicate them here).
+keypoint_home_positions = {
+    "base": np.array([0.0, 0.0, 0.0]),
+    "shoulder": np.array([0.0, 0.0, d1]),
+    "elbow": np.array([a2, 0.0, d1]),
+    "wrist": np.array([a2 + a3, 0.0, d1]),
+    "ee": np.array([a2 + a3 + a4, 0.0, d1]),
+}
+
+# --- Render settings ---------------------------------------------------------
+OUTPUT_PATH = os.path.join(current_dir, "mp4", "7_dof_arm_overview.mp4")
+WIDTH = 1080
+HEIGHT = 1080
+FPS = 60
+CRF = 16
+
+# Oversampling for smooth trails.
+STRIDE = 4
+PROPAGATION_HZ = FPS * STRIDE
+
+# --- Camera settings ---------------------------------------------------------
+OVERVIEW_AZIMUTH = np.radians(60.0)
+OVERVIEW_ELEVATION = np.radians(15.0)
+OVERVIEW_RADIUS_MARGIN = 1.0
+OVERVIEW_FOV_DEG = 60.0
+
+
+if __name__ == "__main__":
+    import jaxlie
+
+    problem.settings.prp.dt = 1.0 / PROPAGATION_HZ
+    problem.initialize()
+    problem.solve()
+    results = problem.post_process()
+
+    ee_pos = np.asarray(results.trajectory["ee_position"], dtype=np.float64)
+    n_frames = len(ee_pos)
+
+    # -- Extract joint keypoint positions from propagated transforms -----------
+    keypoints = np.zeros((n_frames, 5, 3))
+    joint_quats = np.zeros((n_frames, 5, 4))
+    for k, name in enumerate(joint_names):
+        T_k = np.asarray(results.trajectory[f"T_{name}"])  # (T, 4, 4)
+        p_home = np.append(keypoint_home_positions[name], 1.0)
+        keypoints[:, k] = (T_k @ p_home)[:, :3]
+        joint_quats[:, k] = np.array(
+            [jaxlie.SO3.from_matrix(T_k[t, :3, :3]).wxyz for t in range(n_frames)]
+        )
+
+    # -- Build viser scene (mirrors examples/arm/7_dof_arm.py) -----------------
+    server = create_server(ee_pos, show_grid=False)
+    server.scene.add_grid("/grid", width=1.5, height=1.5, cell_size=0.25)
+    server.scene.add_frame("/origin", axes_length=0.1, axes_radius=0.003)
+
+    # Waypoint markers
+    marker_colors = {
+        "home": (100, 150, 255),
+        "pre_grasp": (255, 180, 50),
+        "grasp": (255, 50, 50),
+        "pre_place": (255, 180, 50),
+        "place": (255, 50, 50),
+    }
+    add_target_markers(
+        server,
+        waypoint_positions,
+        radius=0.015,
+        colors=[marker_colors[name] for name in waypoint_names],
+    )
+
+    add_ellipsoid_obstacles(
+        server,
+        centers=[obstacle_center],
+        radii=[np.full(3, 1.0 / obstacle_radius)],
+    )
+
+    # Ghost EE trajectory + animated trail
+    ee_colors = compute_velocity_colors(np.asarray(results.trajectory.get("velocity")))
+    add_ghost_trajectory(server, ee_pos, ee_colors, point_size=0.005)
+    _, update_trail = add_animated_trail(server, ee_pos, ee_colors, point_size=0.008)
+
+    # Animated EE position marker
+    _, update_marker = add_position_marker(server, ee_pos, radius=0.015)
+
+    # Animated arm links (line segments between consecutive keypoints)
+    link_rgb = np.array(
+        [
+            [180, 180, 180],  # base -> shoulder
+            [100, 180, 255],  # shoulder -> elbow
+            [100, 255, 150],  # elbow -> wrist
+            [255, 200, 100],  # wrist -> ee
+        ],
+        dtype=np.uint8,
+    )
+    link_colors = np.stack([link_rgb, link_rgb], axis=1)  # (4, 2, 3)
+
+    init_points = np.stack(
+        [np.stack([keypoints[0, k], keypoints[0, k + 1]]) for k in range(4)]
+    ).astype(np.float32)
+
+    arm_handle = server.scene.add_line_segments(
+        "/arm_links",
+        points=init_points,
+        colors=link_colors,
+        line_width=5.0,
+    )
+
+    # Joint coordinate frames
+    joint_frame_handles = []
+    for k in range(5):
+        h = server.scene.add_frame(
+            f"/joint_{joint_names[k]}",
+            wxyz=joint_quats[0, k].astype(np.float32),
+            position=keypoints[0, k].astype(np.float32),
+            axes_length=0.06,
+            axes_radius=0.002,
+        )
+        joint_frame_handles.append(h)
+
+    def update_arm(frame_idx: int) -> None:
+        pts = np.stack(
+            [np.stack([keypoints[frame_idx, k], keypoints[frame_idx, k + 1]]) for k in range(4)]
+        ).astype(np.float32)
+        arm_handle.points = pts
+        for k, h in enumerate(joint_frame_handles):
+            h.position = keypoints[frame_idx, k].astype(np.float32)
+            h.wxyz = joint_quats[frame_idx, k].astype(np.float32)
+
+    # -- Manual-step handle for the renderer -----------------------------------
+    traj_time = np.asarray(results.trajectory["time"], dtype=np.float64).flatten()
+    handle = AnimatedServerHandle(
+        server=server,
+        traj_time=traj_time,
+        update_callbacks=[update_trail, update_marker, update_arm],
+    )
+
+    # -- Camera: overview framing the full workspace ---------------------------
+    # Frame on waypoint positions + EE path so the full motion is visible.
+    all_points = np.vstack([ee_pos, np.array(waypoint_positions)])
+    static_pose = overview_pose(
+        all_points,
+        azimuth=OVERVIEW_AZIMUTH,
+        elevation=OVERVIEW_ELEVATION,
+        radius_margin=OVERVIEW_RADIUS_MARGIN,
+        fov_deg=OVERVIEW_FOV_DEG,
+    )
+
+    def camera_pose_fn(frame_idx: int):
+        return static_pose
+
+    render_animation_to_video(
+        handle,
+        OUTPUT_PATH,
+        camera_pose_fn,
+        width=WIDTH,
+        height=HEIGHT,
+        fps=FPS,
+        crf=CRF,
+        stride=STRIDE,
+    )

openscvx-0.4.1.dev172/examples/animations/_camera.py

@@ -0,0 +1,142 @@
+"""Reusable camera pose helpers for viser animation rendering.
+
+All functions return ``(cam_position, cam_wxyz, look_at)`` tuples suitable for
+passing to ``render_animation_to_video``'s ``camera_pose_fn`` argument. They
+depend only on numpy and ``viser.transforms`` — no openscvx imports.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import viser.transforms as vtf
+
+
+def look_at_wxyz(pos: np.ndarray, target: np.ndarray, up: np.ndarray) -> np.ndarray:
+    """Quaternion (w,x,y,z) for a camera at ``pos`` looking at ``target``.
+
+    Uses the OpenCV camera convention that viser expects: +X right, +Y down,
+    +Z forward. See ``examples/animations/camera_control_notes.md``.
+    """
+    forward = target - pos
+    forward /= np.linalg.norm(forward)
+    right = np.cross(forward, up)
+    right_norm = np.linalg.norm(right)
+    if right_norm < 1e-6:
+        # Gimbal lock: forward is (nearly) parallel to up. Pick an arbitrary
+        # world axis that isn't, so the camera stays defined. The chosen axis
+        # determines the "roll" of the camera at the singularity — not great
+        # cinematically, but prevents a NaN crash.
+        fallback = np.array([1.0, 0.0, 0.0]) if abs(forward[0]) < 0.9 else np.array([0.0, 1.0, 0.0])
+        right = np.cross(forward, fallback)
+        right_norm = np.linalg.norm(right)
+    right /= right_norm
+    cam_down = np.cross(forward, right)  # = -world_up projected perp to forward
+    R_world_cam = np.stack([right, cam_down, forward], axis=1)
+    return vtf.SO3.from_matrix(R_world_cam).wxyz
+
+
+def chase_pose(
+    subject: np.ndarray,
+    focus: np.ndarray,
+    *,
+    chase_distance: float = 15.0,
+    vertical_offset: float = 2.0,
+    up=(0.0, 0.0, 1.0),
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Return ``(cam_pos, cam_wxyz, look_at)`` for a chase camera behind ``subject``.
+
+    The camera sits on the ray from ``focus`` through ``subject``, extended
+    ``chase_distance`` units past the subject, then lifted along world up by
+    ``vertical_offset``. It always looks at ``focus``.
+    """
+    subject = np.asarray(subject, dtype=np.float64)
+    focus = np.asarray(focus, dtype=np.float64)
+    up = np.asarray(up, dtype=np.float64)
+
+    ray = subject - focus
+    ray_norm = np.linalg.norm(ray)
+    if ray_norm < 1e-6:
+        cam_pos = subject + vertical_offset * up
+    else:
+        cam_pos = subject + chase_distance * (ray / ray_norm) + vertical_offset * up
+
+    wxyz = look_at_wxyz(cam_pos, focus, up)
+    return cam_pos, wxyz, focus
+
+
+def onboard_pose(
+    position: np.ndarray,
+    attitude_wxyz: np.ndarray,
+    R_sb: np.ndarray,
+    *,
+    forward_offset: float = 0.0,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Return ``(cam_pos, cam_wxyz, look_at)`` for a sensor-mounted FPV camera.
+
+    Places the camera at ``position`` (shifted slightly forward along the sensor
+    boresight by ``forward_offset``) with orientation matching the sensor frame —
+    i.e. looking along the sensor boresight (+Z in sensor frame, mapped through
+    ``R_sb`` and the body attitude to world coordinates).
+    """
+    # R_body_to_world from the attitude quaternion (w, x, y, z)
+    w, x, y, z = attitude_wxyz
+    R_bw = np.array(
+        [
+            [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+            [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+            [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+        ],
+        dtype=np.float64,
+    )
+
+    # Sensor-to-world: columns are the sensor axes in world coords.
+    # R_sb is body-to-sensor, so R_sb.T is sensor-to-body.
+    R_sensor_to_world = R_bw @ R_sb.T
+
+    # Viser uses OpenCV convention (+X right, +Y DOWN, +Z forward).
+    # The sensor frame has +Y UP, so we rotate 180deg around the boresight (Z)
+    # to flip both X and Y, converting to the convention viser expects.
+    R_opencv_from_sensor = np.diag([-1.0, -1.0, 1.0])
+    R_cam_to_world = R_sensor_to_world @ R_opencv_from_sensor
+
+    wxyz = vtf.SO3.from_matrix(R_cam_to_world).wxyz
+    # Boresight is sensor +Z expressed in world frame (unchanged by the flip).
+    boresight_world = R_sensor_to_world[:, 2]
+    cam_pos = position + forward_offset * boresight_world
+    look_at = cam_pos + 10.0 * boresight_world
+    return cam_pos, wxyz, look_at
+
+
+def overview_pose(
+    positions: np.ndarray,
+    *,
+    azimuth: float = np.radians(135.0),
+    elevation: float = np.radians(25.0),
+    radius_margin: float = 0.75,
+    fov_deg: float = 60.0,
+    up=(0.0, 0.0, 1.0),
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Return a static ``(cam_pos, cam_wxyz, look_at)`` that frames all ``positions``.
+
+    The camera is placed on a sphere around the centroid of ``positions``,
+    parameterized by ``azimuth`` (angle in XY from +X, CCW) and ``elevation``
+    (angle above the horizon). The radius is auto-computed so the full extent
+    fits within ``fov_deg``, then scaled by ``radius_margin``.
+    """
+    up = np.asarray(up, dtype=np.float64)
+    center = positions.mean(axis=0)
+    max_extent = np.max(np.linalg.norm(positions - center, axis=1))
+    half_fov_rad = np.radians(fov_deg / 2.0)
+    radius = max_extent / np.sin(half_fov_rad) * radius_margin
+
+    cos_el = np.cos(elevation)
+    cam_pos = center + radius * np.array(
+        [
+            cos_el * np.cos(azimuth),
+            cos_el * np.sin(azimuth),
+            np.sin(elevation),
+        ]
+    )
+    look_at = center.copy()
+    wxyz = look_at_wxyz(cam_pos, look_at, up)
+    return cam_pos, wxyz, look_at

openscvx-0.4.1.dev172/examples/animations/_render.py

@@ -0,0 +1,261 @@
+"""Offline video rendering for animated viser examples.
+
+Pipes raw RGB frames from ``client.get_render()`` directly into ffmpeg over
+stdin, so there are no intermediate PNG files and no Python image library
+required. The only runtime dependency is ``ffmpeg`` on ``PATH``; ``openscvx``
+itself gains nothing from this module.
+
+Typical usage (from an animation example):
+
+.. code-block:: python
+
+    handle = create_animated_plotting_server(results, ..., controls="manual")
+
+    def camera_pose_fn(frame_idx):
+        return chase_pose(positions[frame_idx], target_center)
+
+    render_animation_to_video(handle, "out.mp4", camera_pose_fn)
+
+The render blocks on a viser client connection, so you run the script, wait
+for the "[render] waiting for a viser client..." line, open the printed viser
+URL in a browser, and the render starts automatically.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+import viser
+
+from examples.plotting_viser import AnimatedServerHandle
+
+# frame_idx -> (camera_position, camera_wxyz, camera_look_at)
+CameraPoseFn = Callable[[int], tuple[np.ndarray, np.ndarray, np.ndarray]]
+
+
+def wait_for_client(
+    server: viser.ViserServer,
+    timeout_s: float = 300.0,
+    poll_interval_s: float = 0.25,
+) -> viser.ClientHandle:
+    """Block until at least one viser client connects; return the first one.
+
+    Prints a reminder so the user knows they need to open the printed viser
+    URL in a browser for the render to proceed.
+    """
+    print(
+        f"[render] waiting for a viser client to connect "
+        f"(open the viser URL above; timeout in {int(timeout_s)}s)..."
+    )
+    t0 = time.time()
+    while True:
+        clients = server.get_clients()
+        if clients:
+            client = next(iter(clients.values()))
+            print("[render] client connected.")
+            return client
+        if time.time() - t0 > timeout_s:
+            raise TimeoutError(
+                f"No viser client connected within {timeout_s:.0f}s. "
+                f"Open the viser URL in a browser to start the render."
+            )
+        time.sleep(poll_interval_s)
+
+
+def render_animation_to_video(
+    handle: AnimatedServerHandle,
+    output_path: str | Path,
+    camera_pose_fn: CameraPoseFn,
+    *,
+    width: int = 1280,
+    height: int = 720,
+    fps: int = 30,
+    crf: int = 16,
+    preset: str = "slow",
+    background_color: tuple[int, int, int] = (16, 17, 19),
+    start_frame: int = 0,
+    end_frame: int | None = None,
+    stride: int = 1,
+    settle_s: float = 0.0,
+    client: viser.ClientHandle | None = None,
+    progress_every: int = 30,
+    fov_deg: float | None = None,
+) -> Path:
+    """Render frames of ``handle`` to an H.264 mp4 by piping raw RGB into ffmpeg.
+
+    Each frame is fetched with ``transport_format="png"`` so we get a *lossless*
+    RGBA array from the browser — no JPEG pre-compression stacked under the
+    final h.264 pass. The alpha channel is composited onto ``background_color``
+    in numpy before writing.
+
+    Why compositing is necessary: viser's dark mode puts the canvas over a
+    ``theme.colors.dark[9]`` (= ``#101113``) DOM element (see viser client
+    ``App.tsx:426``), and the browser compositor blends the scene over that
+    background at display time. But ``client.get_render`` returns only the
+    WebGL canvas pixels, which are transparent where nothing is drawn — so
+    we have to composite ourselves. The default ``background_color`` matches
+    Mantine's ``dark[9]`` exactly so the rendered frames are indistinguishable
+    from the live view.
+
+    The video's playback rate (``fps``) is independent of how many frames the
+    trajectory contains — ``stride`` controls the frame range from the trajectory
+    that gets written. For realtime playback, pick ``fps`` so that
+    ``len(range(start_frame, end_frame, stride)) / fps`` matches the trajectory
+    duration. For slow-motion, raise ``fps`` relative to that; for time-lapse,
+    lower it.
+
+    Args:
+        handle: Handle returned by
+            ``create_animated_plotting_server(..., controls="manual")``.
+        output_path: Destination mp4 file. Parent dirs are created.
+        camera_pose_fn: ``frame_idx -> (position, wxyz, look_at)``. Called once
+            per rendered frame to position the camera.
+        width: Output video width in pixels.
+        height: Output video height in pixels.
+        fps: Output video frame rate.
+        crf: H.264 constant-rate factor; lower is higher quality. 16 is
+            visually near-lossless, 18 is high quality, 23 is ffmpeg's default.
+        preset: ffmpeg x264 preset (``ultrafast``..``veryslow``). ``slow`` gives
+            noticeably better quality/size than ``medium`` for static-heavy 3D
+            scenes at modest encode-time cost.
+        background_color: RGB tuple (0..255) for the scene background. Applied
+            both to viser's scene (so the live view matches) and as the
+            composite color for alpha channel in rendered frames.
+        start_frame: First trajectory frame index to render (inclusive).
+        end_frame: One past the last trajectory frame to render. ``None`` means
+            up to ``handle.n_frames``.
+        stride: Trajectory frame stride. ``stride=2`` renders every other
+            frame, halving the output length at fixed ``fps``.
+        settle_s: Optional sleep between pushing scene state and calling
+            ``get_render``. Usually 0; bump if you see torn/partial frames.
+        client: Pre-connected client. If ``None``, waits for one.
+        progress_every: Print a progress line every N rendered frames.
+        fov_deg: If given, override the client camera's vertical field of view
+            (in degrees) before rendering. Useful for matching a sensor FOV.
+
+    Returns:
+        Absolute path to the written mp4.
+    """
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        raise RuntimeError(
+            "ffmpeg not found on PATH. Install it locally (e.g. "
+            "`brew install ffmpeg` on macOS) — openscvx does not include it "
+            "as a package dependency."
+        )
+
+    output_path = Path(output_path).expanduser().resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Push the background color to viser so the live browser view matches the
+    # rendered output. `configure_theme(dark_mode=True)` only styles GUI panels;
+    # the 3D canvas clear color is controlled separately by set_background_image.
+    bg_rgb = np.asarray(background_color, dtype=np.uint8).reshape(1, 1, 3)
+    bg_image = np.broadcast_to(bg_rgb, (2, 2, 3)).copy()
+    handle.server.scene.set_background_image(bg_image, format="png")
+    bg_float = np.asarray(background_color, dtype=np.float32).reshape(1, 1, 3)
+
+    if client is None:
+        client = wait_for_client(handle.server)
+
+    if fov_deg is not None:
+        client.camera.fov = np.radians(fov_deg)
+
+    n = handle.n_frames
+    if end_frame is None:
+        end_frame = n
+    frame_indices = list(range(start_frame, min(end_frame, n), max(stride, 1)))
+    if not frame_indices:
+        raise ValueError(
+            f"No frames to render: start_frame={start_frame}, "
+            f"end_frame={end_frame}, n_frames={n}, stride={stride}"
+        )
+
+    cmd = [
+        ffmpeg,
+        "-y",
+        "-f",
+        "rawvideo",
+        "-vcodec",
+        "rawvideo",
+        "-s",
+        f"{width}x{height}",
+        "-pix_fmt",
+        "rgb24",
+        "-r",
+        str(fps),
+        "-i",
+        "-",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-crf",
+        str(crf),
+        "-preset",
+        preset,
+        "-movflags",
+        "+faststart",
+        str(output_path),
+    ]
+
+    print(f"[render] {len(frame_indices)} frame(s) @ {fps} fps, {width}x{height} -> {output_path}")
+
+    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE)
+    assert proc.stdin is not None
+
+    try:
+        t_render_start = time.time()
+        for out_i, frame_i in enumerate(frame_indices):
+            handle.step(frame_i)
+            pos, wxyz, look_at = camera_pose_fn(frame_i)
+            with client.atomic():
+                client.camera.position = pos
+                client.camera.wxyz = wxyz
+                client.camera.look_at = look_at
+            if settle_s > 0:
+                time.sleep(settle_s)
+            # PNG transport is lossless RGBA. JPEG would introduce a second
+            # compression pass on top of h.264 and visibly hurts quality.
+            img = client.get_render(height=height, width=width, transport_format="png")
+            if img.ndim != 3 or img.shape[0] != height or img.shape[1] != width:
+                raise RuntimeError(
+                    f"Unexpected get_render shape {img.shape}; "
+                    f"expected ({height}, {width}, 3 or 4)."
+                )
+            if img.dtype != np.uint8:
+                img = img.astype(np.uint8)
+            if img.shape[2] == 4:
+                # Composite RGBA onto the chosen background color. Empty scene
+                # pixels come back alpha=0 so they'd otherwise be undefined.
+                alpha = img[:, :, 3:4].astype(np.float32) * (1.0 / 255.0)
+                rgb = img[:, :, :3].astype(np.float32)
+                composed = rgb * alpha + bg_float * (1.0 - alpha)
+                img = composed.astype(np.uint8)
+            proc.stdin.write(img.tobytes())
+            if progress_every > 0 and (out_i + 1) % progress_every == 0:
+                elapsed = time.time() - t_render_start
+                done = out_i + 1
+                rate = done / max(elapsed, 1e-6)
+                eta = (len(frame_indices) - done) / max(rate, 1e-6)
+                print(
+                    f"[render]   frame {done}/{len(frame_indices)} ({rate:.1f} fps, eta {eta:.0f}s)"
+                )
+        proc.stdin.close()
+    except BrokenPipeError as e:
+        proc.wait()
+        raise RuntimeError(
+            "ffmpeg closed its input pipe unexpectedly. See ffmpeg stderr above."
+        ) from e
+
+    ret = proc.wait()
+    if ret != 0:
+        raise RuntimeError(f"ffmpeg exited with code {ret}")
+
+    print(f"[render] done: {output_path}")
+    return output_path