antioch-py 2.2.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

common/message/image.py

@@ -3,13 +3,30 @@ from __future__ import annotations
 from enum import Enum
 
 import numpy as np
+from foxglove.schemas import RawImage as FoxgloveRawImage
+from pydantic import Field
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class ImageEncoding(str, Enum):
     """
     Image encodings with associated metadata.
+
+    Example:
+        ```python
+        from common.message import ImageEncoding
+
+        # Get bytes per pixel for an encoding
+        encoding = ImageEncoding.RGB8
+        bpp = encoding.bytes_per_pixel  # 3
+
+        # Get numpy dtype for an encoding
+        dtype = encoding.numpy_dtype  # np.uint8
+
+        # Get number of channels
+        channels = encoding.channels  # 3
+        ```
     """
 
     # Monochrome images
@@ -92,17 +109,31 @@ 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.
+    Example:
+        ```python
+        from common.message import Image, ImageEncoding
+        import numpy as np
+
+        # Create an image from a numpy array
+        rgb_array = np.zeros((480, 640, 3), dtype=np.uint8)
+        rgb_array[:, :, 0] = 255  # Red channel
+        image = Image.from_numpy(rgb_array, ImageEncoding.RGB8)
+
+        # Convert back to numpy for processing
+        array = image.to_numpy()
+        print(f"Shape: {array.shape}")  # (480, 640, 3)
+
+        # Create a depth image
+        depth_array = np.ones((480, 640), dtype=np.float32) * 2.5
+        depth_image = Image.from_numpy(depth_array, ImageEncoding.DEPTH_F32)
+        ```
     """
 
     _type = "antioch/image"
-    encoding: ImageEncoding
-    width: int
-    height: int
-    data: bytes
+    encoding: ImageEncoding = Field(description="Pixel encoding format of the image")
+    width: int = Field(description="Image width in pixels")
+    height: int = Field(description="Image height in pixels")
+    data: bytes = Field(description="Raw image data as bytes")
 
     @classmethod
     def from_numpy(cls, array: np.ndarray, encoding: ImageEncoding | None = None) -> Image:
@@ -169,3 +200,21 @@ class Image(Message):
         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)
+
+    def to_foxglove(self) -> FoxgloveRawImage:
+        """
+        Convert to Foxglove RawImage for telemetry.
+
+        :return: Foxglove RawImage schema.
+        """
+
+        step = self.width * self.encoding.bytes_per_pixel
+        return FoxgloveRawImage(
+            timestamp=None,
+            frame_id="",
+            width=self.width,
+            height=self.height,
+            encoding=self.encoding.value,
+            step=step,
+            data=self.data,
+        )

common/message/imu.py

@@ -1,4 +1,6 @@
-from common.message.base import Message
+from pydantic import Field
+
+from common.message.message import Message
 from common.message.quaternion import Quaternion
 from common.message.vector import Vector3
 
@@ -6,9 +8,27 @@ from common.message.vector import Vector3
 class ImuSample(Message):
     """
     IMU sensor sample data.
+
+    Contains linear acceleration, angular velocity, and orientation from an
+    inertial measurement unit sensor.
+
+    Example:
+        ```python
+        from common.message import ImuSample, Vector3, Quaternion
+
+        # Create an IMU sample
+        sample = ImuSample(
+            linear_acceleration=Vector3(x=0.0, y=0.0, z=9.81),  # Gravity
+            angular_velocity=Vector3(x=0.01, y=0.0, z=0.0),
+            orientation=Quaternion.identity(),
+        )
+
+        # Access acceleration components
+        accel_z = sample.linear_acceleration.z
+        ```
     """
 
     _type = "antioch/imu_sample"
-    linear_acceleration: Vector3
-    angular_velocity: Vector3
-    orientation: Quaternion
+    linear_acceleration: Vector3 = Field(description="Linear acceleration in m/s² (x, y, z)")
+    angular_velocity: Vector3 = Field(description="Angular velocity in rad/s (x, y, z)")
+    orientation: Quaternion = Field(description="Orientation as quaternion (w, x, y, z)")

common/message/joint.py

@@ -1,4 +1,6 @@
-from common.message.base import Message
+from pydantic import Field
+
+from common.message.message import Message
 
 
 class JointState(Message):
@@ -7,12 +9,27 @@ class JointState(Message):
 
     Represents the complete physical state of a joint including its position,
     velocity, and measured effort (force/torque).
+
+    Example:
+        ```python
+        from common.message import JointState
+
+        # Create a joint state
+        state = JointState(
+            name="shoulder_pan",
+            position=1.57,
+            velocity=0.1,
+            effort=5.0,
+        )
+        print(f"{state.name}: pos={state.position:.2f} rad")
+        ```
     """
 
     _type = "antioch/joint_state"
