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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenrivercam
-Version: 0.8.9
+Version: 0.8.10
 Summary: pyorc: free and open-source image-based surface velocity and discharge.
 Author-email: Hessel Winsemius <winsemius@rainbowsensing.com>
 Requires-Python: >=3.9
@@ -21,7 +21,7 @@ Requires-Dist: click
 Requires-Dist: cython; platform_machine == 'armv7l'
 Requires-Dist: dask
 Requires-Dist: descartes
-Requires-Dist: ffpiv
+Requires-Dist: ffpiv>=0.1.4
 Requires-Dist: flox
 Requires-Dist: geojson
 Requires-Dist: geopandas

{pyopenrivercam-0.8.9.dist-info → pyopenrivercam-0.8.10.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pyorc/__init__.py,sha256=mvuksjtx7rr3dGsP3AIlI2DOsT-dK-WNkLnRv2hBqSA,523
+pyorc/__init__.py,sha256=ZeURmlD1_OTTOXcunlmrtV0H9un_mP9Q4Cr0NlSU-uo,524
 pyorc/const.py,sha256=Ia0KRkm-E1lJk4NxQVPDIfN38EBB7BKvxmwIHJrGPUY,2597
 pyorc/cv.py,sha256=CTv0TbbcKeSQmKsX8mdVDXpSkhKZmr8SgT20YXMvZ0s,49156
 pyorc/helpers.py,sha256=90TDtka0ydAydv3g5Dfc8MgtuSt0_9D9-HOtffpcBds,30636
@@ -9,8 +9,8 @@ pyorc/sample_data.py,sha256=53NVnVmEksDw8ilbfhFFCiFJiGAIpxdgREbA_xt8P3o,2508
 pyorc/api/__init__.py,sha256=k2OQQH4NrtXTuVm23d0g_SX6H5DhnKC9_kDyzJ4dWdk,428
 pyorc/api/cameraconfig.py,sha256=NP9F7LhPO3aO6FRWkrGl6XpX8O3K59zfTtaYR3Kujqw,65419
 pyorc/api/cross_section.py,sha256=un7_VFHMOpBM8FE7lQnZIsaxidnABzFWlyaDHIUfzoA,52039
-pyorc/api/frames.py,sha256=QJfcftmh47nClw5yGsMULdJXEsAVzucseiLb4LbpVJU,23671
-pyorc/api/mask.py,sha256=HVag3RkMu4ZYQg_pIZFhiJYkBGYLVBxeefdmWvFTR-4,14371
+pyorc/api/frames.py,sha256=Kls4mpU_4hoUaXs9DJf2S6RHyp2D5emXJkAQWvvT39U,24300
+pyorc/api/mask.py,sha256=COsL4fxz-Rsn-wgpojpJ1se4FGA8CZ_R1jx3iVUYB30,16462
 pyorc/api/orcbase.py,sha256=C23QTKOyxHUafyJsq_t7xn_BzAEvf4DDfzlYAopons8,4189
 pyorc/api/plot.py,sha256=-rDmEccwpJXojCyBEKFCd8NpBwLhcZ8tsOq62n26zu4,30898
 pyorc/api/transect.py,sha256=KU0ZW_0NqYD4jeDxvuWJi7X06KqrcgO9afP7QmWuixA,14162
@@ -25,10 +25,10 @@ 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/velocimetry/__init__.py,sha256=lYM7oJZWxgJ2SpE22xhy7pBYcgkKFHMBHYmDvvMbtZk,148
-pyorc/velocimetry/ffpiv.py,sha256=MW_6fQ0vxRTA-HYwncgeWHGWiUQFSmM4unYxT7EfnEI,7372
+pyorc/velocimetry/ffpiv.py,sha256=CYUjgwnB5osQmJ83j3E00B9P0_hS-rFuhyvufxKXtag,17487
 pyorc/velocimetry/openpiv.py,sha256=6BxsbXLzT4iEq7v08G4sOhVlYFodUpY6sIm3jdCxNMs,13149
-pyopenrivercam-0.8.9.dist-info/entry_points.txt,sha256=Cv_WI2Y6QLnPiNCXGli0gS4WAOAeMoprha1rAR3vdRE,44
-pyopenrivercam-0.8.9.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-pyopenrivercam-0.8.9.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pyopenrivercam-0.8.9.dist-info/METADATA,sha256=8NK4zolq3oMRgMuTKCWZTypoLjzPcev_-it5frg8aac,11633
-pyopenrivercam-0.8.9.dist-info/RECORD,,
+pyopenrivercam-0.8.10.dist-info/entry_points.txt,sha256=Cv_WI2Y6QLnPiNCXGli0gS4WAOAeMoprha1rAR3vdRE,44
+pyopenrivercam-0.8.10.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+pyopenrivercam-0.8.10.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pyopenrivercam-0.8.10.dist-info/METADATA,sha256=05xRhY6LmvJNoWvlGH1KkoAiVHb-rGQcya7gYWxHmdw,11641
+pyopenrivercam-0.8.10.dist-info/RECORD,,

pyorc/__init__.py

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

pyorc/api/frames.py

@@ -107,6 +107,7 @@ class Frames(ORCBase):
         window_size: Optional[tuple[int, int]] = None,
         overlap: Optional[tuple[int, int]] = None,
         engine: str = "numba",
+        ensemble_corr: bool = False,
         **kwargs,
     ) -> xr.Dataset:
         """Perform PIV computation on projected frames.
@@ -126,6 +127,11 @@ class Frames(ORCBase):
             select the compute engine, can be "openpiv" (default), "numba", or "numpy". "numba" will give the fastest
             performance but is still experimental. It can boost performance by almost an order of magnitude compared
             to openpiv or numpy. both "numba" and "numpy" use the FF-PIV library as back-end.
+        ensemble_corr : bool, optional
+            only used with `engine="numba"` or `engine="numpy"`.
+            If True, performs PIV by first averaging cross-correlations across all frames and then deriving velocities.
+            If False, computes velocities for each frame pair separately. Default is True.
+
         **kwargs : dict
             keyword arguments to pass to the piv engine. For "numba" and "numpy" the argument `chunks` can be provided
             with an integer defining in how many batches of work the total velocimetry problem should be subdivided.
@@ -162,6 +168,8 @@ class Frames(ORCBase):
         coords, mesh_coords = self.get_piv_coords(window_size, search_area_size, overlap)
         # provide kwargs for OpenPIV analysis
         if engine == "openpiv":
+            # thresholds are not used.
+
             import warnings
 
             warnings.warn(
@@ -169,6 +177,10 @@ class Frames(ORCBase):
                 DeprecationWarning,
                 stacklevel=2,
             )
+            # Remove threshold parameters from kwargs
+            kwargs.pop("corr_min", None)
+            kwargs.pop("s2n_min", None)
+            kwargs.pop("count_min", None)
             kwargs = {
                 **kwargs,
                 "search_area_size": search_area_size[0],
@@ -187,7 +199,9 @@ class Frames(ORCBase):
                 "res_x": camera_config.resolution,
                 "res_y": camera_config.resolution,
             }
-            ds = ffpiv.get_ffpiv(self._obj, coords["y"], coords["x"], dt, engine=engine, **kwargs)
+            ds = ffpiv.get_ffpiv(
+                self._obj, coords["y"], coords["x"], dt, engine=engine, ensemble_corr=ensemble_corr, **kwargs
+            )
         else:
             raise ValueError(f"Selected PIV engine {engine} does not exist.")
         # add all 2D-coordinates

pyorc/api/mask.py

@@ -1,12 +1,13 @@
+"""Masking methods for velocimetry."""
+
 import copy
 import functools
-import numpy as np
 import warnings
-import xarray as xr
 
-from ..const import v_x, v_y, s2n, corr
-from .. import helpers
+import numpy as np
 
+from pyorc import helpers
+from pyorc.const import corr, s2n, v_x, v_y
 
 commondoc = """
     Returns
