flowtracks 1.6.2.dev3__py3-none-any.whl → 1.6.2.dev4__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.dev3'
-__version_tuple__ = version_tuple = (1, 6, 2, 'dev3')
+__version__ = version = '1.6.2.dev4'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev4')
 
-__commit_id__ = commit_id = 'g17f6da530'
+__commit_id__ = commit_id = 'gc00cb25a5'

flowtracks/eulerian.py

@@ -150,6 +150,12 @@ def eulerian_grid(scene, grid_params, first, last, cycletime=None,
     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.

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/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.dev3.dist-info → flowtracks-1.6.2.dev4.dist-info}/METADATA

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

@@ -1,15 +1,15 @@
 flowtracks/__init__.py,sha256=iCexskmRtpNJ0fNZWRFkQAqrku7csbKy5NtL2YQNYeo,1532
-flowtracks/_version.py,sha256=ioGLROz7BQPlJdI-WwRRXLPAhGzUpsK8HZGSNQ17PCs,541
+flowtracks/_version.py,sha256=ZWyF90B5Js1Ikxd3zd_HluOAb1r35l1-eoSda5mck90,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=b6otBh_fjwfMPGKsitBMmM-zhcp8qq7SiWyx-cnGaGU,41495
+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=Pror0OmWXmlZz5yyEY2qKKQM5t_BMtKeYIAw26I0JeQ,13043
 flowtracks/interpolation.py,sha256=njuB-bvWK5M2tc2Ibm6ZWNg6Tm6H-PTn0a63IldlJaA,39414
-flowtracks/io.py,sha256=muNcht-yBDQM7vJaNHl9l6ag9iO0OTzWU12_etx_QEU,47869
+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
@@ -25,29 +25,29 @@ 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=QzZ7gKqRGNti6caPHcwCr_4VUCjzzDxMA2CBS5-pq84,8391
+flowtracks/writers.py,sha256=NAVz8H2w-Wtiy__acB9uT_NDSO6RqpEywcxm8tk1peg,9273
 flowtracks/zarr_scene.py,sha256=PKCtiTT1t0Hj74Q572ra5DM3uM8lQK1A6DzzfUxvIzI,10468
-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,,
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/batch_Lagrangian_to_Eulerian.py,sha256=e7mQFqyqvCeAHRKiN1IaxdNJi0e2FU84c7QNrx0L-m0,2296
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/hdf5_scene_analysis.ipynb,sha256=jn0Z_ZVL1-iXaiKXwyAeb74NbXsBpnocCxCSDh814eU,243097
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/linking_trajectories.ipynb,sha256=udz0GLDiPv68BYySg4yO1HWzaB9Sdy3YA3IhnIHDeII,8820
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_dual_rig_trajectories.py,sha256=dzeK0C-knwq1bPOwo0p1RhWrb0RPp-T31rBaGEptXcc,6737
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_flowtracks.py,sha256=7FIJNwBx9aBRmaM5ofmYTXSWEjE0wZqDfs8J47Tmw6U,9440
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_hdf5_vs_zarr_scene_analysis.py,sha256=bjXlMsLJTxJ0JkvGcVZbuDOFYZU4OvdabtDUgqb15So,4536
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_linking_trajectories_zarr.py,sha256=Ny_WUbiZWo0aKw-u2KGFWrhMv-8BvNgBy0UHIqCobYg,8210
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_phase_averaging_demo.py,sha256=vg6j2ayKGl-5uj08bdzzb6pujzJJQ_5bUsG7UuPP7dM,9270
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_phase_metrics.py,sha256=kBc2e_b-orDrm3AnuUXCcxsvmfQWyCtE826pFeolMGE,9367
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_vtk_writers_preview.py,sha256=Otrhhp-QFf6F94EOs6rWu5xOCpbS16EfWy_iMFp7e_I,14611
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/marimo_zarr_dashboard.py,sha256=jVIum6hdEelH4ef7vRgsfLhrbmMsuErsJBzxrnEImnw,9268
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/repeated_interpolation.ipynb,sha256=t9SfoIWRu5XP0SrphWbQy508uzyEibVz61FGjl51fjA,8861
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/run_pipeline.py,sha256=5fGE2tIP6XjFZ1sEYmqBujuLaXFfRL-rNnbr2p2CDfM,7205
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/visualize_marimo.py,sha256=jWrg5IWjY-bmSQwQjaO5qTr0t_G48CsqJYpevdQrxeY,13026
+flowtracks-1.6.2.dev4.data/data/flowtracks-examples/visualize_results.py,sha256=SbPg3EoDcuIyo0rUz3E-AnT4sLWDVJFhgC6xVcracW4,7583
+flowtracks-1.6.2.dev4.data/scripts/analyse_fhdf.py,sha256=QH08NdImGukTEGuZEKFxjStcSelXBv-8A-22G6KtXqM,1315
+flowtracks-1.6.2.dev4.dist-info/licenses/LICENSE.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev4.dist-info/licenses/LICENSES/BSD-3-Clause.txt,sha256=XiJR9O5snDB6sAz0bcncOU6msceZgjPRxejWEQGg40Q,1505
+flowtracks-1.6.2.dev4.dist-info/licenses/LICENSES/GPL-3.0-only.txt,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+flowtracks-1.6.2.dev4.dist-info/METADATA,sha256=5FSsqSUpZRPt6m3eOTVB-aQF_2vDOZOelKmkNibfg-k,4773
+flowtracks-1.6.2.dev4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flowtracks-1.6.2.dev4.dist-info/entry_points.txt,sha256=U6028E7yQZQiZoXWMl7w4xgZUPwPxAGiAuuMB__c-yQ,60
+flowtracks-1.6.2.dev4.dist-info/top_level.txt,sha256=cR54RNb9y2Wfr_BfuOezmNJOMB4GfIHh1-luXTREnQA,11
+flowtracks-1.6.2.dev4.dist-info/RECORD,,