antioch-py 2.0.6__py3-none-any.whl

common/message/color.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from pydantic import field_validator
+
+from common.message.base import Message
+
+
+class Color(Message):
+    """
+    An RGBA color with values in the range [0.0, 1.0].
+
+    Used in image annotations and visualization.
+    """
+
+    _type = "antioch/color"
+    r: float
+    g: float
+    b: float
+    a: float
+
+    @field_validator("r", "g", "b", "a")
+    @classmethod
+    def validate_range(cls, v: float) -> float:
+        """
+        Validate that color values are in the range [0.0, 1.0].
+
+        :param v: The color value to validate.
+        :return: The validated color value.
+        :raises ValueError: If the value is not in [0.0, 1.0].
+        """
+
+        if not 0.0 <= v <= 1.0:
+            raise ValueError(f"Color values must be in range [0.0, 1.0], got {v}")
+        return v
+
+    def __repr__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Color(r={self.r}, g={self.g}, b={self.b}, a={self.a})"
+
+    def __str__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Color(r={self.r}, g={self.g}, b={self.b}, a={self.a})"
+
+    @classmethod
+    def rgba(cls, r: float, g: float, b: float, a: float = 1.0) -> Color:
+        """
+        Create a color from RGBA values.
+
+        :param r: Red component [0.0, 1.0].
+        :param g: Green component [0.0, 1.0].
+        :param b: Blue component [0.0, 1.0].
+        :param a: Alpha component [0.0, 1.0]. Defaults to 1.0 (opaque).
+        :return: A Color instance.
+        """
+
+        return cls(r=r, g=g, b=b, a=a)
+
+    @classmethod
+    def rgb(cls, r: float, g: float, b: float) -> Color:
+        """
+        Create an opaque color from RGB values.
+
+        :param r: Red component [0.0, 1.0].
+        :param g: Green component [0.0, 1.0].
+        :param b: Blue component [0.0, 1.0].
+        :return: A Color instance with alpha = 1.0.
+        """
+
+        return cls(r=r, g=g, b=b, a=1.0)
+
+    @classmethod
+    def red(cls) -> Color:
+        """
+        Create a red color.
+
+        :return: Red color (1.0, 0.0, 0.0, 1.0).
+        """
+
+        return cls(r=1.0, g=0.0, b=0.0, a=1.0)
+
+    @classmethod
+    def green(cls) -> Color:
+        """
+        Create a green color.
+
+        :return: Green color (0.0, 1.0, 0.0, 1.0).
+        """
+
+        return cls(r=0.0, g=1.0, b=0.0, a=1.0)
+
+    @classmethod
+    def blue(cls) -> Color:
+        """
+        Create a blue color.
+
+        :return: Blue color (0.0, 0.0, 1.0, 1.0).
+        """
+
+        return cls(r=0.0, g=0.0, b=1.0, a=1.0)
+
+    @classmethod
+    def white(cls) -> Color:
+        """
+        Create a white color.
+
+        :return: White color (1.0, 1.0, 1.0, 1.0).
+        """
+
+        return cls(r=1.0, g=1.0, b=1.0, a=1.0)
+
+    @classmethod
+    def black(cls) -> Color:
+        """
+        Create a black color.
+
+        :return: Black color (0.0, 0.0, 0.0, 1.0).
+        """
+
+        return cls(r=0.0, g=0.0, b=0.0, a=1.0)
+
+    @classmethod
+    def transparent(cls) -> Color:
+        """
+        Create a transparent color.
+
+        :return: Transparent color (0.0, 0.0, 0.0, 0.0).
+        """
+
+        return cls(r=0.0, g=0.0, b=0.0, a=0.0)

common/message/frame.py

