pyopenrivercam 0.8.10__tar.gz → 0.8.11__tar.gz

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.8.11] = 2025-10-01
+### Added
+- Derivation of transect properties surface area and wetted perimeter.
+- Added method `transect.get_v_surf` for average surface velocity, and `transect.get_v_bulk` for bulk velocity.
+### Changed
+- Using `add_text=True` in `transect.plot` now also displays average surface and bulk velocity.  
+### Deprecated
+### Removed
+- `transect.get_wetted_perspective` is no longer required as this can be derived from `transect.cross_section`.
+- `transect.get_xyz_perspective` is no longer required as this can be derived from `transect.cross_section`.
+### Fixed
+
 ## [0.8.10] = 2025-09-22
 ### Added
 - option `ensemble_corr` with `frames.get_piv`. This performs ensemble correlation averaging on cross-correlation and

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenrivercam
-Version: 0.8.10
+Version: 0.8.11
 Summary: pyorc: free and open-source image-based surface velocity and discharge.
 Author-email: Hessel Winsemius <winsemius@rainbowsensing.com>
 Requires-Python: >=3.9

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/pyorc/__init__.py

@@ -1,6 +1,6 @@
 """pyorc: free and open-source image-based surface velocity and discharge."""
 
-__version__ = "0.8.10"
+__version__ = "0.8.11"
 
 from .api import CameraConfig, CrossSection, Frames, Transect, Velocimetry, Video, get_camera_config, load_camera_config  # noqa
 from .project import *  # noqa

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/pyorc/api/cross_section.py

@@ -13,7 +13,7 @@ from matplotlib import patheffects
 from scipy.interpolate import interp1d
 from scipy.optimize import differential_evolution
 from shapely import affinity, geometry
-from shapely.ops import polygonize
+from shapely.ops import polygonize, split
 
 from pyorc import cv, plot_helpers
 
@@ -613,16 +613,21 @@ class CrossSection:
             raise ValueError("Amount of water line crossings must be 2 for a planar surface estimate.")
         return geometry.Polygon(list(wls[0].coords) + list(wls[1].coords[::-1]))
 
-    def get_wetted_surface_sz(self, h: float) -> geometry.Polygon:
-        """Retrieve a wetted surface perpendicular to flow direction (SZ) for a water level, as a geometry.Polygon.
+    def get_wetted_surface_sz(self, h: float, perimeter: bool = False) -> Union[geometry.MultiPolygon, geometry.MultiLineString]:
+        """Retrieve a wetted surface or perimeter perpendicular to flow direction (SZ) for a water level.
 
-        This is a useful method for instance to estimate m2 wetted surface for a given water level in the cross
-        section.
+        This returns a `geometry.MultiPolygon` when a surface is requested (`perimeter=False`), and
+        `geometry.MultiLineString` when a perimeter is requested (`perimeter=True`).
+
+        This is a useful method for instance to estimate m2 wetted surface or m wetted perimeter length for a given
+        water level in the cross section.
 
         Parameters
         ----------
         h : float
             water level [m]
+        perimeter : bool, optional
+            If set to True, return a linestring with the wetted perimeter instead.
 
         Returns
         -------
