hdr.py

Go to the documentation of this file.

from __future__ import annotations
 
import ctypes
from enum import Enum
from typing import Any, TypeAlias
 
import numpy as np
import numpy.typing as npt
 
from ids_peak_icv import lib_loader
from ids_peak_icv.exceptions import NotSupportedException
from ids_peak_icv.backend.datatypes import peak_icv_hdr_handle, peak_icv_image_handle
from ids_peak_icv.backend.utils import execute_and_map_return_codes, create_array, transform
from ids_peak_icv.datatypes.image import Image, _check_and_get_icv_image
from ids_peak_common.datatypes.pixelformat import PixelFormat
from ids_peak_common.datatypes.geometry.size import Size
 
# Note: We loose type info here, as it is stored as a pointer to a python object
ImageArray: TypeAlias = npt.NDArray[np.object_]
 
 
class HDRAlgorithm(Enum):
    """!
    @brief
    Specifies the HDR reconstruction algorithm.
 
    Defines the algorithm used to reconstruct a High Dynamic Range (HDR) image
    from multiple input images captured with different exposure settings.
 
    @note
       Currently, only the Debevec HDR reconstruction algorithm is supported.
       Additional algorithms may be introduced in future releases.
 
    @ingroup ids_peak_icv_python_hdr
    @since ids_peak_icv 1.2
    """
 
    DEBEVEC = 0
    """!
    @brief
    Debevec HDR reconstruction algorithm.
 
    Uses the method proposed by Debevec and Malik to estimate the camera
    response curve (CRC) and combine multiple exposures into an HDR image.
    
    @since ids_peak_icv 1.2
    """
 
 
class HDR:
    """!
    @brief
    Performs High Dynamic Range (HDR) image reconstruction.
 
    This class provides functionality to generate a High Dynamic Range (HDR)
    image from a set of input images captured with different exposure settings.
    The input images are expected to depict the same scene while varying exactly
    one parameter: either the exposure time OR the gain.
 
    Internally, the HDR reconstruction is performed using the Debevec algorithm.
    A key part of this process is determining the *Camera Response Curve* (CRC),
    which maps digital pixel values to relative radiance.
    The algorithm is fixed at construction time.
 
    ### Typical usage
    - Create an `HDR` object
    - Optionally calculating the response curve using ``estimate_response_curve()``
    - Generate the HDR image using `process()`
 
    @note
        All input images must have
        the **same resolution**,
        the **same pixel format**
        and being captured from an **identical viewpoint of the same scene**
        without any change in camera position or scene content.
        Any mismatch may lead to invalid HDR reconstruction results.
 
    ### Limitations
    - All input images must be compatible (same resolution, pixel format, and scene)
    - At least two input images must be provided
    - Only the Debevec HDR 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 an HDR processing object.
 
        Creates and initializes an HDR object using the default HDR reconstruction
        algorithm (Debevec).
 
        @since ids_peak_icv 1.2
        """
        self._handle = peak_icv_hdr_handle()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_HDR_Create,
            ctypes.pointer(self._handle),
        )
 
    def __del__(self) -> None:
        """!
        @brief
        Destroys the HDR object and releases backend resources.
 
        @since ids_peak_icv 1.2
        """
        if hasattr(self, "_handle") and self._handle:
            lib_loader.dll().peak_icv_HDR_Destroy(self._handle)
 
    @property
    def algorithm(self) -> HDRAlgorithm:
        """!
        @brief
        Returns the HDR algorithm used by this object.
 
        The algorithm is defined at construction time and determines how
        the input images are combined during HDR reconstruction.
 
        @return The HDR algorithm identifier.
 
        @since ids_peak_icv 1.2
        """
        algorithm = ctypes.c_int()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_HDR_GetAlgorithm,
            self._handle,
            ctypes.pointer(algorithm),
        )
        return HDRAlgorithm(algorithm.value)
 
    def estimate_response_curve(self, images: ImageArray) -> None:
        """!
        @brief
        Estimates the *Camera Response Curve* (CRC) from a set of input images.
 
        This method calculates the response characteristics of the camera sensor.
        The CRC defines the relationship between
        scene radiance and the measured pixel values.
 
        All input images must meet the following conditions:
        - Represent the same scene.
        - Be compatible in size and pixel format.
        - Contain valid metadata for either exposure time or gain,
          and the values for the chosen parameter must vary across the given images
          (e.g., `ids_peak_common.datatype.MetadataKey.DeviceExposureTime` or
          `ids_peak_common.datatype.MetadataKey.DeviceGain`).
 
        Performing this estimation step explicitly can significantly reduce the processing
        time of subsequent calls to ``process()``, as the curve does not need to be
        re-calculated.
 
        If this method is not called, the response curve is estimated automatically
        during the first call to ``process()``.
 
        @supportedPixelformats{HDR}
 
        @param images:
            Images of the same scene with different exposure time or gain metadata.
            Must not be empty.
 
        @since ids_peak_icv 1.3
        """
        if not isinstance(images, np.ndarray):
            raise NotSupportedException(
                "Parameter images has to be a numpy array of ids_peak_icv or ids_peak_ipl images.")
 
        _images = []
        for image in images:
            _images.append(_check_and_get_icv_image(image))
 
        image_handles = create_array(peak_icv_image_handle, len(_images))
        transform(_images, image_handles, lambda image: image._handle)
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_HDR_EstimateResponseCurve,
            self._handle,
            image_handles,
            ctypes.c_size_t(len(image_handles)),
        )
 
    def process(self, images: ImageArray) -> Image:
        """!
        @brief
        Generates an HDR image from the specified input images.
 
        Processes the provided images and combines them into a single HDR image.
 
        All input images must meet the following conditions:
        - Represent the same scene.
        - Be compatible in size and pixel format.
        - Contain valid metadata for either exposure time or gain,
          and the values for the chosen parameter must vary across the given images
          (e.g., `ids_peak_common.datatype.MetadataKey.DeviceExposureTime` or
          `ids_peak_common.datatype.MetadataKey.DeviceGain`).
 
        If the camera response curve has not been explicitly estimated
        using ``estimate_response_curve()``,
        an internal estimation step is performed automatically
        when it is first called.
        This may increase the overall processing time for the first call.
 
        @supportedPixelformats{HDR}
 
        @param images:
            Images of the same scene with different exposure time or gain metadata.
            Must not be empty.
 
        @return
            The resulting HDR image with pixel format Mono32fIDS resp. RGB32fIDS.
 
        @since ids_peak_icv 1.2
        """
        if not isinstance(images, np.ndarray):
            raise NotSupportedException(
                "Parameter images has to be a numpy array of ids_peak_icv images.")
 
        _images = []
        for image in images:
            _images.append(_check_and_get_icv_image(image))
 
        image_handles = create_array(peak_icv_image_handle, len(images))
        transform(images, image_handles, lambda image: image._handle)
 
        # Query output pixel format
        output_pixel_format = ctypes.c_uint()
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_HDR_Process_GetOutputPixelFormat,
            self._handle,
            ctypes.c_uint(images[0].pixel_format.value),
            ctypes.pointer(output_pixel_format),
        )
 
        output_image = Image.create_from_pixel_format_and_size(
            PixelFormat(output_pixel_format.value),
            Size(images[0].width, images[0].height),
        )
 
        execute_and_map_return_codes(
            lib_loader.dll().peak_icv_HDR_Process,
            self._handle,
            image_handles,
            ctypes.c_size_t(len(image_handles)),
            output_image._handle,
        )
 
        return output_image