flowtracks 1.6.2.dev1__py3-none-any.whl → 1.6.2.dev3__py3-none-any.whl

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/_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.dev3'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev3')
 
-__commit_id__ = commit_id = 'g343cf68fa'
+__commit_id__ = commit_id = 'g17f6da530'

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,15 @@ 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.
+
     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 +181,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/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.dist-info → flowtracks-1.6.2.dev3.dist-info}/METADATA

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

@@ -1,9 +1,9 @@
-flowtracks/__init__.py,sha256=UHxu1eFrWI0DD2kPLy-GdF2WEMkbx1dBRkN_4NmqD7M,1341
-flowtracks/_version.py,sha256=sX-4f5T5duAZRGqZmFciqVEpgoXPx5071sKVdXva8CM,541
+flowtracks/__init__.py,sha256=iCexskmRtpNJ0fNZWRFkQAqrku7csbKy5NtL2YQNYeo,1532
+flowtracks/_version.py,sha256=ioGLROz7BQPlJdI-WwRRXLPAhGzUpsK8HZGSNQ17PCs,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=ksW4pxKS-C56ew3qWtKn6dweIctgDoaR5_1_QK3H6g8,40456
+flowtracks/eulerian.py,sha256=b6otBh_fjwfMPGKsitBMmM-zhcp8qq7SiWyx-cnGaGU,41495
 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