@@ -0,0 +1,50 @@
+from pydantic import Field
+
+from common.message.base import Message
+from common.message.quaternion import Quaternion
+from common.message.vector import Vector3
+
+
+class FrameTransform(Message):
+    """
+    A transform between two reference frames in 3D space.
+
+    :param parent_frame_id: Name of the parent frame.
+    :param child_frame_id: Name of the child frame.
+    :param translation: Translation component of the transform.
+    :param rotation: Rotation component of the transform.
+    """
+
+    _type = "antioch/frame_transform"
+    parent_frame_id: str = Field(description="Name of the parent frame")
+    child_frame_id: str = Field(description="Name of the child frame")
+    translation: Vector3 = Field(description="Translation component of the transform")
+    rotation: Quaternion = Field(description="Rotation component of the transform")
+
+    @classmethod
+    def identity(cls, parent_frame_id: str, child_frame_id: str) -> "FrameTransform":
+        """
+        Create an identity transform between two frames.
+
+        :param parent_frame_id: Name of the parent frame.
+        :param child_frame_id: Name of the child frame.
+        :return: Identity frame transform.
+        """
+
+        return cls(
+            parent_frame_id=parent_frame_id,
+            child_frame_id=child_frame_id,
+            translation=Vector3.zeros(),
+            rotation=Quaternion.identity(),
+        )
+
+
+class FrameTransforms(Message):
+    """
+    An array of FrameTransform messages.
+
+    :param transforms: Array of transforms.
+    """
+
+    _type = "antioch/frame_transforms"
+    transforms: list[FrameTransform] = Field(default_factory=list, description="Array of transforms")

common/message/image.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from enum import Enum
+
+import numpy as np
+
+from common.message.base import Message
+
+
+class ImageEncoding(str, Enum):
+    """
+    Image encodings with associated metadata.
+    """
+
+    # Monochrome images
+    MONO8 = "mono8"
+    MONO16 = "mono16"
+
+    # Color images
+    RGB8 = "rgb8"
+    RGBA8 = "rgba8"
+    BGR8 = "bgr8"
+    BGRA8 = "bgra8"
+
+    # Depth images
+    DEPTH_U16 = "16UC1"
+    DEPTH_F32 = "32FC1"
+
+    @property
+    def bytes_per_pixel(self) -> int:
+        """
+        Get the number of bytes per pixel for this encoding.
+
+        :return: The number of bytes per pixel.
+        """
+
+        return {
+            ImageEncoding.MONO8: 1,
+            ImageEncoding.MONO16: 2,
+            ImageEncoding.RGB8: 3,
+            ImageEncoding.RGBA8: 4,
+            ImageEncoding.BGR8: 3,
+            ImageEncoding.BGRA8: 4,
+            ImageEncoding.DEPTH_U16: 2,
+            ImageEncoding.DEPTH_F32: 4,
+        }[self]
+
+    @property
+    def numpy_dtype(self) -> np.dtype:
+        """
+        Get the numpy dtype for this encoding.
+
+        :return: The numpy dtype.
+        """
+
+        dtype_map = {
+            ImageEncoding.MONO8: np.uint8,
+            ImageEncoding.MONO16: np.uint16,
+            ImageEncoding.RGB8: np.uint8,
+            ImageEncoding.RGBA8: np.uint8,
+            ImageEncoding.BGR8: np.uint8,
+            ImageEncoding.BGRA8: np.uint8,
+            ImageEncoding.DEPTH_U16: np.uint16,
+            ImageEncoding.DEPTH_F32: np.float32,
+        }
+        return np.dtype(dtype_map[self])
+
+    @property
+    def channels(self) -> int:
+        """
+        Get the number of color channels.
+
+        :return: The number of color channels.
+        """
+
+        if self in (
+            ImageEncoding.MONO8,
+            ImageEncoding.MONO16,
+            ImageEncoding.DEPTH_U16,
+            ImageEncoding.DEPTH_F32,
+        ):
+            return 1
+        elif self in (ImageEncoding.RGB8, ImageEncoding.BGR8):
+            return 3
+        elif self in (ImageEncoding.RGBA8, ImageEncoding.BGRA8):
+            return 4
+        else:
+            return 1
+
+
+class Image(Message):
+    """
+    An image with raw data.
+
+    :param encoding: The encoding of the image.
+    :param width: The width of the image in pixels.
+    :param height: The height of the image in pixels.
+    :param data: The raw image data bytes.
+    """
+
+    _type = "antioch/image"
+    encoding: ImageEncoding
+    width: int
+    height: int
+    data: bytes
+
+    @classmethod
+    def from_numpy(cls, array: np.ndarray, encoding: ImageEncoding | None = None) -> Image:
+        """
+        Create an Image from a numpy array.
+
+        For uint8 encodings (RGB8, RGBA8, MONO8), pixel values should be in the range [0, 255].
+        For float32 depth encodings (DEPTH_F32), values are typically in meters.
+        For uint16 encodings (DEPTH_U16, MONO16), values use the full uint16 range.
+
+        If the array dtype doesn't match the encoding's dtype, it will be converted
+        via astype().
+
+        :param array: The numpy array containing image data.
+        :param encoding: The image encoding (auto-detected if None).
+        :return: An Image instance.
+        :raises ValueError: If array shape doesn't match a supported format.
+        """
+
+        # Auto-detect encoding based on array shape and dtype
+        if encoding is None:
+            if array.ndim == 2:
+                # Grayscale or depth
+                if array.dtype == np.uint8:
+                    encoding = ImageEncoding.MONO8
+                elif array.dtype == np.uint16:
+                    encoding = ImageEncoding.DEPTH_U16
+                elif array.dtype == np.float32:
+                    encoding = ImageEncoding.DEPTH_F32
+                else:
+                    raise ValueError(f"Unsupported dtype for 2D array: {array.dtype}")
+            elif array.ndim == 3:
+                # Color image
+                channels = array.shape[2]
+                if channels == 3:
+                    encoding = ImageEncoding.RGB8
+                elif channels == 4:
+                    encoding = ImageEncoding.RGBA8
+                else:
+                    raise ValueError(f"Unsupported number of channels: {channels}")
+            else:
+                raise ValueError(f"Unsupported array dimensions: {array.ndim}")
+
+        # Convert array dtype to match encoding if necessary
+        expected_dtype = encoding.numpy_dtype
+        if array.dtype != expected_dtype:
+            array = array.astype(expected_dtype)
+
+        # Standard packing (handles both contiguous and non-contiguous)
+        if array.ndim < 2:
+            raise ValueError(f"Image array must be at least 2D, got shape {array.shape}")
+        height, width = array.shape[:2]
+        data = array.tobytes()
+        return cls(encoding=encoding, width=width, height=height, data=data)
+
+    def to_numpy(self) -> np.ndarray:
+        """
+        Convert the image to a numpy array.
+
+        :return: A numpy array with the image data.
+        """
+
+        # Standard contiguous buffer
+        shape = (self.height, self.width) if self.encoding.channels == 1 else (self.height, self.width, self.encoding.channels)
+        array = np.frombuffer(self.data, dtype=self.encoding.numpy_dtype)
+        return array.reshape(shape)

