pyopenrivercam 0.8.10__py3-none-any.whl → 0.8.12__py3-none-any.whl

{pyopenrivercam-0.8.10.dist-info → pyopenrivercam-0.8.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenrivercam
-Version: 0.8.10
+Version: 0.8.12
 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.dist-info → pyopenrivercam-0.8.12.dist-info}/RECORD

@@ -1,6 +1,6 @@
-pyorc/__init__.py,sha256=ZeURmlD1_OTTOXcunlmrtV0H9un_mP9Q4Cr0NlSU-uo,524
+pyorc/__init__.py,sha256=osrK3G2RA5IsF1ka-QHSPa7gXf7JCXQuUWK8RnR1I1A,524
 pyorc/const.py,sha256=Ia0KRkm-E1lJk4NxQVPDIfN38EBB7BKvxmwIHJrGPUY,2597
-pyorc/cv.py,sha256=CTv0TbbcKeSQmKsX8mdVDXpSkhKZmr8SgT20YXMvZ0s,49156
+pyorc/cv.py,sha256=fXGqT8vBn9-z6UxS5ho7thP9VQll9RrYHJW5KnUJQjo,50250
 pyorc/helpers.py,sha256=90TDtka0ydAydv3g5Dfc8MgtuSt0_9D9-HOtffpcBds,30636
 pyorc/plot_helpers.py,sha256=gLKslspsF_Z4jib5jkBv2wRjKnHTbuRFgkp_PCmv-uU,1803
 pyorc/project.py,sha256=CGKfICkQEpFRmh_ZeDEfbQ-wefJt7teWJd6B5IPF038,7747
@@ -8,12 +8,12 @@ pyorc/pyorc.sh,sha256=-xOSUNnMAwVbdNkjKNKMZMaBljWsGLhadG-j0DNlJP4,5
 pyorc/sample_data.py,sha256=53NVnVmEksDw8ilbfhFFCiFJiGAIpxdgREbA_xt8P3o,2508
 pyorc/api/__init__.py,sha256=k2OQQH4NrtXTuVm23d0g_SX6H5DhnKC9_kDyzJ4dWdk,428
 pyorc/api/cameraconfig.py,sha256=NP9F7LhPO3aO6FRWkrGl6XpX8O3K59zfTtaYR3Kujqw,65419
-pyorc/api/cross_section.py,sha256=un7_VFHMOpBM8FE7lQnZIsaxidnABzFWlyaDHIUfzoA,52039
+pyorc/api/cross_section.py,sha256=MH0AEw5K1Kc1ClZeQRBUYkShZYVk41fshLn6GzCZAas,65212
 pyorc/api/frames.py,sha256=Kls4mpU_4hoUaXs9DJf2S6RHyp2D5emXJkAQWvvT39U,24300
-pyorc/api/mask.py,sha256=COsL4fxz-Rsn-wgpojpJ1se4FGA8CZ_R1jx3iVUYB30,16462
+pyorc/api/mask.py,sha256=-owe66kte2ob3_Zndf21JR-LyEX_1mECbHOuqNfzuMc,16507
 pyorc/api/orcbase.py,sha256=C23QTKOyxHUafyJsq_t7xn_BzAEvf4DDfzlYAopons8,4189
-pyorc/api/plot.py,sha256=-rDmEccwpJXojCyBEKFCd8NpBwLhcZ8tsOq62n26zu4,30898
-pyorc/api/transect.py,sha256=KU0ZW_0NqYD4jeDxvuWJi7X06KqrcgO9afP7QmWuixA,14162
+pyorc/api/plot.py,sha256=MxIEIS8l46bUaca0GtMazx8-k2_TbfQLrPCPAjuWos8,31082
+pyorc/api/transect.py,sha256=wENKWt0u0lHtT0lPYv47faHf_iAN9Mmeev-vwWjnz6E,13382
 pyorc/api/velocimetry.py,sha256=bfU_XPbUbrdBI2XGprzh_3YADbGHfy4OuS1oBlbLEEI,12047
 pyorc/api/video.py,sha256=lGD6bcV6Uu2u3zuGF_m3KxX2Cyp9k-YHUiXA42TOE3E,22458
 pyorc/cli/__init__.py,sha256=A7hOQV26vIccPnDc8L2KqoJOSpMpf2PiMOXS18pAsWg,32