@@ -18,9 +19,8 @@ commondoc = """
 """
 
 
-def _base_mask(time_allowed=False, time_required=False):
-    """
-    wrapper generator for creating generalized structure masking methods for velocimetry
+def _base_mask(time_allowed=False, time_required=False, multi_timestep_required=False):
+    """Wrap generator for creating generalized structure masking methods for velocimetry.
 
     Parameters
     ----------
@@ -28,14 +28,19 @@ def _base_mask(time_allowed=False, time_required=False):
         If set, the dimension "time" is allowed, if not set, mask method can only be applied on datasets without "time"
     time_required
         If set, the dimension "time" is required, if not set, mask method does not require dimension "time" in dataset.
+    multi_timestep_required : bool, optional
+        If set, the masking method requires multiple timesteps in the dataset in order to be applicable.
 
     Returns
     -------
     func : function
         masking method, decorated with standard procedures
+
     """
+
     def decorator_func(mask_func):
         mask_func.__doc__ = f"{mask_func.__doc__}{commondoc}"
+
         # wrap function so that it takes over the docstring and is seen as integral part of the class
         @functools.wraps(mask_func)
         def wrapper_func(ref, inplace=False, reduce_time=False, *args, **kwargs):
@@ -48,18 +53,26 @@ def _base_mask(time_allowed=False, time_required=False):
                 raise AssertionError("Dataset is not a valid velocimetry dataset")
             if time_required:
                 # then automatically time is also allowed
-                if not("time" in ds.dims):
+                if "time" not in ds.dims:
                     raise AssertionError(
-                f'This mask requires dimension "time". The dataset does not contain dimension "time" or you have set'
-                f'reduce_time=True. Apply this mask without applying any reducers in time.'
-            )
+                        'This mask requires dimension "time". The dataset does not contain dimension "time" or you '
+                        "have set `reduce_time=True`. Apply this mask without applying any reducers in time."
+                    )
             if time_required:
-                if not("time" in ds):
+                if "time" not in ds:
                     raise AssertionError(
-                f'This mask requires dimension "time". The dataset does not contain dimension "time".'
-                f'Apply this mask before applying any reducers in time.'
-            )
-            if not(time_allowed or time_required) and "time" in ds:
+                        "This mask requires dimension `time`. The dataset does not contain dimension `time`."
+                        "Apply this mask before applying any reducers in time."
+                    )
+                # only check for this, when time is required
+                if multi_timestep_required:
+                    if len(ds.time) < 2:
+                        raise AssertionError(
+                            "This mask requires multiple timesteps in the dataset in order to be applicable. This "
+                            "error typically occurs when applying `Frames.get_piv(ensemble_corr=True)` as this only "
+                            "yields one single time step."
+                        )
+            if not (time_allowed or time_required) and "time" in ds:
                 # function must be applied per time step
                 mask = ds.groupby("time", squeeze=False).map(mask_func, **kwargs)
             else:
@@ -71,18 +84,22 @@ def _base_mask(time_allowed=False, time_required=False):
                 for var in ref._obj.data_vars:
                     ref._obj[var] = ref._obj[var].where(mask)
             return mask
+
         return wrapper_func
+
     return decorator_func
 
+
 class _Velocimetry_MaskMethods:
-    """
-    Enables use of ``ds.velocimetry.filter`` functions as attributes on a Dataset containing velocimetry results.
+    """Enable use of ``ds.velocimetry.filter`` functions as attributes on a Dataset containing velocimetry results.
+
     For example, ``Dataset.velocimetry.filter.minmax``. This will return either the dataset with filtered data using
     For example, ``Dataset.velocimetry.filter.minmax``. This will return either the dataset with filtered data using
     the ``minmax`` filter when ``inplace=True`` or the mask that should be applied to filter when ``inplace=False``
     (default). ds.velocimetry.filter([mask1, mask2, ...]) applies the provided filters in the list of filters on
-    the dataset by first combining all masks into one, and then applying that mask on the dataset
+    the dataset by first combining all masks into one, and then applying that mask on the dataset.
     """
