flowtracks 1.6.2.dev6__tar.gz → 1.6.2.dev11__tar.gz

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/.gitignore

@@ -12,3 +12,6 @@ doc/build/*
 .pypi_token
 uv.lock
 flowtracks/_version.py
+
+# manim render output of videos/*.py (regenerated by the script)
+media/

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev6
+Version: 1.6.2.dev11
 Summary: Library for handling 3D PTV trajectory databases and Lagrangian/Eulerian turbulence post-processing.
 Author-email: Yosef Meller <yosefm@gmail.com>
 License-Expression: GPL-3.0-only AND BSD-3-Clause

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/flowtracks/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.6.2.dev6'
-__version_tuple__ = version_tuple = (1, 6, 2, 'dev6')
+__version__ = version = '1.6.2.dev11'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev11')
 
-__commit_id__ = commit_id = 'g519243be4'
+__commit_id__ = commit_id = 'g5e011b439'

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/flowtracks/graphics.py

@@ -315,3 +315,197 @@ def plot_trajectories_3d(source, trajids=None, scalars="speed", context=0,
     if show:
         plotter.show()
     return plotter
+
+
+def _far_walls(bounds, toward_camera, step):
+    """Grey back walls (the three box faces away from the camera) and their
+    grid lines every ``step``, as two PolyData."""
+    import pyvista as pv
+
+    lo, hi = np.asarray(bounds[0::2], float), np.asarray(bounds[1::2], float)
+    walls, lines = [], []
+    for ax in range(3):
+        level = lo[ax] if toward_camera[ax] > 0 else hi[ax]
+        u, v = [a for a in range(3) if a != ax]
+        corners = np.zeros((4, 3))
+        corners[:, ax] = level
+        corners[:, u] = [lo[u], hi[u], hi[u], lo[u]]
+        corners[:, v] = [lo[v], lo[v], hi[v], hi[v]]
+        walls.append(pv.PolyData(corners, faces=[4, 0, 1, 2, 3]))
+        # grid lines lifted a hair off the wall so they never z-fight it
+        lift = 1e-3 * (hi[ax] - lo[ax]) * (1 if level == lo[ax] else -1)
+        for a, b in ((u, v), (v, u)):
+            ticks = np.arange(np.ceil(lo[a] / step) * step, hi[a] + 1e-9, step)
+            for t in ticks:
+                seg = np.zeros((2, 3))
+                seg[:, ax] = level + lift
+                seg[:, a] = t
+                seg[:, b] = [lo[b], hi[b]]
+                lines.append(pv.Line(seg[0], seg[1]))
+    return pv.merge(walls), pv.merge(lines)
+
+
+def _box_axis_labels(pl, bounds, toward_camera, step, titles, font_size):
+    """Tick labels every ``step`` and axis titles along the box edges nearest
+    the camera on the floor (x, z) and on the far vertical edge (y), as
+    ParaView draws them. (VTK's cube-axes actor caps the label count at its
+    own tick spacing, so it cannot label every ``step``.)"""
+    lo, hi = np.asarray(bounds[0::2], float), np.asarray(bounds[1::2], float)
+    near = np.where(np.asarray(toward_camera) > 0, hi, lo)
+    far = np.where(np.asarray(toward_camera) > 0, lo, hi)
+    out = np.where(np.asarray(toward_camera) > 0, 1.0, -1.0)  # outward, camera side
+    off = 0.035 * np.max(hi - lo)
+    edges = (  # axis, anchor of the edge, outward offset of its labels
+        (0, np.array([0.0, lo[1], near[2]]), np.array([0.0, -off, out[2] * off])),
+        (2, np.array([near[0], lo[1], 0.0]), np.array([out[0] * off, -off, 0.0])),
+        (1, np.array([far[0], 0.0, near[2]]), np.array([-out[0] * off, 0.0, out[2] * off])),
+    )
+    for ax, anchor, shift in edges:
+        ticks = np.arange(np.ceil(lo[ax] / step) * step, hi[ax] + 1e-9, step)
+        pts = np.tile(anchor + shift, (len(ticks), 1))
+        pts[:, ax] = ticks
+        pl.add_point_labels(pts, [f"{t:.0f}" for t in ticks], font_size=font_size,
+                            text_color="black", shape=None, show_points=False,
+                            always_visible=True, name=f"ticks{ax}")
+        mid = anchor + 2.6 * shift
+        mid[ax] = (lo[ax] + hi[ax]) / 2
+        pl.add_point_labels([mid], [titles[ax]], font_size=int(font_size * 1.3),
+                            text_color="black", shape=None, show_points=False,
+                            always_visible=True, name=f"title{ax}")
+
+
+def _use_font_file(pl, font_file):
+    """Point every text of the plotter at a TrueType file. (VTK's built-in
+    sans font draws '[' and ']' as parentheses.)"""
+    props = []
+    for actor in pl.actors.values():
+        if hasattr(actor, "GetTextProperty"):
+            props.append(actor.GetTextProperty())
+        mapper = actor.GetMapper() if hasattr(actor, "GetMapper") else None
+        if mapper is not None and hasattr(mapper, "GetLabelTextProperty"):
+            props.append(mapper.GetLabelTextProperty())
+        # add_point_labels: the style sits on the label hierarchy feeding the mapper
+        source = mapper.GetInputAlgorithm() if hasattr(mapper, "GetInputAlgorithm") else None
+        if source is not None and hasattr(source, "GetTextProperty"):
+            props.append(source.GetTextProperty())
+    for bar in pl.scalar_bars.values():
+        props += [bar.GetTitleTextProperty(), bar.GetLabelTextProperty()]
+    for prop in props:
+        prop.SetFontFamily(4)  # VTK_FONT_FILE
+        prop.SetFontFile(str(font_file))
+
+
+def animate_trajectories_3d(source, out_dir, frames=None, *, component=1, tail=20,
+                            pos_scale=1.0, bounds=None, cmap="coolwarm",
+                            clim=(-0.5, 0.5), bar_title=None, bar_labels=21,
+                            bar_fmt="%.2f", view_direction=(-1.0, 1.0, 1.0),
+                            view_up=(0.0, 1.0, 0.0), zoom=1.0, window_center=(0.0, 0.0),
+                            window_size=(1920, 1080), point_size=6.0,
+                            grid_step=500.0, axis_titles=("x", "y", "z"),
+                            wall_color=(0.54, 0.54, 0.54), background="white",
+                            font_size=20, font_file=None, outlines=(),
+                            outline_color="black", outline_width=3.0, movie=None,
+                            fps=10, label=None):
+    """Off-screen movie frames of trajectories as trailing beads (PyVista).
+
+    Every frame shows each particle's last ``tail`` positions as shaded
+    spheres coloured by one velocity component (``component``: 0, 1, 2), in a
+    box with grey back walls, a ``grid_step`` grid and labelled axes, seen
+    with a fixed parallel-projection camera -- the usual ParaView look.
+
+    source - zarr path / ZarrScene / Scene, as :func:`plot_trajectories_3d`.
+    out_dir - PNG frames are written as ``frame_0000.png`` ...
+    frames - frame numbers to render (default: every frame of the source).
+    pos_scale - multiplies positions (e.g. 1000 for m -> mm axes).
+    bounds - (x0, x1, y0, y1, z0, z1) of the box, in scaled units (default:
+        the data's 0.5-99.5 percentile box).
+    view_direction - from the scene towards the camera; ``view_up`` the
+        screen's up; ``zoom`` > 1 enlarges; ``window_center`` shifts the
+        projection centre in normalized window units (VTK SetWindowCenter).
+    movie - if given, the frames are also encoded to this .mp4 with ffmpeg.
+    label - optional ``str.format`` text drawn bottom-left, given ``frame``.
+    font_file - TrueType file for all text (VTK's built-in font has no
+        square brackets).
+    outlines - (N, 3) point arrays in scaled units, each drawn as a closed
+        line (e.g. the top and bottom rims of a cylindrical vessel).
+
+    Returns the list of PNG paths.
+    """
+    import shutil
+    import subprocess
+
+    import pyvista as pv
+
+    from flowtracks.writers import _trajectory_arrays
+
+    pos, vel, time, _ = _trajectory_arrays(source)
+    pos = pos * pos_scale
+    value = vel[:, component]
+    order = np.argsort(time, kind="stable")
+    pos, value, time = pos[order], value[order], time[order]
+    if frames is None:
+        frames = np.unique(time)
+    if bounds is None:
+        lo, hi = np.percentile(pos, 0.5, axis=0), np.percentile(pos, 99.5, axis=0)
+        bounds = (lo[0], hi[0], lo[1], hi[1], lo[2], hi[2])
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    direction = np.asarray(view_direction, float)
+    direction /= np.linalg.norm(direction)
+    walls, grid = _far_walls(bounds, direction, grid_step)
+
+    pl = pv.Plotter(off_screen=True, window_size=list(window_size))
+    pl.set_background(background)
+    pl.add_mesh(walls, color=wall_color, lighting=False, name="walls")
+    pl.add_mesh(grid, color="black", line_width=1.5, name="grid")
+    for k, ring in enumerate(outlines):
+        ring = np.asarray(ring, float)
+        line = pv.lines_from_points(np.vstack([ring, ring[:1]]))
+        pl.add_mesh(line, color=outline_color, line_width=outline_width,
+                    render_lines_as_tubes=True, name=f"outline{k}")
+    _box_axis_labels(pl, bounds, direction, grid_step, axis_titles, font_size)
+    pl.add_axes(viewport=(0.0, 0.82, 0.12, 1.0))
+    centre = np.array([(bounds[0] + bounds[1]) / 2, (bounds[2] + bounds[3]) / 2,
+                       (bounds[4] + bounds[5]) / 2])
+    size = np.linalg.norm(np.subtract(bounds[1::2], bounds[0::2]))
+    pl.enable_parallel_projection()
+    pl.camera.focal_point = centre
+    pl.camera.position = centre + direction * 4 * size
+    pl.camera.up = view_up
+    pl.reset_camera(bounds=list(bounds))
+    pl.camera.parallel_scale /= zoom
+    pl.camera.SetWindowCenter(*window_center)
+
+    bar = dict(title=bar_title or "", vertical=True, position_x=0.93, position_y=0.02,
+               height=0.96, width=0.012, n_labels=bar_labels, fmt=bar_fmt,
+               color="black", title_font_size=int(font_size * 1.2),
+               label_font_size=font_size)
+    paths = []
+    starts = np.searchsorted(time, np.asarray(frames) - tail + 1, side="left")
+    ends = np.searchsorted(time, np.asarray(frames), side="right")
+    for i, (frame, s, e) in enumerate(zip(frames, starts, ends)):
+        beads = pv.PolyData(pos[s:e] if e > s else np.zeros((0, 3)))
+        if e > s:
+            beads.point_data["value"] = value[s:e]
+            pl.add_mesh(beads, scalars="value", cmap=cmap, clim=clim,
+                        point_size=point_size, render_points_as_spheres=True,
+                        style="points", scalar_bar_args=bar, name="beads")
+        if label:
+            pl.add_text(label.format(frame=frame), position="lower_left",
+                        font_size=font_size, color="black", name="label")
+        if font_file:
+            _use_font_file(pl, font_file)
+        path = out_dir / f"frame_{i:04d}.png"
+        pl.screenshot(str(path))
+        paths.append(path)
+    pl.close()
+
+    if movie is not None:
+        ffmpeg = shutil.which("ffmpeg")
+        if ffmpeg is None:
+            raise RuntimeError("ffmpeg not found; the PNG frames are in " + str(out_dir))
+        subprocess.run([ffmpeg, "-v", "error", "-y", "-framerate", str(fps),
+                        "-i", str(out_dir / "frame_%04d.png"), "-c:v", "libx264",
+                        "-pix_fmt", "yuv420p", "-crf", "18", str(movie)], check=True)
+    return paths

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/flowtracks.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev6
+Version: 1.6.2.dev11
 Summary: Library for handling 3D PTV trajectory databases and Lagrangian/Eulerian turbulence post-processing.
 Author-email: Yosef Meller <yosefm@gmail.com>
 License-Expression: GPL-3.0-only AND BSD-3-Clause

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/flowtracks.egg-info/SOURCES.txt

@@ -753,6 +753,7 @@ flowtracks.egg-info/scm_version.json
 flowtracks.egg-info/top_level.txt
 scripts/analyse_fhdf.py
 scripts/convert_tracers_to_zarr.py
+scripts/make_trajectory_movie.py
 scripts/run_postptv_analysis.py
 scripts/view_trajectories_3d.py
 tests/conftest.py
@@ -795,4 +796,5 @@ tests/testing_fodder/three_trajects_simple.h5
 tests/testing_fodder/ptvis/ptv_is.10001
 tests/testing_fodder/ptvis/ptv_is.10002
 tests/testing_fodder/ptvis/ptv_is.10003
-tests/testing_fodder/ptvis/ptv_is.10004
+tests/testing_fodder/ptvis/ptv_is.10004
+videos/flowtracks_explainer.py

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/flowtracks.egg-info/scm_file_list.json

@@ -745,6 +745,7 @@
     "requriments.txt",
     "scripts/analyse_fhdf.py",
     "scripts/convert_tracers_to_zarr.py",
+    "scripts/make_trajectory_movie.py",
     "scripts/run_postptv_analysis.py",
     "scripts/view_trajectories_3d.py",
     "setup.py",
@@ -788,6 +789,7 @@
     "tests/testing_fodder/ptvis/ptv_is.10003",
     "tests/testing_fodder/ptvis/ptv_is.10004",
     "tests/testing_fodder/sequence.cfg",
-    "tests/testing_fodder/three_trajects_simple.h5"
+    "tests/testing_fodder/three_trajects_simple.h5",
+    "videos/flowtracks_explainer.py"
   ]
 }

flowtracks-1.6.2.dev11/flowtracks.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.6.1",
+  "distance": 11,
+  "node": "g5e011b4397bfc96c57556fc1da4392c5a37f699f",
+  "dirty": false,
+  "branch": "master",
+  "node_date": "2026-10-10"
+}

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/pyproject.toml

@@ -100,6 +100,8 @@ ignore = ["E501", "E701", "E741"]
 "scripts/**" = ["E402", "F401", "F841"]
 "benchmarks/**" = ["E402", "F401", "F841"]
 "doc/**" = ["E402", "F401"]
+# manim scenes use manim's documented `from manim import *` idiom
+"videos/**" = ["F403", "F405"]
 # F401: test modules import names to prove they are importable / to be
 # used by other tests via `from test_x import ...`.
 "tests/**" = ["E402", "F401"]

flowtracks-1.6.2.dev11/scripts/make_trajectory_movie.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Trajectory movie from postptv/openptv2 `res/run.zarr/trajectories` stores.
+
+Trailing-tail 3D segments colored by vertical velocity (coolwarm, +-0.5 m/s),
+fixed camera angle, wireframe barrel rings, horizontal colorbar — in the
+style of the Ilmenau `movie_up.avi` reference.
+
+Defaults below are the Ilmenau 8-camera bubble run (pos in m with PTV
+columns X, Y=height, Z=depth); point BASE/RIGS/OUT at any dataset with the
+same `trajectories/{pos,vel,time,trajid}` schema.
+
+Usage:
+  python make_trajectory_movie.py --test-frame 10250   # single PNG preview
+  python make_trajectory_movie.py --render-all          # all PNG frames
+  python make_trajectory_movie.py --render-all --mode full --elev 25 --azim -55 \
+      --stride 10 --max-tracks 15000 --outdir movie_frames_iso_full  # iso pathlines
+Then: ffmpeg -framerate 10 -i frame_%04d.png -c:v mpeg4 movie_up2.avi
+"""
+import argparse
+import sys
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+import zarr
+from mpl_toolkits.mplot3d.art3d import Line3DCollection
+
+BASE = Path("/Users/alex/Downloads/Ilmenau")
+RIGS = [BASE / "openptv_illmenau_4cam" / "res" / "run.zarr",
+        BASE / "openptv_illmenau_5678" / "res" / "run.zarr"]
+OUT = BASE / "Full_measurement_with_8_cameras" / "movie_frames_up2"
+CYL_R = 3575.0  # mm wall radius
+ELEV, AZIM = 86, -45  # fixed camera angle (movie_up style: top-down)
+TAIL = 5  # trailing frames per streak (tails mode)
+WMIN, WMAX = -0.5, 0.5
+EVERY = 5  # frame stride over 10001..10500 -> 100 movie frames
+SEGLEN_CAP = 250.0  # mm; drop longer single-step jumps (ghosts)
+
+
+def load():
+    xs, ys, hs, ws, ts, ds = [], [], [], [], [], []
+    # NOTE: trajid namespaces of the two rigs collide: offset each rig
+    # (same convention as generate_ilmenau_davis_results.py).
+    for zpath, off in zip(RIGS, [0, 1000000]):
+        g = zarr.open(str(zpath / "trajectories"), mode="r")
+        pos = g["pos"][:] * 1000.0  # m -> mm; cols X, Yheight, Zdepth
+        vel = g["vel"][:]
+        tim = g["time"][:].astype(np.int64)
+        tra = g["trajid"][:].astype(np.int64) + off
+        order = np.lexsort((tim, tra))
+        xs.append(pos[order][:, 0])
+        ys.append(pos[order][:, 2])  # depth on plot-Y
+        hs.append(pos[order][:, 1])  # height on plot-Z
+        ws.append(vel[order][:, 1])  # vertical velocity
+        ts.append(tim[order])
+        ds.append(tra[order])
+    return (np.concatenate(xs), np.concatenate(ys), np.concatenate(hs),
+            np.concatenate(ws), np.concatenate(ts), np.concatenate(ds))
+
+
+def draw_frame(frm, X, Y, H, W, T, out_path, dpi=120):
+    sel = (T >= frm - TAIL) & (T <= frm)
+    # consecutive-point segments within the window
+    idx = np.nonzero(sel)[0]
+    if len(idx) < 2:
+        return False
+    brk = np.nonzero(np.diff(idx) > 1)[0]
+    starts = np.r_[idx[0], idx[brk + 1]]
+    ends = np.r_[idx[brk], idx[-1]]
+    ok = ends > starts
+    starts, ends = starts[ok], ends[ok]
+    segs = np.stack(
+        [np.column_stack([X[starts], Y[starts], H[starts]]),
+         np.column_stack([X[ends], Y[ends], H[ends]])],
+        axis=1,
+    )
+    # drop ghost streaks: single steps above the speed cap
+    seglen = np.linalg.norm(segs[:, 1] - segs[:, 0], axis=1)
+    keep = seglen <= SEGLEN_CAP
+    segs, starts, ends = segs[keep], starts[keep], ends[keep]
+    if len(segs) < 1:
+        return False
+    cols = np.clip((W[starts] + W[ends]) / 2, WMIN, WMAX)
+
+    render_segments(segs, cols, out_path, dpi=dpi)
+    return True
+
+
+def build_full_trails(X, Y, H, W, T, D, max_tracks):
+    """Precompute full-length trail segments for the longest trajectories.
+
+    Returns (segs (M,2,3), colors (M,), end_times (M,)) with gap jumps
+    (dt > 2 frames) and ghost steps removed. Render loop then only masks
+    end_times <= frame. Rig trajid namespaces are pre-offset in load().
+    """
+    order = np.lexsort((T, D))
+    Xs, Ys, Hs, Ws, Ts, Ds = X[order], Y[order], H[order], W[order], T[order], D[order]
+    _, inv, cnt = np.unique(Ds, return_counts=True, return_inverse=True)
+    thresh = np.sort(cnt)[-min(max_tracks, len(cnt))]
+    m = cnt[inv] >= thresh
+    Xs, Ys, Hs, Ws, Ts, Ds = Xs[m], Ys[m], Hs[m], Ws[m], Ts[m], Ds[m]
+    link = (Ds[1:] == Ds[:-1]) & (Ts[1:] - Ts[:-1] >= 1) & (Ts[1:] - Ts[:-1] <= 2)
+    i0 = np.nonzero(link)[0]
+    segs = np.stack(
+        [np.column_stack([Xs[i0], Ys[i0], Hs[i0]]),
+         np.column_stack([Xs[i0 + 1], Ys[i0 + 1], Hs[i0 + 1]])],
+        axis=1,
+    )
+    seglen = np.linalg.norm(segs[:, 1] - segs[:, 0], axis=1)
+    good = seglen <= SEGLEN_CAP
+    return (segs[good],
+            np.clip((Ws[i0[good]] + Ws[i0[good] + 1]) / 2, WMIN, WMAX),
+            Ts[i0[good] + 1])
+
+
+def render_segments(segs, cols, out_path, dpi=120):
+    fig = plt.figure(figsize=(12, 12), dpi=dpi)
+    ax = fig.add_subplot(111, projection="3d")
+    th = np.linspace(0, 2 * np.pi, 200)
+    for z in (HZMIN, HZMAX):
+        ax.plot(CYL_R * np.cos(th), CYL_R * np.sin(th),
+                np.full_like(th, z), color="black", lw=1.5)
+    for ang in (0, np.pi / 2, np.pi, 3 * np.pi / 2):
+        ax.plot([CYL_R * np.cos(ang)] * 2, [CYL_R * np.sin(ang)] * 2,
+                [HZMIN, HZMAX], color="black", lw=1.0, alpha=0.6)
+    if len(segs) > 0:
+        lc = Line3DCollection(segs, cmap="coolwarm",
+                              norm=matplotlib.colors.Normalize(vmin=WMIN, vmax=WMAX),
+                              linewidths=0.6, alpha=0.55)
+        lc.set_array(cols)
+        ax.add_collection3d(lc)
+    ax.set_xlim(-4000, 4000)
+    ax.set_ylim(-4000, 4000)
+    ax.set_zlim(HZMIN - 200, HZMAX + 200)
+    ax.set_xlabel("X [mm]")
+    ax.set_ylabel("Y [mm]")
+    ax.set_zlabel("Z [mm]")
+    ax.view_init(elev=ELEV, azim=AZIM)
+    sm = plt.cm.ScalarMappable(cmap="coolwarm",
+                               norm=matplotlib.colors.Normalize(vmin=WMIN, vmax=WMAX))
+    sm.set_array([])
+    cb = plt.colorbar(sm, ax=ax, fraction=0.035, pad=0.04, orientation="horizontal")
+    cb.set_label(r"$w$ [m/s]")
+    cb.set_ticks([-0.5, -0.25, 0.0, 0.25, 0.5])
+    fig.tight_layout()
+    fig.savefig(out_path)
+    plt.close(fig)
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--test-frame", type=int, default=None)
+    ap.add_argument("--render-all", action="store_true")
+    ap.add_argument("--dpi", type=int, default=120)
+    ap.add_argument("--mode", choices=["tails", "full"], default="tails",
+                    help="tails: TAIL-frame streaks; full: whole trajectory up to frame")
+    ap.add_argument("--elev", type=float, default=None)
+    ap.add_argument("--azim", type=float, default=None)
+    ap.add_argument("--stride", type=int, default=None)
+    ap.add_argument("--max-tracks", type=int, default=15000,
+                    help="longest-first cap (full mode only)")
+    ap.add_argument("--outdir", type=str, default=None)
+    args = ap.parse_args()
+
+    if args.elev is not None:
+        ELEV = args.elev
+    if args.azim is not None:
+        AZIM = args.azim
+    if args.stride is not None:
+        EVERY = args.stride
+    if args.outdir is not None:
+        OUT = Path(args.outdir)
+        if not OUT.is_absolute():
+            OUT = BASE / OUT
+
+    print("loading trajectories...", flush=True)
+    X, Y, H, W, T, D = load()
+    HZMIN, HZMAX = float(np.percentile(H, 1)), float(np.percentile(H, 99))
+    print(f"points={len(X)} H range 1/99pct=({HZMIN:.0f},{HZMAX:.0f})", flush=True)
+    OUT.mkdir(exist_ok=True)
+
+    if args.mode == "full":
+        print("building full-length trails...", flush=True)
+        SEGS, COLS, ET = build_full_trails(X, Y, H, W, T, D, args.max_tracks)
+        print(f"trail segments: {len(SEGS)}", flush=True)
+        frames = list(range(10001, 10501, EVERY))
+        for i, f in enumerate(frames):
+            m = ET <= f
+            if m.sum() < 1:
+                continue
+            render_segments(SEGS[m], COLS[m], OUT / f"frame_{i:04d}.png", dpi=args.dpi)
+            if i % 10 == 0:
+                print(f"{i}/{len(frames)} nseg={m.sum()}", flush=True)
+        print("done", flush=True)
+        sys.exit(0)
+
+    if args.test_frame is not None:
+        ok = draw_frame(args.test_frame, X, Y, H, W, T,
+                        OUT / f"test_{args.test_frame}.png", dpi=args.dpi)
+        print("test frame written:", ok, flush=True)
+    elif args.render_all:
+        frames = list(range(10001, 10501, EVERY))
+        for i, f in enumerate(frames):
+            draw_frame(f, X, Y, H, W, T, OUT / f"frame_{i:04d}.png", dpi=args.dpi)
+            if i % 10 == 0:
+                print(f"{i}/{len(frames)}", flush=True)
+        print("done", flush=True)
+    else:
+        ap.print_help()
+        sys.exit(1)

{flowtracks-1.6.2.dev6 → flowtracks-1.6.2.dev11}/tests/test_graphics_3d.py

@@ -148,3 +148,80 @@ def test_plot_titles_show_recorded_units(tmp_path):
     plot_trajectories_3d(store, plotter=pl, show=False)
     assert "speed [m s-1]" in dict(pl.scalar_bars)
     pl.close()
+
+
+def test_far_walls_are_the_faces_away_from_the_camera():
+    from flowtracks.graphics import _far_walls
+
+    walls, grid = _far_walls((0, 4, 0, 2, 0, 6), (-1.0, 1.0, 1.0), 1.0)
+    centres = walls.cell_centers().points
+    # camera on -x, +y, +z: back walls at x = 4 (max), floor y = 0 (min), z = 0 (min)
+    assert sorted(map(tuple, np.round(centres, 6))) == sorted(
+        [(4.0, 1.0, 3.0), (2.0, 0.0, 3.0), (2.0, 1.0, 0.0)])
+    # grid lines every 1.0 across each wall: (5+3) + (5+7) + (3+7)
+    assert grid.n_lines == 30
+
+
+def _can_render():
+    """Screenshots need an OpenGL context. On a headless CI runner VTK
+    segfaults instead of raising (and pyvista.system_supports_plotting()
+    still says yes), so probe one tiny render in a child process."""
+    import subprocess
+    import sys
+
+    probe = ("import pyvista as pv; pl = pv.Plotter(off_screen=True, window_size=[8, 8]); "
+             "pl.add_mesh(pv.Sphere()); pl.screenshot(return_img=True)")
+    try:
+        return subprocess.run([sys.executable, "-c", probe], capture_output=True,
+                              timeout=120).returncode == 0
+    except subprocess.TimeoutExpired:
+        return False
+
+
+needs_render = pytest.mark.skipif(not _can_render(),
+                                  reason="no OpenGL context for off-screen rendering")
+
+
+@needs_render
+def test_animate_writes_frames_with_trailing_beads(tmp_path, monkeypatch):
+    from flowtracks import graphics
+
+    shown = []
+    real = pv.Plotter.add_mesh
+
+    def spy(self, mesh, *args, **kw):
+        if kw.get("name") == "beads":
+            shown.append(mesh.n_points)
+        return real(self, mesh, *args, **kw)
+
+    monkeypatch.setattr(pv.Plotter, "add_mesh", spy)
+    src = Tracks()  # times 0..9 (id 7), 0..2 (id 3), 0..4 (id 5)
+    paths = graphics.animate_trajectories_3d(
+        src, tmp_path, frames=[0, 4, 9], tail=3, window_size=(160, 120),
+        bounds=(0, 0.01, -0.01, 0.01, -0.01, 0.01), grid_step=0.005)
+    assert [p.name for p in paths] == ["frame_0000.png", "frame_0001.png", "frame_0002.png"]
+    assert all(p.stat().st_size > 0 for p in paths)
+    # frame 0: 3 tracks at t=0; frame 4: t=2..4 -> id7 3 + id5 3 + id3 1; frame 9: id7 3
+    assert shown == [3, 7, 3]
+
+
+@needs_render
+def test_animate_draws_outlines_closed(tmp_path, monkeypatch):
+    from flowtracks import graphics
+
+    seen = {}
+    real = pv.Plotter.add_mesh
+
+    def spy(self, mesh, *args, **kw):
+        if str(kw.get("name", "")).startswith("outline"):
+            seen[kw["name"]] = mesh.n_points
+        return real(self, mesh, *args, **kw)
+
+    monkeypatch.setattr(pv.Plotter, "add_mesh", spy)
+    a = np.linspace(0, 2 * np.pi, 12, endpoint=False)
+    ring = np.column_stack([0.005 * np.cos(a), np.zeros_like(a), 0.005 * np.sin(a)])
+    graphics.animate_trajectories_3d(
+        Tracks(), tmp_path, frames=[0], window_size=(160, 120),
+        bounds=(-0.01, 0.01, -0.01, 0.01, -0.01, 0.01), grid_step=0.005,
+        outlines=[ring, ring + [0, 0.005, 0]])
+    assert seen == {"outline0": 13, "outline1": 13}  # closed: first point repeated