@@ -23,12 +23,12 @@ pyorc/cli/log.py,sha256=Vg8GznmrEPqijfW6wv4OCl8R00Ld_fVt-ULTitaDijY,2824
 pyorc/cli/main.py,sha256=qhAZkUuAViCpHh9c19tpcpbs_xoZJkYHhOsEXJBFXfM,12742
 pyorc/service/__init__.py,sha256=vPrzFlZ4e_GjnibwW6-k8KDz3b7WpgmGcwSDk0mr13Y,55
 pyorc/service/camera_config.py,sha256=OsRLpe5jd-lu6HT4Vx5wEg554CMS-IKz-q62ir4VbPo,2375
-pyorc/service/velocimetry.py,sha256=UFjxmq5Uhk8wnBLScAyTaVWTPTCnH9hJdKOYBFrGZ_Y,33288
+pyorc/service/velocimetry.py,sha256=bPI1OdN_fi0gZES08mb7yqCS_4I-lKSZ2JvWSGTRD1E,34434
 pyorc/velocimetry/__init__.py,sha256=lYM7oJZWxgJ2SpE22xhy7pBYcgkKFHMBHYmDvvMbtZk,148
 pyorc/velocimetry/ffpiv.py,sha256=CYUjgwnB5osQmJ83j3E00B9P0_hS-rFuhyvufxKXtag,17487
 pyorc/velocimetry/openpiv.py,sha256=6BxsbXLzT4iEq7v08G4sOhVlYFodUpY6sIm3jdCxNMs,13149
-pyopenrivercam-0.8.10.dist-info/entry_points.txt,sha256=Cv_WI2Y6QLnPiNCXGli0gS4WAOAeMoprha1rAR3vdRE,44
-pyopenrivercam-0.8.10.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-pyopenrivercam-0.8.10.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pyopenrivercam-0.8.10.dist-info/METADATA,sha256=05xRhY6LmvJNoWvlGH1KkoAiVHb-rGQcya7gYWxHmdw,11641
-pyopenrivercam-0.8.10.dist-info/RECORD,,
+pyopenrivercam-0.8.12.dist-info/entry_points.txt,sha256=Cv_WI2Y6QLnPiNCXGli0gS4WAOAeMoprha1rAR3vdRE,44
+pyopenrivercam-0.8.12.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+pyopenrivercam-0.8.12.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pyopenrivercam-0.8.12.dist-info/METADATA,sha256=hU0j9dsG6ksjRTM6UdMLVJ15TGzGQ9lW1mHhxDKxJy0,11641
+pyopenrivercam-0.8.12.dist-info/RECORD,,

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.12"
 
 from .api import CameraConfig, CrossSection, Frames, Transect, Velocimetry, Video, get_camera_config, load_camera_config  # noqa
 from .project import *  # noqa

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
 
@@ -278,7 +278,7 @@ class CrossSection:
         Parameters
         ----------
         h : float
-            water level [m]
+            water level [m].
         sz : bool, optional
             If set, return water level line in y-z projection, by default False.
         extend_by : float, optional
@@ -613,16 +613,23 @@ 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 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 for a given water level in the cross
-        section.
+        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 +637,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 +655,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
@@ -1074,6 +1099,182 @@ class CrossSection:
             )
         return ax
 
