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 function and combine multiple exposures into an HDR image.
    """
 
 
class HDR:
    """!
    @brief
    Performs High Dynamic Range (HDR) image reconstruction.
 
    This class combines multiple images of the same scene captured with
    different exposure settings into a single HDR image.
 
    Internally, the Debevec algorithm is used.
    The algorithm is fixed at construction time.
 
    ### Typical usage
    - Create an HDR object
    - Optionally call :meth:`calibrate`
    - Call :meth:`process` to generate the HDR image
 
    @ingroup ids_peak_icv_python_hdr
    @since ids_peak_icv 1.2
    """
 
    def __init__(self, *args: Any, **kwargs: Any) -> None:
        """!
        @brief
       Creates an HDR processing object using the default HDR algorithm.
 
       @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
        @return
            The HDR reconstruction algorithm used by this object.
 
        @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 calibrate(self, images: ImageArray) -> None:
        """!
        @brief
        Performs an optional HDR calibration step.
 
        Calibration estimates camera response characteristics and may
        reduce processing time when calling :meth:`process`.
 
        @param images:
            Images of the same scene with different exposure settings.
            Must not be empty.
 
        @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 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_Calibrate,
            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.
 
        If the HDR object was not explicitly calibrated using
        :meth:`calibrate`, calibration is performed implicitly.
 
        @param images:
            Images of the same scene with different exposure settings.
            All input images must contain exposure time metadata.
            Must not be empty.
 
        @return
            The resulting HDR image.
 
        @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