@@ -630,6 +635,12 @@ class CrossSection:
             Wetted surface as a polygon, in Y-Z projection.
 
         """
+
+        def avg_y(line):
+            """Compute average y-coordinate of a line."""
+            ys = [p[1] for p in line.coords]
+            return sum(ys) / len(ys)
+
         wl = self.get_cs_waterlevel(
             h=h, sz=True, extend_by=0.1
         )  # extend a small bit to guarantee crossing with the bottom coordinates
@@ -642,6 +653,18 @@ class CrossSection:
         if bottom_points[-1].y < zl:
             bottom_points.append(geometry.Point(bottom_points[-1].x, zl + 0.1))
         bottom_line = geometry.LineString(bottom_points)
+        if perimeter:
+            wl_z = wl.coords[0][-1]
+            split_segments = split(bottom_line, wl)
+            filtered = []
+            for seg in split_segments.geoms:
+                seg_z = avg_y(seg)
+                if seg_z < wl_z:
+                    # segment is below water level, add to perimeter
+                    filtered.append(seg)
+
+            return geometry.MultiLineString(filtered)
+            # return wetted_perim
         pol = list(polygonize(wl.union(bottom_line)))
         if len(pol) == 0:
             # create infinitely small polygon at lowest z coordinate

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/pyorc/api/plot.py

@@ -752,8 +752,10 @@ def plot_text(ax, ds, prefix, suffix):
     yloc = 0.95
     _ds.transect.get_river_flow(q_name="q")
     Q = np.abs(_ds.river_flow)
+    v_surf = _ds.transect.get_v_surf()
+    v_bulk = _ds.transect.get_v_bulk()
     string = prefix
-    string += "Water level: {:1.2f} m\nDischarge: {:1.2f} m3/s".format(_ds.transect.h_a, Q.values)
+    string += f"$h_a$: {_ds.transect.h_a:1.2f} m | $v_{{surf}}$: {v_surf.values:1.2f} m/s | $\overline{{v}}$: {v_bulk.values:1.2f} m/s\n$Q$: {Q.values:1.2f} m3/s" # .format(_ds.transect.h_a, Q.values)
     if "q_nofill" in ds:
         _ds.transect.get_river_flow(q_name="q_nofill")
         Q_nofill = np.abs(_ds.river_flow)
@@ -765,7 +767,7 @@ def plot_text(ax, ds, prefix, suffix):
         xloc,
         yloc,
         string,
-        size=24,
+        size=18,
         horizontalalignment="right",
         verticalalignment="top",
         path_effects=path_effects,

{pyopenrivercam-0.8.10 → pyopenrivercam-0.8.11}/pyorc/api/transect.py

@@ -2,6 +2,7 @@
 
 import numpy as np
 import xarray as xr
+from shapely import geometry
 from xarray.core import utils
 
 from pyorc import helpers
@@ -34,6 +35,26 @@ class Transect(ORCBase):
         coords = [[_x, _y, _z] for _x, _y, _z in zip(self._obj.xcoords, self._obj.ycoords, self._obj.zcoords)]
         return CrossSection(camera_config=self.camera_config, cross_section=coords)
 
+    @property
+    def wetted_surface_polygon(self) -> geometry.MultiPolygon:
+        """Return wetted surface as `shapely.geometry.MultiPolygon` object."""
+        return self.cross_section.get_wetted_surface_sz(self.h_a)
+
+    @property
+    def wetted_perimeter_linestring(self) -> geometry.MultiLineString:
+        """Return wetted perimeter as `shapely.geometry.MultiLineString` object."""
+        return self.cross_section.get_wetted_surface_sz(self.h_a, perimeter=True)
+
+    @property
+    def wetted_surface(self) -> float:
+        """Return wetted surface as float."""
+        return self.wetted_surface_polygon.area
+
+    @property
+    def wetted_perimeter(self) -> float:
+        """Return wetted perimeter as float."""
+        return self.wetted_perimeter_linestring.length
+
     def vector_to_scalar(self, v_x="v_x", v_y="v_y"):
         """Set "v_eff" and "v_dir" variables as effective velocities over cross-section, and its angle.
 
@@ -129,30 +150,6 @@ class Transect(ORCBase):
         points_proj = self.camera_config.project_points(points, within_image=within_image, swap_y_coords=True)
         return points_proj
 
-    def get_wetted_perspective(self, h, sample_size=1000):
-        """Get wetted polygon in camera perspective.
-
-        Parameters
-        ----------
-        h : float
-            The water level value to calculate the surface perspective.
-        sample_size : int, optional
-            The number of points to densify the transect with, by default 1000
-
-        Returns
-        -------
-        ndarray
-            A numpy array containing the points forming the wetted polygon perspective.
-
-        """
-        bottom_points, surface_points = self.get_bottom_surface_z_perspective(h=h, sample_size=sample_size)
-        # concatenate points reversing one set for preps of a polygon
-        pol_points = np.concatenate([bottom_points, np.flipud(surface_points)], axis=0)
-
-        # add the first point at the end to close the polygon
-        pol_points = np.concatenate([pol_points, pol_points[0:1]], axis=0)
-        return pol_points
-
     def get_depth_perspective(self, h, sample_size=1000, interval=25):
         """Get line (x, y) pairs that show the depth over several intervals in the wetted part of the cross section.
 
@@ -177,64 +174,59 @@ class Transect(ORCBase):
         # make line pairs
         return list(zip(bottom_points, surface_points))
 
-    def get_xyz_perspective(self, trans_mat=None, xs=None, ys=None, mask_outside=True):
-        """Get camera-perspective column, row coordinates from cross-section locations.
+    def get_v_surf(self, v_name="v_eff"):
+        """Compute mean surface velocity in locations that are below water level.
 
         Parameters
         ----------
-        trans_mat : np.ndarray, optional
-             perspective transform matrix (Default value = None)
-        xs : np.array, optional
-            x-coordinates to transform, derived from self.x if not provided (Default value = None)
-        ys :
-            y-coordinates to transform, derived from self.y if not provided (Default value = None)
-        mask_outside :
-            values not fitting in the original camera frame are set to NaN (Default value = True)
+        v_name : str, optional
+             name of variable where surface velocities [m s-1] are stored (Default value = "v_eff")
 
         Returns
         -------
-        cols : list of ints
-            columns of locations in original camera perspective
-        rows : list of ints
-            rows of locations in original camera perspective
-
+        xr.DataArray
+            mean surface velocities for all provided quantiles or time steps
 
         """
