flowtracks 1.6.2.dev11__tar.gz → 1.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev11
+Version: 1.7.0
 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.7.0/doc/clean.rst

@@ -0,0 +1,29 @@
+Cleaning chain
+==============
+
+:func:`flowtracks.clean.clean_trajectories` turns raw tracker output (one row
+per point with a trajectory id, positions in metres) into smooth trajectories
+in one call: :doc:`repair <repair>`, Savitzky-Golay smoothing, a split at
+fast violent turns the repair missed, two stitching passes (the second
+tighter) with smoothing in between, and a final smoothing.
+
+Every setting has a default in :data:`flowtracks.clean.CLEAN_DEFAULTS` except
+the frame rate, which must be stated. :func:`flowtracks.clean.resolve_settings`
+merges a parameter-file section and explicit overrides onto the defaults and
+reports where each value came from, so nothing is hidden in a script:
+
+.. code:: python
+
+   from flowtracks.clean import clean_trajectories, resolve_settings
+   from flowtracks.io import save_zarr_trajectories
+
+   settings, sources = resolve_settings(yaml_section, {"gap1": 8})
+   trajs = clean_trajectories(trajid, frame, pos, settings)
+   save_zarr_trajectories(trajs, "clean.zarr", overwrite=True)
+
+The pieces are usable on their own: :func:`flowtracks.clean.trajectories_from_arrays`
+(flat arrays to :class:`~flowtracks.trajectory.Trajectory` objects) and
+:func:`flowtracks.clean.kink_split`.
+
+.. automodule:: flowtracks.clean
+   :members:

{flowtracks-1.6.2.dev11 → flowtracks-1.7.0}/doc/index.rst

@@ -28,6 +28,8 @@ Contents:
    graphics
    smoothing
    repair
+   clean
+   merge
    pairs
    scene
    analysis

flowtracks-1.7.0/doc/merge.rst

@@ -0,0 +1,34 @@
+Merging two camera systems
+==========================
+
+When two camera systems (two rigs, or two recordings) see a common volume,
+each produces its own trajectories in its own frame and the particles in the
+overlap appear twice. :mod:`flowtracks.merge` provides the generic steps:
+
+1. :func:`~flowtracks.merge.estimate_rigid_map` measures the rigid map between
+   the two frames from particles both systems see in the same frame. For each
+   candidate rotation the same-frame neighbour differences pile up at the true
+   offset; the sharpest pile wins and the offset is refined on tight pairs. With
+   no sharp pile it refuses (``ValueError``) rather than guess.
+2. :func:`~flowtracks.merge.apply_rigid` maps the second system's positions
+   (and, with zero offset, velocities and accelerations) into the first.
+3. :func:`~flowtracks.merge.overlap_counts` counts the same-frame shared points
+   of every trajectory pair; :func:`~flowtracks.merge.best_partners` gives each
+   trajectory its partner and :func:`~flowtracks.merge.duplicates` the
+   second-system trajectories a keep-the-longer rule removes.
+
+.. code:: python
+
+   from flowtracks.merge import (apply_rigid, best_partners, duplicates,
+                                 estimate_rigid_map, overlap_counts)
+
+   rig = estimate_rigid_map(same_frame_point_pairs,
+                            [("0", np.eye(3)), ("180", np.diag([-1, 1, -1]))])
+   pos_b_in_a = apply_rigid(pos_b, rig["matrix"], rig["offset"])
+   shared = overlap_counts(tracks_a, tracks_b, tol=20.0)
+
+A complete use, with the facility's own frame, walls and output layout, is
+``scripts/illmenau/merge_dual_rig.py`` in openptv2.
+
+.. automodule:: flowtracks.merge
+   :members:

{flowtracks-1.6.2.dev11 → flowtracks-1.7.0}/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.dev11'
-__version_tuple__ = version_tuple = (1, 6, 2, 'dev11')
+__version__ = version = '1.7.0'
+__version_tuple__ = version_tuple = (1, 7, 0)
 