+    def _preprocess_level_range(
+        self,
+        min_h: Optional[float] = None,
+        max_h: Optional[float] = None,
+        min_z: Optional[float] = None,
+        max_z: Optional[float] = None,
+    ):
+        """Set minimum and maximum z-levels (if not provided) based on the camera config."""
+        if min_z is None:
+            if min_h is not None:
+                min_z = self.camera_config.h_to_z(min_h)
+                min_z = np.maximum(min_z, self.z.min())
+        if max_z is None:
+            if max_h is not None:
+                max_z = self.camera_config.h_to_z(max_h)
+                max_z = np.minimum(max_z, self.z.max())
+        if min_z and max_z:
+            # check for z_min < z_max
+            if min_z > max_z:
+                raise ValueError("Minimum water level is higher than maximum water level.")
+        return min_z, max_z
+
+    def _preprocess_l_range(self, l_min: float, l_max: float, ds_max=0.5, dz_max=0.02) -> List[float]:
+        """Generate a list of evaluation points between l_min and l_max for water level detection.
+
+        Controls on evaluation are that vertically (using `self.z`), points are at least `dz_max` meters apart and
+        horizontally (using `self.s`), points are included if the distance between them exceeds `dz_min` meters.
+
+        Parameters
+        ----------
+        l_min: float
+            Minimum l value for evaluation.
+        l_max: float
+            Maximum l value for evaluation.
+        ds_max : float, optional
+            maximum step size between evaluation points in horizontal direction, by default 0.5.
+        dz_max : float, optional
+            maximum step size between evaluation points in vertical direction, by default 0.02.
+
+        Returns
+        -------
+        Tuple[List[float], List[float]]
+            lists of l-coordinates and associated z-coordinates for evaluation.
+
+        """
+        # # Initial list of evaluation points
+        # l_range = []
+        # z_range = []
+        # Start with the first point within the range
+        current_l = l_min
+        last_z = None
+        last_s = None
+
+        # Add all points from self.l that lie within [l_min, l_max]
+        valid_l_indices = (self.l >= l_min) & (self.l <= l_max)  # Logical filter
+        l_range = list(self.l[valid_l_indices])
+        z_range = list(self.z[valid_l_indices])
+
+        # Iterate over the self.l values by interpolating within the range
+        while current_l <= l_max:
+            # Interpolate x, y, z, and s using the available properties
+            # x = self.interp_x(current_l)
+            # y = self.interp_y(current_l)
+            z = self.interp_z(current_l)
+            s = self.interp_s_from_l(current_l)
+
+            # Append the point if it satisfies the required criteria
+            if last_z is None or last_s is None or abs(z - last_z) >= dz_max or abs(s - last_s) >= ds_max:
+                l_range.append(current_l)
+                z_range.append(z)
+                last_z = z
+                last_s = s
+
+            # Increment l
+            current_l += 0.01  # Increment in steps small enough to meet any constraint
+
+        # add the final l
+        if current_l > l_max:
+            l_range.append(l_max)
+            z_range.append(self.interp_z(l_max))
+
+        # sort l_range and z_range by incremental l_range
+        sorted_indices = np.argsort(l_range)
+        l_range = np.array(l_range)[sorted_indices]
+        z_range = np.array(z_range)[sorted_indices]
+
+        return l_range, z_range
+
+    def _water_level_score_range(
+        self,
+        img: np.ndarray,
+        bank: BANK_OPTIONS = "far",
+        bin_size: int = 5,
+        length: float = 2.0,
+        padding: float = 0.5,
+        offset: float = 0.0,
+        ds_max: Optional[float] = 0.5,
+        dz_max: Optional[float] = 0.02,
+        min_h: Optional[float] = None,
+        max_h: Optional[float] = None,
+        min_z: Optional[float] = None,
+        max_z: Optional[float] = None,
+    ) -> float:
+        """Evaluate a range of scores for water level detection.
+
+        This computes the histogram score for a range of l values and returns all scores for further evaluation.
+        The histogram score is a measure of dissimilarity (low means very dissimilar) of pixel intensity distributions
+        left and right of hypothesized water lines. The evaluation points along the cross section (l-values) are
+        determined by two parameters max_ds (maximum step in horizontal direction) and max_dz (maximum step in vertical
+        direction).
+
+        Parameters
+        ----------
+        img : np.ndarray
+            image (uint8) used to estimate water level from.
+        bank: Literal["far", "near", "both"], optional
+            select from which bank to detect the water level. Use this if camera is positioned in a way that only
+            one shore is clearly distinguishable and not obscured. Typically you will use "far" if the camera is
+            positioned on one bank, aimed perpendicular to the flow. Use "near" if not the full cross section is
+            visible, but only the part nearest the camera. And leave empty when both banks are clearly visible and
+            approximately the same in distance (e.g. middle of a bridge). If not provided, the bank is detected based
+            on the best estimate from both banks.
+        bin_size : int, optional
+            Size of bins for histogram calculation of the provided image intensities, default 5.
+        length : float, optional
+            length of the waterline [m], by default 2.0
+        padding : float, optional
+            amount of distance [m] to extend the polygon beyond the waterline, by default 0.5. Two polygons are drawn
+            left and right of hypothesized water line at -padding and +padding.
+        offset : float, optional
+            perpendicular offset of the waterline from the cross-section [m], by default 0.0
+        ds_max : float, optional
+            maximum step size between evaluation points in horizontal direction, by default 0.5.
+        dz_max : float, optional
+            maximum step size between evaluation points in vertical direction, by default 0.02.
+        min_h : float, optional
+            minimum water level to try detection [m]. If not provided, the minimum water level is taken from the
+            cross section.
+        max_h : float, optional
+            maximum water level to try detection [m]. If not provided, the maximum water level is taken from the
+            cross section.
+        min_z : float, optional
+            same as min_h but using z-coordinates instead of local datum, min_z overrules min_h
+        max_z : float, optional
+            same as max_z but using z-coordinates instead of local datum, max_z overrules max_h
+
+        """
+        l_min, l_max = self.get_line_of_interest(bank=bank)
+        min_z, max_z = self._preprocess_level_range(min_h, max_h, min_z, max_z)
+        l_range, z_range = self._preprocess_l_range(l_min=l_min, l_max=l_max, ds_max=ds_max, dz_max=dz_max)
+        if len(img.shape) == 3:
+            # flatten image first if it his a time dimension
+            img = img.mean(axis=2)
+        assert (
+            img.shape[0] == self.camera_config.height
+        ), f"Image height {img.shape[0]} is not the same as camera_config height {self.camera_config.height}"
+        assert (
+            img.shape[1] == self.camera_config.width
+        ), f"Image width {img.shape[1]} is not the same as camera_config width {self.camera_config.width}"
+
+        # gridded results
+        results = [
+            self.get_histogram_score(
+                x=[l],
+                img=img,
+                bin_size=bin_size,
+                offset=offset,
+                padding=padding,
+                length=length,
+                min_z=min_z,
+                max_z=max_z,
+            )
+            for l in l_range
+        ]
+        return l_range, z_range, results
+
     def detect_water_level(
         self,
         img: np.ndarray,
@@ -1087,11 +1288,11 @@ class CrossSection:
         min_z: Optional[float] = None,
         max_z: Optional[float] = None,
     ) -> float:
