pyopenrivercam 0.8.6__tar.gz → 0.8.8__tar.gz

{pyopenrivercam-0.8.6 → pyopenrivercam-0.8.8}/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [0.8.8] = 2025-07-14
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+- issues with plotting cross sections in edge cases with water levels equal to lowest point or above highest point
+- fixed problem with situations where either the cross section data from a shapefile or the camera configuration
+  did not contain CRS information. This is now correctly parsed when creating a `CrossSection` instance.
+
+## [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
@@ -5,6 +39,7 @@
 ### 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

{pyopenrivercam-0.8.6 → pyopenrivercam-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenrivercam
-Version: 0.8.6
+Version: 0.8.8
 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.6 → pyopenrivercam-0.8.8}/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.6 → pyopenrivercam-0.8.8}/pyorc/__init__.py

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

{pyopenrivercam-0.8.6 → pyopenrivercam-0.8.8}/pyorc/api/cameraconfig.py

@@ -115,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:
@@ -132,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)
+        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
-            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:
@@ -324,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):
@@ -399,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,
@@ -629,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).
 
@@ -861,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,
-    ):
-        """Set lens and distortion parameters.
+    def set_bbox_from_width_length(self, points: List[List[float]]):
+        """Establish bbox based on three provided points.
+
+        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.
 
-        If not provided, they are derived by optimizing pnp fitting together with optimizing the focal length.
+        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
+
+        """
+        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
 
-        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.
+    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
 
         """
-        if camera_matrix is not None and dist_coeffs is not None:
-            # both are provided by user, so no fitting needed
-            self.camera_matrix = camera_matrix
-            self.dist_coeffs = dist_coeffs
-            return
+        # 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,
+            )
 
-        if hasattr(self, "gcps"):
+        # 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"],
@@ -902,9 +1000,14 @@ class CameraConfig:
                     self.height,
                     self.width,
                     lens_position=self.lens_position,
-                    camera_matrix=camera_matrix,
-                    dist_coeffs=dist_coeffs,
+                    camera_matrix=self.camera_matrix,
+                    dist_coeffs=self.dist_coeffs,
                 )
+        # 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.6 → pyopenrivercam-0.8.8}/pyorc/api/cross_section.py

@@ -146,12 +146,14 @@ class CrossSection:
         """
         # if cross_section is a GeoDataFrame, check if it has a CRS, if yes, convert coordinates to crs of CameraConfig
         if isinstance(cross_section, gpd.GeoDataFrame):
-            if cross_section.crs is not None and camera_config.crs is not None:
+            crs_cs = getattr(cross_section, "crs", None)
+            crs_cam = getattr(camera_config, "crs", None)
+            if crs_cs is not None and crs_cam is not None:
                 cross_section.to_crs(camera_config.crs, inplace=True)
-            elif cross_section.crs is not None or camera_config.crs is not None:
+            elif crs_cs is not None or crs_cam 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,17 +246,33 @@ 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
 
-    def get_cs_waterlevel(self, h: float, sz=False) -> geometry.LineString:
+    @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, extend_by=None) -> geometry.LineString:
         """Retrieve LineString of water surface at cross-section at a given water level.
 
         Parameters
@@ -263,18 +281,44 @@ class CrossSection:
             water level [m]
         sz : bool, optional
             If set, return water level line in y-z projection, by default False.
+        extend_by : float, optional
+            If set, the line will be extended left and right using the defined float in meters
 
         Returns
         -------
         geometry.LineString
-            horizontal line at water level (2d if sz=True, 3d if yz=False)
+            horizontal line at water level (2d if `sz`=True, 3d if `yz`=False)
 
         """
         # get water level in camera config vertical datum
         z = self.camera_config.h_to_z(h)
         if sz:
-            return geometry.LineString(zip(self.s, [z] * len(self.s)))
-        return geometry.LineString(zip(self.x, self.y, [z] * len(self.x)))
+            if extend_by is None:
+                s_coords = self.s
+            else:
+                s_coords = np.concatenate([[-np.abs(extend_by)], self.s, [self.s[-1] + np.abs(extend_by)]])
+            return geometry.LineString(zip(s_coords, [z] * len(s_coords)))
+        if extend_by is not None:
+            alpha = np.arctan((self.x[1] - self.x[0]) / (self.y[1] - self.y[0]))
+            x_coords = np.concatenate(
+                [
+                    [self.x[0] - np.cos(alpha) * np.abs(extend_by)],
+                    self.x,
+                    [self.x[-1] + np.cos(alpha) * np.abs(extend_by)],
+                ]
+            )
+            y_coords = np.concatenate(
+                [
+                    [self.y[0] - np.sin(alpha) * np.abs(extend_by)],
+                    self.y,
+                    [self.y[-1] + np.sin(alpha) * np.abs(extend_by)],
+                ]
+            )
+        else:
+            x_coords = self.x
+            y_coords = self.y
+
+        return geometry.LineString(zip(x_coords, y_coords, [z] * len(x_coords)))
 
     def get_csl_point(
         self, h: Optional[float] = None, l: Optional[float] = None, camera: bool = False, swap_y_coords: bool = False
@@ -586,16 +630,32 @@ class CrossSection:
             Wetted surface as a polygon, in Y-Z projection.
 
         """