-__commit_id__ = commit_id = 'g5e011b439'
+__commit_id__ = commit_id = 'g4ea7448e5'

flowtracks-1.7.0/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-1.7.0/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.dev11 → flowtracks-1.7.0}/flowtracks.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev11
+Version: 1.7.0
 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.dev11 → flowtracks-1.7.0}/flowtracks.egg-info/SOURCES.txt

@@ -457,12 +457,14 @@ data/tracers.zarr/trajectories/vel/c/3/0
 data/tracers.zarr/trajectories/vel/c/3/1
 doc/an_scene.rst
 doc/analysis.rst
+doc/clean.rst
 doc/conf.py
 doc/datastruct.rst
 doc/graphics.rst
 doc/index.rst
 doc/interpolation.rst
 doc/io.rst
+doc/merge.rst
 doc/pairs.rst
 doc/particle.rst
 doc/repair.rst
@@ -718,6 +720,7 @@ flowtracks/__init__.py
 flowtracks/_version.py
 flowtracks/an_scene.py
 flowtracks/analysis.py
+flowtracks/clean.py
 flowtracks/combine.py
 flowtracks/eulerian.py
 flowtracks/flux.py
@@ -726,6 +729,7 @@ flowtracks/future_idea_xarray_dask_zarr.py
 flowtracks/graphics.py
 flowtracks/interpolation.py
 flowtracks/io.py
+flowtracks/merge.py
 flowtracks/nhist.py
 flowtracks/pairs.py
 flowtracks/particle.py
@@ -760,6 +764,7 @@ tests/conftest.py
 tests/helpers.py
 tests/test_analysis.py
 tests/test_binning_equivalence.py
+tests/test_clean.py
 tests/test_derived_fields.py
 tests/test_eulerian_grid.py
 tests/test_eulerian_upgrades.py
@@ -768,6 +773,7 @@ tests/test_graphics_3d.py
 tests/test_idw_call.py
 tests/test_interp.py
 tests/test_io.py
+tests/test_merge.py
 tests/test_nhist.py
 tests/test_phase_align_synthetic_sets.py
 tests/test_phase_average_xr.py

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

@@ -455,12 +455,14 @@
     "doc/_static/repeated_interpolation.html",
     "doc/an_scene.rst",
     "doc/analysis.rst",
+    "doc/clean.rst",
     "doc/conf.py",
     "doc/datastruct.rst",
     "doc/graphics.rst",
     "doc/index.rst",
     "doc/interpolation.rst",
     "doc/io.rst",
+    "doc/merge.rst",
     "doc/pairs.rst",
     "doc/particle.rst",
     "doc/repair.rst",
@@ -713,6 +715,7 @@
     "flowtracks/__init__.py",
     "flowtracks/an_scene.py",
     "flowtracks/analysis.py",
+    "flowtracks/clean.py",
     "flowtracks/combine.py",
     "flowtracks/eulerian.py",
     "flowtracks/flux.py",
@@ -721,6 +724,7 @@
     "flowtracks/graphics.py",
     "flowtracks/interpolation.py",
     "flowtracks/io.py",
+    "flowtracks/merge.py",
     "flowtracks/nhist.py",
     "flowtracks/pairs.py",
     "flowtracks/particle.py",
@@ -753,6 +757,7 @@
     "tests/helpers.py",
     "tests/test_analysis.py",
     "tests/test_binning_equivalence.py",
+    "tests/test_clean.py",
     "tests/test_derived_fields.py",
     "tests/test_eulerian_grid.py",
     "tests/test_eulerian_upgrades.py",
@@ -761,6 +766,7 @@
     "tests/test_idw_call.py",
     "tests/test_interp.py",
     "tests/test_io.py",
+    "tests/test_merge.py",
     "tests/test_nhist.py",
     "tests/test_phase_align_synthetic_sets.py",
     "tests/test_phase_average_xr.py",