-    position: float
-    velocity: float
-    effort: float
+    name: str = Field(description="Name of the joint")
+    position: float = Field(description="Joint position in radians")
+    velocity: float = Field(description="Joint velocity in radians per second")
+    effort: float = Field(description="Joint effort (force/torque) in Nm")
 
 
 class JointTarget(Message):
@@ -20,28 +37,70 @@ 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.
+    PD controller. The name field is required to identify which joint is being
+    targeted. Position, velocity, and effort are optional - omitted values are
+    not controlled.
+
+    Example:
+        ```python
+        from common.message import JointTarget
+
+        # Position control target
+        target = JointTarget(name="elbow", position=0.5)
+
+        # Velocity control target
+        vel_target = JointTarget(name="wrist", velocity=0.2)
+
+        # Combined position and velocity target
+        combined = JointTarget(name="shoulder", position=1.0, velocity=0.1)
+        ```
     """
 
     _type = "antioch/joint_target"
-    position: float | None = None
-    velocity: float | None = None
-    effort: float | None = None
+    name: str = Field(description="Name of the joint to control")
+    position: float | None = Field(default=None, description="Target position in radians")
+    velocity: float | None = Field(default=None, description="Target velocity in radians per second")
+    effort: float | None = Field(default=None, description="Target effort (force/torque) in Nm")
 
 
 class JointStates(Message):
     """
     Collection of joint states for an actuator group.
+
+    Example:
+        ```python
+        from common.message import JointStates, JointState
+
+        # Create states for a robot arm
+        states = JointStates(states=[
+            JointState(name="joint1", position=0.0, velocity=0.0, effort=0.0),
+            JointState(name="joint2", position=1.57, velocity=0.1, effort=2.5),
+        ])
+
+        for state in states.states:
+            print(f"{state.name}: {state.position:.2f} rad")
+        ```
     """
 
     _type = "antioch/joint_states"
-    states: list[JointState]
+    states: list[JointState] = Field(description="List of joint states")
 
 
 class JointTargets(Message):
     """
     Collection of joint targets for an actuator group.
+
+    Example:
+        ```python
+        from common.message import JointTargets, JointTarget
+
+        # Create targets for multiple joints
+        targets = JointTargets(targets=[
+            JointTarget(name="joint1", position=0.5),
+            JointTarget(name="joint2", position=1.0),
+        ])
+        ```
     """
 
     _type = "antioch/joint_targets"
-    targets: list[JointTarget]
+    targets: list[JointTarget] = Field(description="List of joint targets")

common/message/log.py

@@ -1,14 +1,24 @@
 import time
 from enum import Enum
 
+from foxglove.schemas import Log as FoxgloveLog, LogLevel as FoxgloveLogLevel
 from pydantic import Field
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class LogLevel(str, Enum):
     """
     Log level.
+
+    Example:
+        ```python
+        from common.message import LogLevel
+
+        level = LogLevel.INFO
+        if level == LogLevel.ERROR:
+            print("Error occurred")
+        ```
     """
 
     DEBUG = "debug"
@@ -20,12 +30,47 @@ class LogLevel(str, Enum):
 class Log(Message):
     """
     Log entry structure.
+
+    Example:
+        ```python
+        from common.message import Log, LogLevel
+
+        # Create a log entry
+        log = Log(
+            let_us=1000000,
+            level=LogLevel.INFO,
+            message="Robot initialized successfully",
+            channel="robot.init",
+        )
+        ```
     """
 
     _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
+    timestamp_us: int = Field(default_factory=lambda: int(time.time_ns() // 1000), description="Wall clock timestamp in microseconds")
+    let_us: int = Field(description="Logical event time in microseconds")
+    level: LogLevel = Field(description="Log severity level")
+    message: str | None = Field(default=None, description="Log message text")
+    channel: str | None = Field(default=None, description="Log channel/category")
+    telemetry: bytes | None = Field(default=None, description="Optional serialized telemetry data")
+
+    def to_foxglove(self) -> FoxgloveLog:
+        """
+        Convert to Foxglove Log for telemetry.
+
+        :return: Foxglove Log schema.
+        """
+
+        level_map = {
+            LogLevel.DEBUG: FoxgloveLogLevel.Debug,
+            LogLevel.INFO: FoxgloveLogLevel.Info,
+            LogLevel.WARNING: FoxgloveLogLevel.Warning,
+            LogLevel.ERROR: FoxgloveLogLevel.Error,
+        }
+        return FoxgloveLog(
+            timestamp=None,
+            level=level_map[self.level],
+            message=self.message or "",
+            name=self.channel or "",
+            file="",
+            line=0,
+        )

common/message/pir.py

@@ -1,18 +1,33 @@
 from pydantic import Field
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class PirStatus(Message):
     """
     PIR sensor status containing detection state and signal information.