+
     def __init__(self, velocimetry):
         # make the original dataset also available on the plotting object
         self.velocimetry = velocimetry
@@ -90,20 +107,26 @@ class _Velocimetry_MaskMethods:
         # Add to class _FilterMethods
 
     def __call__(self, mask, inplace=False, *args, **kwargs):
-        """
+        """Perform mask operation on dataset.
+
         Parameters
         ----------
         mask : xr.DataArray or list of xr.DataArrays
             mask(s) to be applied on dataset, can have mix of y, x and time y, x dimensions
-        *args :
-        **kwargs :
+        inplace : bool, optional
+            If set (default unset), the mask is applied to the dataset inplace. Otherwise, a mask is returned.
+        *args : list
+            list arguments passed to mask function
+        **kwargs : dict
+            keyword arguments passed to mask function
 
         Returns
         -------
         ds : xr.Dataset
             Dataset containing filtered velocimetry results
+
         """
-        if not(isinstance(mask, list)):
+        if not (isinstance(mask, list)):
             # combine masks
             mask = [mask]
         if inplace:
@@ -120,17 +143,17 @@ class _Velocimetry_MaskMethods:
                 ds[corr] = ds[corr].where(m)
                 ds[s2n] = ds[s2n].where(m)
             return ds
+
     @_base_mask(time_allowed=True)
-    def minmax(self, s_min=0.1, s_max=5.):
-        """
-    Masks values if the velocity scalar lies outside a user-defined valid range.
+    def minmax(self, s_min=0.1, s_max=5.0):
+        """Masks values if the velocity scalar lies outside a user-defined valid range.
 
-    Parameters
-    ----------
-    s_min : float, optional
-        minimum scalar velocity [m s-1] (default: 0.1)
-    s_max : float, optional
-        maximum scalar velocity [m s-1] (default: 5.)
+        Parameters
+        ----------
+        s_min : float, optional
+            minimum scalar velocity [m s-1] (default: 0.1)
+        s_max : float, optional
+            maximum scalar velocity [m s-1] (default: 5.)
 
         """
         s = (self[v_x] ** 2 + self[v_y] ** 2) ** 0.5
@@ -140,69 +163,69 @@ class _Velocimetry_MaskMethods:
 
     @_base_mask(time_allowed=True)
     def angle(self, angle_expected=0.5 * np.pi, angle_tolerance=0.25 * np.pi):
-        """
-    filters on the expected angle. The function filters points entirely where the mean angle over time
-    deviates more than input parameter angle_bounds (in radians). The function also filters individual
-    estimates in time, in case the user wants this (filter_per_timestep=True), in case the angle on
-    a specific time step deviates more than the defined amount from the average.
-    note: this function does not work appropriately, if the expected angle (+/- anglebounds) are within
-    range of zero, as zero is the same as 2*pi. This exception may be resolved in the future if necessary.
+        """Mask values that are outside expected direction with angle tolerance.
+
+        The function filters points entirely where the mean angle over time
+        deviates more than input parameter angle_bounds (in radians). The function also filters individual
+        estimates in time, in case the user wants this (filter_per_timestep=True), in case the angle on
+        a specific time step deviates more than the defined amount from the average.
+        note: this function does not work appropriately, if the expected angle (+/- anglebounds) are within
+        range of zero, as zero is the same as 2*pi. This exception may be resolved in the future if necessary.
+
+        Parameters
+        ----------
+        angle_expected : float
+            angle (0 - 2*pi), measured clock-wise from vertical upwards direction, expected
+            in the velocities, default: 0.5*np.pi (meaning from left to right in the x, y coordinate system)
+        angle_tolerance : float (0 - 2*pi)
+            maximum deviation from expected angle allowed (default: 0.25 * np.pi).
 