common/message/imu.py

@@ -0,0 +1,14 @@
+from common.message.base import Message
+from common.message.quaternion import Quaternion
+from common.message.vector import Vector3
+
+
+class ImuSample(Message):
+    """
+    IMU sensor sample data.
+    """
+
+    _type = "antioch/imu_sample"
+    linear_acceleration: Vector3
+    angular_velocity: Vector3
+    orientation: Quaternion

common/message/joint.py

@@ -0,0 +1,47 @@
+from common.message.base import Message
+
+
+class JointState(Message):
+    """
+    State of a single joint.
+
+    Represents the complete physical state of a joint including its position,
+    velocity, and measured effort (force/torque).
+    """
+
+    _type = "antioch/joint_state"
+    position: float
+    velocity: float
+    effort: float
+
+
+class JointTarget(Message):
+    """
+    Control target for a single joint.
+
+    Specifies desired position, velocity, and/or effort targets for a joint's
+    PD controller. All fields are optional - omitted values are not controlled.
+    """
+
+    _type = "antioch/joint_target"
+    position: float | None = None
+    velocity: float | None = None
+    effort: float | None = None
+
+
+class JointStates(Message):
+    """
+    Collection of joint states for an actuator group.
+    """
+
+    _type = "antioch/joint_states"
+    states: list[JointState]
+
+
+class JointTargets(Message):
+    """
+    Collection of joint targets for an actuator group.
+    """
+
+    _type = "antioch/joint_targets"
+    targets: list[JointTarget]

common/message/log.py

