pyopenrivercam 0.8.5__tar.gz → 0.8.7__tar.gz

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [0.8.7] = 2025-06-30
+### Added
+- CLI option `--cross_wl`
+- A new 3-point bounding box estimation, ideal for selecting a bounding box in strongly oblique cases. First select left
+  bank, then right bank, then a point up- or downstream from the selected line for the size of the bounding box.
+- `rvec` and `tvec` are written to camera configuration after fitting.
+### Changed
+- CLI option `--cross_wl` now replaces `--cross` for optical water level estimation. `--cross` is only used for
+  discharge calculation
+- Plotting in camera objective is accelerated
+- water level detection with `CrossSection.detect_water_level` can now consume either `min_z` and `max_z` (for levels
+  in the original coordinate system) or `min_h` and `max_h` (for levels using the local `h_ref` datum if provided).
+  These minimum and maximum levels can be used to pre-condition the level range that the algoithm will seek in.
+- Pose fitting can now be performed with a pre-defined camera matrix and set of distortion coefficients. This is very
+  useful when a user has already pre-calibrated these parameters. It will improve the fit of the `rvec` and `tvec`,
+  i.e. rotation and translation vectors.
+- Changed code coverage reporting from Codecov to sonarqube for code coverage reports. Codecov caused issues with
+  numba code.
+### Deprecated
+### Removed
+### Fixed
+- incorrect estimation of optical water level if `bank="near"` was used. This resulted in only a smaller portion of the
+  cross section being used. Now the full nearby side is used.
+
+## [0.8.6] = 2025-05-16
+### Added
+- added options `--k1`, `--k2` and `--focal_length` to command line interface for cases where
+  focal length, and distortion coefficients are already known
+### Changed
+- optimization of intrinsics can now also be done with partly already known data. If k1 and k2 are known
+  these can be passed as camera
+- Debug messaging increased in `service.velocimetry`.
+### Deprecated
+### Removed
+### Fixed
+
+
 ## [0.8.5] = 2025-03-25
 ### Added
 - option `--cross` can now also be provided at service level. Only relevant

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenrivercam
-Version: 0.8.5
+Version: 0.8.7
 Summary: pyorc: free and open-source image-based surface velocity and discharge.
 Author-email: Hessel Winsemius <winsemius@rainbowsensing.com>
 Requires-Python: >=3.9
