xyz_image.py

Go to the documentation of this file.

from __future__ import annotations
 
import ctypes
from typing import Any, TYPE_CHECKING
 
from ids_peak_common.datatypes.geometry.size import Size
from ids_peak_common.datatypes.pixelformat import PixelFormat
from ids_peak_icv import lib_loader
from ids_peak_icv.backend.datatypes import peak_icv_image_handle, peak_common_size
from ids_peak_icv.backend.utils import execute_and_map_return_codes
from ids_peak_icv.datatypes.image import Image
from ids_peak_icv.exceptions import NotPossibleException
 
if TYPE_CHECKING:
    from ids_peak_icv.datatypes.undistorted_image import UndistortedImage
    from ids_peak_icv.calibration.extrinsic_parameters import ExtrinsicParameters
 
 
class XYZImage(Image):
    """!
    @brief
    Represents a three-channel image encoding cartesian coordinates (x, y, z) of a 3D point.
 
    This image is derived from an undistorted depth map
    that contains embedded intrinsic parameters and uses radial coordinates.
 
    In contrast to radial coordinates,
    which measure the direct distance from the optical center to the object,
    cartesian coordinates project these measurements onto a uniform plane.
 
    For example:
    If the camera faces a flat wall,
    only the cartesian coordinates will form a flat plane,
    whereas radial values will increase towards the image edges.
 
    @ingroup ids_peak_icv_python_types
    @since ids_peak_icv 1.1
    """
 
    @classmethod
    def create_from_undistorted_image(cls, undistorted_depth_map: UndistortedImage) -> XYZImage:
        """!
        @brief
        Constructs a cartesian coordinate image from an undistorted depth map.
 
        To convert a distorted depth map into the required format,
        use the `Undistortion` class beforehand.
 
        @supportedPixelformats{XYZImageTransformer}
 
        @param undistorted_depth_map:
            An image encoding radial distances to 3D points
            that contains embedded intrinsic camera parameters.
 
        @since ids_peak_icv 1.1
        """
        return cls(_undistorted_depth_map=undistorted_depth_map)
 
    def __init__(self, *args: Any, **kwargs: Any) -> None:
        """!
        @brief
        In order to create a xyz image, please refer to the class methods.
 
        @since ids_peak_icv 1.1
        """
        if "_undistorted_depth_map" in kwargs:
            image = Image.create_from_pixel_format_and_size(PixelFormat.COORD3D_ABC32F,
                                                            Size(kwargs["_undistorted_depth_map"].width,
                                                                 kwargs["_undistorted_depth_map"].height))
            super().__init__(_handle=image._handle)
            image._handle = peak_icv_image_handle(None)  # necessary to ensure only one handle delete call
 
            execute_and_map_return_codes(lib_loader.dll().peak_icv_Transform_DepthMap_To_XYZImage,
                                         self._handle_handle_handle,
                                         kwargs["_undistorted_depth_map"].intrinsic_parameters._parameters,
                                         ctypes.sizeof(
                                             kwargs["_undistorted_depth_map"].intrinsic_parameters._parameters),
                                         kwargs["_undistorted_depth_map"]._handle)
        elif "_handle" in kwargs:
            super().__init__(_handle=kwargs["_handle"])
        else:
            raise NotPossibleException(
                "Cannot initialize {} with __init__. Please use a classmethod.".format(self.__class__.__name__))
 
    def transform_to_workspace(self, extrinsic_parameters: ExtrinsicParameters) -> XYZImage:
        """!
        @brief
        Transforms the camera-centric coordinates into workspace coordinates.
 
        This applies the inverse of the provided extrinsic matrix
        to map the 3D points
        from the camera's perspective
        into the physical workspace.
 
        @param extrinsic_parameters:
            Extrinsic parameters from the workspace calibration.
 
        @since ids_peak_icv 1.1
        """
        output_handle = peak_icv_image_handle()
        image_size = peak_common_size(self._size.width, self._size.height)
 
        execute_and_map_return_codes(lib_loader.dll().peak_icv_Image_Create,
                                     ctypes.pointer(output_handle),
                                     ctypes.c_int(PixelFormat.COORD3D_ABC32F.value),
                                     image_size)
        execute_and_map_return_codes(lib_loader.dll().peak_icv_Image_TransformToWorkspace,
                                     self._handle_handle_handle,
                                     extrinsic_parameters._parameters, ctypes.sizeof(extrinsic_parameters._parameters),
                                     output_handle)
 
        return XYZImage(_handle=output_handle)