metadata_key.py

Go to the documentation of this file.

from dataclasses import dataclass
from enum import Enum
from typing import Type, Any
 
from ids_peak_common.datatypes.geometry.rectangle import Rectangle
 
 
@dataclass(frozen=True)
class _MetadataKeyInfo:
    string_value: str
    type: Type[Any]
 
 
class MetadataKey(Enum):
    """!
    @brief
    Enumerates all compile-time known metadata keys.
 
    Each enum value carries both:
    - A string identifier (used internally in Metadata).
    - The expected Python type of its value.
 
    This makes it easy to use type-safe keys without an extra trait class.
 
    Example::
 
        key = MetadataKey.DEVICE_TIMESTAMP
        print(key.string_value) # outputs: device_timestamp
        print(key.type) # outputs: <class 'int'>
 
    @ingroup ids_peak_common_python_types
    """
 
    DEVICE_TIMESTAMP = _MetadataKeyInfo("DeviceTimestamp", int)
    """!
    @brief
    Device-provided image acquisition timestamp in nanoseconds.
 
    The timestamp is expressed in nanoseconds and is relative to an
    unspecified reference point (t = 0). It does not represent an
    absolute wall-clock time, but instead the elapsed time since
    that reference. The difference between timestamps of consecutive
    images indicates the time interval between their recordings.
    """
 
    DEVICE_FRAME_ID = _MetadataKeyInfo("DeviceFrameID", int)
    """!
    @brief
    A sequentially incremented identifier for the frame.
 
    The frame ID is a sequentially incremented value that increases by one
    from one frame to the next. It serves as a means to detect missing or
    out-of-order frames in a stream. Once the maximum value supported by
    the underlying technology is reached, the frame ID wraps back to zero.
    The exact wrap-around point is not fixed and depends on the implementation.
    """
 
    BINNING_HORIZONTAL = _MetadataKeyInfo("BinningHorizontal", int)
    """!
    @brief
    Horizontal pixel binning factor.
 
    Indicates how many adjacent pixels are combined horizontally.
    """
 
    BINNING_VERTICAL = _MetadataKeyInfo("BinningVertical", int)
    """!
    @brief
    Vertical pixel binning factor.
 
    Indicates how many adjacent pixels are combined vertically.
    """
 
    ROI = _MetadataKeyInfo("Roi", Rectangle)
    """!
    @brief
    Region of interest applied to the image.
 
    Defines the rectangular area of the image that remains after
    processing steps such as cropping or scaling were applied.
    Coordinates and dimensions are expressed in pixels.
    """
 
    DEVICE_EXPOSURE_TIME = _MetadataKeyInfo("DeviceExposureTime", float)
    """!
    @brief
    Device exposure time the image was captured with.
 
    Specified in microseconds (µs).
    """
 
    SYSTEM_TIMESTAMP = _MetadataKeyInfo("SystemTimestamp", int)
    """!
    @brief
    Timestamp of the system since unix epoch in nanoseconds.
 
    Provides the system timestamp corresponding to the device timestamp,
    expressed as nanoseconds since the Unix epoch (00:00:00 UTC on January 1, 1970).
    This allows data to be associated with a system time, for example
    for logging or correlating with other system events.
    
    The system timestamp is not intended for high-precision timing due to
    device-side timestamping and host processing delays. For applications
    requiring high timing accuracy, use the DeviceTimestamp directly.
    """
 
    DEVICE_EXPOSURE_TIME_SEQUENCE = _MetadataKeyInfo("DeviceExposureTimeSequence", list[float])
    """!
    @brief
    Device exposure time sequence the image was captured with.
    
    This feature applies exclusively to HDR pixel formats
    where multiple exposures are acquired within a single image frame.
    During unpacking, the individual exposures are separated into distinct images,
    and the corresponding exposure time for each image is written to DEVICE_EXPOSURE_TIME
 
    Specified in microseconds (µs).
    
    @since ids_peak_common 1.3
    """
 
    DEVICE_GAIN = _MetadataKeyInfo("DeviceGain", float)
    """!
    @brief
    Device gain the image was captured with.
    """
 
    DEVICE_GAIN_SEQUENCE = _MetadataKeyInfo("DeviceGainSequence", list[float])
    """!
    @brief
    Device gain sequence the image was captured with.
    
    This feature applies exclusively to HDR pixel formats
    where multiple gains are used for acquisition within a single image frame.
    During unpacking, the individual gains are separated into distinct images,
    and the corresponding gain for each image is written to DEVICE_GAIN
    """
 
    @property
    def string_value(self) -> str:
        """!
        @brief Return the string_value for this metadata key."""
        return self.value.string_value
 
    @property
    def type(self) -> Type[Any]:
        """!
        @brief Return the expected Python type for this metadata key."""
        return self.value.type
 
    def __str__(self) -> str:
        """!
        @brief
        Return a human-readable string of the MetadataKey object.
        """
        return f"{self.string_value} ({self.type.__name__})"
 
    def __repr__(self) -> str:
        """!
        @brief
        Return an unambiguous string of the MetadataKey object.
        """
        return (f"{self.__class__.__name__}.{self.name}"
                f"(string_value={self.value.string_value!r}, "
                f"type={self.value.type!r})")