+
+    Passive Infrared (PIR) sensors detect motion by measuring changes in
+    infrared radiation in their field of view.
+
+    Example:
+        ```python
+        from common.message import PirStatus
+
+        # Create a PIR status
+        status = PirStatus(
+            is_detected=True,
+            signal_strength=0.85,
+            threshold=0.5,
+        )
+
+        # Check for motion
+        if status.is_detected:
+            print(f"Motion detected! Signal: {status.signal_strength}")
+        ```
     """
 
     _type = "antioch/pir_status"
-    is_detected: bool = Field(description="Whether motion is currently detected (aggregated across all sensors)")
-    signal_strength: float = Field(description="Max absolute signal strength across all sensors")
-
-    # Multi-sensor status
-    sensor_states: list[bool] = Field(default_factory=list, description="Detection state per sensor (Center, Left, Right)")
-    sensor_signals: list[float] = Field(default_factory=list, description="Signal strength per sensor")
-    sensor_thresholds: list[float] = Field(default_factory=list, description="Detection threshold per sensor")
+    is_detected: bool = Field(description="Whether motion is currently detected")
+    signal_strength: float = Field(description="Analog signal strength [0.0, 1.0]")
+    threshold: float = Field(description="Detection threshold [0.0, 1.0]")

common/message/plot.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from common.message.message import Message
+
+
+class PlotData(Message):
+    """
+    Simple X/Y plot data for Foxglove visualization.
+
+    Use with Foxglove's Plot panel by selecting:
+    - X: .x[:]
+    - Y: .y[:]
+
+    Example:
+        ```python
+        from common.message import PlotData
+        import numpy as np
+
+        distances = np.linspace(0, 10, 128)
+        values = np.random.rand(128)
+
+        plot = PlotData.from_arrays(distances, values)
+        sim.logger.telemetry("radar/mti/radar_left", plot)
+        ```
+    """
+
+    _type = "antioch/plot_data"
+
+    x: list[float] = Field(default_factory=list, description="X-axis values")
+    y: list[float] = Field(default_factory=list, description="Y-axis values")
+
+    @classmethod
+    def from_arrays(cls, x: Any, y: Any) -> PlotData:
+        """
+        Create PlotData from arrays or lists.
+
+        :param x: X values (numpy array or list).
+        :param y: Y values (numpy array or list).
+        :return: PlotData instance.
+        """
+
+        x_list = x.tolist() if hasattr(x, "tolist") else list(x)
+        y_list = y.tolist() if hasattr(y, "tolist") else list(y)
+        return cls(x=x_list, y=y_list)
+
+    def to_foxglove(self) -> dict[str, Any]:
+        """
+        Convert to Foxglove-compatible dict.
+
+        :return: Dict with x and y arrays.
+        """
+
+        return {"x": self.x, "y": self.y}

common/message/point.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
-from common.message.base import Message
+from foxglove.schemas import Point2 as FoxglovePoint2, Point3 as FoxglovePoint3
+from pydantic import Field
+
+from common.message.message import Message
 
 
 class Point2(Message):
@@ -8,11 +11,25 @@ class Point2(Message):
     A point representing a position in 2D space.
 
     Used in image annotations and 2D coordinate systems.
+
+    Example:
+        ```python
+        from common.message import Point2
+
+        # Create a 2D point
+        point = Point2(x=100.0, y=200.0)
+
+        # Create using factory method
+        origin = Point2.zero()
+
+        # Convert to Foxglove for visualization
+        foxglove_point = point.to_foxglove()
+        ```
     """
 
     _type = "antioch/point2"
