chromatic_adaption_feature.py

Go to the documentation of this file.

from __future__ import annotations
 
import enum
from ids_peak_common.datatypes.range import Range
from ids_peak_icv.pipeline._internal.color_matrix_transformation_module import (
    ColorMatrixTransformationModule
)
from ids_peak_icv.pipeline.datatypes import ColorSpace, ChromaticAdaptionAlgorithm
from ids_peak_icv.pipeline.features.ifeature import IFeature
 
 
class ChromaticAdaptionFeature(IFeature):
    """!
    @brief
    Adjusts to changes in lighting conditions to maintain consistent color perception
    despite variations in light sources.
 
    In industrial imaging, white balance can fail due to the lack of a neutral reference in the image, such as when the
    scene contains no gray or white areas, or when the colors are unevenly distributed (as in images dominated by a single color).
    In these cases, traditional white balance algorithms, like the gray world method, may fail to produce accurate color corrections.
 
    Chromatic adaptation provides an alternative solution by adjusting the image’s colors based on the known or
    estimated correlated color temperature of the light source.
 
    @note
        If chromatic adaption is used in combination with white balance, the result is indefinite.
 
    Default Configuration:
        - Chromatic adaption algorithm = Bradford
        - Color space = SRGB_D65
        - Color temperature = undefined (chromatic adaption won't be applied)
 
    @since ids_peak_icv 1.3
    @ingroup ids_peak_icv_python_pipeline_features
    """
 
    def __init__(self, module: ColorMatrixTransformationModule) -> None:
        """!
        @brief
        Creates a ChromaticAdaptionFeature for an existing color matrix transformation module.
 
        @param module: Reference to the underlying ColorMatrixTransformationModule.
 
        @since ids_peak_icv 1.3
        """
        self._module = module
 
    @property
    def enabled(self) -> bool:
        """!
        @brief
        Indicates whether chromatic adaptation is enabled.
 
        @return True if enabled; otherwise, False.
 
        @since ids_peak_icv 1.3
        """
        return self._module.chromatic_adaption_enabled
 
    @enabled.setter
    def enabled(self, value: bool) -> None:
        """!
        @brief
        Enables or disables chromatic adaptation.
 
        @param value: Set to True to enable the feature, or False to disable it.
 
        @since ids_peak_icv 1.3
        """
        self._module.chromatic_adaption_enabled = value
 
    def reset_to_default(self) -> None:
        """!
        @brief
        Resets the chromatic adaption configuration to the default values.
 
        @note The enabled state does not change when calling this function.
 
        @since ids_peak_icv 1.3
        """
        self._module.reset_chromatic_adaption()
 
    @property
    def target_color_space(self) -> ColorSpace:
        """!
        @brief
        Retrieves the current target color space.
 
        @return The currently set color space.
 
        @since ids_peak_icv 1.3
        """
        return self._module.target_color_space
 
    @target_color_space.setter
    def target_color_space(self, value: ColorSpace) -> None:
        """!
        @brief
        Sets the target color space.
 
        A color space is a specific implementation of a color model, mapping colors to a defined range of values
        (e.g., standard primaries, white point, and gamma).
 
        @param value: The color space to set.
 
        @since ids_peak_icv 1.3
        """
        self._module.target_color_space = value
 
    @property
    def algorithm(self) -> ChromaticAdaptionAlgorithm:
        """!
        @brief
        Retrieves the current chromatic adaption algorithm.
 
        @return The currently set chromatic adaption algorithm.
 
        @since ids_peak_icv 1.3
        """
        return self._module.chromatic_adaption_algorithm
 
    @algorithm.setter
    def algorithm(self, value: ChromaticAdaptionAlgorithm) -> None:
        """!
        @brief
        Sets the algorithm used for chromatic adaption.
 
        The algorithms use a CAT (chromatic adaptation transform) matrix.
 
        @param value: The chromatic adaption algorithm to set.
 
        @since ids_peak_icv 1.3
        """
        self._module.chromatic_adaption_algorithm = value
 
    @property
    def color_temperature(self) -> int:
        """!
        @brief
        Retrieves the current color temperature.
 
        @return The current color temperature in Kelvin.
 
        @exception NotPossibleException: If the color temperature has not been set (it has no default value).
 
        @since ids_peak_icv 1.3
        """
        return self._module.color_temperature
 
    @color_temperature.setter
    def color_temperature(self, value: int) -> None:
        """!
        @brief
        Sets the color temperature of the light source.
        If no color temperature is explicitly set the chromatic adaption won't be applied.
 
        @param value: The color temperature in Kelvin to set. Must be within the allowed range.
 
        @since ids_peak_icv 1.3
        """
        self._module.color_temperature = value
 
    def has_color_temperature(self) -> bool:
        """!
        @brief
        Checks whether a color temperature has been set.
 
        @return True if a color temperature is set, False otherwise.
 
        @since ids_peak_icv 1.3
        """
        return self._module.has_color_temperature()
 
    @property
    def color_temperature_range(self) -> Range:
        """!
        @brief
        Returns the allowed temperature range for the current combination of color space and algorithm.
 
        @return A Range representing the allowed temperature range in Kelvin.
 
        @since ids_peak_icv 1.3
        """
        return self._module.color_temperature_range