-        """Detect water level optically from provided image.
+        """Detect water level from provided image through optimization.
 
         Water level detection is done by first detecting the water line along the cross-section by comparisons
         of distribution functions left and right of hypothesized water lines, and then looking up the water level
-        associated with the water line location.
+        associated with the water line location. A differential evolution optimization is used to find the optimum.
 
         Parameters
         ----------
@@ -1124,19 +1325,14 @@ class CrossSection:
         max_z : float, optional
             same as max_z but using z-coordinates instead of local datum, max_z overrules max_h
 
-        """
-        if min_z is None:
-            if min_h is not None:
-                min_z = self.camera_config.h_to_z(min_h)
-                min_z = np.maximum(min_z, self.z.min())
-        if max_z is None:
-            if max_h is not None:
-                max_z = self.camera_config.h_to_z(max_h)
-                max_z = np.minimum(max_z, self.z.max())
-        if min_z and max_z:
-            if min_z > max_z:
-                raise ValueError("Minimum water level is higher than maximum water level.")
+        Returns
+        -------
+        float
+            Most likely water level, according to optimization and scoring (most distinct intensity PDF)
 
+        """
+        l_min, l_max = self.get_line_of_interest(bank=bank)
+        min_z, max_z = self._preprocess_level_range(min_h, max_h, min_z, max_z)
         if len(img.shape) == 3:
             # flatten image first if it his a time dimension
             img = img.mean(axis=2)
@@ -1146,9 +1342,7 @@ class CrossSection:
         assert (
             img.shape[1] == self.camera_config.width
         ), f"Image width {img.shape[1]} is not the same as camera_config width {self.camera_config.width}"
