flowtracks 1.6.2.dev6__py3-none-any.whl → 1.6.2.dev12__py3-none-any.whl

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.dev12'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev12')
 
-__commit_id__ = commit_id = 'g519243be4'
+__commit_id__ = commit_id = 'g4ea7448e5'

flowtracks/clean.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Alex Liberzon
+"""
+Cleaning chain for raw tracker output: repair, kink split, smoothing, stitching.
+
+Raw linkage from a tracker (one row per point, with a trajectory id) is turned
+into smooth trajectories in one call, :func:`clean_trajectories`:
+
+1. repair (:func:`flowtracks.repair.repair_arrays`): cut wrong links, attach
+   single points, join pieces across short gaps;
+2. Savitzky-Golay smoothing (:func:`flowtracks.smoothing.savitzky_golay`);
+3. kink split: a fast, violent turn (larger than ``kink_deg`` on steps longer
+   than ``kink_step_mm``) is a wrong link the repair missed; the pieces get
+   fresh ids;
+4. smoothing, a first stitch (``gap1``, ``dist1``, ``vd1``), smoothing;
+5. a second kink split, smoothing, a second, tighter stitch (``gap2``,
+   ``dist2``, ``vd2``);
+6. final smoothing (optionally a longer window for long trajectories).
+
+Positions are in metres, so velocities are in m/s at the given frame rate.
+Every setting has a default in :data:`CLEAN_DEFAULTS`; ``fps`` has none on
+purpose -- the frame rate must be stated. :func:`resolve_settings` merges a
+parameter-file section and overrides onto the defaults and reports where each
+value came from.
+"""
+
+import numpy as np
+
+from flowtracks.repair import repair_arrays
+from flowtracks.smoothing import savitzky_golay
+from flowtracks.stitching import stitch_trajectories
+from flowtracks.trajectory import Trajectory
+
+#: Default settings of :func:`clean_trajectories` (positions in metres).
+CLEAN_DEFAULTS = dict(
+    fps=None,                  # frame rate [Hz]; required
+    repair_max_gap=1,          # repair: max frame gap for attach / join,
+    repair_max_distance_mm=0.3,  # max distance [mm],
+    repair_link_percentile=99.9,  # link check calibrated on this percentile,
+    repair_cut_factor=2.0,     # cut threshold factor,
+    repair_cut=True,           # and which of the three repairs run
+    repair_attach=True,
+    repair_join=True,
+    sg_window=7,               # Savitzky-Golay window / order
+    sg_order=2,
+    kink_deg=90.0,             # kink split: turn angle ...
+    kink_step_mm=25.0,         # ... on steps longer than this
+    gap1=12,                   # first stitch: max gap [frames],
+    dist1=0.05,                #   max distance [m],
+    vd1=0.5,                   #   max velocity difference [m/s]
+    gap2=8,                    # second (tight) stitch on clean ends
+    dist2=0.025,
+    vd2=0.35,
+    win_long=0,                # >0: final smoothing (win_long, order_long)
+    order_long=3,              #   for tracks with >= len_long points
+    len_long=25,
+)
+
+
+def resolve_settings(section=None, overrides=None, source_name="parameter file"):
+    """Settings of :func:`clean_trajectories`: defaults <- section <- overrides.
+
+    Arguments:
+    section - mapping read from a parameter file (may be None).
+    overrides - mapping of explicit values (e.g. command-line flags); None
+        values are ignored.
+    source_name - how ``section`` is named in the returned sources.
+
+    Returns:
+    (settings, sources) - two dicts keyed like :data:`CLEAN_DEFAULTS`; sources
+    say "override", ``source_name`` or "default" for every key.
+
+    Raises ValueError on an unknown key in ``section`` or a missing ``fps``.
+    """
+    section = dict(section or {})
+    overrides = {k: v for k, v in (overrides or {}).items() if v is not None}
+    unknown = sorted(set(section) - set(CLEAN_DEFAULTS))
+    if unknown:
+        raise ValueError(f"unknown cleaning settings: {unknown}")
+    settings, sources = {}, {}
+    for k, v in CLEAN_DEFAULTS.items():
+        cast = float if k == "fps" else type(v)
+        if k in overrides:
+            settings[k], sources[k] = cast(overrides[k]), "override"
+        elif k in section:
+            settings[k], sources[k] = cast(section[k]), source_name
+        else:
+            settings[k], sources[k] = v, "default"
+    if settings["fps"] is None:
+        raise ValueError("fps (frame rate) must be given")
+    return settings, sources
+
+
+def trajectories_from_arrays(trajid, time, pos):
+    """Trajectory objects (zero velocity) from flat one-row-per-point arrays.
+
+    Rows are grouped by ``trajid`` and ordered by ``time`` inside each group;
+    groups of a single point are dropped.
+    """
+    trajid, time, pos = np.asarray(trajid), np.asarray(time), np.asarray(pos)
+    order = np.argsort(trajid, kind="stable")
+    tj, tm, pp = trajid[order], time[order], pos[order]
+    bounds = np.flatnonzero(np.diff(tj)) + 1
+    starts = np.r_[0, bounds]
+    out = []
+    for i, s in enumerate(starts):
+        e = int(bounds[i]) if i < len(bounds) else len(tj)
+        if e - s >= 2:
+            o = np.argsort(tm[s:e], kind="stable")
+            out.append(Trajectory(pp[s:e][o], np.zeros_like(pp[s:e][o]),
+                                  tm[s:e][o], int(tj[s])))
+    return out
+
+
+def kink_split(trajs, max_deg, step_min, fresh_start=10_000_000):
+    """Split trajectories at fast, violent turns.
+
+    A point is a cut point when the velocity turns by more than ``max_deg``
+    degrees there and both the step into it and the step out of it are longer
+    than ``step_min`` (position units). Every piece of a cut trajectory gets a
+    fresh id counting from ``fresh_start``, so readers grouping by id cannot
+    put the pieces back together.
+
+    Returns:
+    (trajectories, number of cuts)
+    """
+    out, ncuts, nxt = [], 0, fresh_start
+    for tr in trajs:
+        v = tr.velocity()
+        n = np.linalg.norm(v, axis=1)
+        t, p = np.asarray(tr.time()), tr.pos()
+        st = np.linalg.norm(np.diff(p, axis=0), axis=1)
+        ok = (n[:-1] > 1e-12) & (n[1:] > 1e-12)
+        cosang = np.ones(len(v) - 1)
+        cosang[ok] = np.clip((v[:-1][ok] * v[1:][ok]).sum(1) / (n[:-1][ok] * n[1:][ok]),
+                             -1, 1)
+        ang = np.degrees(np.arccos(cosang))
+        instep = np.concatenate([st[:1], st[:-1]])
+        bad = np.flatnonzero((ang > max_deg) & (instep > step_min) & (st > step_min)) + 1
+        ncuts += len(bad)
+        segs = np.split(np.arange(len(t)), bad)
+        if len(segs) == 1:
+            out.append(tr)
+            continue
+        for seg in segs:
+            if len(seg) >= 2:
+                out.append(Trajectory(p[seg], v[seg], t[seg], nxt))
+                nxt += 1
+    return out, ncuts
+
+
+def clean_trajectories(trajid, time, pos, settings, log=print):
+    """Run the cleaning chain (module docstring) on flat tracker output.
+
+    Arguments:
+    trajid, time, pos - (N,), (N,), (N, 3) one row per point, pos in metres.
+    settings - complete settings, e.g. from :func:`resolve_settings`.
+    log - callable for progress lines, or None for silence.
+
+    Returns:
+    list of smoothed :class:`~flowtracks.trajectory.Trajectory` objects.
+    """
+    log = log or (lambda *a, **k: None)
+    c = settings
+    fps, sgw, sgo = c["fps"], c["sg_window"], c["sg_order"]
+    tj, rep = repair_arrays(
+        trajid, time, pos, max_gap=c["repair_max_gap"],
+        max_distance=c["repair_max_distance_mm"] * 1e-3,
+        link_percentile=c["repair_link_percentile"], cut=c["repair_cut"],
+        attach=c["repair_attach"], join=c["repair_join"],
+        cut_factor=c["repair_cut_factor"])
+    log(f"repair: cut={rep.get('links_cut')} joins={rep.get('joins')}")
+    s1 = savitzky_golay(trajectories_from_arrays(tj, time, pos), fps, sgw, sgo,
+                        min_window=5)
+    split, ncuts = kink_split(s1, c["kink_deg"], c["kink_step_mm"] / 1000.0)
+    log(f"kinksplit(>{c['kink_deg']}deg, steps>{c['kink_step_mm']}mm): "
+        f"{len(s1)} -> {len(split)} objs, {ncuts} cuts")
+    s2 = savitzky_golay(split, fps, sgw, sgo, min_window=5)
+    st = stitch_trajectories(s2, fps=fps, max_gap=c["gap1"],
+                             max_distance=c["dist1"], max_vel_diff=c["vd1"])
+    s2b = savitzky_golay(st, fps, sgw, sgo, min_window=5)
+    split2, _ = kink_split(s2b, c["kink_deg"], c["kink_step_mm"] / 1000.0,
+                           fresh_start=20_000_000)
+    s2c = savitzky_golay(split2, fps, sgw, sgo, min_window=5)
+    st2 = stitch_trajectories(s2c, fps=fps, max_gap=c["gap2"],
+                              max_distance=c["dist2"], max_vel_diff=c["vd2"])
+    if c["win_long"] > 0:
+        short = [t for t in st2 if len(t) < c["len_long"]]
+        long = [t for t in st2 if len(t) >= c["len_long"]]
+        s_short = savitzky_golay(short, fps, sgw, sgo, min_window=5)
+        s_long = savitzky_golay(long, fps, c["win_long"], c["order_long"],
+                                min_window=7)
+        out = s_short + s_long
+        log(f"two-tier final smooth: {len(s_short)}x({sgw},{sgo}) + {len(s_long)}x"
+            f"({c['win_long']},{c['order_long']})")
+    else:
+        out = savitzky_golay(st2, fps, sgw, sgo, min_window=5)
+    lens = np.array([len(t) for t in out]) if out else np.zeros(1, int)
+    log(f"final: n={len(out)} joined1={len(s2) - len(st)} "
+        f"joined2={len(s2c) - len(st2)} med={np.median(lens):.0f} "
+        f"max={lens.max()} rows={lens.sum()}")
+    return out

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/merge.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Alex Liberzon
+"""
+Merging trajectory datasets of two camera systems that see a common volume.
+
+Two systems (two camera rigs, two recordings of one rig) each produce their
+own trajectories in their own coordinate frame. Where their volumes overlap
+the same particle appears twice. This module
+
+1. measures the rigid map between the two frames from particles both systems
+   see in the same frame (:func:`estimate_rigid_map`): for each candidate
+   rotation, the same-frame neighbour differences pile up at the true offset;
+   the rotation whose pile is sharpest wins and the offset is refined on tight
+   pairs. No sharp pile means no common particles, and it refuses
+   (ValueError) rather than guess;
+2. maps points of the second system into the first (:func:`apply_rigid`);
+3. finds the trajectory pairs that share same-frame points closer than a
+   tolerance (:func:`overlap_counts`), each trajectory's best partner
+   (:func:`best_partners`) and the duplicates a keep-the-longer rule removes
+   (:func:`duplicates`).
+
+Units are whatever the inputs use; tolerances are in the same unit.
+"""
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+
+def estimate_rigid_map(pairs, rotations, search_radius=150.0, bin_size=6.0,
+                       tight=8.0, min_peak=50, min_ratio=100.0, refine=2,
+                       log=print):
+    """Rigid map from system B to system A: ``p_A = R @ p_B - offset``.
+
+    Arguments:
+    pairs - list of (points_A, points_B) arrays, (n, 3) and (m, 3), each pair
+        taken in the same frame (use well-triangulated points only).
+    rotations - list of (label, 3x3 matrix) candidates for R.
+    search_radius - neighbours of a point of A within this distance of the
+        rotated B points vote for the offset.
+    bin_size - histogram bin of the votes; the offset is the densest bin.
+    tight - pairs closer than this after the first estimate refine it.
+    min_peak, min_ratio - the densest bin must hold at least ``min_peak``
+        votes and ``min_ratio`` times the mean, or the map is refused.
+    refine - number of refinement passes (median of the tight pairs).
+    log - callable for progress lines, or None.
+
+    Returns:
+    dict with matrix (3x3), offset (3,), label of the chosen rotation,
+    n_pairs (tight pairs of the last pass) and spread (median absolute
+    deviation of their differences, per axis).
+    """
+    log = log or (lambda *a, **k: None)
+    nbins = int(round(2 * search_radius / bin_size))
+    best = None
+    for label, M in rotations:
+        M = np.asarray(M, dtype=float)
+        diffs = []
+        for pa, pb in pairs:
+            if not len(pa) or not len(pb):
+                continue
+            pbm = pb @ M.T
+            for k, js in enumerate(cKDTree(pbm).query_ball_point(pa, search_radius)):
+                if js:
+                    diffs.append(pbm[js] - pa[k])
+        if not diffs:
+            continue
+        d = np.vstack(diffs)
+        H, edges = np.histogramdd(d, bins=nbins,
+                                  range=[(-search_radius, search_radius)] * 3)
+        i = np.unravel_index(H.argmax(), H.shape)
+        peak = np.array([edges[k][i[k]] + bin_size / 2 for k in range(3)])
+        score = H.max() / max(H.mean(), 1e-9)
+        log(f"  rotation {label}: densest {bin_size:g} bin {int(H.max())} "
+            f"({score:.0f}x the mean)")
+        if best is None or H.max() > best[1]:
+            best = (M, H.max(), score, peak, label)
+    if best is None or best[1] < min_peak or best[2] < min_ratio:
+        raise ValueError("no common particles between the two systems")
+    M, _, _, off, label = best
+    for _ in range(refine):
+        dd = []
+        for pa, pb in pairs:
+            if not len(pa) or not len(pb):
+                continue
+            q = pb @ M.T - off
+            dist, j = cKDTree(q).query(pa, distance_upper_bound=tight)
+            ok = np.isfinite(dist)
+            dd.append(pb[j[ok]] @ M.T - pa[ok])
+        dd = np.vstack(dd)
+        off = np.median(dd, axis=0)
+    spread = np.median(np.abs(dd - off), axis=0)
+    log(f"  B -> A: rotation {label}, offset {np.round(off, 2)}, "
+        f"{len(dd)} pairs, spread (MAD) {np.round(spread, 2)}")
+    return dict(matrix=M, offset=off, label=label, n_pairs=len(dd), spread=spread)
+
+
+def apply_rigid(points, matrix, offset=0.0):
+    """``points @ matrix.T - offset``: system-B points (or, with offset 0,
+    velocities and accelerations) in system A's frame."""
+    return np.asarray(points, dtype=float) @ np.asarray(matrix).T - offset
+
+
+def overlap_counts(tracks_a, tracks_b, tol):
+    """Same-frame shared points of every trajectory pair of A and B.
+
+    Arguments:
+    tracks_a, tracks_b - mappings id -> mapping with "time" (n,) and "pos"
+        (n, 3), both in one frame of reference.
+    tol - a point of A and the nearest point of B in the same frame closer
+        than this count as shared.
+
+    Returns:
+    {(id_a, id_b): number of shared points}
+    """
+    bframe = {}
+    for tid, t in tracks_b.items():
+        for f, p in zip(t["time"], t["pos"]):
+            bframe.setdefault(int(f), []).append((tid, p))
+    btree = {f: (cKDTree(np.array([p for _, p in v])), v) for f, v in bframe.items()}
+    shared = {}
+    for tid, t in tracks_a.items():
+        for f, p in zip(t["time"], t["pos"]):
+            if int(f) not in btree:
+                continue
+            tree, v = btree[int(f)]
+            dist, j = tree.query(p, k=1)
+            if dist < tol:
+                key = (tid, v[j][0])
+                shared[key] = shared.get(key, 0) + 1
+    return shared
+
+
+def best_partners(shared):
+    """Each trajectory's partner in the other system: the one it shares most
+    points with. Returns ({id_a: (id_b, n)}, {id_b: (id_a, n)})."""
+    partner_a, partner_b = {}, {}
+    for (atid, btid), n in shared.items():
+        if n > partner_a.get(atid, (None, 0))[1]:
+            partner_a[atid] = (btid, n)
+        if n > partner_b.get(btid, (None, 0))[1]:
+            partner_b[btid] = (atid, n)
+    return partner_a, partner_b
+
+
+def duplicates(shared, len_a, len_b):
+    """Ids of B trajectories that share any point with an A trajectory at
+    least as long (``len_a``, ``len_b``: id -> number of points). Dropping
+    them keeps one copy of every overlapping particle, the longer one, and
+    A on ties."""
+    return {btid for (atid, btid) in shared if len_a[atid] >= len_b[btid]}

