flowtracks 1.6.2.dev1__tar.gz → 1.6.2.dev4__tar.gz

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev1
+Version: 1.6.2.dev4
 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.dev1 → flowtracks-1.6.2.dev4}/flowtracks/__init__.py

@@ -21,6 +21,12 @@ from flowtracks.eulerian import (
     save_zarr,
 )
 from flowtracks.phase_average import fluctuations, phase_average
+from flowtracks.phasing import (
+    assign_bins,
+    bin_of_frame,
+    phase_of_frame,
+    validate_bins,
+)
 from flowtracks.smoothing import savitzky_golay
 from flowtracks.stitching import stitch_trajectories
 from flowtracks.writers import (
@@ -41,6 +47,10 @@ __all__ = [
     "finite_difference_velocity",
     "phase_average",
     "fluctuations",
+    "validate_bins",
+    "assign_bins",
+    "phase_of_frame",
+    "bin_of_frame",
     "derived_fields",
     "save_zarr",
     "save_dataset",

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/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.dev1'
-__version_tuple__ = version_tuple = (1, 6, 2, 'dev1')
+__version__ = version = '1.6.2.dev4'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev4')
 
-__commit_id__ = commit_id = 'g343cf68fa'
+__commit_id__ = commit_id = 'gc00cb25a5'

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/flowtracks/eulerian.py

@@ -128,11 +128,12 @@ def _bin_counts_sums_ceil(pos, vel, ti, mins, deltas, shape):
     return counts, sums
 
 
-def eulerian_grid(scene, grid_params, first, last, cycletime,
+def eulerian_grid(scene, grid_params, first, last, cycletime=None,
                   deltat=90, base_time=100000, min_count=50,
                   smoothing_sigma=None, *, fill_value=float("nan"),
                   qc=None, chunk_frames=None, add_valid=True, fin=None,
-                  voxel_rule="half-open") -> xr.Dataset:
+                  voxel_rule="half-open", n_frames_in_period=None,
+                  n_phases=None, phase_zero_frame=None) -> xr.Dataset:
     """Bin Lagrangian particles onto a (x, y, z, phase) grid of mean velocities.
 
     Same math as batch_Lagrangian_to_Eulerian.eulerian_grid, but: reads the
@@ -140,6 +141,21 @@ def eulerian_grid(scene, grid_params, first, last, cycletime,
     query per frame, bins every particle at once with np.histogramdd, and
     returns a self-describing Dataset instead of writing HDF5.
 
+    Phase-bin naming (shared with openptv-cloud/openptv-analysis — same
+    users, one vocabulary; see :mod:`flowtracks.phasing` for the full
+    definition and its rules): ``n_frames_in_period`` is ``cycletime``,
+    ``n_phases`` is ``fin``, ``phase_zero_frame`` is ``base_time``. Pass
+    either style; when both are given the new-style name wins. Narrow
+    (gappy) bins — ``phase_width`` in :mod:`flowtracks.phasing` — are a
+    caller-side frame selection (see :func:`flowtracks.phasing.bin_of_frame`);
+    this gridder always tiles contiguously.
+
+    Input contract (NOT validated — the caller states it): positions in
+    METRES, velocities in METRES PER SECOND. The output dataset is labelled
+    ``m`` / ``m s-1`` (CF) on that basis. Per-frame velocities (no frame
+    rate known) average arithmetically fine, but the ``m s-1`` label is then
+    wrong — relabel to ``m frame-1`` downstream, or state the frame rate.
+
     smoothing_sigma (in grid cells, scalar or per-axis (sx, sy, sz)) applies
     Gaussian kernel smoothing to the velocity sums AND the counts before the
     division (Shepard/kernel estimate); min_count then acts on smoothed counts.
@@ -171,6 +187,17 @@ def eulerian_grid(scene, grid_params, first, last, cycletime,
     prefilter to the strict exclusive box (both bounds exclusive), so
     the binned set matches the legacy inputs exactly.
     """
+    if n_frames_in_period is not None:
+        cycletime = n_frames_in_period
+    if cycletime is None:
+        raise ValueError(
+            "eulerian_grid() needs a period: pass cycletime (legacy) or "
+            "n_frames_in_period (shared vocabulary)."
+        )
+    if n_phases is not None:
+        fin = n_phases
+    if phase_zero_frame is not None:
+        base_time = phase_zero_frame
     zaman = deltat * 2 + 1
     fin = int(np.ceil(cycletime / zaman)) if fin is None else int(fin)
     edges = [np.linspace(grid_params[f"min_{d}"], grid_params[f"max_{d}"],

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/flowtracks/io.py

@@ -1226,7 +1226,8 @@ def read_zarr_trajectories(zarr_path, first=None, last=None, group="trajectories
     return []
 
 
-def save_zarr_trajectories(trajects, zarr_path, group="trajectories", overwrite=True):
+def save_zarr_trajectories(trajects, zarr_path, group="trajectories", overwrite=True,
+                           units=None):
     """
     Save a list of Trajectory objects into a Zarr directory store.
 
@@ -1235,6 +1236,11 @@ def save_zarr_trajectories(trajects, zarr_path, group="trajectories", overwrite=
     zarr_path - path to the target .zarr directory.
     group - sub-group name inside the Zarr store.
     overwrite - if True, overwrite existing arrays in the group.
+    units - dict of per-array units recorded on the group, e.g.
+        {"pos": "m", "vel": "m s-1", "accel": "m s-2", "time": "frame"}.
+        The writer never guesses: omit it only when the caller truly does
+        not know, in which case no unit claim is stored. Honest rule: no
+        frame rate means per-frame velocity units ("m frame-1"), never "m s-1".
     """
     import zarr
 
@@ -1275,4 +1281,7 @@ def save_zarr_trajectories(trajects, zarr_path, group="trajectories", overwrite=
         accel_arr = np.concatenate(all_accel, axis=0)
         target_group.create_array("accel", data=accel_arr, overwrite=overwrite)
 
+    if units:
+        target_group.attrs.update({f"{k}_units": v for k, v in units.items()})
+
 

flowtracks-1.6.2.dev4/flowtracks/phasing.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""One shared phase-bin definition for periodic PTV post-processing.
+
+Every package in the OpenPTV family (flowtracks itself, openptv-cloud,
+openptv-analysis — same users) uses these names and these rules, so a
+``post_analysis.binning`` block means the same thing everywhere:
+
+Canonical names (all self-explainable):
+
+  n_frames_in_period — period length, in frames
+  n_phases           — number of phase bins per cycle (the output count)
+  phase_width        — bin width in cycle units [0, 1); default 1/n_phases
+  phase_zero_frame   — frame anchoring phase 0
+
+Rules enforced by :func:`validate_bins` (fail loudly, never ship NaNs):
+
+  1 <= n_phases <= n_frames_in_period (more bins than frames would stay
+  empty by construction — with whole-frame counting there are only
+  n_frames_in_period distinct phases per cycle);
+  0 < phase_width <= 1/n_phases (bins never overlap in time; narrower bins
+  leave gaps — some frames go unused, which is intentional).
+
+Bins are uniform and start-anchored: bin ``i`` covers
+``[i/n_phases, i/n_phases + phase_width)``. :func:`assign_bins` returns -1
+for samples falling in gaps.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "validate_bins",
+    "assign_bins",
+    "phase_of_frame",
+    "bin_of_frame",
+]
+
+
+def validate_bins(n_frames_in_period, n_phases, phase_width=None) -> float:
+    """Check one bin definition; return the effective width (cycle units).
+
+    Raises SystemExit on violation — a bad binning must fail loudly before
+    any averaging, never ship silent NaN phases.
+    """
+    try:
+        period = int(n_frames_in_period)
+    except (TypeError, ValueError):
+        raise SystemExit(
+            "[phasing] n_frames_in_period must be a positive integer "
+            f"(got {n_frames_in_period!r})."
+        )
+    try:
+        n = int(n_phases)
+    except (TypeError, ValueError):
+        raise SystemExit(
+            f"[phasing] n_phases must be a positive integer (got {n_phases!r})."
+        )
+    if period < 1:
+        raise SystemExit("[phasing] n_frames_in_period must be >= 1.")
+    if n < 1:
+        raise SystemExit("[phasing] n_phases must be >= 1.")
+    if n > period:
+        raise SystemExit(
+            f"[phasing] n_phases ({n}) cannot exceed n_frames_in_period "
+            f"({period}): with whole-frame counting there are only {period} "
+            "distinct phases per cycle, so the extra bins would stay empty. "
+            f"Use n_phases <= {period}."
+        )
+    spacing = 1.0 / n
+    width = float(phase_width) if phase_width is not None else spacing
+    if not width > 0:
+        raise SystemExit("[phasing] phase_width must be positive.")
+    if width > spacing + 1e-12:
+        raise SystemExit(
+            f"[phasing] phase_width ({width:.4g}) exceeds the phase spacing "
+            f"(1/n_phases = {spacing:.4g}): bins would overlap in time. "
+            "Maximum is 1/n_phases (contiguous bins, no gaps)."
+        )
+    return width
+
+
+def phase_of_frame(frame, n_frames_in_period, phase_zero_frame=0) -> float:
+    """Phase in [0, 1) of one frame number."""
+    period = int(n_frames_in_period)
+    return ((int(frame) - int(phase_zero_frame)) % period) / period
+
+
+def bin_of_frame(frame, n_phases, n_frames_in_period,
+                 phase_width=None, phase_zero_frame=0) -> int:
+    """Bin index of one frame number, or -1 when it falls in a gap."""
+    n = int(n_phases)
+    width = float(phase_width) if phase_width is not None else 1.0 / n
+    phase = phase_of_frame(frame, n_frames_in_period, phase_zero_frame)
+    idx = min(int(phase * n), n - 1)
+    return idx if (phase * n - idx) < width * n - 1e-12 else -1
+
+
+def assign_bins(phase, n_phases, phase_width=None):
+    """Bin index per sample phase, or -1 for samples in gaps.
+
+    phase: array-like floats in [0, 1). Default width (None) = 1/n_phases,
+    i.e. contiguous tiling with no gaps.
+    """
+    phase = np.asarray(phase, dtype=float)
+    n = int(n_phases)
+    width = float(phase_width) if phase_width is not None else 1.0 / n
+    idx = np.minimum((phase * n).astype(int), n - 1)
+    intra = phase * n - idx  # position inside the bin, 0..1
+    keep_fraction = width * n  # how much of each bin is covered
+    return np.where(intra < keep_fraction - 1e-12, idx, -1)

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/flowtracks/writers.py

@@ -134,13 +134,20 @@ def _clean(values: np.ndarray) -> np.ndarray:
 
 
 def write_eulerian_series(ds: xr.Dataset, out_dir: Path, prefix: str = "phase",
-                          time_dim: str = "phase", dt: float = 1.0) -> Path:
+                           time_dim: str = "phase", dt: float = 1.0,
+                           units: dict | None = None) -> Path:
     """Write one Eulerian grid file per ``time_dim`` step plus a ``.pvd`` series.
 
     Grid type is chosen from axis spacing: ``vtkImageData`` (``.vti``) when x,
     y and z are each uniformly spaced, ``vtkRectilinearGrid`` (``.vtr``)
     otherwise. Vector fields named by ``VEL_VARS`` are combined into a single
     "velocity" array; every other data variable is written as a scalar.
+
+    ``units`` maps array name to unit string (e.g. ``{"velocity": "m s-1"}``)
+    and is stored as grid field data (``units:<name>``); when omitted, the
+    dataset's own ``units`` attrs are carried over where present. VTK has no
+    unit system, so this is annotation, not enforcement — but the reader no
+    longer has to guess.
     """
     import pyvista as pv
 
@@ -179,6 +186,17 @@ def write_eulerian_series(ds: xr.Dataset, out_dir: Path, prefix: str = "phase",
                 # skip rather than silently reshape/truncate them.
                 continue
             grid.point_data[name] = _clean(da.values).ravel(order="F")
+        fields = dict(units) if units else {}
+        for name, da in snap.data_vars.items():
+            if name not in fields and da.attrs.get("units"):
+                fields[name] = da.attrs["units"]
+        if "velocity" in grid.point_data:
+            for v in VEL_VARS:
+                if v in fields:
+                    fields["velocity"] = fields.pop(v)
+                    break
+        for k, val in fields.items():
+            grid.field_data[f"units:{k}"] = np.array([str(val)])
         path = out_dir / f"{prefix}_{i:04d}.{ext}"
         grid.save(str(path))
         entries.append((i * dt, path))

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/flowtracks.egg-info/PKG-INFO

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

@@ -730,6 +730,7 @@ flowtracks/nhist.py
 flowtracks/pairs.py
 flowtracks/particle.py
 flowtracks/phase_average.py
+flowtracks/phasing.py
 flowtracks/pipeline.py
 flowtracks/provenance.py
 flowtracks/repair.py
@@ -770,6 +771,7 @@ tests/test_nhist.py
 tests/test_phase_align_synthetic_sets.py
 tests/test_phase_average_xr.py
 tests/test_phase_shift_extraction_and_vtr_export.py
+tests/test_phasing.py
 tests/test_post_analysis_edge_cases.py
 tests/test_post_analysis_xr.py
 tests/test_provenance.py

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/flowtracks.egg-info/scm_file_list.json

@@ -725,6 +725,7 @@
     "flowtracks/pairs.py",
     "flowtracks/particle.py",
     "flowtracks/phase_average.py",
+    "flowtracks/phasing.py",
     "flowtracks/pipeline.py",
     "flowtracks/provenance.py",
     "flowtracks/repair.py",
@@ -763,6 +764,7 @@
     "tests/test_phase_align_synthetic_sets.py",
     "tests/test_phase_average_xr.py",
     "tests/test_phase_shift_extraction_and_vtr_export.py",
+    "tests/test_phasing.py",
     "tests/test_post_analysis_edge_cases.py",
     "tests/test_post_analysis_xr.py",
     "tests/test_provenance.py",

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

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

flowtracks-1.6.2.dev4/tests/test_phasing.py

@@ -0,0 +1,96 @@
+"""The one shared phase-bin definition (flowtracks.phasing).
+
+Same names, same rules as openptv-cloud/openptv-analysis: n_phases can
+never exceed n_frames_in_period, bins never overlap (phase_width <=
+1/n_phases), gaps are allowed. eulerian_grid accepts the new-style
+aliases for its three time knobs.
+"""
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent / 'src'))
+from helpers import FakeScene
+
+from flowtracks import eulerian as lag
+from flowtracks.phasing import (
+    assign_bins,
+    bin_of_frame,
+    phase_of_frame,
+    validate_bins,
+)
+
+GRID = {
+    'stepx': 2, 'stepy': 2, 'stepz': 2,
+    'min_x': -1.0, 'max_x': 1.0,
+    'min_y': -1.0, 'max_y': 1.0,
+    'min_z': -1.0, 'max_z': 1.0,
+}
+
+
+def test_more_phases_than_period_frames_is_rejected():
+    with pytest.raises(SystemExit, match="cannot exceed"):
+        validate_bins(5, 20)
+
+
+def test_phase_width_wider_than_spacing_is_rejected():
+    with pytest.raises(SystemExit, match="would overlap"):
+        validate_bins(20, 4, 0.3)
+
+
+def test_narrow_bins_leave_gaps():
+    assert assign_bins(np.array([0.0, 0.1, 0.2, 0.3]), 5, 0.05).tolist() == [
+        0, -1, 1, -1,
+    ]
+
+
+def test_frame_to_bin_mapping():
+    assert phase_of_frame(6, 5, 1) == pytest.approx(0.0)
+    assert bin_of_frame(2, 5, 5, None, 1) == 1
+    # period 20, 5 bins, narrow width: frame 2 sits mid-bin -> gap
+    assert bin_of_frame(2, 5, 20, 0.05, 1) == -1
+    assert bin_of_frame(1, 5, 20, 0.05, 1) == 0
+
+
+def test_eulerian_grid_new_style_aliases_match_old_style():
+    def _scene():
+        pos = np.zeros((5, 3))
+        vel = np.tile(np.array([1.0, 2.0, 3.0]), (5, 1))
+        return FakeScene(pos, vel)
+
+    old = lag.eulerian_grid(
+        _scene(), GRID, first=100001, last=100005, cycletime=100,
+        deltat=90, base_time=100000, min_count=1,
+    )
+    new = lag.eulerian_grid(
+        _scene(), GRID, first=100001, last=100005,
+        n_frames_in_period=100, deltat=90, phase_zero_frame=100000,
+        min_count=1, n_phases=old.sizes["phase"],
+    )
+    np.testing.assert_allclose(
+        new["u_ins_mean"].values, old["u_ins_mean"].values, equal_nan=True
+    )
+    assert new.sizes["phase"] == old.sizes["phase"]
+
+
+def test_save_zarr_trajectories_records_units(tmp_path):
+    import zarr
+
+    from flowtracks.io import save_zarr_trajectories
+    from flowtracks.trajectory import Trajectory
+
+    tr = Trajectory(
+        pos=np.zeros((3, 3)), velocity=np.ones((3, 3)),
+        time=np.array([1, 2, 3]), trajid=7,
+    )
+    save_zarr_trajectories(
+        [tr], tmp_path / "run.zarr",
+        units={"pos": "m", "vel": "m s-1", "time": "frame"},
+    )
+    grp = zarr.open_group(str(tmp_path / "run.zarr"), mode="r")["trajectories"]
+    assert grp.attrs["pos_units"] == "m"
+    assert grp.attrs["vel_units"] == "m s-1"
+    assert grp.attrs["time_units"] == "frame"

{flowtracks-1.6.2.dev1 → flowtracks-1.6.2.dev4}/tests/test_writers.py

@@ -157,3 +157,14 @@ def test_export_run_to_paraview_with_eulerian_ds(tmp_path):
     result = export_run_to_paraview(store, tmp_path / "out", eulerian_ds=ds)
     assert result["trajectories"].exists()
     assert result["eulerian"].exists()
+
+
+def test_eulerian_series_carries_units_as_field_data(tmp_path):
+    import pyvista as pv
+
+    ds = _eulerian_dataset(np.linspace(0, 2, 4))
+    ds["u_ins_mean"].attrs["units"] = "m s-1"
+    write_eulerian_series(ds, tmp_path, units={"par_ave2": "1"})
+    grid = pv.read(str(tmp_path / "phase_0000.vti"))
+    assert grid.field_data["units:velocity"] == ["m s-1"]
+    assert grid.field_data["units:par_ave2"] == ["1"]

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

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