-        # determine the relevant start point if only one is used
-        # import pdb;pdb.set_trace()
-        l_min, l_max = self.get_line_of_interest(bank=bank)
+
         opt = differential_evolution(
             self.get_histogram_score,
             popsize=50,
@@ -1167,3 +1361,93 @@ class CrossSection:
                 stacklevel=2,
             )
         return h
+
+    def detect_water_level_s2n(
+        self,
+        img: np.ndarray,
+        bank: BANK_OPTIONS = "far",
+        bin_size: int = 5,
+        length: float = 2.0,
+        padding: float = 0.5,
+        offset: float = 0.0,
+        ds_max: Optional[float] = 0.5,
+        dz_max: Optional[float] = 0.02,
+        min_h: Optional[float] = None,
+        max_h: Optional[float] = None,
+        min_z: Optional[float] = None,
+        max_z: Optional[float] = None,
+    ) -> float:
+        """Detect water level optically from provided image, through evaluation of a vector of locations.
+
+        Water level detection is done by first detecting the water line along the cross-section by comparisons
+        of distribution functions left and right of hypothesized water lines, and then looking up the water level
+        associated with the water line location. Because a full vector of results is evaluated, the signal to noise
+        ratio can be evaluated and used to understand the quality of the water level detection. Two parameters are used
+        to control the spacing between l (location) coordinates: `ds_max` controls the maximum step size in horizontal
+        direction, `dz_max` controls the maximum step size in vertical direction.
+
+        Parameters
+        ----------
+        img : np.ndarray
+            image (uint8) used to estimate water level from.
+        bank: Literal["far", "near", "both"], optional
+            select from which bank to detect the water level. Use this if camera is positioned in a way that only
+            one shore is clearly distinguishable and not obscured. Typically you will use "far" if the camera is
+            positioned on one bank, aimed perpendicular to the flow. Use "near" if not the full cross section is
+            visible, but only the part nearest the camera. And leave empty when both banks are clearly visible and
+            approximately the same in distance (e.g. middle of a bridge). If not provided, the bank is detected based
+            on the best estimate from both banks.
+        bin_size : int, optional
+            Size of bins for histogram calculation of the provided image intensities, default 5.
+        length : float, optional
+            length of the waterline [m], by default 2.0.
+        padding : float, optional
+            amount of distance [m] to extend the polygon beyond the waterline, by default 0.5. Two polygons are drawn
+            left and right of hypothesized water line at -padding and +padding.
+        offset : float, optional
+            perpendicular offset of the waterline from the cross-section [m], by default 0.0.
+        ds_max : float, optional
+            maximum step size between evaluation points in horizontal direction, by default 0.5.
+        dz_max : float, optional
+            maximum step size between evaluation points in vertical direction, by default 0.02.
+        min_h : float, optional
+            minimum water level to try detection [m]. If not provided, the minimum water level is taken from the
+            cross section.
+        max_h : float, optional
+            maximum water level to try detection [m]. If not provided, the maximum water level is taken from the
+            cross section.
+        min_z : float, optional
+            same as min_h but using z-coordinates instead of local datum, min_z overrules min_h.
+        max_z : float, optional
+            same as max_z but using z-coordinates instead of local datum, max_z overrules max_h.
+
+        Returns
+        -------
+        float
+            Most likely water level, according to optimization and scoring (most distinct intensity PDF).
+        float
+            Signal to noise ratio, calculated as the mean of all computed scores divided by the optimum (lowest) score
+            found in the entire l-range.
+
+        """
+        l_range, z_range, results = self._water_level_score_range(
+            img=img,
+            bank=bank,
+            bin_size=bin_size,
+            length=length,
+            padding=padding,
+            offset=offset,
+            ds_max=ds_max,
+            dz_max=dz_max,
+            min_h=min_h,
+            max_h=max_h,
+            min_z=min_z,
+            max_z=max_z,
+        )
+        # find optimum (minimum score)
+        idx = np.argmin(results)
+        s2n = np.mean(results) / results[idx]
+        z = z_range[idx]
+        h = self.camera_config.z_to_h(z)
+        # warning if the optimum is on the edge of the search space for l
+        return h, s2n

pyorc/api/mask.py