-    Parameters
-    ----------
-    angle_expected : float
-        angle (0 - 2*pi), measured clock-wise from vertical upwards direction, expected
-        in the velocities, default: 0.5*np.pi (meaning from left to right in the x, y coordinate system)
-    angle_tolerance : float (0 - 2*pi)
-        maximum deviation from expected angle allowed (default: 0.25 * np.pi).
         """
         angle = np.arctan2(self[v_x], self[v_y])
         mask = np.abs(angle - angle_expected) < angle_tolerance
         return mask
 
-    @_base_mask(time_required=True)
+    @_base_mask(time_required=True, multi_timestep_required=True)
     def count(self, tolerance=0.33):
-        """
-    Masks locations with a too low amount of valid velocities in time, measured by fraction with ``tolerance``.
-    Usually applied *after* having applied several other filters.
+        """Mask locations with a too low amount of valid velocities in time, measured by fraction with ``tolerance``.
+
+        Usually applied *after* having applied several other filters.
+
+        Parameters
+        ----------
+        tolerance : float (0-1)
+            tolerance for fractional amount of valid velocities after all filters. If less than the fraction is
+            available, the entire velocity will be set to missings.
 
-    Parameters
-    ----------
-    tolerance : float (0-1)
-        tolerance for fractional amount of valid velocities after all filters. If less than the fraction is
-        available, the entire velocity will be set to missings.
         """
         mask = self[v_x].count(dim="time") > tolerance * len(self.time)
         return mask
 
-
     @_base_mask(time_allowed=True)
     def corr(self, tolerance=0.1):
-        """
-    Masks values with too low correlation
+        """Mass values with too low correlation.
+
+        Parameters
+        ----------
+        tolerance : float (0-1)
+            tolerance for correlation value (default: 0.1). If correlation is lower than tolerance, it is masked
 
-    Parameters
-    ----------
-    tolerance : float (0-1)
-        tolerance for correlation value (default: 0.1). If correlation is lower than tolerance, it is masked
         """
         return self[corr] > tolerance
 
+    @_base_mask(time_required=True, multi_timestep_required=True)
+    def outliers(self, tolerance=1.0, mode="or"):
+        """Mask outliers measured by amount of standard deviations from the mean.
 
-    @_base_mask(time_required=True)
-    def outliers(self, tolerance=1., mode="or"):
-        """
-    Mask outliers measured by amount of standard deviations from the mean.
+        Parameters
+        ----------
+        tolerance : float
+            amount of standard deviations allowed from the mean
+        mode : str
+            can be "and" or "or" (default). If "or" ("and"), then only one (both) of two vector components need(s) to
+            be within tolerance.
 
-    Parameters
-    ----------
-    tolerance :  float
-        amount of standard deviations allowed from the mean
-    mode : str
-         can be "and" or "or" (default). If "or" ("and"), then only one (both) of two vector components need(s) to
-         be within tolerance.
         """
-
         with warnings.catch_warnings():
             warnings.simplefilter("ignore", category=RuntimeWarning)
             x_std = self[v_x].std(dim="time")
@@ -217,19 +240,20 @@ class _Velocimetry_MaskMethods:
             mask = x_condition & y_condition
         return mask
 
-    @_base_mask(time_required=True)
+    @_base_mask(time_required=True, multi_timestep_required=True)
     def variance(self, tolerance=5, mode="and"):
-        """
-    Masks locations if their variance (std/mean in time) is above a tolerance level for either or both
-    x and y direction.
+        """Mask locations if their variance (std/mean in time) is above a tolerance level.
+
+        This is calculated for either or both x and y direction.
+
+        Parameters
+        ----------
+        tolerance :  float
+            amount of standard deviations allowed from the mean
+        mode : str
+            can be "and" (default) or "or". If "or" ("and"), then only one (both) of two vector components need(s) to
+            be within tolerance.
 