-    x: float
-    y: float
+    x: float = Field(description="X coordinate")
+    y: float = Field(description="Y coordinate")
 
     def __repr__(self) -> str:
         """
@@ -54,18 +71,41 @@ class Point2(Message):
 
         return cls(x=0.0, y=0.0)
 
+    def to_foxglove(self) -> FoxglovePoint2:
+        """
+        Convert to Foxglove Point2 for telemetry.
+
+        :return: Foxglove Point2 schema.
+        """
+
+        return FoxglovePoint2(x=self.x, y=self.y)
+
 
 class Point3(Message):
     """
     A point representing a position in 3D space.
 
     Used in 3D graphics and spatial coordinate systems.
+
+    Example:
+        ```python
+        from common.message import Point3
+
+        # Create a 3D point
+        point = Point3(x=1.0, y=2.0, z=3.0)
+
+        # Create at origin
+        origin = Point3.zero()
+
+        # Create using factory method
+        p = Point3.new(x=0.5, y=1.0, z=0.0)
+        ```
     """
 
     _type = "antioch/point3"
-    x: float
-    y: float
-    z: float
+    x: float = Field(description="X coordinate")
+    y: float = Field(description="Y coordinate")
+    z: float = Field(description="Z coordinate")
 
     def __repr__(self) -> str:
         """
@@ -107,3 +147,12 @@ class Point3(Message):
         """
 
         return cls(x=0.0, y=0.0, z=0.0)
+
+    def to_foxglove(self) -> FoxglovePoint3:
+        """
+        Convert to Foxglove Point3 for telemetry.
+
+        :return: Foxglove Point3 schema.
+        """
+
+        return FoxglovePoint3(x=self.x, y=self.y, z=self.z)

common/message/point_cloud.py

@@ -1,25 +1,50 @@
 import struct
 
+from foxglove.schemas import (
+    PackedElementField,
+    PackedElementFieldNumericType as NumericType,
+    PointCloud as FoxglovePointCloud,
+    Pose as FoxglovePose,
+    Quaternion as FoxgloveQuaternion,
+    Vector3 as FoxgloveVector3,
+)
 from pydantic import Field, model_validator
 
-from common.message.base import Message
+from common.message.message 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.
+    Point clouds are used for representing 3D sensor data such as LiDAR
+    scans or depth camera point clouds.
+
+    Example:
+        ```python
+        from common.message import PointCloud
+
+        # Create a point cloud
+        cloud = PointCloud(
+            frame_id="lidar_link",
+            x=[1.0, 2.0, 3.0],
+            y=[0.5, 1.0, 1.5],
+            z=[0.1, 0.2, 0.3],
+        )
+
+        # Convert to Foxglove for visualization
+        foxglove_cloud = cloud.to_foxglove()
+
+        # Get packed bytes for transmission
+        data = cloud.to_bytes()
+        ```
     """
 
     _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")
+    frame_id: str = Field(default="", description="Frame of reference for the point cloud")
+    x: list[float] = Field(description="X coordinates of points in meters")
+    y: list[float] = Field(description="Y coordinates of points in meters")
+    z: list[float] = Field(description="Z coordinates of points in meters")
 
     @model_validator(mode="after")
     def validate_array_lengths(self) -> "PointCloud":
@@ -47,17 +72,28 @@ class PointCloud(Message):
 
         return bytes(data)
 
-    @staticmethod
-    def combine(point_clouds: list["PointCloud"], frame_id: str = "") -> "PointCloud":
+    def to_foxglove(self) -> FoxglovePointCloud:
         """
-        Combine multiple point clouds into a single point cloud.
+        Convert to Foxglove PointCloud for telemetry.
 
-        :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.
+        :return: Foxglove PointCloud schema.
         """
 
-        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)
+        # Pack point data as interleaved x, y, z floats
+        data = self.to_bytes()
+
+        return FoxglovePointCloud(
+            timestamp=None,
+            frame_id=self.frame_id,
+            pose=FoxglovePose(
+                position=FoxgloveVector3(x=0, y=0, z=0),
+                orientation=FoxgloveQuaternion(x=0, y=0, z=0, w=1),
+            ),
+            point_stride=12,  # 3 floats * 4 bytes
+            fields=[
+                PackedElementField(name="x", offset=0, type=NumericType.Float32),
+                PackedElementField(name="y", offset=4, type=NumericType.Float32),
+                PackedElementField(name="z", offset=8, type=NumericType.Float32),
+            ],
+            data=data,
+        )