{flowtracks-1.6.2.dev6.dist-info → flowtracks-1.6.2.dev12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev6
+Version: 1.6.2.dev12
 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.dev12.dist-info/RECORD

@@ -0,0 +1,55 @@
+flowtracks/__init__.py,sha256=iCexskmRtpNJ0fNZWRFkQAqrku7csbKy5NtL2YQNYeo,1532
+flowtracks/_version.py,sha256=MhSZ23Xb3S2pgcATsSw3UWCpsNnTFAH_LfLqatUUdYs,543
+flowtracks/an_scene.py,sha256=QV_gtzp-5h1CqAW1Y6ieGco9BxXQDE4f_7-fcy3fluI,7361
+flowtracks/analysis.py,sha256=nob5-pKxjPzB34_oQsxmxYALz4Q_s1BTpC5_VgXX3ss,6320
+flowtracks/clean.py,sha256=IFwyoR7IfA98u0jjqp99EyeRqA1sOVlEiNH9My-pjzg,9055
+flowtracks/combine.py,sha256=-UQtbTH4vjQS88_92h5UZlS60OfQofTWEV6SL1prXgI,4455
+flowtracks/eulerian.py,sha256=PMt0_TtjrFwRPEvSEKm_wn8YZdClSux4yXEuxiB2EjM,41872
+flowtracks/flux.py,sha256=w4K_jjDWTBIOj4BkoeNoKjIRcvg_6stCqNF8iivxF-A,15137
+flowtracks/format_docstrings.py,sha256=iJVJmtTUYEDEcmF5XSRZ08zpvlVc9lU66CZeqSpEKic,1987
+flowtracks/future_idea_xarray_dask_zarr.py,sha256=4ZS6QuZ2s_sUaiCW0XBo74GrP5fw_clVyhWNjT5gbds,6101
+flowtracks/graphics.py,sha256=PMyfYPedfBumIJ9cPeTCukkFFPGNr9lyq49BsOyVBzA,23750
+flowtracks/interpolation.py,sha256=njuB-bvWK5M2tc2Ibm6ZWNg6Tm6H-PTn0a63IldlJaA,39414
+flowtracks/io.py,sha256=sujLgtY8WIymMZugDv2jlQeL9QR_hZn-MaZPPKsAPvA,48366
+flowtracks/merge.py,sha256=hg5sYw2oL1YuxpbefiYAESUThKaAXs00RcsV9StIjSc,6445
+flowtracks/nhist.py,sha256=3xdrfSTSpTojXJcyhwBgagHBmKrm0U_AEsP3BjP9H1o,4089
+flowtracks/pairs.py,sha256=ehYDDTmjeRuzkSAMpdlwnwwAZOPNLKGF_e5HmcKw-2g,4034
+flowtracks/particle.py,sha256=sVng1X8Xp3V9_wgJK2EGsDEx1OFQjd3L63Fzn--MWkM,671
+flowtracks/phase_average.py,sha256=jjtrHYg0ukGRnJtRawJ6sWhdyrlV_16qBLlfNVxEQHw,3035
+flowtracks/phasing.py,sha256=us7WfMYrx6dCCPNwucvN34G_0A7EKS9ieH1TrnpwM0I,4320
+flowtracks/pipeline.py,sha256=0wOeeFqQGN_Lhgq-QFeQNg0oEKtJSGDhhZdv81M1PDg,5167
+flowtracks/provenance.py,sha256=8L2BXmLdBcZRncUkr8oJbeU5JKdebj1Cgxrbzdy5o7A,2115
+flowtracks/repair.py,sha256=rxaE1hcxQjNx19tLJOhL619lSfkB7Kfh6kXpJ_fSMfg,19122
+flowtracks/scene.py,sha256=ovR1wXmgLGB9mZo62NPkcgxUzhlqiEcItLYJINAl2zk,19622
+flowtracks/sequence.py,sha256=u_HOev5YydpgoknPQ1lB2WUG5ZZKSu_u9ySNGUu9D38,12984
+flowtracks/smoothing.py,sha256=wXlvi3RBN6iZgaQRAVOxprhsjLMlxc4JIcuQMpRCQvs,7376
+flowtracks/stitching.py,sha256=HFsIRdAfqyhmES1OwIFslyWTF9U7kPJ5OKtjBl4YWqA,16895
+flowtracks/trajectory.py,sha256=uL4-byZ2tycdrAwGoET4AfLHuKaWRnc8VHLO5zv9MOg,11831
+flowtracks/vortex.py,sha256=4lG3QkvvnWhAHy4tl1pJrBGFLdrlP4pxNdhCZI1VZ4Q,2529
+flowtracks/wall_shear.py,sha256=k9Q5FEchIO9J_onXPOw4PNJQfmsrSyVVvX4RdW-rQlE,6788
+flowtracks/writers.py,sha256=0LnRiuqmyhcw8Ju3v9vCOERymNmxHG7cXKy6r8uLOTo,10358
+flowtracks/zarr_scene.py,sha256=PKCtiTT1t0Hj74Q572ra5DM3uM8lQK1A6DzzfUxvIzI,10468
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/batch_Lagrangian_to_Eulerian.py,sha256=e7mQFqyqvCeAHRKiN1IaxdNJi0e2FU84c7QNrx0L-m0,2296
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/hdf5_scene_analysis.ipynb,sha256=jn0Z_ZVL1-iXaiKXwyAeb74NbXsBpnocCxCSDh814eU,243097
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/linking_trajectories.ipynb,sha256=udz0GLDiPv68BYySg4yO1HWzaB9Sdy3YA3IhnIHDeII,8820
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_dual_rig_trajectories.py,sha256=dzeK0C-knwq1bPOwo0p1RhWrb0RPp-T31rBaGEptXcc,6737
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_flowtracks.py,sha256=7FIJNwBx9aBRmaM5ofmYTXSWEjE0wZqDfs8J47Tmw6U,9440
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_hdf5_vs_zarr_scene_analysis.py,sha256=bjXlMsLJTxJ0JkvGcVZbuDOFYZU4OvdabtDUgqb15So,4536
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_linking_trajectories_zarr.py,sha256=Ny_WUbiZWo0aKw-u2KGFWrhMv-8BvNgBy0UHIqCobYg,8210
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_phase_averaging_demo.py,sha256=vg6j2ayKGl-5uj08bdzzb6pujzJJQ_5bUsG7UuPP7dM,9270
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_phase_metrics.py,sha256=kBc2e_b-orDrm3AnuUXCcxsvmfQWyCtE826pFeolMGE,9367
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_vtk_writers_preview.py,sha256=Otrhhp-QFf6F94EOs6rWu5xOCpbS16EfWy_iMFp7e_I,14611
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/marimo_zarr_dashboard.py,sha256=jVIum6hdEelH4ef7vRgsfLhrbmMsuErsJBzxrnEImnw,9268
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/repeated_interpolation.ipynb,sha256=t9SfoIWRu5XP0SrphWbQy508uzyEibVz61FGjl51fjA,8861
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/run_pipeline.py,sha256=5fGE2tIP6XjFZ1sEYmqBujuLaXFfRL-rNnbr2p2CDfM,7205
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/visualize_marimo.py,sha256=jWrg5IWjY-bmSQwQjaO5qTr0t_G48CsqJYpevdQrxeY,13026
+flowtracks-1.6.2.dev12.data/data/flowtracks-examples/visualize_results.py,sha256=SbPg3EoDcuIyo0rUz3E-AnT4sLWDVJFhgC6xVcracW4,7583
+flowtracks-1.6.2.dev12.data/scripts/analyse_fhdf.py,sha256=QH08NdImGukTEGuZEKFxjStcSelXBv-8A-22G6KtXqM,1315
+flowtracks-1.6.2.dev12.dist-info/licenses/LICENSE.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev12.dist-info/licenses/LICENSES/BSD-3-Clause.txt,sha256=XiJR9O5snDB6sAz0bcncOU6msceZgjPRxejWEQGg40Q,1505
+flowtracks-1.6.2.dev12.dist-info/licenses/LICENSES/GPL-3.0-only.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev12.dist-info/METADATA,sha256=xq3JCpam1JKUGzMP8oeAQAaLdiRoF5LjVsH5nwQytz0,4774
+flowtracks-1.6.2.dev12.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flowtracks-1.6.2.dev12.dist-info/entry_points.txt,sha256=U6028E7yQZQiZoXWMl7w4xgZUPwPxAGiAuuMB__c-yQ,60
+flowtracks-1.6.2.dev12.dist-info/top_level.txt,sha256=cR54RNb9y2Wfr_BfuOezmNJOMB4GfIHh1-luXTREnQA,11
+flowtracks-1.6.2.dev12.dist-info/RECORD,,

flowtracks-1.6.2.dev6.dist-info/RECORD

@@ -1,53 +0,0 @@
-flowtracks/__init__.py,sha256=iCexskmRtpNJ0fNZWRFkQAqrku7csbKy5NtL2YQNYeo,1532
-flowtracks/_version.py,sha256=-2KICqAEdPWLo6oH9F7DHgtleuBtdR0ws16EQh2o6wM,541
-flowtracks/an_scene.py,sha256=QV_gtzp-5h1CqAW1Y6ieGco9BxXQDE4f_7-fcy3fluI,7361
-flowtracks/analysis.py,sha256=nob5-pKxjPzB34_oQsxmxYALz4Q_s1BTpC5_VgXX3ss,6320
-flowtracks/combine.py,sha256=-UQtbTH4vjQS88_92h5UZlS60OfQofTWEV6SL1prXgI,4455
-flowtracks/eulerian.py,sha256=PMt0_TtjrFwRPEvSEKm_wn8YZdClSux4yXEuxiB2EjM,41872
-flowtracks/flux.py,sha256=w4K_jjDWTBIOj4BkoeNoKjIRcvg_6stCqNF8iivxF-A,15137
-flowtracks/format_docstrings.py,sha256=iJVJmtTUYEDEcmF5XSRZ08zpvlVc9lU66CZeqSpEKic,1987
-flowtracks/future_idea_xarray_dask_zarr.py,sha256=4ZS6QuZ2s_sUaiCW0XBo74GrP5fw_clVyhWNjT5gbds,6101
-flowtracks/graphics.py,sha256=ulMTpPRGzQanAjna480XLMMQJL92Q4Wdtky8inqnwtE,13909
-flowtracks/interpolation.py,sha256=njuB-bvWK5M2tc2Ibm6ZWNg6Tm6H-PTn0a63IldlJaA,39414
-flowtracks/io.py,sha256=sujLgtY8WIymMZugDv2jlQeL9QR_hZn-MaZPPKsAPvA,48366
-flowtracks/nhist.py,sha256=3xdrfSTSpTojXJcyhwBgagHBmKrm0U_AEsP3BjP9H1o,4089
-flowtracks/pairs.py,sha256=ehYDDTmjeRuzkSAMpdlwnwwAZOPNLKGF_e5HmcKw-2g,4034
-flowtracks/particle.py,sha256=sVng1X8Xp3V9_wgJK2EGsDEx1OFQjd3L63Fzn--MWkM,671
-flowtracks/phase_average.py,sha256=jjtrHYg0ukGRnJtRawJ6sWhdyrlV_16qBLlfNVxEQHw,3035
-flowtracks/phasing.py,sha256=us7WfMYrx6dCCPNwucvN34G_0A7EKS9ieH1TrnpwM0I,4320
-flowtracks/pipeline.py,sha256=0wOeeFqQGN_Lhgq-QFeQNg0oEKtJSGDhhZdv81M1PDg,5167
-flowtracks/provenance.py,sha256=8L2BXmLdBcZRncUkr8oJbeU5JKdebj1Cgxrbzdy5o7A,2115
-flowtracks/repair.py,sha256=rxaE1hcxQjNx19tLJOhL619lSfkB7Kfh6kXpJ_fSMfg,19122
-flowtracks/scene.py,sha256=ovR1wXmgLGB9mZo62NPkcgxUzhlqiEcItLYJINAl2zk,19622
-flowtracks/sequence.py,sha256=u_HOev5YydpgoknPQ1lB2WUG5ZZKSu_u9ySNGUu9D38,12984
-flowtracks/smoothing.py,sha256=wXlvi3RBN6iZgaQRAVOxprhsjLMlxc4JIcuQMpRCQvs,7376
-flowtracks/stitching.py,sha256=HFsIRdAfqyhmES1OwIFslyWTF9U7kPJ5OKtjBl4YWqA,16895
-flowtracks/trajectory.py,sha256=uL4-byZ2tycdrAwGoET4AfLHuKaWRnc8VHLO5zv9MOg,11831
-flowtracks/vortex.py,sha256=4lG3QkvvnWhAHy4tl1pJrBGFLdrlP4pxNdhCZI1VZ4Q,2529
-flowtracks/wall_shear.py,sha256=k9Q5FEchIO9J_onXPOw4PNJQfmsrSyVVvX4RdW-rQlE,6788
-flowtracks/writers.py,sha256=0LnRiuqmyhcw8Ju3v9vCOERymNmxHG7cXKy6r8uLOTo,10358
-flowtracks/zarr_scene.py,sha256=PKCtiTT1t0Hj74Q572ra5DM3uM8lQK1A6DzzfUxvIzI,10468
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/batch_Lagrangian_to_Eulerian.py,sha256=e7mQFqyqvCeAHRKiN1IaxdNJi0e2FU84c7QNrx0L-m0,2296
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/hdf5_scene_analysis.ipynb,sha256=jn0Z_ZVL1-iXaiKXwyAeb74NbXsBpnocCxCSDh814eU,243097
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/linking_trajectories.ipynb,sha256=udz0GLDiPv68BYySg4yO1HWzaB9Sdy3YA3IhnIHDeII,8820
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_dual_rig_trajectories.py,sha256=dzeK0C-knwq1bPOwo0p1RhWrb0RPp-T31rBaGEptXcc,6737
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_flowtracks.py,sha256=7FIJNwBx9aBRmaM5ofmYTXSWEjE0wZqDfs8J47Tmw6U,9440
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_hdf5_vs_zarr_scene_analysis.py,sha256=bjXlMsLJTxJ0JkvGcVZbuDOFYZU4OvdabtDUgqb15So,4536
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_linking_trajectories_zarr.py,sha256=Ny_WUbiZWo0aKw-u2KGFWrhMv-8BvNgBy0UHIqCobYg,8210
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_phase_averaging_demo.py,sha256=vg6j2ayKGl-5uj08bdzzb6pujzJJQ_5bUsG7UuPP7dM,9270
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_phase_metrics.py,sha256=kBc2e_b-orDrm3AnuUXCcxsvmfQWyCtE826pFeolMGE,9367
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_vtk_writers_preview.py,sha256=Otrhhp-QFf6F94EOs6rWu5xOCpbS16EfWy_iMFp7e_I,14611
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/marimo_zarr_dashboard.py,sha256=jVIum6hdEelH4ef7vRgsfLhrbmMsuErsJBzxrnEImnw,9268
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/repeated_interpolation.ipynb,sha256=t9SfoIWRu5XP0SrphWbQy508uzyEibVz61FGjl51fjA,8861
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/run_pipeline.py,sha256=5fGE2tIP6XjFZ1sEYmqBujuLaXFfRL-rNnbr2p2CDfM,7205
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/visualize_marimo.py,sha256=jWrg5IWjY-bmSQwQjaO5qTr0t_G48CsqJYpevdQrxeY,13026
-flowtracks-1.6.2.dev6.data/data/flowtracks-examples/visualize_results.py,sha256=SbPg3EoDcuIyo0rUz3E-AnT4sLWDVJFhgC6xVcracW4,7583
-flowtracks-1.6.2.dev6.data/scripts/analyse_fhdf.py,sha256=QH08NdImGukTEGuZEKFxjStcSelXBv-8A-22G6KtXqM,1315
-flowtracks-1.6.2.dev6.dist-info/licenses/LICENSE.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
-flowtracks-1.6.2.dev6.dist-info/licenses/LICENSES/BSD-3-Clause.txt,sha256=XiJR9O5snDB6sAz0bcncOU6msceZgjPRxejWEQGg40Q,1505
-flowtracks-1.6.2.dev6.dist-info/licenses/LICENSES/GPL-3.0-only.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
-flowtracks-1.6.2.dev6.dist-info/METADATA,sha256=jdbbG4k4qcw6lRlEaa1CvQrpWv21S7wDBffoIcyH3Cs,4773
-flowtracks-1.6.2.dev6.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-flowtracks-1.6.2.dev6.dist-info/entry_points.txt,sha256=U6028E7yQZQiZoXWMl7w4xgZUPwPxAGiAuuMB__c-yQ,60
-flowtracks-1.6.2.dev6.dist-info/top_level.txt,sha256=cR54RNb9y2Wfr_BfuOezmNJOMB4GfIHh1-luXTREnQA,11
-flowtracks-1.6.2.dev6.dist-info/RECORD,,