-    Parameters
-    ----------
-    tolerance :  float
-        amount of standard deviations allowed from the mean
-    mode : str
-         can be "and" (default) or "or". If "or" ("and"), then only one (both) of two vector components need(s) to
-         be within tolerance.
         """
         x_std = self[v_x].std(dim="time")
         y_std = self[v_y].std(dim="time")
@@ -245,47 +269,52 @@ class _Velocimetry_MaskMethods:
             mask = x_condition & y_condition
         return mask
 
-
-    @_base_mask(time_required=True)
+    @_base_mask(time_required=True, multi_timestep_required=True)
     def rolling(self, wdw=5, tolerance=0.5):
-        """
-    Masks values if neighbours over a certain rolling length before and after, have a
-    significantly higher velocity than value under consideration, measured by tolerance.
+        """Mask values for strongly deviating values from neighbours over rolling length.
+
+        Deviation is measured by ``tolerance``.
+
+        Parameters
+        ----------
+        wdw : int, optional
+            amount of time steps in rolling window (centred) (default: 5)
+        tolerance : float, optional
+            tolerance as relative deviation from mean of values, including value itself (default: 0.5)
 
-    Parameters
-    ----------
-    wdw : int, optional
-        amount of time steps in rolling window (centred) (default: 5)
         """
         s = (self[v_x] ** 2 + self[v_y] ** 2) ** 0.5
-        s_rolling = s.fillna(0.).rolling(time=wdw, center=True).max()
+        s_rolling = s.fillna(0.0).rolling(time=wdw, center=True).max()
         mask = s > tolerance * s_rolling
         return mask
 
-
     @_base_mask()
     def window_nan(self, tolerance=0.7, wdw=1, **kwargs):
