color_matrix_transformation_module.py

Go to the documentation of this file.

import ctypes
from typing import cast
 
import numpy as np
 
from ids_peak_common import Interval, Range, PixelFormat
from ids_peak_common.serialization import IArchive
from ids_peak_common.pipeline.modules.iautofeature_module import IAutoFeature
from ids_peak_icv import lib_loader
from ids_peak_icv.backend.datatypes import (peak_icv_color_correction_matrix,
                                              peak_icv_color_matrix_transformation_handle, peak_common_interval_f,
                                              peak_common_range_u)
from ids_peak_icv.backend.utils import execute_and_map_return_codes
from ids_peak_icv.datatypes.image import Image
from ids_peak_icv.pipeline._internal.module_base import ModuleBase
from ids_peak_icv.pipeline.datatypes import ChromaticAdaptionAlgorithm, ColorSpace
 
 
class ColorMatrixTransformationModule(ModuleBase):
    """!
    @brief
    Color matrix transformation is an image pipeline module that applies a color correction matrix to an image.
 
    Provides the features ColorCorrectionFeature, SaturationFeature and ChromaticAdaptionFeature.
 
    Default configuration:
        - Color correction matrix = 3x3 identity matrix
        - Saturation = 1.0
        - no chromatic adaption correction applied
 
    @since ids_peak_icv 1.0
    """
 
    DEFAULT_MATRIX: np.ndarray = np.eye(3)
    """!
    @brief
    Default color correction matrix value.
    
    @since ids_peak_icv 1.0
    """
 
    DEFAULT_SATURATION: float = 1.0
    """!
    @brief
    Default saturation value.
    
    @since ids_peak_icv 1.0
    """
 
    SUPPORTED_PIXEL_FORMATS = [
        PixelFormat.RGB_8, PixelFormat.RGB_10, PixelFormat.RGB_12, PixelFormat.BGR_8, PixelFormat.BGR_10,
        PixelFormat.BGR_12, PixelFormat.RGBA_8, PixelFormat.RGBA_10, PixelFormat.RGBA_12, PixelFormat.BGRA_8,
        PixelFormat.BGRA_10, PixelFormat.BGRA_12
    ]
 
    def __init__(self) -> None:
        """!
        @brief
        Initialize a color matrix transformation module with default settings.
 
        @since ids_peak_icv 1.0
        """
        super().__init__()
 
        _color_matrix_transformation_handle = peak_icv_color_matrix_transformation_handle()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_Create,
            ctypes.pointer(_color_matrix_transformation_handle)
        )
        self._handle = _color_matrix_transformation_handle
        self._auto_feature_module_auto_feature_module: IAutoFeature | None = None
 
        self.reset_to_default()
 
    def __del__(self) -> None:
        if hasattr(self, "_handle") and self._handle:
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_Destroy(self._handle)
 
    @property
    def type(self) -> str:
        """!
        @brief
        Returns the type of the module for serialization purposes.
 
        @return Module type
 
        @since ids_peak_icv 1.0
        """
        return "ColorMatrixTransformation"
 
    @property
    def version(self) -> int:
        """!
        @brief
        Return the module version.
 
        @return Module version.
 
        @since ids_peak_icv 1.3
        """
        return 2
 
    @property
    def enabled(self) -> bool:
        """!
        @brief
        Gets whether this module is enabled.
 
        When disabled, :func:`process` returns the input image unchanged.
 
        @return True if the module is enabled, False otherwise.
 
        @since ids_peak_icv 1.0
        """
        return self.color_correction_enabledcolor_correction_enabledcolor_correction_enabled or self.saturation_enabledsaturation_enabledsaturation_enabled or self.chromatic_adaption_enabledchromatic_adaption_enabledchromatic_adaption_enabled
 
    @enabled.setter
    def enabled(self, enabled: bool) -> None:
        """!
        @brief
        Enables or disables the module.
 
        When disabled, :func:`process` returns the input image unchanged.
 
        @param enabled: True to enable, False to disable.
 
        @since ids_peak_icv 1.0
        """
        self.color_correction_enabledcolor_correction_enabledcolor_correction_enabled = enabled
        self.saturation_enabledsaturation_enabledsaturation_enabled = enabled
        self.chromatic_adaption_enabledchromatic_adaption_enabledchromatic_adaption_enabled = enabled
        self._update_matrix_in_auto_feature_module()
 
    @property
    def matrix(self) -> np.ndarray:
        """!
        @brief
        Gets the current color correction matrix.
 
        @return The current color correction matrix.
 
        @since ids_peak_icv 1.0
        """
        matrix = self.DEFAULT_MATRIX
 
        c_matrix = peak_icv_color_correction_matrix.from_buffer_copy(
            np.asarray(matrix, dtype=np.float32).flatten().tobytes())
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_GetColorCorrectionMatrix,
            self._handle,
            ctypes.pointer(c_matrix),
        )
        return cast(np.ndarray, np.frombuffer(memoryview(c_matrix), dtype=np.float32).reshape(3, 3).copy())
 
    @matrix.setter
    def matrix(self, matrix: np.ndarray) -> None:
        """!
        @brief
        Sets the color correction matrix.
 
        @param matrix: The color correction matrix.
 
        @since ids_peak_icv 1.0
        """
        c_matrix = peak_icv_color_correction_matrix.from_buffer_copy(
            np.asarray(matrix, dtype=np.float32).flatten().tobytes())
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_SetColorCorrectionMatrix,
            self._handle,
            c_matrix
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def saturation(self) -> float:
        """!
        @brief
        Gets the current saturation value.
 
        @return The current saturation value.
 
        @since ids_peak_icv 1.0
        """
        saturation = ctypes.c_float()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_GetSaturation,
            self._handle,
            ctypes.byref(saturation))
        return saturation.value
 
    @saturation.setter
    def saturation(self, saturation: float) -> None:
        """!
        @brief
        Sets the saturation value.
 
        @param saturation: The saturation value.
 
        @since ids_peak_icv 1.0
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_SetSaturation,
            self._handle,
            ctypes.c_float(saturation))
        if self.saturation_enabledsaturation_enabledsaturation_enabled:
            self._update_matrix_in_auto_feature_module()
 
    @property
    def saturation_range(self) -> Interval:
        """!
        @brief
        Gets the valid range for saturation.
 
        @return The valid saturation range.
 
        @since ids_peak_icv 1.0
        """
        c_interval = peak_common_interval_f()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_GetSaturationRange,
            self._handle, ctypes.pointer(c_interval))
        return Interval(c_interval.minimum, c_interval.maximum)
 
    @property
    def color_correction_enabled(self) -> bool:
        """!
        @brief
        Gets whether color correction is enabled.
 
        When enabled, :func:`process` applies color correction to the input image.
 
        @return True if color correction is enabled, False otherwise.
 
        @since ids_peak_icv 1.0
        """
        enabled = ctypes.c_bool()
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ColorCorrection_IsEnabled,
            self._handle,
            ctypes.byref(enabled),
        )
        return bool(enabled.value)
 
    @color_correction_enabled.setter
    def color_correction_enabled(self, enabled: bool) -> None:
        """!
        @brief
        Enables or disables color correction.
 
        When enabled, :func:`process` applies color correction to the input image.
 
        @param enabled: True to enable, False to disable.
 
        @since ids_peak_icv 1.0
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ColorCorrection_SetEnabled,
            self._handle,
            ctypes.c_bool(enabled),
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def chromatic_adaption_enabled(self) -> bool:
        """!
        @brief
        Checks if the chromatic adaptation feature is enabled.
 
        @return True if chromatic adaptation is currently active, false otherwise.
 
        @since ids_peak_icv 1.3
        """
        enabled = ctypes.c_bool()
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_IsEnabled,
            self._handle,
            ctypes.byref(enabled),
        )
        return bool(enabled.value)
 
    @chromatic_adaption_enabled.setter
    def chromatic_adaption_enabled(self, enabled: bool) -> None:
        """!
        @brief
        Enables or disables the chromatic adaptation feature.
 
        @param enabled: True to enable chromatic adaptation, false to disable it.
 
        @since ids_peak_icv 1.3
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_SetEnabled,
            self._handle,
            ctypes.c_bool(enabled),
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def chromatic_adaption_algorithm(self) -> ChromaticAdaptionAlgorithm:
        """!
        @brief
        Returns the current algorithm used for chromatic adaptation.
 
        @return The active ChromaticAdaptionAlgorithm.
 
        @since ids_peak_icv 1.3
        """
        algorithm = ctypes.c_int()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_GetAlgorithm,
            self._handle,
            ctypes.byref(algorithm),
        )
        return ChromaticAdaptionAlgorithm(algorithm.value)
 
    @chromatic_adaption_algorithm.setter
    def chromatic_adaption_algorithm(self, algorithm: ChromaticAdaptionAlgorithm) -> None:
        """!
        @brief
        Sets the algorithm used to calculate the chromatic adaptation transformation.
 
        @param algorithm: The ChromaticAdaptionAlgorithm to apply.
 
        @since ids_peak_icv 1.3
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_SetAlgorithm,
            self._handle,
            algorithm.value,
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def target_color_space(self) -> ColorSpace:
        """!
        @brief
        Returns the target color space used for chromatic adaptation.
 
        @return The current target ColorSpace.
 
        @since ids_peak_icv 1.3
        """
        color_space = ctypes.c_int()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_GetTargetColorSpace,
            self._handle,
            ctypes.byref(color_space),
        )
        return ColorSpace(color_space.value)
 
    @target_color_space.setter
    def target_color_space(self, color_space: ColorSpace) -> None:
        """!
        @brief
        Sets the target color space for the chromatic adaptation transformation.
 
        @param color_space: The target ColorSpace.
 
        @since ids_peak_icv 1.3
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_SetTargetColorSpace,
            self._handle,
            color_space.value,
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def color_temperature(self) -> int:
        """!
        @brief
        Returns the currently configured source color temperature in Kelvin.
 
        @return The color temperature value in Kelvin.
 
        @since ids_peak_icv 1.3
        """
        temperature = ctypes.c_uint32()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_GetColorTemperature,
            self._handle,
            ctypes.byref(temperature),
        )
        return int(temperature.value)
 
    @color_temperature.setter
    def color_temperature(self, temperature: int) -> None:
        """!
        @brief
        Sets the source color temperature in Kelvin to be used for chromatic adaptation.
 
        @param temperature: The color temperature value in Kelvin.
 
        @since ids_peak_icv 1.3
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_SetColorTemperature,
            self._handle,
            ctypes.c_uint32(int(temperature)),
        )
        self._update_matrix_in_auto_feature_module()
 
    @property
    def color_temperature_range(self) -> Range:
        """!
        @brief
        Returns the valid range of values for color temperature.
 
        @return A Range denoting the min and max allowed temperature values as well as its allowed increment.
 
        @since ids_peak_icv 1.3
        """
        c_range = peak_common_range_u()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_GetColorTemperatureRange,
            self._handle,
            ctypes.byref(c_range),
        )
        return Range(c_range.minimum, c_range.maximum, c_range.increment)
 
    def has_color_temperature(self) -> bool:
        """!
        @brief
        Checks if a specific color temperature has been explicitly set.
 
        @return True if a color temperature is configured, false otherwise.
 
        @since ids_peak_icv 1.3
        """
        value = ctypes.c_bool()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_HasColorTemperature,
            self._handle,
            ctypes.byref(value),
        )
        return bool(value.value)
 
    def reset_color_temperature(self) -> None:
        """!
        @brief
        Resets the color temperature to its default, uninitialized state.
 
        @since ids_peak_icv 1.3
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ChromaticAdaption_ResetColorTemperature,
            self._handle,
        )
        self._update_matrix_in_auto_feature_module()
 
    def reset_chromatic_adaption(self) -> None:
        """!
        @brief
        Resets all chromatic adaptation settings (temperature, algorithm, color space) to their default values.
 
        @since ids_peak_icv 1.3
        """
        self.chromatic_adaption_algorithmchromatic_adaption_algorithmchromatic_adaption_algorithm = ChromaticAdaptionAlgorithm.BRADFORD
        self.target_color_spacetarget_color_spacetarget_color_space = ColorSpace.SRGB_D65
        self.reset_color_temperature()
 
    @property
    def saturation_enabled(self) -> bool:
        """!
        @brief
        Gets whether saturation is enabled.
 
        When enabled, :func:`process` applies saturation to the input image.
 
        @return True if saturation is enabled, False otherwise.
 
        @since ids_peak_icv 1.0
        """
        enabled = ctypes.c_bool()
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_Saturation_IsEnabled,
            self._handle,
            ctypes.byref(enabled),
        )
        return bool(enabled.value)
 
    @saturation_enabled.setter
    def saturation_enabled(self, enabled: bool) -> None:
        """!
        @brief
        Enables or disables saturation.
 
        When enabled, :func:`process` applies saturation to the input image.
 
        @param enabled: True to enable, False to disable.
 
        @since ids_peak_icv 1.0
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_Saturation_SetEnabled,
            self._handle,
            ctypes.c_bool(enabled),
        )
        self._update_matrix_in_auto_feature_module()
 
    def process(self, input_image: Image) -> Image:
        """!
        @brief
        Processes the input image and returns a color corrected and/or saturated output image.
 
        @supportedPixelformats{ColorMatrixTransformation}
 
        Images with other formats are passed through unmodified.
 
        @note This operation disregards any specified image regions and processes the entire image.
 
        @param input_image: The input image to be processed.
 
        @return The input image after in-place color correction and/or saturation has been applied.
 
        @since ids_peak_icv 1.0
        """
        if not self.enabledenabledenabledenabledenabledenabled:
            return input_image
 
        if input_image.pixel_format not in self.SUPPORTED_PIXEL_FORMATS:
            return input_image
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_ProcessInplace,
            self._handle,
            input_image._handle
        )
        return input_image
 
    def reset_to_default(self) -> None:
        """!
        @brief
        Resets all settings to their defaults.
 
        Default configuration:
          - matrix = identity
          - saturation = 1.0
          - no chromatic adaption correction
 
        @note The enabled state does not change when calling this function.
 
        @since ids_peak_icv 1.0
        """
        self.matrixmatrixmatrix = self.DEFAULT_MATRIX
        self.saturationsaturationsaturation = self.DEFAULT_SATURATION
        self.reset_chromatic_adaption()
 
    def serialize(self, archive: IArchive) -> None:
        """!
        @brief
        Serializes the object's internal state into the provided archive.
 
        This function populates the given archive with all parameters required to fully represent the current state of the object.
        It ensures that the object can be reconstructed or transmitted accurately by saving all relevant data members
        in a consistent and structured format.
 
        @param archive: The target archive that will store the serialized parameters.
 
        @since ids_peak_icv 1.0
        """
        super().serialize(archive)
 
        saturation_archive = archive.create_archive()
 
        archive.set("Version", self.versionversionversionversion)
 
        saturation_archive.set("Enabled", self.saturation_enabledsaturation_enabledsaturation_enabled)
        saturation_archive.set("Value", self.saturationsaturationsaturation)
        archive.set("Saturation", saturation_archive)
 
        color_correction_matrix_archive = archive.create_archive()
        color_correction_matrix_archive.set("Enabled", self.color_correction_enabledcolor_correction_enabledcolor_correction_enabled)
        color_correction_matrix_archive.set("Matrix",
                                            cast(list[float], cast(np.ndarray, self.matrixmatrixmatrix).flatten().tolist()))
        archive.set("ColorCorrection", color_correction_matrix_archive)
 
        chromatic_archive = archive.create_archive()
        chromatic_archive.set("Enabled", self.chromatic_adaption_enabledchromatic_adaption_enabledchromatic_adaption_enabled)
        chromatic_archive.set("Algorithm", self.chromatic_adaption_algorithmchromatic_adaption_algorithmchromatic_adaption_algorithm.name.capitalize())
        chromatic_archive.set("TargetColorSpace", self.target_color_spacetarget_color_spacetarget_color_space.name)
 
        if self.has_color_temperature():
            chromatic_archive.set("ColorTemperature", self.color_temperaturecolor_temperaturecolor_temperature)
 
        archive.set("ChromaticAdaption", chromatic_archive)
 
    def deserialize(self, archive: IArchive) -> None:
        """!
        @brief
        Restores the object's state from the provided archive.
 
        This function reads and applies all necessary parameters from the given archive
        to reconstruct the internal state of the object.
        It ensures that the object is restored to a valid and consistent state.
 
        @param archive: The source archive containing the serialized parameters.
 
        @exception CorruptedException: If Archive is malformed, misses keys or the values are invalid
        @exception NotSupportedException: If the 'Version' entry indicates an unsupported version.
 
        @note This function requires that the archive contains all expected fields as produced by
              a corresponding serialize() call.
 
        @since ids_peak_icv 1.0
        """
        super()._validate_version(archive)
 
        saturation_archive = archive.get_archive("Saturation")
        self.saturation_enabledsaturation_enabledsaturation_enabled = saturation_archive.get("Enabled", bool)
        self.saturationsaturationsaturation = saturation_archive.get("Value", float)
 
        color_correction_matrix_archive = archive.get_archive("ColorCorrection")
        self.color_correction_enabledcolor_correction_enabledcolor_correction_enabled = color_correction_matrix_archive.get("Enabled", bool)
        self.matrixmatrixmatrix = np.array(color_correction_matrix_archive.get("Matrix", list)).reshape(3, 3)
 
        version = archive.get("Version", int)
 
        if version >= self.versionversionversionversion:
            chromatic_archive = archive.get_archive("ChromaticAdaption")
 
            self.chromatic_adaption_enabledchromatic_adaption_enabledchromatic_adaption_enabled = chromatic_archive.get("Enabled", bool)
            self.chromatic_adaption_algorithmchromatic_adaption_algorithmchromatic_adaption_algorithm = ChromaticAdaptionAlgorithm[
                chromatic_archive.get("Algorithm", str).upper()]
            self.target_color_spacetarget_color_spacetarget_color_space = ColorSpace[chromatic_archive.get("TargetColorSpace", str).upper()]
 
            if chromatic_archive.has("ColorTemperature"):
                self.color_temperaturecolor_temperaturecolor_temperature = chromatic_archive.get("ColorTemperature", int)
            else:
                self.reset_color_temperature()
        else:
            self.reset_chromatic_adaption()
 
    def _set_autofeature_module(self, auto_feature_module: IAutoFeature | None) -> None:
        self._auto_feature_module_auto_feature_module = auto_feature_module
        self._update_matrix_in_auto_feature_module()
 
    @property
    def effective_matrix(self) -> np.ndarray:
        """!
        @brief
        Returns the final effective matrix calculated by concatenating all enabled transformations
        (e.g., Chromatic Adaptation, Color Correction, and Saturation).
 
        @return The combined effective color correction matrix.
 
        @since ids_peak_icv 1.3
        """
        c_matrix = peak_icv_color_correction_matrix()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_Preprocessing_ColorMatrixTransformation_GetEffectiveMatrix,
            self._handle, ctypes.byref(c_matrix)
        )
        return cast(np.ndarray, np.frombuffer(memoryview(c_matrix), dtype=np.float32).reshape(3, 3).copy())
 
    def _update_matrix_in_auto_feature_module(self) -> None:
        if self._auto_feature_module_auto_feature_module:
            matrix = self.effective_matrix
            self._auto_feature_module_auto_feature_module.set_color_correction_matrix(matrix.flatten().tolist())