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

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

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

@@ -1,6 +1,6 @@
-pyorc/__init__.py,sha256=5wLWixrMpcQEFTVDSFHd_K2iG-iNi3WxQydqTrq3xzU,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,11 +8,11 @@ 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=60n9EPe3HYvJxsX4CKb2pz3pf6hDRzqDrPR6uQOdvD8,53047
+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=WUgJ5CJAY6-tstB7wd1vMs-jrcqIQxCmUfEBITtJWMU,31078
+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
@@ -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.11.dist-info/entry_points.txt,sha256=Cv_WI2Y6QLnPiNCXGli0gS4WAOAeMoprha1rAR3vdRE,44
-pyopenrivercam-0.8.11.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-pyopenrivercam-0.8.11.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pyopenrivercam-0.8.11.dist-info/METADATA,sha256=hNo75nJNt8C2xbKpILV2gX_3jq6oLKEOkBgHpaRHLBE,11641
-pyopenrivercam-0.8.11.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.11"
+__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

@@ -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,7 +613,9 @@ 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, perimeter: bool = False) -> Union[geometry.MultiPolygon, geometry.MultiLineString]:
+    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
@@ -1097,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,
@@ -1110,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
         ----------
@@ -1147,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)
@@ -1169,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,
@@ -1190,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:
@@ -755,7 +753,13 @@ def plot_text(ax, ds, prefix, suffix):
     v_surf = _ds.transect.get_v_surf()
     v_bulk = _ds.transect.get_v_bulk()
     string = prefix
-    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)
+    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)

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()