-        if xs is None:
-            xs = self._obj.x.values
-        if ys is None:
-            ys = self._obj.y.values
-        # compute bathymetry as measured in local height reference (such as staff gauge)
-        # if self.camera_config.gcps["h_ref"] is None:
-        #     h_ref = 0.0
-        # else:
-        #     h_ref = self.camera_config.gcps["h_ref"]
-        hs = self.camera_config.z_to_h(self._obj.zcoords).values
-        # zs = (self._obj.zcoords - self.camera_config.gcps["z_0"] + h_ref).values
-        if trans_mat is None:
-            ms = [self.camera_config.get_M(h, reverse=True, to_bbox_grid=True) for h in hs]
+        ## Mean velocity over entire profile
+        z_a = self.camera_config.h_to_z(self.h_a)
+
+        depth = z_a - self._obj.zcoords
+        depth[depth < 0] = 0.0
+
+        # ds.transect.camera_config.get_depth(ds.zcoords, ds.transect.h_a)
+        wet_scoords = self._obj.scoords[depth > 0].values
+        if len(wet_scoords) == 0:
+            # no wet points found. Velocity can only be missing
+            v_av = np.nan
+        if len(wet_scoords) > 1:
+            velocity_int = self._obj[v_name].fillna(0.0).integrate(coord="scoords")  # m2/s
+            width = (wet_scoords[-1] + (wet_scoords[-1] - wet_scoords[-2]) * 0.5) - (
+                wet_scoords[0] - (wet_scoords[1] - wet_scoords[0]) * 0.5
+            )
+            v_av = velocity_int / width
         else:
-            # use user defined M instead
-            ms = [trans_mat for _ in hs]
-        # compute row and column position of vectors in original reprojected background image col/row coordinates
-        cols, rows = zip(
-            *[
-                helpers.xy_to_perspective(
-                    x, y, self.camera_config.resolution, trans_mat, reverse_y=self.camera_config.shape[0]
-                )
-                for x, y, trans_mat in zip(xs, ys, ms)
-            ],
-        )
-        # ensure y coordinates start at the top in the right orientation
-        shape_y, shape_x = self.camera_shape
-        rows = shape_y - np.array(rows)
-        cols = np.array(cols)
-        if mask_outside:
-            # remove values that do not fit in the frames
-            cols[np.any([cols < 0, cols > self.camera_shape[1]], axis=0)] = np.nan
-            rows[np.any([rows < 0, rows > self.camera_shape[0]], axis=0)] = np.nan
-
-        return cols, rows
+            v_av = self._obj[v_name][:, depth > 0]
+        return v_av
+
+    def get_v_bulk(self, q_name="q"):
+        """Compute the bulk velocity.
+
+        Parameters
+        ----------
+        q_name : str, optional
+            name of variable where depth integrated velocities [m2 s-1] are stored (Default value = "q")
+
+        Returns
+        -------
+        xr.DataArray
+            bulk velocities for all provided quantiles or time steps
+
+        """
+        discharge = self._obj[q_name].fillna(0.0).integrate(coord="scoords")
+        wet_surf = self.wetted_surface
+        v_bulk = discharge / wet_surf
+        return v_bulk
 
     def get_river_flow(self, q_name="q", discharge_name="river_flow"):
         """Integrate time series of depth averaged velocities [m2 s-1] into cross-section integrated flow [m3 s-1].