-        wl = self.get_cs_waterlevel(h=h, sz=True)
+        wl = self.get_cs_waterlevel(
+            h=h, sz=True, extend_by=0.1
+        )  # extend a small bit to guarantee crossing with the bottom coordinates
+        zl = wl.xy[1][0]
         # create polygon by making a union
-        pol = list(polygonize(wl.union(self.cs_linestring_sz)))
+        bottom_points = self.cs_points_sz
+        # add a point left and right slightly above the level if the level is below the water level
+        if bottom_points[0].y < zl:
+            bottom_points.insert(0, geometry.Point(bottom_points[0].x, zl + 0.1))
+        if bottom_points[-1].y < zl:
+            bottom_points.append(geometry.Point(bottom_points[-1].x, zl + 0.1))
+        bottom_line = geometry.LineString(bottom_points)
+        pol = list(polygonize(wl.union(bottom_line)))
         if len(pol) == 0:
-            raise ValueError("Water level is not crossed by cross section and therefore undefined.")
+            # create infinitely small polygon at lowest z coordinate
+            lowest_z = min(self.z)
+            lowest_s = self.s[list(self.z).index(lowest_z)]
+            # make an infinitely small polygon around the lowest point in the cross section
+            pol = [geometry.Polygon([(lowest_s, lowest_z)] * 3)]
         elif len(pol) > 1:
-            raise ValueError("Water level is crossed by multiple polygons.")
-        else:
-            pol = pol[0]
-        return pol
+            # detect which polygons have their average z coordinate below the defined water level
+            pol = [p for p in pol if p.centroid.xy[1][0] < zl]
+            # raise ValueError("Water level is crossed by multiple polygons.")
+        # else:
+        #     pol = pol[0]
+        return geometry.MultiPolygon(pol)
 
     def get_wetted_surface(self, h: float, camera: bool = False, swap_y_coords=False) -> geometry.Polygon:
         """Retrieve a wetted surface for a given water level, as a geometry.Polygon.
@@ -617,13 +677,16 @@ class CrossSection:
 
 
         """
-        pol = self.get_wetted_surface_sz(h=h)
-        coords = [[self.interp_x_from_s(p[0]), self.interp_y_from_s(p[0]), p[1]] for p in pol.exterior.coords]
-        if camera:
-            coords_proj = self.camera_config.project_points(coords, swap_y_coords=swap_y_coords)
-            return geometry.Polygon(coords_proj)
-        else:
-            return geometry.Polygon(coords)
+        pols = self.get_wetted_surface_sz(h=h)
+        pols_proj = []
+        for pol in pols.geoms:
+            coords = [[self.interp_x_from_s(p[0]), self.interp_y_from_s(p[0]), p[1]] for p in pol.exterior.coords]
+            if camera:
+                coords_proj = self.camera_config.project_points(coords, swap_y_coords=swap_y_coords)
+                pols_proj.append(geometry.Polygon(coords_proj))
+            else:
+                pols_proj.append(geometry.Polygon(coords))
+        return geometry.MultiPolygon(pols_proj)
 
     def get_line_of_interest(self, bank: BANK_OPTIONS = "far") -> List[float]:
         """Retrieve the points of interest within the cross-section for water level detection.
@@ -670,18 +733,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)
@@ -857,12 +928,20 @@ class CrossSection:
         plt.axes
 
         """
-        surf = self.get_planar_surface(h=h, length=length, offset=offset, swap_y_coords=swap_y_coords, camera=camera)
-        if camera:
-            p = plot_helpers.plot_polygon(surf, ax=ax, label="surface", **kwargs)
-        else:
-            p = plot_helpers.plot_3d_polygon(surf, ax=ax, label="surface", **kwargs)
-        return p.axes
+        try:
+            surf = self.get_planar_surface(
+                h=h, length=length, offset=offset, swap_y_coords=swap_y_coords, camera=camera
+            )
+            if camera:
+                p = plot_helpers.plot_polygon(surf, ax=ax, label="surface", **kwargs)
+            else:
+                p = plot_helpers.plot_3d_polygon(surf, ax=ax, label="surface", **kwargs)
+            return p.axes
+        except Exception:
+            warnings.warn(
+                "Cannot plot planar surface as there are too many crossings",
+                stacklevel=2,
+            )
 
     def plot_bottom_surface(
         self, length: float = 2.0, offset: float = 0.0, camera: bool = False, ax=None, swap_y_coords=False, **kwargs
@@ -1003,6 +1082,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 +1113,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 +1147,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])