flowtracks 1.6.2.dev4__tar.gz → 1.6.2.dev6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtracks
-Version: 1.6.2.dev4
+Version: 1.6.2.dev6
 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.dev4 → flowtracks-1.6.2.dev6}/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.dev4'
-__version_tuple__ = version_tuple = (1, 6, 2, 'dev4')
+__version__ = version = '1.6.2.dev6'
+__version_tuple__ = version_tuple = (1, 6, 2, 'dev6')
 
-__commit_id__ = commit_id = 'gc00cb25a5'
+__commit_id__ = commit_id = 'g519243be4'

{flowtracks-1.6.2.dev4 → flowtracks-1.6.2.dev6}/flowtracks/graphics.py

@@ -20,6 +20,8 @@ PyVista (VTK, GPU-rendered polylines -- the ``vtk`` extra), from the same
 PolyData the ``.vtp`` ParaView writer saves.
 """
 
+from pathlib import Path
+
 import matplotlib.pyplot as pl
 import numpy as np
 
@@ -249,7 +251,8 @@ def select_trajectories(source, by="length", n=10, min_points=20, min_extent=0.0
 
 def plot_trajectories_3d(source, trajids=None, scalars="speed", context=0,
                          plotter=None, cmap="plasma", clim=None, line_width=3,
-                         point_size=6, title=None, bar_title=None, show=True):
+                         point_size=6, title=None, bar_title=None, show=True,
+                         units=None):
     """Interactive 3D trajectory view (PyVista): polylines coloured by a point
     array (``speed``, ``time``, ``trajid``), points drawn as spheres so short
     tracks stay visible.
