tone_mapping.py

Go to the documentation of this file.

from __future__ import annotations
 
import ctypes
from enum import Enum
from typing import Any
 
from ids_peak_icv import lib_loader
from ids_peak_icv.backend.datatypes import (
    peak_icv_tone_mapping_handle,
    peak_icv_image_handle,
)
from ids_peak_icv.backend.utils import execute_and_map_return_codes
from ids_peak_icv.datatypes.image import Image, _check_icv_image
from ids_peak_common.datatypes.pixelformat import PixelFormat
from ids_peak_common.datatypes.geometry.size import Size
 
 
class ToneMappingAlgorithm(Enum):
    """!
    @brief
    Specifies the tone mapping algorithm.
 
    Defines the algorithm used to map a High Dynamic Range (HDR) image to a
    displayable Low Dynamic Range (LDR) image.
 
    @note
       Currently, only the Reinhard tone mapping algorithm is supported.
       Additional tone mapping algorithms may be added in future versions.
 
    @ingroup ids_peak_icv_python_hdr
    @since ids_peak_icv 1.2
    """
 
    REINHARD = 0
    """!
    @brief
    Reinhard tone mapping operator.
 
    Applies a global tone mapping operator based on the method proposed
    by Reinhard et al. to compress the dynamic range of an HDR image while
    preserving visual contrast.
    """
 
 
class ToneMapping:
    """!
    @brief
    Performs tone mapping on HDR images.
 
    This class provides functionality to convert a High Dynamic Range (HDR)
    image into a displayable Low Dynamic Range (LDR) image using a tone
    mapping algorithm.
 
    Internally, tone mapping is performed using the Reinhard tone mapping
    operator, which is currently the only supported algorithm. The algorithm
    is fixed at object creation time.
 
    ### Typical usage
    - Create a :class:`ToneMapping` object
    - Optionally query or set the tone mapping algorithm
    - Call :meth:`process` to convert an HDR image into an LDR image
 
    ### Limitations
    - The input image must be a valid HDR image.
    - Only the Reinhard tone mapping algorithm is currently supported.
 
    @ingroup ids_peak_icv_python_hdr
    @since ids_peak_icv 1.2
    """
 
    def __init__(self, *args: Any, **kwargs: Any) -> None:
        """!
        @brief
        Constructs a tone mapping object.
 
        Creates and initializes a tone mapping object using the default
        tone mapping algorithm (Reinhard).
 
        @since ids_peak_icv 1.2
        """
        self._handle = peak_icv_tone_mapping_handle()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_ToneMapping_Create,
            ctypes.pointer(self._handle),
        )
 
    def __del__(self) -> None:
        """!
        @brief
        Destroys the tone mapping object.
 
        Releases all resources associated with the tone mapping object.
 
        @since ids_peak_icv 1.2
        """
        if hasattr(self, "_handle") and self._handle:
            lib_loader.dll().peak_icv_ToneMapping_Destroy(self._handle)
 
    @property
    def algorithm(self) -> ToneMappingAlgorithm:
        """!
        @brief
        Returns the tone mapping algorithm used by this object.
 
        The algorithm is defined at construction time and determines how
        the input HDR image is converted into a displayable image.
 
        @return
            The tone mapping algorithm identifier.
 
        @since ids_peak_icv 1.2
        """
        algorithm = ctypes.c_int()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_ToneMapping_GetAlgorithm,
            self._handle,
            ctypes.pointer(algorithm),
        )
        return ToneMappingAlgorithm(algorithm.value)
 
    @algorithm.setter
    def algorithm(self, algorithm: ToneMappingAlgorithm) -> None:
        """!
        @brief
        Sets the tone mapping algorithm.
 
        @param algorithm:
            The tone mapping algorithm to use.
 
        @since ids_peak_icv 1.2
        """
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_ToneMapping_SetAlgorithm,
            self._handle,
            ctypes.c_int(algorithm.value),
        )
 
    def process(self, image: Image) -> Image:
        """!
        @brief
        Applies tone mapping to an HDR image.
 
        Processes the provided HDR image and converts it into a displayable
        Low Dynamic Range (LDR) image using the tone mapping algorithm
        associated with this object.
 
        The input image must be compatible with the tone mapping configuration.
 
        @param image:
            The HDR image to be tone mapped.
 
        @return
            The resulting tone-mapped image.
 
        @since ids_peak_icv 1.2
        """
        _check_icv_image(image)
 
        # Query the output pixel format from the backend
        output_pixel_format = ctypes.c_int()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_ToneMapping_Process_GetOutputPixelFormat,
            self._handle,
            ctypes.c_int(image.pixel_format.value),
            ctypes.pointer(output_pixel_format),
        )
 
        # Create output image with same size and backend-defined pixel format
        output_image = Image.create_from_pixel_format_and_size(
            PixelFormat(output_pixel_format.value),
            Size(image.width, image.height),
        )
 
        # Perform tone mapping
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_ToneMapping_Process,
            self._handle,
            image._handle,
            output_image._handle,
        )
 
        return output_image