flowtracks-1.7.0/flowtracks.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.7.0",
+  "distance": 0,
+  "node": "g4ea7448e5a3f9d854c567b42be097caee8b9aa84",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-11"
+}

flowtracks-1.7.0/tests/test_clean.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileCopyrightText: Alex Liberzon
+import numpy as np
+import pytest
+
+from flowtracks.clean import (
+    CLEAN_DEFAULTS,
+    clean_trajectories,
+    kink_split,
+    resolve_settings,
+    trajectories_from_arrays,
+)
+from flowtracks.trajectory import Trajectory
+
+
+def test_resolve_settings_defaults_section_overrides_and_sources():
+    s, src = resolve_settings({"fps": 10, "gap1": 6}, {"gap1": 4, "vd1": None},
+                              source_name="p.yaml")
+    assert s["fps"] == 10.0 and isinstance(s["fps"], float)
+    assert (s["gap1"], src["gap1"]) == (4, "override")
+    assert (s["vd1"], src["vd1"]) == (CLEAN_DEFAULTS["vd1"], "default")
+    assert src["fps"] == "p.yaml"
+    assert set(s) == set(CLEAN_DEFAULTS)
+
+
+def test_resolve_settings_refuses_unknown_keys_and_missing_fps():
+    with pytest.raises(ValueError, match="unknown"):
+        resolve_settings({"fps": 10, "gapp1": 3})
+    with pytest.raises(ValueError, match="fps"):
+        resolve_settings({"gap1": 3})
+
+
+def test_trajectories_from_arrays_groups_orders_and_drops_single_points():
+    trajid = np.array([7, 3, 7, 3, 9, 7])
+    time = np.array([2, 1, 0, 0, 5, 1])
+    pos = np.arange(18.0).reshape(6, 3)
+    trajs = trajectories_from_arrays(trajid, time, pos)
+    assert [t.trajid() for t in trajs] == [3, 7]
+    assert trajs[1].time().tolist() == [0, 1, 2]
+    assert np.array_equal(trajs[1].pos(), pos[[2, 5, 0]])
+
+
+def test_kink_split_cuts_a_fast_reversal_into_fresh_ids():
+    n, step = 10, np.array([0.03, 0.0, 0.0])
+    v = np.r_[np.tile(step, (n, 1)), np.tile(-step, (n, 1))]
+    p = np.cumsum(np.r_[[np.zeros(3)], v[:-1]], axis=0)  # out and straight back
+    t = np.arange(2 * n)
+    out, ncuts = kink_split([Trajectory(p, v, t, 1)], 90.0, 0.025, fresh_start=100)
+    assert ncuts == 1
+    assert [o.trajid() for o in out] == [100, 101]
+    assert sum(len(o) for o in out) == 2 * n
+    slow = Trajectory(p / 10, v / 10, t, 2)
+    assert kink_split([slow], 90.0, 0.025)[1] == 0  # short steps: noise, kept
+
+
+def test_clean_trajectories_stitches_a_broken_track_and_smooths():
+    rng = np.random.default_rng(0)
+    fps = 10.0
+    step = np.array([0.01, 0.0, 0.0])  # 0.1 m/s
+    t = np.arange(60)
+    truth = np.outer(t, step)
+    keep = (t < 25) | (t > 28)  # four missing frames
+    pos = truth[keep] + rng.normal(0, 1e-5, (keep.sum(), 3))
+    trajid = np.where(t[keep] < 25, 1, 2)
+    settings, _ = resolve_settings({"fps": fps})
+    out = clean_trajectories(trajid, t[keep], pos, settings, log=None)
+    assert len(out) == 1
+    tr = out[0]
+    assert (tr.time()[0], tr.time()[-1]) == (0, 59)  # the gap is bridged
+    assert np.allclose(tr.velocity()[5:-5], step * fps, atol=2e-3)