@@ -78,7 +78,8 @@ width=100 align="right">
 
 [![PyPI](https://badge.fury.io/py/pyopenrivercam.svg)](https://pypi.org/project/pyopenrivercam)
 [![Conda-Forge](https://anaconda.org/conda-forge/pyopenrivercam/badges/version.svg)](https://anaconda.org/conda-forge/pyopenrivercam)
-[![codecov](https://codecov.io/gh/localdevices/pyorc/branch/main/graph/badge.svg?token=0740LBNK6J)](https://codecov.io/gh/localdevices/pyorc)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=localdevices_pyorc&metric=coverage)](https://sonarcloud.io/summary/new_code?id=localdevices_pyorc)
+[![python](https://img.shields.io/pypi/pyversions/pyopenrivercam?color=%2376519B)](https://pypi.org/project/pyopenrivercam/)
 [![docs_latest](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://localdevices.github.io/pyorc/latest)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/localdevices/pyorc.git/main?labpath=examples)
 [![License](https://img.shields.io/github/license/localdevices/pyorc?style=flat)](https://github.com/localdevices/pyorc/blob/main/LICENSE)
@@ -107,7 +108,6 @@ We are seeking funding for the following frequently requested functionalities:
 * Exports to simple text formats and GIS-compatible layers
 * Exports to augmented reality videos
 * Implementation of additional processing algorithms (STIV and LSPTV)
-* Implementation of several optical methods for reading water levels
 * Improved nighttime / poor weather conditions processing through learning approaches
 
 If you wish to fund this or other work on features, please contact us at info@rainbowsensing.com.
@@ -156,7 +156,7 @@ dependencies as follows:
 pip install pyopenrivercam[extra]
 ```
 The `[extra]` section ensures that also geographical plotting is supported, which we recommend especially for the
-set up of a camera configuration.
+set up of a camera configuration with RTK-GPS measured control points.
 
 ### Upgrading from pypi with pip
 

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/README.md

@@ -8,7 +8,8 @@ width=100 align="right">
 
 [![PyPI](https://badge.fury.io/py/pyopenrivercam.svg)](https://pypi.org/project/pyopenrivercam)
 [![Conda-Forge](https://anaconda.org/conda-forge/pyopenrivercam/badges/version.svg)](https://anaconda.org/conda-forge/pyopenrivercam)
-[![codecov](https://codecov.io/gh/localdevices/pyorc/branch/main/graph/badge.svg?token=0740LBNK6J)](https://codecov.io/gh/localdevices/pyorc)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=localdevices_pyorc&metric=coverage)](https://sonarcloud.io/summary/new_code?id=localdevices_pyorc)
+[![python](https://img.shields.io/pypi/pyversions/pyopenrivercam?color=%2376519B)](https://pypi.org/project/pyopenrivercam/)
 [![docs_latest](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://localdevices.github.io/pyorc/latest)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/localdevices/pyorc.git/main?labpath=examples)
 [![License](https://img.shields.io/github/license/localdevices/pyorc?style=flat)](https://github.com/localdevices/pyorc/blob/main/LICENSE)
@@ -37,7 +38,6 @@ We are seeking funding for the following frequently requested functionalities:
 * Exports to simple text formats and GIS-compatible layers
 * Exports to augmented reality videos
 * Implementation of additional processing algorithms (STIV and LSPTV)
-* Implementation of several optical methods for reading water levels
 * Improved nighttime / poor weather conditions processing through learning approaches
 
 If you wish to fund this or other work on features, please contact us at info@rainbowsensing.com.
@@ -86,7 +86,7 @@ dependencies as follows:
 pip install pyopenrivercam[extra]
 ```
 The `[extra]` section ensures that also geographical plotting is supported, which we recommend especially for the
-set up of a camera configuration.
+set up of a camera configuration with RTK-GPS measured control points.
 
 ### Upgrading from pypi with pip
 

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/pyorc/__init__.py

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

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/pyorc/api/cameraconfig.py

@@ -47,7 +47,6 @@ class CameraConfig:
         lens_position: Optional[List[float]] = None,
         corners: Optional[List[List[float]]] = None,
         gcps: Optional[Dict[str, Union[List, float]]] = None,
-        lens_pars: Optional[Dict[str, float]] = None,
         calibration_video: Optional[str] = None,
         is_nadir: Optional[bool] = False,
         stabilize: Optional[List[List]] = None,
@@ -90,10 +89,6 @@ class CameraConfig:
             the same vertical reference as the measured bathymetry and other survey points,
             "crs": int, str or CRS object, CRS in which "dst" points are measured. If None, a local coordinate system is
             assumed (e.g. from spirit level).
-        lens_pars : dict, optional
-            Lens parameters, containing: "k1": float, barrel lens distortion parameter (default: 0.),
-            "c": float, optical center (default: 2.),
-            "focal_length": float, focal length (default: width of image frame)
         calibration_video : str, optional
             local path to video file containing a checkerboard pattern. Must be 9x6 if called directly, otherwise use
             ``.calibrate_camera`` explicitly and provide ``chessboard_size`` explicitly. When used, an automated camera
@@ -120,6 +115,8 @@ class CameraConfig:
         self.height = height
         self.width = width
         self.is_nadir = is_nadir
+        self.camera_matrix = camera_matrix
+        self.dist_coeffs = dist_coeffs
         self.rvec = rvec
         self.tvec = tvec
         if crs is not None:
@@ -137,19 +134,14 @@ class CameraConfig:
             self.lens_position = None
         if gcps is not None:
             self.set_gcps(**gcps)
-        if camera_matrix is None or dist_coeffs is None:
-            if self.is_nadir:
-                # with nadir, no perspective can be constructed, hence, camera matrix and dist coeffs will be set
-                # to default values
-                self.camera_matrix = cv._get_cam_mtx(self.height, self.width)
-                self.dist_coeffs = cv.DIST_COEFFS
-            # camera pars are incomplete and need to be derived
-            else:
-                self.set_intrinsic(camera_matrix=camera_matrix, lens_pars=lens_pars)
+        if self.is_nadir:
+            # with nadir, no perspective can be constructed, hence, camera matrix and dist coeffs will be set
+            # to default values
+            self.camera_matrix = cv.get_cam_mtx(self.height, self.width)
+            self.dist_coeffs = cv.DIST_COEFFS
+        # camera pars are incomplete and need to be derived
         else:
-            # camera matrix and dist coeffs can also be set hard, this overrules the lens_pars option
-            self.camera_matrix = camera_matrix
-            self.dist_coeffs = dist_coeffs
+            self.calibrate()
         if calibration_video is not None:
             self.set_lens_calibration(calibration_video, plot=False)
         if bbox is not None:
@@ -201,6 +193,27 @@ class CameraConfig:
     def dist_coeffs(self, dist_coeffs):
         self._dist_coeffs = dist_coeffs.tolist() if isinstance(dist_coeffs, np.ndarray) else dist_coeffs
 
+    @property
+    def focal_length(self):
+        """Get focal length."""
+        if not self.camera_matrix:
+            return None
+        return self.camera_matrix[0][0]
+
+    @property
+    def k1(self):
+        """Get first distortion coefficient."""
+        if not self.dist_coeffs:
+            return None
+        return self.dist_coeffs[0]
+
+    @property
+    def k2(self):
+        """Get second distortion coefficient."""
+        if not self.dist_coeffs:
+            return None
+        return self.dist_coeffs[1]
+
     @property
     def gcps_dest(self):
         """Get destination coordinates of GCPs.
@@ -308,12 +321,12 @@ class CameraConfig:
         tvec_cam += self.gcps_mean
         # transform back to world
         rvec, tvec = cv.pose_world_to_camera(rvec_cam, tvec_cam)
-        return _, rvec, tvec
+        return rvec, tvec
 
     @property
     def rvec(self):
         """Return rvec from precise N point solution."""
-        return self.pnp[1].tolist() if self._rvec is None else self._rvec
+        return self.pnp[0].tolist() if self._rvec is None else self._rvec
 
     @rvec.setter
     def rvec(self, _rvec):
@@ -383,11 +396,11 @@ class CameraConfig:
     @property
     def tvec(self):
         """Return tvec from precise N point solution."""
-        return self.pnp[2].tolist() if self._tvec is None else self._tvec
+        return self.pnp[1].tolist() if self._tvec is None else self._tvec
 
     @tvec.setter
     def tvec(self, _tvec):
-        self._tvec = _tvec.tolist if isinstance(_tvec, np.ndarray) else _tvec
+        self._tvec = _tvec.tolist() if isinstance(_tvec, np.ndarray) else _tvec
 
     def set_lens_calibration(
         self,
@@ -613,6 +626,17 @@ class CameraConfig:
         dist_wall = (dist_shore**2 + depth**2) ** 0.5
         return dist_wall
 
+    def get_extrinsic(self):
+        """Return rotation and translation vector based on control points and intrinsic parameters."""
+        # solve rvec and tvec with reduced coordinates, this ensure that the solvepnp solution is stable.
+        _, rvec, tvec = cv.solvepnp(self.gcps_reduced, self.gcps["src"], self.camera_matrix, self.dist_coeffs)
+        # ensure that rvec and tvec are corrected for the fact that mean gcp location was subtracted
+        rvec_cam, tvec_cam = cv.pose_world_to_camera(rvec, tvec)
+        tvec_cam += self.gcps_mean
+        # transform back to world
+        rvec, tvec = cv.pose_world_to_camera(rvec_cam, tvec_cam)
+        return rvec, tvec
+
     def z_to_h(self, z: float) -> float:
         """Convert z coordinates of bathymetry to height coordinates in local reference (e.g. staff gauge).
 
@@ -845,39 +869,129 @@ class CameraConfig:
             f"a list of lists of 4 coordinates must be given, resulting in (4, "
             f"2) shape. Current shape is {corners.shape} "
         )
+        assert self.gcps["z_0"] is not None, "The water level must be set before the bounding box can be established."
 
         # get homography
         corners_xyz = self.unproject_points(corners, np.ones(4) * self.gcps["z_0"])
         bbox = cv.get_aoi(corners_xyz, resolution=self.resolution)
         self.bbox = bbox
 
-    def set_intrinsic(
-        self,
-        camera_matrix: Optional[List[List]] = None,
-        dist_coeffs: Optional[List[List]] = None,
-        lens_pars: Optional[Dict[str, float]] = None,
-    ):
-        """Set lens and distortion parameters.
+    def set_bbox_from_width_length(self, points: List[List[float]]):
+        """Establish bbox based on three provided points.
 
-        If not provided, they are derived by optimizing pnp fitting together with optimizing the focal length.
+        The points are provided in the original camera perspective as [col, row] and require that a water level
+        has already been set in order to project them in a feasible way.
+
+        first point : left bank (seen in downstream direction)
+        second point : right bank
+        third point : selected upstream or downstream of the two points.
+
+        The last point defines how large the bounding box is in up-and-downstream direction. A user should attempt to
+        choose the first two points roughly in the middle of the intended bounding box. The last point is then
+        used to estimate the length perpendicular to the line between the first two points. The bounding box is
+        extended in both directions with the same length.
 
         Parameters
         ----------
-        camera_matrix : Optional[List[List]]
-            A defined camera matrix to set as intrinsic parameters. If not provided, it will use default values or
-            those derived from ground control points (GCPs) if available.
+        points : list of lists (3)
+            [columns, row] coordinates in original camera perspective without any undistortion applied
 
-        dist_coeffs : Optional[List[List]]
-            Distortion coefficients to be used for the camera. If not provided, it will use default values or those
-            derived from GCPs if available.
+        """
+        assert np.array(points).shape == (3, 2), (
+            f"a list of lists of 3 coordinates must be given, resulting in (3, "
+            f"2) shape. Current shape is {np.array(points).shape} "
+        )
+        assert self.gcps["z_0"] is not None, "The water level must be set before the bounding box can be established."
+        # get homography
+        points_xyz = self.unproject_points(points, np.ones(3) * self.gcps["z_0"])
+        bbox = cv.get_aoi(points_xyz, resolution=self.resolution, method="width_length")
+        self.bbox = bbox
 
-        lens_pars : Optional[Dict[str, float]]
-            Lens parameters to be set. These will override any default settings or those derived from GCPs if provided.
+    def rotate_translate_bbox(self, angle: float = None, xoff: float = None, yoff: float = None):
+        """Rotate and translate the bounding box.
+
+        Parameters
+        ----------
+        angle : float, optional
+            Rotation angle in radians (anti-clockwise) around the center of the bounding box
+        xoff : float, optional
+            Translation distance in x direction in CRS units
+        yoff : float, optional
+            Translation distance in y direction in CRS units
+
+        Returns
+        -------
+        CameraConfig
+            New CameraConfig instance with rotated and translated bounding box
 
         """
-        # first set a default estimate from pose if 3D gcps are available
-        self.set_lens_pars()  # default parameters use width of frame
-        if hasattr(self, "gcps"):
+        # Make a deep copy of current config
+        new_config = copy.deepcopy(self)
+
+        # Get the current bbox
+        bbox = new_config.bbox
+        if bbox is None:
+            return new_config
+
+        # Apply rotation if specified
+        if angle is not None:
+            print(angle)
+            # # Convert to radians
+            # angle = np.radians(rotation)
+            # Get centroid as origin
+            centroid = bbox.centroid
+            # Apply rotation around centroid
+            bbox = shapely.affinity.rotate(
+                bbox,
+                angle,
+                origin=centroid,
+                use_radians=True,
+            )
+
+        # Now perform translation. Get coordinates of corners
+        coords = list(bbox.exterior.coords)
+
+        # Get unit vectors of x and y directions
+        p1 = np.array(coords[0])
+        p2 = np.array(coords[1])  # second point
+        p3 = np.array(coords[2])  # third point
+
+        x_vec = p2 - p1
+        y_vec = p3 - p2
+
+        x_vec = x_vec / np.linalg.norm(x_vec)
+        y_vec = y_vec / np.linalg.norm(y_vec)
+        # Project translations onto these vectors
+        dx = 0 if xoff is None else xoff * x_vec[0]
+        dy = 0 if xoff is None else xoff * x_vec[1]
+
+        dx -= 0 if yoff is None else yoff * y_vec[0]
+        dy -= 0 if yoff is None else yoff * y_vec[1]
+
+        # Apply translation
+        bbox = shapely.affinity.translate(bbox, xoff=dx, yoff=dy)
+        new_config.bbox = bbox
+        return new_config
+
+    def calibrate(
+        self,
+    ):
+        """Calibrate camera parameters using ground control.
+
+        If nothing provided, they are derived by optimizing pnp fitting together with optimizing the focal length
+        and two radial distortion coefficients (k1, k2).
+
+        You may also provide camera matrix or distortion coefficients, which will only optimize
+        the remainder parameters.
+
+        As a result, the following is updated on the CameraConfig instance:
+        - camera_matrix: the 3x3 camera matrix
+        - dist_coeffs: the 5x1 distortion coefficients
+        - rvec: the 3x1 rotation vector
+        - tvec: the 3x1 translation vector
+        """
+        if hasattr(self, "gcps") and (self.camera_matrix is None or self.dist_coeffs is None):
+            # some calibration is needed, and there are GCPs available for it
             if len(self.gcps["src"]) >= 4:
                 self.camera_matrix, self.dist_coeffs, err = cv.optimize_intrinsic(
                     self.gcps["src"],
@@ -886,36 +1000,14 @@ class CameraConfig:
                     self.height,
                     self.width,
                     lens_position=self.lens_position,
+                    camera_matrix=self.camera_matrix,
+                    dist_coeffs=self.dist_coeffs,
                 )
-            if lens_pars is not None:
-                # override with lens parameter set by user
-                self.set_lens_pars(**lens_pars)
-            if camera_matrix is not None and dist_coeffs is not None:
-                # override with
-                self.camera_matrix = camera_matrix
-                self.dist_coeffs = dist_coeffs
-
-    def set_lens_pars(self, k1: Optional[float] = 0.0, c: Optional[float] = 2.0, focal_length: Optional[float] = None):
-        """Set the lens parameters of the given CameraConfig.
-
-        Parameters
-        ----------
-        k1 : float, optional
-            lens curvature [-], zero (default) means no curvature
-        c : float, optional
-            optical centre [1/n], where n is the fraction of the lens diameter, 2.0 (default) means in the
-            centre.
-        focal_length : float, optional
-            focal length [mm], typical values could be 2.8, or 4 (default).
-
-
-        """
-        assert isinstance(k1, (int, float)), "k1 must be a float"
-        assert isinstance(c, (int, float)), "c must be a float"
-        if focal_length is not None:
-            assert isinstance(focal_length, (int, float, None)), "f must be a float"
-        self.dist_coeffs = cv._get_dist_coefs(k1)
-        self.camera_matrix = cv._get_cam_mtx(self.height, self.width, c=c, focal_length=focal_length)
+        # finally, also derive the rvec and tvec if camera matrix and distortion coefficients are known
+        if self.camera_matrix is not None and self.dist_coeffs is not None:
+            rvec, tvec = self.get_extrinsic()
+            self.rvec = rvec
+            self.tvec = tvec
 
     def set_gcps(
         self, src: List[List], dst: List[List], z_0: float, h_ref: Optional[float] = None, crs: Optional[Any] = None

{pyopenrivercam-0.8.5 → pyopenrivercam-0.8.7}/pyorc/api/cross_section.py

@@ -151,7 +151,7 @@ class CrossSection:
             elif cross_section.crs is not None or camera_config.crs is not None:
                 raise ValueError("if a CRS is used, then both camera_config and cross_section must have a CRS.")
             g = cross_section.geometry
-            x, y, z = g.x, g.y, g.z
+            x, y, z = g.x.values, g.y.values, g.z.values
         else:
             x, y, z = list(map(list, zip(*cross_section)))
 
@@ -244,15 +244,31 @@ class CrossSection:
         diff_xy = np.array(point2_xy) - np.array(point1_xy)
         return np.arctan2(diff_xy[1], diff_xy[0])
 
+    @property
+    def distance_camera(self):
+        """Estimate distance of mean coordinate of cross section to camera position."""
+        coord_mean = np.mean(self.cs_linestring.coords, axis=0)
+        return np.sum((self.camera_config.estimate_lens_position() - coord_mean) ** 2) ** 0.5
+
     @property
     def idx_closest_point(self):
         """Determine index of point in cross-section, closest to the camera."""
-        return self.d.argmin()
+        return 0 if self.d[0] < self.d[-1] else len(self.d) - 1
 
     @property
     def idx_farthest_point(self):
         """Determine index of point in cross-section, farthest from the camera."""
-        return self.d.argmax()
+        return 0 if self.d[0] > self.d[-1] else len(self.d) - 1
+
+    @property
+    def within_image(self):
+        """Check if any of the points of the cross section fall inside the image objective."""
+        # check if cross section is visible within the image objective
+        pix = self.camera_config.project_points(np.array(list(map(list, self.cs_linestring.coords))), within_image=True)
+        # check which points fall within the image objective
+        within_image = np.all([pix[:, 0] >= 0, pix[:, 0] < 1920, pix[:, 1] >= 0, pix[:, 1] < 1080], axis=0)
+        # check if there are any points within the image objective and return result
+        return bool(np.any(within_image))
 
     def get_cs_waterlevel(self, h: float, sz=False) -> geometry.LineString:
         """Retrieve LineString of water surface at cross-section at a given water level.
@@ -670,18 +686,26 @@ class CrossSection:
         offset: float = 0.0,
         padding: float = 0.5,
         length: float = 2.0,
+        min_z: Optional[float] = None,
+        max_z: Optional[float] = None,
         min_samples: int = 50,
     ):
         """Retrieve a histogram score for a given l-value."""
         l = x[0]
-        # print(l)
+        if min_z is not None:
+            if self.interp_z(l) < min_z:
+                # return worst score
+                return 2.0 + np.abs(self.interp_z(l) - min_z)
+        elif max_z is not None:
+            if self.interp_z(l) > max_z:
+                return 2.0 + np.abs(self.interp_z(l) - max_z)
         pol1 = self.get_csl_pol(l=l, offset=offset, padding=(0, padding), length=length, camera=True)[0]
         pol2 = self.get_csl_pol(l=l, offset=offset, padding=(-padding, 0), length=length, camera=True)[0]
         # get intensity values within polygons
         ints1 = cv.get_polygon_pixels(img, pol1)
         ints2 = cv.get_polygon_pixels(img, pol2)
         if ints1.size < min_samples or ints2.size < min_samples:
-            # return a strong penalty score value
+            # return a strong penalty score value if there are too few samples
             return 2.0
         _, _, norm_counts1 = _histogram(ints1, normalize=True, bin_size=bin_size)
         bin_centers, bin_edges, norm_counts2 = _histogram(ints2, normalize=True, bin_size=bin_size)
@@ -986,7 +1010,7 @@ class CrossSection:
             lens_position_xy = self.camera_config.estimate_lens_position()[0:2]
             dists = [((p.x - lens_position_xy[0]) ** 2 + (p.y - lens_position_xy[1]) ** 2) ** 0.5 for p in points]
             points = self.get_csl_point(h=h, camera=True, swap_y_coords=swap_y_coords)  # find camera positions
-            x, y = points[np.argmin(dists)].xy
+            x, y = points[np.argmax(dists)].xy
             x, y = float(x[0]), float(y[0])
 
             # only plot text in 2D camera perspective at farthest point
@@ -1003,6 +1027,10 @@ class CrossSection:
         length: float = 2.0,
         padding: float = 0.5,
         offset: float = 0.0,
+        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.
 
@@ -1030,11 +1058,32 @@ class CrossSection:
             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
+        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
 
         """
-        """Attempt to detect the water line level along the cross-section, using a provided pre-treated image."""
+        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.")
+
         if len(img.shape) == 3:
-            # flatten image first
+            # flatten image first if it his a time dimension
             img = img.mean(axis=2)
         assert (
             img.shape[0] == self.camera_config.height
@@ -1043,12 +1092,13 @@ class CrossSection:
             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,
             bounds=[(l_min, l_max)],
-            args=(img, bin_size, offset, padding, length),
+            args=(img, bin_size, offset, padding, length, min_z, max_z),
             atol=0.01,  # one mm
         )
         z = self.interp_z(opt.x[0])