binning_feature.py

Go to the documentation of this file.

from __future__ import annotations
 
import enum
 
from ids_peak_common.datatypes.interval import Interval
 
from ids_peak_icv.pipeline._internal.downsampling_module import DownsamplingModule, DownsamplingMode
from ids_peak_icv.pipeline.features.ifeature import IFeature
 
 
class BinningMode(enum.Enum):
    """!
    @brief
    Mode parameter for the binning algorithm.
 
    The enum holding the possible modes.
 
    @since ids_peak_icv 1.0
    @ingroup ids_peak_icv_python_pipeline_types
    """
 
    BINNING_AVERAGE = 0
    """!
    @brief
    The averaged pixel values of neighboring rows and/or columns are computed during binning.
    
    @since ids_peak_icv 1.0
    """
 
    BINNING_SUM = 1
    """!
    @brief
    The pixel values of neighboring rows and/or columns are summed during binning.
    
    @since ids_peak_icv 1.0
    """
 
 
class BinningFeature(IFeature):
    """!
    @brief
    Binning is used to decrease the image size.
 
    @supportedPixelformats{ImageTransformation}
 
    This method reduces resolution by summarizing or averaging groups of pixels
    in the horizontal (x) and/or vertical (y) directions.
    It helps preserve image quality by minimizing aliasing artifacts.
 
    @note Processes the entire image, ignoring any specified image region.
 
    @note The alpha channel of the input image (if present) is also ignored.
              This is because the alpha channel can have different interpretations
              — such as transparency, segmentation labels, or masks —
              each of which would require different handling during binning.
              Consequently, the alpha channel of the output image is always set to the maximum possible pixel value.
 
    @note Binning permanently reduces image resolution. The original resolution cannot be recovered
              after binning is applied.
 
    Default configuration:
        - x = 1
        - y = 1
        - BinningMode.BinningAverage
 
    @since ids_peak_icv 1.0
    @ingroup ids_peak_icv_python_pipeline_features
    """
 
    def __init__(self, module: DownsamplingModule) -> None:
        """!
        @brief
        Creates a BinningFeature for an existing downsampling module.
 
        @param module: Reference to the underlying DownsamplingModule.
 
        @since ids_peak_icv 1.0
        """
        self._module = module
 
    @property
    def enabled(self) -> bool:
        """!
        @brief
        Gets whether this feature is currently enabled.
 
        @return True if enabled; otherwise False.
 
        @since ids_peak_icv 1.0
        """
        return self._module.enabled
 
    @enabled.setter
    def enabled(self, enabled: bool) -> None:
        """!
        @brief
        Enables or disables the feature.
 
        @param enabled: True to enable, False to disable.
 
        @since ids_peak_icv 1.0
        """
        self._module.enabled = enabled
 
    def reset_to_default(self) -> None:
        """!
        @brief
        Resets all settings to their defaults.
 
        Default configuration:
            - x = 1
            - y = 1
            - mode = BinningMode.BinningAverage
 
        @note The enabled state does not change when calling this function.
 
        @since ids_peak_icv 1.0
        """
        self._module.reset_to_default()
 
    @property
    def x(self) -> int:
        """!
        @brief
        Gets the current number of columns used for binning.
 
        @return The current number of columns summarized/averaged during binning.
 
        @since ids_peak_icv 1.0
        """
        return self._module.x
 
    @x.setter
    def x(self, value: int) -> None:
        """!
        @brief
        Sets the number of columns used for binning.
 
        @param value: An integer value representing the number of columns summarized/averaged during binning.
                      Valid values are within the range returned by object.range.
        @exception OutOfRangeException: If value is outside the valid range.
 
        @since ids_peak_icv 1.0
        """
        self._module.x = value
 
    @property
    def y(self) -> int:
        """!
        @brief
        Gets the current number of rows used for binning.
 
        @return The current number of rows summarized/averaged during binning.
 
        @since ids_peak_icv 1.0
        """
        return self._module.y
 
    @y.setter
    def y(self, value: int) -> None:
        """!
        @brief
        Sets the number of rows used for binning.
 
        @param value: An integer value representing the number of rows summarized/averaged during binning.
                      Valid values are within the range returned by object.range.
        @exception OutOfRangeException: If value is outside the valid range.
 
        @since ids_peak_icv 1.0
        """
        self._module.y = value
 
    @property
    def mode(self) -> BinningMode:
        """!
        @brief
        Gets the current BinningMode.
 
        @return The current BinningMode.
 
        @since ids_peak_icv 1.0
        """
        return BinningMode(self._module.mode.value)
 
    @mode.setter
    def mode(self, value: BinningMode) -> None:
        """!
        @brief
        Sets the BinningMode.
 
        @param value: The BinningMode to set.
 
        @since ids_peak_icv 1.0
        """
        self._module.mode = DownsamplingMode(value.value)
 
    @property
    def range(self) -> Interval:
        """!
        @brief
        Gets the valid range for the binning factors x and y.
 
        The returned interval specifies the minimum and maximum values that can be passed to object.x or object.y.
 
        @return An Interval representing the valid binning factor range.
 
        @since ids_peak_icv 1.0
        """
        return self._module.range