@@ -264,14 +267,30 @@ def plot_trajectories_3d(source, trajids=None, scalars="speed", context=0,
         with the same title into one shared colour range, so give each
         subplot its own title to keep its own range.
     show - call ``plotter.show()``; pass False to compose or screenshot.
+    units - ``{"pos": "m", "vel": "m s-1", "time": "frame"}`` for axis and
+        colour-bar titles (``x [m]``, ``speed [m s-1]``). When omitted and
+        ``source`` is a Zarr path, whatever the writer recorded is used;
+        otherwise titles stay bare rather than guessed.
 
     Returns the plotter.
     """
     import pyvista as pv
 
-    from flowtracks.writers import _trajectory_arrays, trajectory_polydata
-
-    poly = trajectory_polydata(source, trajids)
+    from flowtracks.writers import (
+        _trajectory_arrays,
+        trajectory_polydata,
+        trajectory_units,
+    )
+
+    if units is None and isinstance(source, (str, Path)):
+        units = trajectory_units(source)
+    units = units or {}
+    pos_u = f" [{units['pos']}]" if units.get("pos") else ""
+    scalar_u = f" [{units['vel']}]" if scalars in ("speed", "velocity") and units.get("vel") else ""
+    if not scalar_u and scalars == "time" and units.get("time"):
+        scalar_u = f" [{units['time']}]"
+
+    poly = trajectory_polydata(source, trajids, units=units or None)
     if plotter is None:
         plotter = pv.Plotter()
     if context:
@@ -280,14 +299,15 @@ def plot_trajectories_3d(source, trajids=None, scalars="speed", context=0,
         plotter.add_points(pos[pick], color="grey", opacity=0.15, point_size=2,
                            name="context")
     if poly.n_points:
-        bar = {"title": bar_title or scalars}
+        bar = {"title": (bar_title or scalars) + scalar_u}
         plotter.add_mesh(poly, scalars=scalars, cmap=cmap, clim=clim, line_width=line_width,
                          render_lines_as_tubes=True, scalar_bar_args=bar, name="tracks")
         plotter.add_mesh(poly.extract_points(np.arange(poly.n_points), adjacent_cells=False),
                          scalars=scalars, cmap=cmap, clim=clim, point_size=point_size,
                          render_points_as_spheres=True, style="points",
                          show_scalar_bar=False, name="points")
-    plotter.show_grid(xtitle="x", ytitle="y", ztitle="z", fmt="%.3g",
+    plotter.show_grid(xtitle=f"x{pos_u}", ytitle=f"y{pos_u}", ztitle=f"z{pos_u}",
+                       fmt="%.3g",
                       n_xlabels=3, n_ylabels=3, n_zlabels=3)
     plotter.add_axes()
     if title:

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

@@ -69,17 +69,43 @@ def _trajectory_arrays(source):
     raise TypeError(f"Unsupported trajectory source: {type(source)!r}")
 
 
-def trajectory_polydata(source, trajids=None):
+def trajectory_units(source) -> dict:
+    """Units recorded on a trajectories store ({pos, vel, time, ...} units).
+
+    Zarr paths report what the writer recorded; anything else reports {} --
+    the caller then labels without units rather than guessing.
+    """
+    if isinstance(source, (str, Path)):
+        try:
+            import zarr
+
+            group = zarr.open_group(str(source), mode="r")
+            target = group["trajectories"] if "trajectories" in group else group
+            return {
+                k[:-6]: v
+                for k, v in dict(target.attrs).items()
+                if k.endswith("_units")
+            }
+        except Exception:
+            pass
+    return {}
+
+
+def trajectory_polydata(source, trajids=None, units=None):
     """Lagrangian trajectories as VTK PolyData: points + one polyline per trajid.
 
     ``source`` as for :func:`write_trajectories_vtp`. ``trajids`` optionally
     keeps only those trajectories. Point data: ``trajid``, ``time``,
-    ``velocity``, ``speed``. Shared by the ``.vtp`` writer and
-    :func:`flowtracks.graphics.plot_trajectories_3d`.
+    ``velocity``, ``speed``. ``units`` (e.g. ``{"pos": "m"}``) is stored as
+    field data (``units:<name>``); when omitted and ``source`` is a Zarr path,
+    whatever the writer recorded is carried over. Shared by the ``.vtp``
+    writer and :func:`flowtracks.graphics.plot_trajectories_3d`.
     """
     import pyvista as pv
 
     pos, vel, time, trajid = _trajectory_arrays(source)
+    if units is None and isinstance(source, (str, Path)):
+        units = trajectory_units(source)
     if trajids is not None:
         keep = np.isin(trajid, np.asarray(trajids))
         pos, vel, time, trajid = pos[keep], vel[keep], time[keep], trajid[keep]
@@ -104,6 +130,8 @@ def trajectory_polydata(source, trajids=None):
     poly.point_data["time"] = time
     poly.point_data["velocity"] = vel
     poly.point_data["speed"] = np.linalg.norm(vel, axis=1)
+    for k, val in (units or {}).items():
+        poly.field_data[f"units:{k}"] = np.array([str(val)])
     return poly
 
 

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

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

@@ -1,7 +1,7 @@
 {
   "tag": "1.6.1",
-  "distance": 4,
-  "node": "gc00cb25a5c5a2e52738c1f2d61c7855f3f57716e",
+  "distance": 6,
+  "node": "g519243be4860573bfe4fd6cab7c98583d605735a",
   "dirty": false,
   "branch": "master",
   "node_date": "2026-10-06"

{flowtracks-1.6.2.dev4 → flowtracks-1.6.2.dev6}/tests/test_graphics_3d.py

@@ -107,3 +107,44 @@ def test_summary_path_and_jump_values():
     assert tab["jump"][row[5]] == pytest.approx(0.0, abs=1e-12)   # gap spaced correctly
     # one point displaced by 3 bends two neighbouring steps: 3 + 3/2 = 4.5
     assert tab["jump"][row[4]] == pytest.approx(4.5)
+
+
+def test_polydata_carries_recorded_units_as_field_data(tmp_path):
+    import zarr
+
+    from flowtracks.writers import trajectory_units
+
+    store = tmp_path / "run.zarr"
+    root = zarr.open_group(str(store), mode="w")
+    grp = root.require_group("trajectories")
+    grp.create_array("pos", data=np.zeros((2, 3)))
+    grp.create_array("vel", data=np.zeros((2, 3)))
+    grp.create_array("time", data=np.zeros(2, dtype=np.int64))
+    grp.create_array("trajid", data=np.zeros(2, dtype=np.int64))
+    grp.attrs.update({"pos_units": "m", "vel_units": "m s-1", "time_units": "frame"})
+
+    assert trajectory_units(store) == {
+        "pos": "m", "vel": "m s-1", "time": "frame",
+    }
+    poly = trajectory_polydata(store)
+    assert poly.field_data["units:pos"] == ["m"]
+    assert poly.field_data["units:vel"] == ["m s-1"]
+
+
+def test_plot_titles_show_recorded_units(tmp_path):
+    import zarr
+
+    store = tmp_path / "run.zarr"
+    root = zarr.open_group(str(store), mode="w")
+    grp = root.require_group("trajectories")
+    n = 6
+    grp.create_array("pos", data=np.tile([0.01, 0.0, 0.0], (n, 1)))
+    grp.create_array("vel", data=np.tile([1.0, 0.0, 0.0], (n, 1)))
+    grp.create_array("time", data=np.arange(n, dtype=np.int64))
+    grp.create_array("trajid", data=np.ones(n, dtype=np.int64))
+    grp.attrs.update({"pos_units": "m", "vel_units": "m s-1", "time_units": "frame"})
+
+    pl = pv.Plotter(off_screen=True)
+    plot_trajectories_3d(store, plotter=pl, show=False)
+    assert "speed [m s-1]" in dict(pl.scalar_bars)
+    pl.close()