@@ -0,0 +1,31 @@
+import time
+from enum import Enum
+
+from pydantic import Field
+
+from common.message.base import Message
+
+
+class LogLevel(str, Enum):
+    """
+    Log level.
+    """
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class Log(Message):
+    """
+    Log entry structure.
+    """
+
+    _type = "antioch/log"
+    timestamp_us: int = Field(default_factory=lambda: int(time.time_ns() // 1000))
+    let_us: int
+    level: LogLevel
+    message: str | None = None
+    channel: str | None = None
+    telemetry: bytes | None = None

common/message/pir.py

@@ -0,0 +1,16 @@
+from pydantic import Field
+
+from common.message.base import Message
+
+
+class PirStatus(Message):
+    """
+    PIR sensor status containing detection state and signal information.
+    """
+
+    _type = "antioch/pir_status"
+    is_detected: bool = Field(description="Whether motion is currently detected")
+    signal_strength: float = Field(description="Current analog signal value after filtering")
+    threshold: float = Field(description="Current detection threshold")
+    element_flux: list[float] = Field(default_factory=list, description="Raw accumulated IR flux per element")
+    element_signal: list[float] = Field(default_factory=list, description="Pyroelectric voltage signal per element (proportional to dT/dt)")

common/message/point.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from common.message.base import Message
+
+
+class Point2(Message):
+    """
+    A point representing a position in 2D space.
+
+    Used in image annotations and 2D coordinate systems.
+    """
+
+    _type = "antioch/point2"
+    x: float
+    y: float
+
+    def __repr__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Point2(x={self.x}, y={self.y})"
+
+    def __str__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Point2(x={self.x}, y={self.y})"
+
+    @classmethod
+    def new(cls, x: float, y: float) -> Point2:
+        """
+        Create a new 2D point.
+
+        :param x: The x coordinate.
+        :param y: The y coordinate.
+        :return: A 2D point.
+        """
+
+        return cls(x=x, y=y)
+
+    @classmethod
+    def zero(cls) -> Point2:
+        """
+        Create a point at the origin.
+
+        :return: A point at (0, 0).
+        """
+
+        return cls(x=0.0, y=0.0)
+
+
+class Point3(Message):
+    """
+    A point representing a position in 3D space.
+
+    Used in 3D graphics and spatial coordinate systems.
+    """
+
+    _type = "antioch/point3"
+    x: float
+    y: float
+    z: float
+
+    def __repr__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Point3(x={self.x}, y={self.y}, z={self.z})"
+
+    def __str__(self) -> str:
+        """
+        Return a readable string representation.
+
+        :return: String representation.
+        """
+
+        return f"Point3(x={self.x}, y={self.y}, z={self.z})"
+
+    @classmethod
+    def new(cls, x: float, y: float, z: float) -> Point3:
+        """
+        Create a new 3D point.
+
+        :param x: The x coordinate.
+        :param y: The y coordinate.
+        :param z: The z coordinate.
+        :return: A 3D point.
+        """
+
+        return cls(x=x, y=y, z=z)
+
+    @classmethod
+    def zero(cls) -> Point3:
+        """
+        Create a point at the origin.
+
+        :return: A point at (0, 0, 0).
+        """
+
+        return cls(x=0.0, y=0.0, z=0.0)

common/message/point_cloud.py

@@ -0,0 +1,63 @@
+import struct
+
+from pydantic import Field, model_validator
+
+from common.message.base import Message
+
+
+class PointCloud(Message):
+    """
+    A collection of 3D points.
+
+    :param frame_id: Frame of reference.
+    :param x: X coordinates of points.
+    :param y: Y coordinates of points.
+    :param z: Z coordinates of points.
+    """
+
+    _type = "antioch/point_cloud"
+    frame_id: str = Field(default="", description="Frame of reference")
+    x: list[float] = Field(description="X coordinates of points")
+    y: list[float] = Field(description="Y coordinates of points")
+    z: list[float] = Field(description="Z coordinates of points")
+
+    @model_validator(mode="after")
+    def validate_array_lengths(self) -> "PointCloud":
+        """
+        Validate that all coordinate arrays have the same length.
+        """
+
+        lengths = [len(self.x), len(self.y), len(self.z)]
+
+        if len(set(lengths)) > 1:
+            raise ValueError(f"All coordinate arrays must have the same length: x={len(self.x)}, y={len(self.y)}, z={len(self.z)}")
+
+        return self
+
+    def to_bytes(self) -> bytes:
+        """
+        Pack point cloud data into bytes for Foxglove.
+
+        :return: Packed data with x, y, z for each point.
+        """
+
+        data = bytearray()
+        for i in range(len(self.x)):
+            data.extend(struct.pack("<fff", self.x[i], self.y[i], self.z[i]))
+
+        return bytes(data)
+
+    @staticmethod
+    def combine(point_clouds: list["PointCloud"], frame_id: str = "") -> "PointCloud":
+        """
+        Combine multiple point clouds into a single point cloud.
+
+        :param point_clouds: List of point clouds to combine.
+        :param frame_id: Frame of reference for the combined point cloud.
+        :return: Combined point cloud with all points.
+        """
+
+        all_x = sum((pc.x for pc in point_clouds), [])
+        all_y = sum((pc.y for pc in point_clouds), [])
+        all_z = sum((pc.z for pc in point_clouds), [])
+        return PointCloud(frame_id=frame_id, x=all_x, y=all_y, z=all_z)