@@ -10,12 +10,11 @@ from pyorc import helpers
 from pyorc.const import corr, s2n, v_x, v_y
 
 commondoc = """
-    Returns
-    -------
-    mask : xr.DataArray
-        mask applicable to input dataset with ``ds.velocimetry.filter(mask)``.
-        If ``inplace=True``, the dataset will be returned masked with ``mask``.
-
+        Returns
+        -------
+        mask : xr.DataArray
+            mask applicable to input dataset with ``ds.velocimetry.filter(mask)``.
+            If ``inplace=True``, the dataset will be returned masked with ``mask``.
 """
 
 
@@ -203,7 +202,7 @@ class _Velocimetry_MaskMethods:
 
     @_base_mask(time_allowed=True)
     def corr(self, tolerance=0.1):
-        """Mass values with too low correlation.
+        """Mask values with too low correlation.
 
         Parameters
         ----------
@@ -304,16 +303,17 @@ class _Velocimetry_MaskMethods:
             (default: 1) wdw is used to fill wdw_x_min and wdwd_y_min with its negative (-wdw) value, and wdw_y_min and
         kwargs : dict
             keyword arguments to pass to ``helpers.stack_window``. These can be:
-            wdw_x_min : int, optional
-                window size in negative x-direction of grid (must be negative), overrules wdw in negative x-direction
-                if set.
-            wdw_x_max : int, optional
-                window size in positive x-direction of grid, overrules wdw in positive x-direction if set
-            wdw_y_min : int, optional
-                window size in negative y-direction of grid (must be negative), overrules wdw in negative y-direction
-                if set.
-            wdw_y_max : int, optional
-                window size in positive y-direction of grid, overrules wdw in positive x-direction if set.
+
+            - ``wdw_x_min`` : int, optional
+              window size in negative x-direction of grid (must be negative), overrules wdw in negative x-direction if
+              set.
+            - ``wdw_x_max`` : int, optional
+              window size in positive x-direction of grid, overrules wdw in positive x-direction if set.
+            - ``wdw_y_min`` : int, optional
+              window size in negative y-direction of grid (must be negative), overrules wdw in negative y-direction if
+              set.
+            - ``wdw_y_max`` : int, optional
+              window size in positive y-direction of grid, overrules wdw in positive x-direction if set.
 
         """
         # collect points within a stride, collate and analyze for nan fraction
@@ -326,7 +326,7 @@ class _Velocimetry_MaskMethods:
     def window_mean(self, tolerance=0.7, wdw=1, mode="or", **kwargs):
         """Mask values when their value deviates significantly from mean.
 
-        This is computed as relative fraction from the mean of its  neighbours (inc. itself).
+        This is computed as relative fraction from the mean of its neighbours (inc. itself).
 
         Parameters
         ----------
@@ -339,16 +339,17 @@ class _Velocimetry_MaskMethods:
             be within tolerance.
         kwargs : dict
             keyword arguments to pass to ``helpers.stack_window``. These can be:
-            wdw_x_min : int, optional
-                window size in negative x-direction of grid (must be negative), overrules wdw in negative x-direction
-                if set.
-            wdw_x_max : int, optional
-                window size in positive x-direction of grid, overrules wdw in positive x-direction if set.
-            wdw_y_min : int, optional
-                window size in negative y-direction of grid (must be negative), overrules wdw in negative y-direction
-                if set.
-            wdw_y_max : int, optional
-                window size in positive y-direction of grid, overrules wdw in positive x-direction if set.
+
+            - ``wdw_x_min`` : int, optional
+              window size in negative x-direction of grid (must be negative), overrules wdw in negative x-direction
+              if set.
+            - ``wdw_x_max`` : int, optional
+              window size in positive x-direction of grid, overrules wdw in positive x-direction if set.
+            - ``wdw_y_min`` : int, optional
+              window size in negative y-direction of grid (must be negative), overrules wdw in negative y-direction
+              if set.
+            - ``wdw_y_max`` : int, optional
+              window size in positive y-direction of grid, overrules wdw in positive x-direction if set.
 
         """
         # collect points within a stride, collate and analyze for median value and deviation

pyorc/api/plot.py

@@ -2,12 +2,11 @@
 
 import copy
 import functools
+import warnings
 
 import matplotlib.pyplot as plt
 import matplotlib.ticker as mticker
 import numpy as np
-import warnings
-
 from matplotlib import colors, patheffects
 
 from pyorc import helpers
@@ -207,10 +206,9 @@ def _base_plot(plot_func):
                                 color="r",
                                 label="water level",
                             )
-                        except:
+                        except Exception:
                             warnings.warn(
-                                "Not able to find a unique location for plotting of water level",
-                                stacklevel=2
+                                "Not able to find a unique location for plotting of water level", stacklevel=2
                             )
 
                     # draw some depth lines for better visual interpretation.
@@ -620,7 +618,7 @@ def set_default_kwargs(kwargs, method="quiver", mode="local"):
         kwargs["cmap"] = "rainbow"  # the famous rainbow colormap!
     if "vmin" not in kwargs and "vmax" not in kwargs and "norm" not in kwargs:
         # set a normalization array
-        norm = [0, 0.05, 0.1, 0.2, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
+        norm = [0, 0.05, 0.1, 0.2, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 5.0, 10.0]
         kwargs["norm"] = colors.BoundaryNorm(norm, ncolors=256, extend="max")
     if method == "quiver":
         if "scale" not in kwargs:
@@ -752,8 +750,16 @@ 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 | "
+        f"$v_{{surf}}$: {v_surf.values:1.2f} m/s | "
+        f"$\\overline{{v}}$: {v_bulk.values:1.2f} m/s\n"
+        f"$Q$: {Q.values:1.2f} m3/s"
+    )
+
     if "q_nofill" in ds:
         _ds.transect.get_river_flow(q_name="q_nofill")
         Q_nofill = np.abs(_ds.river_flow)
@@ -765,7 +771,7 @@ def plot_text(ax, ds, prefix, suffix):
         xloc,
         yloc,
         string,
-        size=24,
+        size=18,
         horizontalalignment="right",
         verticalalignment="top",
         path_effects=path_effects,

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].

pyorc/cv.py

@@ -7,6 +7,7 @@ import warnings
 import cv2
 import numpy as np
 import rasterio
+from numba import jit, prange
 from scipy import optimize
 from shapely.affinity import rotate
 from shapely.geometry import LineString, Point, Polygon
@@ -1034,16 +1035,48 @@ def get_aoi(dst_corners, resolution=None, method="corners"):
     return bbox
 
 
+@jit(nopython=True, cache=True, nogil=True)
+def numba_extract_pixels(img, mask):
+    """Optimized pixel extraction within a polygon-defined mask."""
+    pixel_values = []
+    rows, cols = img.shape
+    for i in prange(rows):
+        for j in prange(cols):
+            if mask[i, j] == 255:
+                pixel_values.append(img[i, j])
+    return np.array(pixel_values)
+
+
 def get_polygon_pixels(img, pol, reverse_y=False):
     """Get pixel intensities within a polygon."""
     if pol.is_empty:
         return np.array([np.nan])
-    polygon_coords = list(pol.exterior.coords)
-    mask = np.zeros_like(img, dtype=np.uint8)
-    cv2.fillPoly(mask, np.array([polygon_coords], np.int32), color=255)
+    min_x, min_y, max_x, max_y = map(int, pol.bounds)
+    # Ensure bounding box remains within the image dimensions
+    min_x = max(min_x, 0)
+    min_y = max(min_y, 0)
+    max_x = min(max_x, img.shape[1])
+    max_y = min(max_y, img.shape[0])
+
     if reverse_y:
-        return np.flipud(img)[mask == 255]
-    return img[mask == 255]
+        img = np.flipud(img)
+
+    # Crop the image based on the bounding box
+    cropped_img = img[min_y:max_y, min_x:max_x]
+    # reduce polygon coordinates to ensure compatibility with cropped_img
+    cropped_polygon_coords = [(x - min_x, y - min_y) for x, y in pol.exterior.coords]
+
+    mask = np.zeros_like(cropped_img, dtype=np.uint8)
+    if 0 in mask.shape:
+        # no shape in mask, so return empty array instantly
+        return np.array([], dtype=np.uint8)
+    try:
+        cv2.fillPoly(mask, [np.array(cropped_polygon_coords, dtype=np.int32)], color=255)
+    except Exception:
+        import pdb
+
+        pdb.set_trace()
+    return numba_extract_pixels(cropped_img, mask)
 
 
 def optimize_intrinsic(src, dst, height, width, c=2.0, lens_position=None, camera_matrix=None, dist_coeffs=None):

pyorc/service/velocimetry.py

@@ -31,29 +31,46 @@ def get_water_level(
     n_start: int = 0,
     n_end: int = 1,
     method: const.ALLOWED_COLOR_METHODS_WATER_LEVEL = "grayscale",
+    s2n_thres: float = 3.0,
     frames_options: Optional[Dict] = None,
     water_level_options: Optional[Dict] = None,
+    logger: logging.Logger = logger,
 ):
     water_level_options = {} if water_level_options is None else water_level_options
     frames_options = {} if frames_options is None else frames_options
-
-    if method not in ["grayscale", "hue", "sat", "val"]:
-        raise ValueError(
-            f"Method {method} not supported for water level detection, choose one"
-            f" of {const.ALLOWED_COLOR_METHODS_WATER_LEVEL}"
-        )
-    da_frames = video.get_frames(method=method)[n_start:n_end]
-    # preprocess
-    da_frames = apply_methods(da_frames, "frames", logger=logger, skip_args=["to_video"], **frames_options)
-    # if preprocessing still results in a time dim, average in time
-    if "time" in da_frames.dims:
-        da_mean = da_frames.mean(dim="time")
-    else:
-        da_mean = da_frames
-    # extract the image
-    img = np.uint8(da_mean.values)
-    h_a = cross_section.detect_water_level(img, **water_level_options)
-    return h_a
+    # if frames_options is list of dict then continue, if not then make list of dict
+    if not isinstance(frames_options, list):
+        frames_options = [frames_options]
+    for frames_options_ in frames_options:
+        # get method from frames_options if available, otherwise use the parent or default one
+        method_ = frames_options_.pop("method", method)
+        s2n_thres_ = frames_options_.pop("s2n_thres", s2n_thres)
+
+        if method_ not in ["grayscale", "hue", "sat", "val"]:
+            raise ValueError(
+                f"Method {method} not supported for water level detection, choose one"
+                f" of {const.ALLOWED_COLOR_METHODS_WATER_LEVEL}"
+            )
+        da_frames = video.get_frames(method=method_)[n_start:n_end]
+        # preprocess
+        logger.debug(f"Applying preprocessing methods {frames_options_}")
+        da_frames = apply_methods(da_frames, "frames", logger=logger, skip_args=["to_video"], **frames_options_)
+        # if preprocessing still results in a time dim, average in time
+        if "time" in da_frames.dims:
+            da_mean = da_frames.mean(dim="time")
+        else:
+            da_mean = da_frames
+        # extract the image
+        img = np.uint8(da_mean.values)
+        h_a, s2n = cross_section.detect_water_level_s2n(img, **water_level_options)
+        if s2n > s2n_thres_:
+            # high enough signal-to-noise ratio, so return, otherwise continue with next frame treatment set
+            logger.debug(f"Found significant water level at h: {h_a:.3f} m with signal-to-noise: {s2n} > {s2n_thres_}")
+            return h_a
+        else:
+            logger.debug(f"Found water level at h: {h_a:.3f} m with too low signal-to-noise: {s2n} < {s2n_thres_}")
+    # if none of frame treatments gives a satisfactory h_a, return None
+    return
 
 
 def vmin_vmax_to_norm(opts):
@@ -434,7 +451,8 @@ class VelocityFlowProcessor(object):
     def water_level(self, **kwargs):
         try:
             self.logger.debug("Estimating water level from video by crossing water line with cross section.")
-            h_a = get_water_level(self.video_obj, cross_section=self.cross_section_wl, **kwargs)
+
+            h_a = get_water_level(self.video_obj, cross_section=self.cross_section_wl, logger=self.logger, **kwargs)
             if h_a is None:
                 self.logger.error("Water level could not be estimated from video. Please set a water level with --h_a.")
                 raise click.Abort()