-        """
-    Masks values if their surrounding neighbours (inc. value itself) contain too many NaNs. Meant to remove isolated
-    velocity estimates.
+        """Masks values if their surrounding neighbours (inc. value itself) contain too many NaNs.
+
+        Meant to remove isolated velocity estimates.
+
+        Parameters
+        ----------
+        tolerance : float, optional
+            minimum amount of valid values in search window measured as a fraction of total amount of values [0-1]
+            (default: 0.3)
+        wdw : int, optional
+            window size to use for sampling neighbours. zero means, only cell itself, 1 means 3x3 window.
+            (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.
 
-    Parameters
-    ----------
-    tolerance : float, optional
-        minimum amount of valid values in search window measured as a fraction of total amount of values [0-1]
-        (default: 0.3)
-    wdw : int, optional
-        window size to use for sampling neighbours. zero means, only cell itself, 1 means 3x3 window.
-        (default: 1) wdw is used to fill wdw_x_min and wdwd_y_min with its negative (-wdw) value, and wdw_y_min and
-        wdw_y_max with its positive value, to create a sampling window.
-    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
         ds_wdw = helpers.stack_window(self, wdw=wdw, **kwargs)
@@ -295,27 +324,32 @@ class _Velocimetry_MaskMethods:
 
     @_base_mask()
     def window_mean(self, tolerance=0.7, wdw=1, mode="or", **kwargs):
-        """
-    Masks values when their value deviates more than tolerance (measured as relative fraction) from the mean of its
-    neighbours (inc. itself).
+        """Mask values when their value deviates significantly from mean.
+
+        This is computed as relative fraction from the mean of its  neighbours (inc. itself).
+
+        Parameters
+        ----------
+        tolerance : float, optional
+            amount of velocity relative to the mean velocity  (default: 0.7)
+        wdw : int, optional
+            window used to determine relevant neighbours
+        mode : str
+            can be "and" (default) or "or". If "or" ("and"), then only one (both) of two vector components need(s) to
+            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.
 
-    Parameters
-    ----------
-    tolerance: float, optional
-        amount of velocity relative to the mean velocity  (default: 0.7)
-    wdw : int, optional
-        window used to determine relevant neighbours
-    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.
-    mode : str
-         can be "and" (default) or "or". If "or" ("and"), then only one (both) of two vector components need(s) to
-         be within tolerance.
         """
         # collect points within a stride, collate and analyze for median value and deviation
         ds_wdw = helpers.stack_window(self, wdw=wdw, **kwargs)
@@ -328,20 +362,24 @@ class _Velocimetry_MaskMethods:
             mask = x_condition & y_condition
         return mask
 
-
     @_base_mask()
     def window_replace(self, wdw=1, iter=1, **kwargs):
-        """
-    Replaces values in a certain window size with mean of their neighbours. Returns a Dataset instead of a mask.
-    NOTE: This functionality may be moved to a different subclass in later releases.
+        """Replace values in a certain window size with mean of their neighbours. Returns a Dataset instead of a mask.
+
+        NOTE: This functionality may be moved to a different subclass in later releases.
+
+        Parameters
+        ----------
+        wdw : int, optional
+            window used to determine relevant neighbours
+        iter : int, optional
+            amount of times to repeat window operator
+        kwargs : dict
+            keyword arguments to pass to ``helpers.stack_window``
 
-    Parameters
-    ----------
-    wdw : int, optional
-        window used to determine relevant neighbours
         """
         ds = copy.deepcopy(self)
-        for n in range(iter):
+        for _ in range(iter):
             # collect points within a stride, collate and analyze for median value and deviation
             ds_wdw = helpers.stack_window(ds, wdw=wdw, **kwargs)
             ds_mean = ds_wdw.mean(dim="stride")

pyorc/velocimetry/ffpiv.py

@@ -2,6 +2,7 @@
 
 import gc
 import warnings
+from typing import Literal, Optional, Tuple
 
 import numpy as np
 import xarray as xr
@@ -21,18 +22,22 @@ def load_frame_chunk(da):
 
 
 def get_ffpiv(
-    frames,
-    y,
-    x,
-    dt,
-    window_size,
-    overlap,
-    search_area_size,
-    res_y,
-    res_x,
-    chunksize=None,
-    memory_factor=2,
-    engine="numba",
+    frames: xr.DataArray,
+    y: np.ndarray,
+    x: np.ndarray,
+    dt: np.ndarray,
+    window_size: Tuple[int, int],
+    overlap: Tuple[int, int],
+    search_area_size: Tuple[int, int],
+    res_y: float,
+    res_x: float,
+    chunksize: Optional[int] = None,
+    memory_factor: float = 2,
+    engine: Literal["numba", "numpy", "openpiv"] = "numba",
+    ensemble_corr: bool = False,
+    corr_min: float = 0.2,
+    s2n_min: float = 3,
+    count_min: float = 0.2,
 ):
     """Compute time-resolved Particle Image Velocimetry (PIV) using Fast Fourier Transform (FFT) within FF-PIV.
 
@@ -70,6 +75,20 @@ def get_ffpiv(
         available memory is divided by this factor to estimate the chunk size. Default is 4.
     engine : str, optional
         ff-piv engine to use, can be "numpy" or "numba". "numba" is generally much faster.
+    ensemble_corr : bool, optional
+        If True, performs PIV by first averaging cross-correlations across all frames and then deriving velocities.
+        If False, computes velocities for each frame pair separately. Default is True.
+    corr_min : float, optional
+        Minimum correlation value to accept for vvelocity detection. Default is 0.2.
+        In cases with background not removed, you may increase this value to reduce noise but preferred is to
+        perform preprocessing in order to reduce background noise.
+    s2n_min : float, optional
+        Minimum signal-to-noise ratio to accept for velocity detection. Default is 3.
+        A value of 1.0 means there is no signal at all, so velocities are entirely
+        random. If you get very little velocities back, you may try to reduce this.
+    count_min : float, optional
+        Minimum amount of frame pairs that result in accepted correlation values after filtering on `corr_min` and
+        `s2n_min`. Default 0.2. If less frame pairs are available, the velocity is filtered out.
 
     Returns
     -------
@@ -116,50 +135,246 @@ def get_ffpiv(
     # check if there are chunks that are too small in size, needs to be at least 2 frames per chunk
     frames_chunks = [frames_chunk for frames_chunk in frames_chunks if len(frames_chunk) >= 2]
     n_rows, n_cols = len(y), len(x)
+    if ensemble_corr:
+        ds = _get_ffpiv_mean(
+            frames_chunks,
+            y,
+            x,
+            dt,
+            res_y,
+            res_x,
+            n_cols,
+            n_rows,
+            window_size,
+            overlap,
+            search_area_size,
+            engine,
+            corr_min,
+            s2n_min,
+            count_min,
+        )
+    else:
+        ds = _get_ffpiv_timestep(
+            frames_chunks, y, x, dt, res_y, res_x, n_cols, n_rows, window_size, overlap, search_area_size, engine
+        )
+    return ds
+
+
+def _get_ffpiv_mean(
+    frames_chunks,
+    y,
+    x,
+    dt,
+    res_y,
+    res_x,
+    n_cols,
+    n_rows,
+    window_size,
+    overlap,
+    search_area_size,
+    engine,
+    corr_min,
+    s2n_min,
+    count_min,
+):
+    def process_frame_chunk(frame_chunk, corr_min, s2n_min):
+        """Process a single frame chunk to compute correlation and signal-to-noise.
+
+        Parameters
+        ----------
+        frame_chunk : xr.DataArray
+            subset of all frames, manageable in memory size.
+        corr_min : float, optional
+            Minimum correlation value to accept for velocity detection.
+        s2n_min : float, optional
+            Minimum signal-to-noise ratio to accept for velocity detection.
+
+        Returns
+        -------
+        corr : np.ndarray
+            correlation windows, filtered for minimum correlation and signal-to-noise.
+        corr_max : np.ndarray
+            maximum correlation per interrogation window
+        s2n : np.ndarray
+            signal-to-noise ratio per interrogation window, computed as max(corr) / mean(corr) per window
+
+        """
+        x_, y_, corr = cross_corr(
+            frame_chunk.values,
+            window_size=window_size,
+            overlap=overlap,
+            search_area_size=search_area_size,
+            normalize=False,
+            engine=engine,
+            verbose=False,
+        )
+        # Suppress RuntimeWarnings and calculate required metrics
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            corr_max = np.max(corr, axis=(-1, -2))
+            s2n = corr_max / np.mean(corr, axis=(-1, -2))
+        # Apply thresholds
+        masks = (corr_max >= corr_min) & (s2n >= s2n_min) & (np.isfinite(corr_max))
+        corr[~masks] = 0.0
+        corr_max[~masks] = s2n[~masks] = 0.0
+
+        return corr, corr_max, s2n
+
+    def aggregate_results(corr_chunks, s2n_chunks, corr_count, corr_sum, n_frames):
+        """Aggregate correlation and signal-to-noise data from multiple chunks into average statistics.
+
+        This function processes correlation and signal-to-noise data chunks to calculate
+        mean correlation, mean maximum correlation, and mean signal-to-noise values after
+        handling missing data and refining input arrays. Final results are reshaped
+        into their respective dimensions for further analysis.
+
+        Parameters
+        ----------
+        corr_chunks: list of numpy.ndarray
+            List of correlation data chunks to be concatenated and processed.
+        s2n_chunks: list of numpy.ndarray
+            List of signal-to-noise ratio chunks to be concatenated and processed.
+        corr_count: numpy.ndarray
+            Array representing the count of non-missing correlation values across frames, this is used for averaging.
+        corr_sum: numpy.ndarray
+            Array representing the sum of correlation values across frames (ex NaN values), this is used for averaging.
+        n_frames: int
+            Total number of frames to normalize and process the data.
+
+        Returns
+        -------
+        tuple of (numpy.ndarray, numpy.ndarray, numpy.ndarray)
+            - corr_mean: Mean correlation values across chunks and frames.
+            - corr_max_mean: Mean maximum correlation values reshaped to fit data dimensions.
+            - s2n_mean: Mean signal-to-noise ratio values reshaped to fit data dimensions.
+
+        """
+        s2n_concat = np.concatenate(s2n_chunks, axis=0)
+        corr_max_concat = np.concatenate(corr_chunks, axis=0)
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=RuntimeWarning)
+            # apply count filter. Very low amounts of found valid correlations are entirely filtered out.
+            corr_sum[corr_count < count_min * n_frames] = np.nan
+            corr_max_concat[:, corr_count.flatten() < count_min * n_frames] = np.nan
+            corr_mean = np.divide(corr_sum, corr_count[..., None, None])  # expand dimensions and divide by count
+            # time average of maxima for output
+            corr_max_mean = np.nanmean(corr_max_concat, axis=0).reshape(-1, n_rows, n_cols)
+            # time averaging of s2n for output
+            s2n_mean = np.nanmean(s2n_concat, axis=0).reshape(-1, n_rows, n_cols)
+
+        return corr_mean, corr_max_mean, s2n_mean
+
+    def finalize_ds(corr_mean, corr_max, s2n, res_x, res_y, dt_av, y, x):
+        """Finalize the dataset by computing displacements, normalizing values, and assembling an `xr.Dataset`.
+
+        Computes displacements from correlation data using pre-defined parameters, normalizes
+        these displacements with the given spatial and temporal resolutions, and returns the results as an
+        `xr.Dataset`. The resulting Dataset contains signal-to-noise ratio data, maximum correlation values,
+        and displacement vectors.
+
+        Parameters
+        ----------
+        corr_mean: numpy.ndarray
+            Array containing mean correlation values.
+        corr_max: numpy.ndarray
+            Array containing maximum correlation values.
+        s2n: numpy.ndarray
+            Signal-to-noise ratio data array.
+        res_x: float
+            Spatial resolution in the x-direction used to convert pix/s into m/s.
+        res_y: float
+            Spatial resolution in the y-direction used to convert pix/s into m/s.
+        dt_av: float
+            Temporal resolution used to convert pix/s into m/s.
+        y: numpy.ndarray
+            Array of spatial coordinates in the y-dimension.
+        x: numpy.ndarray
+            Array of spatial coordinates in the x-dimension.
+
+        Returns
+        -------
+        xarray.Dataset
+            Contains signal-to-noise ratio data, correlation values, and displacement
+            components in the x and y directions in m/s.
+
+        """
+        u, v = u_v_displacement(corr_mean, n_rows, n_cols, engine=engine)
+        u = (u * res_x / dt_av).astype(np.float32)
+        v = (v * res_y / dt_av).astype(np.float32)
+
+        # Build xarray Dataset
+        ds = xr.Dataset(
+            {
+                "s2n": (["time", "y", "x"], s2n),
+                "corr": (["time", "y", "x"], corr_max),
+                "v_x": (["time", "y", "x"], u),
+                "v_y": (["time", "y", "x"], v),
+            },
+            coords={"time": time[0:1], "y": y, "x": x},
+        )
+        return ds
 
     # make progress bar
     pbar = tqdm(range(len(frames_chunks)), position=0, leave=True)
     pbar.set_description("Computing PIV per chunk")
+    # predefine empty lists for processed chunks
+    corr_chunks, s2n_chunks = [], []
+    corr_sum, corr_count = 0.0, 0.0  # initialize the sum of the correlation windows by a zero
+
+    # loop through frame chunks
+    for n in pbar:
+        da = frames_chunks[n]
+        # get time slice
+        da = load_frame_chunk(da)
+        time = da.time[1:]
+        # dt_chunk = dt.sel(time=time)
+        # we need at least one image-pair to do PIV
+        if len(da) < 2:
+            continue
+
+        # perform cross correlation analysis yielding masked correlations for each interrogation window
+        corr, corr_max, s2n = process_frame_chunk(da, corr_min, s2n_min)
+        # housekeeping
+        corr_sum += np.sum(corr, axis=0, keepdims=True)
+        # add found correlations > 0. these are the valid ones
+        corr_count += np.sum(corr_max > 1e-6, axis=0, keepdims=True)
+        corr_chunks.append(corr_max)
+        s2n_chunks.append(s2n)
+
+        # remove chunk safely from memory ASAP
+        frames_chunks[n] = None
+        del da
+        gc.collect()
+    # concatenate results
+    dt_av = dt.values.mean()
+    n_frames = len(corr_chunks)
+    corr_mean, corr_max_mean, s2n_mean = aggregate_results(corr_chunks, s2n_chunks, corr_count, corr_sum, n_frames)
+    # create final dataset
+    return finalize_ds(corr_mean, corr_max_mean, s2n_mean, res_x, res_y, dt_av, y, x)
+
 
-    # Loop over list
-    ds_piv_chunks = []  # datasets with piv results per chunk
+def _get_ffpiv_timestep(
+    frames_chunks, y, x, dt, res_y, res_x, n_cols, n_rows, window_size, overlap, search_area_size, engine, **kwargs
+):
+    # make progress bar
+    pbar = tqdm(range(len(frames_chunks)), position=0, leave=True)
+    pbar.set_description("Computing PIV per chunk")
+    ds_piv_chunks = []
     for n in pbar:
         da = frames_chunks[n]
         # get time slice
         da = load_frame_chunk(da)
         time = da.time[1:]
         dt_chunk = dt.sel(time=time)
-        # check length again, only if ge 2, assess velocities
+        # we need at least one image-pair to do PIV
         if len(da) >= 2:
-            # perform cross correlation analysis yielding correlations for each interrogation window
-            x_, y_, corr = cross_corr(
-                da.values,
-                window_size=window_size,
-                overlap=overlap,
-                search_area_size=search_area_size,
-                normalize=False,
-                engine=engine,
-                verbose=False,
+            u, v, corr_max, s2n = _get_uv_timestep(
+                frames_chunks[n], n_cols, n_rows, window_size, overlap, search_area_size, engine=engine, **kwargs
             )
-            frames_chunks[n] = None
-            del da
-            gc.collect()
-
-            # get the maximum correlation per interrogation window
-            corr_max = np.nanmax(corr, axis=(-1, -2))
-
-            # get signal-to-noise, whilst suppressing nanmean over empty slice warnings
-            with warnings.catch_warnings():
-                warnings.simplefilter("ignore", category=RuntimeWarning)
-                s2n = corr_max / np.nanmean(corr, axis=(-1, -2))
-
-            # reshape corr / s2n to the amount of expected rows and columns
-            s2n = (s2n.reshape(-1, n_rows, n_cols)).astype(np.float32)
-            corr_max = (corr_max.reshape(-1, n_rows, n_cols)).astype(np.float32)
-            u, v = u_v_displacement(corr, n_rows, n_cols, engine=engine)
-            # convert into meter per second and store as float32 to save memory / disk space
             u = (u * res_x / np.expand_dims(dt_chunk, (1, 2))).astype(np.float32)
             v = (v * res_y / np.expand_dims(dt_chunk, (1, 2))).astype(np.float32)
+
             # put s2n, corr_max, u and v in one xarray dataset, with coordinates time, y and x
             ds = xr.Dataset(
                 {
@@ -176,6 +391,39 @@ def get_ffpiv(
             )
             # u and v to meter per second
             ds_piv_chunks.append(ds)
+        # remove chunk safely from memory
+        frames_chunks[n] = None
+        del da
+        gc.collect()
     # concatenate all parts in time
     ds = xr.concat(ds_piv_chunks, dim="time")
     return ds
+
+
+def _get_uv_timestep(da, n_cols, n_rows, window_size, overlap, search_area_size, engine="numba"):
+    # perform cross correlation analysis yielding correlations for each interrogation window
+    x_, y_, corr = cross_corr(
+        da.values,
+        window_size=window_size,
+        overlap=overlap,
+        search_area_size=search_area_size,
+        normalize=False,
+        engine=engine,
+        verbose=False,
+    )
+
+    # get the maximum correlation per interrogation window
+    corr_max = np.nanmax(corr, axis=(-1, -2))
+
+    # get signal-to-noise, whilst suppressing nanmean over empty slice warnings
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=RuntimeWarning)
+        s2n = corr_max / np.nanmean(corr, axis=(-1, -2))
+
+    # reshape corr / s2n to the amount of expected rows and columns
+    s2n = (s2n.reshape(-1, n_rows, n_cols)).astype(np.float32)
+    corr_max = (corr_max.reshape(-1, n_rows, n_cols)).astype(np.float32)
+    u, v = u_v_displacement(corr, n_rows, n_cols, engine=engine)
+
+    # convert into meter per second and store as float32 to save memory / disk space
+    return u, v, corr_max, s2n