@@ -14,6 +14,7 @@ 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
@@ -26,27 +27,27 @@ flowtracks/vortex.py,sha256=4lG3QkvvnWhAHy4tl1pJrBGFLdrlP4pxNdhCZI1VZ4Q,2529
 flowtracks/wall_shear.py,sha256=k9Q5FEchIO9J_onXPOw4PNJQfmsrSyVVvX4RdW-rQlE,6788
 flowtracks/writers.py,sha256=QzZ7gKqRGNti6caPHcwCr_4VUCjzzDxMA2CBS5-pq84,8391
 flowtracks/zarr_scene.py,sha256=PKCtiTT1t0Hj74Q572ra5DM3uM8lQK1A6DzzfUxvIzI,10468
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/batch_Lagrangian_to_Eulerian.py,sha256=e7mQFqyqvCeAHRKiN1IaxdNJi0e2FU84c7QNrx0L-m0,2296
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/hdf5_scene_analysis.ipynb,sha256=jn0Z_ZVL1-iXaiKXwyAeb74NbXsBpnocCxCSDh814eU,243097
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/linking_trajectories.ipynb,sha256=udz0GLDiPv68BYySg4yO1HWzaB9Sdy3YA3IhnIHDeII,8820
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_dual_rig_trajectories.py,sha256=dzeK0C-knwq1bPOwo0p1RhWrb0RPp-T31rBaGEptXcc,6737
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_flowtracks.py,sha256=7FIJNwBx9aBRmaM5ofmYTXSWEjE0wZqDfs8J47Tmw6U,9440
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_hdf5_vs_zarr_scene_analysis.py,sha256=bjXlMsLJTxJ0JkvGcVZbuDOFYZU4OvdabtDUgqb15So,4536
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_linking_trajectories_zarr.py,sha256=Ny_WUbiZWo0aKw-u2KGFWrhMv-8BvNgBy0UHIqCobYg,8210
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_phase_averaging_demo.py,sha256=vg6j2ayKGl-5uj08bdzzb6pujzJJQ_5bUsG7UuPP7dM,9270
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_phase_metrics.py,sha256=kBc2e_b-orDrm3AnuUXCcxsvmfQWyCtE826pFeolMGE,9367
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_vtk_writers_preview.py,sha256=Otrhhp-QFf6F94EOs6rWu5xOCpbS16EfWy_iMFp7e_I,14611
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/marimo_zarr_dashboard.py,sha256=jVIum6hdEelH4ef7vRgsfLhrbmMsuErsJBzxrnEImnw,9268
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/repeated_interpolation.ipynb,sha256=t9SfoIWRu5XP0SrphWbQy508uzyEibVz61FGjl51fjA,8861
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/run_pipeline.py,sha256=5fGE2tIP6XjFZ1sEYmqBujuLaXFfRL-rNnbr2p2CDfM,7205
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/visualize_marimo.py,sha256=jWrg5IWjY-bmSQwQjaO5qTr0t_G48CsqJYpevdQrxeY,13026
-flowtracks-1.6.2.dev1.data/data/flowtracks-examples/visualize_results.py,sha256=SbPg3EoDcuIyo0rUz3E-AnT4sLWDVJFhgC6xVcracW4,7583
-flowtracks-1.6.2.dev1.data/scripts/analyse_fhdf.py,sha256=QH08NdImGukTEGuZEKFxjStcSelXBv-8A-22G6KtXqM,1315
-flowtracks-1.6.2.dev1.dist-info/licenses/LICENSE.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
-flowtracks-1.6.2.dev1.dist-info/licenses/LICENSES/BSD-3-Clause.txt,sha256=XiJR9O5snDB6sAz0bcncOU6msceZgjPRxejWEQGg40Q,1505
-flowtracks-1.6.2.dev1.dist-info/licenses/LICENSES/GPL-3.0-only.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
-flowtracks-1.6.2.dev1.dist-info/METADATA,sha256=Rj-Vf--pDCbat5wzy_wvw9yz7TQ4N-UhJAwomgbHUuE,4773
-flowtracks-1.6.2.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-flowtracks-1.6.2.dev1.dist-info/entry_points.txt,sha256=U6028E7yQZQiZoXWMl7w4xgZUPwPxAGiAuuMB__c-yQ,60
-flowtracks-1.6.2.dev1.dist-info/top_level.txt,sha256=cR54RNb9y2Wfr_BfuOezmNJOMB4GfIHh1-luXTREnQA,11
-flowtracks-1.6.2.dev1.dist-info/RECORD,,
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/batch_Lagrangian_to_Eulerian.py,sha256=e7mQFqyqvCeAHRKiN1IaxdNJi0e2FU84c7QNrx0L-m0,2296
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/hdf5_scene_analysis.ipynb,sha256=jn0Z_ZVL1-iXaiKXwyAeb74NbXsBpnocCxCSDh814eU,243097
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/linking_trajectories.ipynb,sha256=udz0GLDiPv68BYySg4yO1HWzaB9Sdy3YA3IhnIHDeII,8820
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_dual_rig_trajectories.py,sha256=dzeK0C-knwq1bPOwo0p1RhWrb0RPp-T31rBaGEptXcc,6737
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_flowtracks.py,sha256=7FIJNwBx9aBRmaM5ofmYTXSWEjE0wZqDfs8J47Tmw6U,9440
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_hdf5_vs_zarr_scene_analysis.py,sha256=bjXlMsLJTxJ0JkvGcVZbuDOFYZU4OvdabtDUgqb15So,4536
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_linking_trajectories_zarr.py,sha256=Ny_WUbiZWo0aKw-u2KGFWrhMv-8BvNgBy0UHIqCobYg,8210
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_phase_averaging_demo.py,sha256=vg6j2ayKGl-5uj08bdzzb6pujzJJQ_5bUsG7UuPP7dM,9270
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_phase_metrics.py,sha256=kBc2e_b-orDrm3AnuUXCcxsvmfQWyCtE826pFeolMGE,9367
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_vtk_writers_preview.py,sha256=Otrhhp-QFf6F94EOs6rWu5xOCpbS16EfWy_iMFp7e_I,14611
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/marimo_zarr_dashboard.py,sha256=jVIum6hdEelH4ef7vRgsfLhrbmMsuErsJBzxrnEImnw,9268
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/repeated_interpolation.ipynb,sha256=t9SfoIWRu5XP0SrphWbQy508uzyEibVz61FGjl51fjA,8861
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/run_pipeline.py,sha256=5fGE2tIP6XjFZ1sEYmqBujuLaXFfRL-rNnbr2p2CDfM,7205
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/visualize_marimo.py,sha256=jWrg5IWjY-bmSQwQjaO5qTr0t_G48CsqJYpevdQrxeY,13026
+flowtracks-1.6.2.dev3.data/data/flowtracks-examples/visualize_results.py,sha256=SbPg3EoDcuIyo0rUz3E-AnT4sLWDVJFhgC6xVcracW4,7583
+flowtracks-1.6.2.dev3.data/scripts/analyse_fhdf.py,sha256=QH08NdImGukTEGuZEKFxjStcSelXBv-8A-22G6KtXqM,1315
+flowtracks-1.6.2.dev3.dist-info/licenses/LICENSE.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev3.dist-info/licenses/LICENSES/BSD-3-Clause.txt,sha256=XiJR9O5snDB6sAz0bcncOU6msceZgjPRxejWEQGg40Q,1505
+flowtracks-1.6.2.dev3.dist-info/licenses/LICENSES/GPL-3.0-only.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev3.dist-info/METADATA,sha256=kKrzqrX4vP203dJvGLDCw-M09MaprT8BviNIdyEdb2g,4773
+flowtracks-1.6.2.dev3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flowtracks-1.6.2.dev3.dist-info/entry_points.txt,sha256=U6028E7yQZQiZoXWMl7w4xgZUPwPxAGiAuuMB__c-yQ,60
+flowtracks-1.6.2.dev3.dist-info/top_level.txt,sha256=cR54RNb9y2Wfr_BfuOezmNJOMB4GfIHh1-luXTREnQA,11
+flowtracks-1.6.2.dev3.dist-info/RECORD,,