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

common/message/__init__.py

@@ -1,22 +1,32 @@
 from common.message.annotation import CircleAnnotation, ImageAnnotations, PointsAnnotation, PointsAnnotationType, TextAnnotation
 from common.message.array import Array
-from common.message.base import DeserializationError, Message, MessageError, MismatchError, SerializationError
 from common.message.camera import CameraInfo
 from common.message.color import Color
+from common.message.detection import DetectionDistances
+from common.message.foxglove import FoxgloveConvertible
 from common.message.frame import FrameTransform, FrameTransforms
 from common.message.image import Image, ImageEncoding
 from common.message.imu import ImuSample
 from common.message.joint import JointState, JointStates, JointTarget, JointTargets
 from common.message.log import Log, LogLevel
+from common.message.message import (
+    DeserializationError,
+    FileAccessError,
+    Message,
+    MessageError,
+    MismatchError,
+    SerializationError,
+)
 from common.message.pir import PirStatus
+from common.message.plot import PlotData
 from common.message.point import Point2, Point3
 from common.message.point_cloud import PointCloud
 from common.message.pose import Pose
 from common.message.quaternion import Quaternion
-from common.message.radar import RadarDetection, RadarScan
+from common.message.radar import RadarScan, RangeMap
+from common.message.twist import Twist
 from common.message.types import Bool, Float, Int, String
 from common.message.vector import Vector2, Vector3
-from common.message.velocity import Twist
 
 __all__ = [
     "Array",
@@ -25,7 +35,10 @@ __all__ = [
     "CircleAnnotation",
     "Color",
     "DeserializationError",
+    "DetectionDistances",
+    "FileAccessError",
     "Float",
+    "FoxgloveConvertible",
     "FrameTransform",
     "FrameTransforms",
     "Image",
@@ -43,6 +56,7 @@ __all__ = [
     "MessageError",
     "MismatchError",
     "PirStatus",
+    "PlotData",
     "Point2",
     "Point3",
     "PointCloud",
@@ -50,12 +64,12 @@ __all__ = [
     "PointsAnnotationType",
     "Pose",
     "Quaternion",
-    "RadarDetection",
     "RadarScan",
+    "RangeMap",
     "SerializationError",
     "String",
     "TextAnnotation",
+    "Twist",
     "Vector2",
     "Vector3",
-    "Twist",
 ]

common/message/annotation.py

@@ -2,14 +2,33 @@ from __future__ import annotations
 
 from enum import IntEnum
 
-from common.message.base import Message
+from foxglove.schemas import (
+    CircleAnnotation as FoxgloveCircleAnnotation,
+    Color as FoxgloveColor,
+    ImageAnnotations as FoxgloveImageAnnotations,
+    Point2 as FoxglovePoint2,
+    PointsAnnotation as FoxglovePointsAnnotation,
+    PointsAnnotationType as FoxglovePointsAnnotationType,
+    TextAnnotation as FoxgloveTextAnnotation,
+)
+from pydantic import Field
+
 from common.message.color import Color
+from common.message.message import Message
 from common.message.point import Point2
 
 
 class PointsAnnotationType(IntEnum):
     """
     Type of points annotation.
+
+    Example:
+        ```python
+        from common.message import PointsAnnotationType
+
+        # Use as enum value
+        annotation_type = PointsAnnotationType.LINE_STRIP
+        ```
     """
 
     UNKNOWN = 0
@@ -24,14 +43,29 @@ class CircleAnnotation(Message):
     A circle annotation on a 2D image.
 
     Coordinates use the top-left corner of the top-left pixel as the origin.
+
+    Example:
+        ```python
+        from common.message import CircleAnnotation, Point2, Color
+
+        # Create a circle annotation
+        circle = CircleAnnotation(
+            timestamp_us=1000000,
+            position=Point2(x=100.0, y=100.0),
+            diameter=50.0,
+            thickness=2.0,
+            fill_color=Color.transparent(),
+            outline_color=Color.red(),
+        )
+        ```
     """
 
-    timestamp_us: int
-    position: Point2
-    diameter: float
-    thickness: float
-    fill_color: Color
-    outline_color: Color
+    timestamp_us: int = Field(description="Timestamp in microseconds")
+    position: Point2 = Field(description="Center position of the circle")
+    diameter: float = Field(description="Diameter of the circle in pixels")
+    thickness: float = Field(description="Line thickness in pixels")
+    fill_color: Color = Field(description="Fill color of the circle")
+    outline_color: Color = Field(description="Outline color of the circle")
 
 
 class PointsAnnotation(Message):
@@ -39,15 +73,33 @@ class PointsAnnotation(Message):
     An array of points on a 2D image.
 
     Coordinates use the top-left corner of the top-left pixel as the origin.
+
+    Example:
+        ```python
+        from common.message import PointsAnnotation, PointsAnnotationType, Point2, Color
+
+        # Create a line strip annotation
+        annotation = PointsAnnotation(
+            timestamp_us=1000000,
+            type=PointsAnnotationType.LINE_STRIP,
+            points=[
+                Point2(x=10.0, y=10.0),
+                Point2(x=100.0, y=50.0),
+                Point2(x=150.0, y=100.0),
+            ],
+            outline_color=Color.green(),
+            thickness=2.0,
+        )
+        ```
     """
 
-    timestamp_us: int
-    type: PointsAnnotationType
-    points: list[Point2]
-    outline_color: Color
-    outline_colors: list[Color] | None = None
-    fill_color: Color | None = None
-    thickness: float
+    timestamp_us: int = Field(description="Timestamp in microseconds")
+    type: PointsAnnotationType = Field(description="Type of points annotation (points, line_strip, etc.)")
+    points: list[Point2] = Field(description="List of 2D points")
+    outline_color: Color = Field(description="Primary outline color")
+    outline_colors: list[Color] | None = Field(default=None, description="Per-point outline colors")
+    fill_color: Color | None = Field(default=None, description="Fill color for closed shapes")
+    thickness: float = Field(description="Line thickness in pixels")
 
 
 class TextAnnotation(Message):
@@ -56,14 +108,29 @@ class TextAnnotation(Message):
 
     Position uses the bottom-left origin of the text label.
     Coordinates use the top-left corner of the top-left pixel as the origin.
+
+    Example:
+        ```python
+        from common.message import TextAnnotation, Point2, Color
+
+        # Create a text annotation
+        text = TextAnnotation(
+            timestamp_us=1000000,
+            position=Point2(x=50.0, y=30.0),
+            text="Detection: Person",
+            font_size=14.0,
+            text_color=Color.white(),
+            background_color=Color.rgba(0.0, 0.0, 0.0, 0.5),
+        )
+        ```
     """
 
-    timestamp_us: int
-    position: Point2
-    text: str
-    font_size: float
-    text_color: Color
-    background_color: Color
+    timestamp_us: int = Field(description="Timestamp in microseconds")
+    position: Point2 = Field(description="Bottom-left position of the text label")
+    text: str = Field(description="Text content to display")
+    font_size: float = Field(description="Font size in pixels")
+    text_color: Color = Field(description="Color of the text")
+    background_color: Color = Field(description="Background color behind the text")
 
 
 class ImageAnnotations(Message):
@@ -71,12 +138,36 @@ class ImageAnnotations(Message):
     Array of annotations for a 2D image.
 
     Used in the Foxglove Image panel for visualization.
+
+    Example:
+        ```python
+        from common.message import ImageAnnotations, CircleAnnotation, Point2, Color
+
+        # Create an empty annotations container
+        annotations = ImageAnnotations.empty()
+
+        # Or create with annotations
+        annotations = ImageAnnotations(
+            circles=[
+                CircleAnnotation(
+                    timestamp_us=1000000,
+                    position=Point2(x=100.0, y=100.0),
+                    diameter=20.0,
+                    thickness=2.0,
+                    fill_color=Color.transparent(),
+                    outline_color=Color.red(),
+                ),
+            ],
+            points=[],
+            texts=[],
+        )
+        ```
     """
 
     _type = "antioch/image_annotations"
-    circles: list[CircleAnnotation]
-    points: list[PointsAnnotation]
-    texts: list[TextAnnotation]
+    circles: list[CircleAnnotation] = Field(description="Circle annotations")
+    points: list[PointsAnnotation] = Field(description="Points/line annotations")
+    texts: list[TextAnnotation] = Field(description="Text annotations")
 
     @classmethod
     def empty(cls) -> ImageAnnotations:
@@ -87,3 +178,63 @@ class ImageAnnotations(Message):
         """
 
         return cls(circles=[], points=[], texts=[])
+
+    def to_foxglove(self) -> FoxgloveImageAnnotations:
+        """
+        Convert to Foxglove ImageAnnotations for telemetry.
+
+        :return: Foxglove ImageAnnotations schema.
+        """
+
+        # Convert PointsAnnotationType to Foxglove type
+        type_map = {
+            PointsAnnotationType.UNKNOWN: FoxglovePointsAnnotationType.Unknown,
+            PointsAnnotationType.POINTS: FoxglovePointsAnnotationType.Points,
+            PointsAnnotationType.LINE_LOOP: FoxglovePointsAnnotationType.LineLoop,
+            PointsAnnotationType.LINE_STRIP: FoxglovePointsAnnotationType.LineStrip,
+            PointsAnnotationType.LINE_LIST: FoxglovePointsAnnotationType.LineList,
+        }
+
+        # Convert circles
+        circles = [
+            FoxgloveCircleAnnotation(
+                timestamp=None,
+                position=FoxglovePoint2(x=c.position.x, y=c.position.y),
+                diameter=c.diameter,
+                thickness=c.thickness,
+                fill_color=FoxgloveColor(r=c.fill_color.r, g=c.fill_color.g, b=c.fill_color.b, a=c.fill_color.a),
+                outline_color=FoxgloveColor(r=c.outline_color.r, g=c.outline_color.g, b=c.outline_color.b, a=c.outline_color.a),
+            )
+            for c in self.circles
+        ]
+
+        # Convert points annotations
+        points = [
+            FoxglovePointsAnnotation(
+                timestamp=None,
+                type=type_map[p.type],
+                points=[FoxglovePoint2(x=pt.x, y=pt.y) for pt in p.points],
+                outline_color=FoxgloveColor(r=p.outline_color.r, g=p.outline_color.g, b=p.outline_color.b, a=p.outline_color.a),
+                outline_colors=[FoxgloveColor(r=c.r, g=c.g, b=c.b, a=c.a) for c in p.outline_colors] if p.outline_colors else [],
+                fill_color=FoxgloveColor(r=p.fill_color.r, g=p.fill_color.g, b=p.fill_color.b, a=p.fill_color.a) if p.fill_color else None,
+                thickness=p.thickness,
+            )
+            for p in self.points
+        ]
+
+        # Convert text annotations
+        texts = [
+            FoxgloveTextAnnotation(
+                timestamp=None,
+                position=FoxglovePoint2(x=t.position.x, y=t.position.y),
+                text=t.text,
+                font_size=t.font_size,
+                text_color=FoxgloveColor(r=t.text_color.r, g=t.text_color.g, b=t.text_color.b, a=t.text_color.a),
+                background_color=FoxgloveColor(
+                    r=t.background_color.r, g=t.background_color.g, b=t.background_color.b, a=t.background_color.a
+                ),
+            )
+            for t in self.texts
+        ]
+
+        return FoxgloveImageAnnotations(circles=circles, points=points, texts=texts)

common/message/array.py

@@ -5,7 +5,7 @@ from typing import Any
 import numpy as np
 from pydantic import Field, PrivateAttr, model_validator
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class Array(Message):
@@ -27,6 +27,30 @@ class Array(Message):
         cmd = RobotCommand(joint_positions=[0.1, 0.2, 0.3])  # List auto-converts!
 
     This makes it seamless to use in APIs without explicit conversion calls.
+
+    Example:
+        ```python
+        from common.message import Array
+        import numpy as np
+
+        # Create from list
+        arr = Array.from_list([1.0, 2.0, 3.0])
+
+        # Create from numpy
+        np_arr = np.array([0.1, 0.2, 0.3], dtype=np.float32)
+        arr = Array.from_numpy(np_arr)
+
+        # Arithmetic operations
+        arr2 = arr * 2.0
+        arr3 = arr + arr2
+
+        # Statistics
+        mean = arr.mean()
+        magnitude = arr.magnitude()
+
+        # Convert back to numpy
+        result = arr.to_numpy()
+        ```
     """
 
     _type = "antioch/array"

common/message/camera.py

@@ -1,7 +1,7 @@
 import numpy as np
 from pydantic import Field
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class CameraInfo(Message):
@@ -10,6 +10,28 @@ class CameraInfo(Message):
 
     Follows standard camera calibration conventions with support for various
     distortion models and projection operations.
+
+    Example:
+        ```python
+        from common.message import CameraInfo
+
+        # Create camera info for a 640x480 camera
+        camera_info = CameraInfo(
+            width=640,
+            height=480,
+            fx=500.0,
+            fy=500.0,
+            cx=320.0,
+            cy=240.0,
+        )
+
+        # Get the intrinsics matrix
+        K = camera_info.intrinsics_matrix
+
+        # Project a 3D point to pixel coordinates
+        point_3d = np.array([0.5, 0.3, 2.0])
+        u, v = camera_info.project_point(point_3d)
+        ```
     """
 
     _type = "antioch/camera_info"

common/message/color.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from pydantic import field_validator
+from foxglove.schemas import Color as FoxgloveColor
+from pydantic import Field, field_validator
 
-from common.message.base import Message
+from common.message.message import Message
 
 
 class Color(Message):
@@ -10,13 +11,29 @@ class Color(Message):
     An RGBA color with values in the range [0.0, 1.0].
 
     Used in image annotations and visualization.
+
+    Example:
+        ```python
+        from common.message import Color
+
+        # Create a custom color
+        color = Color(r=0.5, g=0.8, b=0.2, a=1.0)
+
+        # Use factory methods for common colors
+        red = Color.red()
+        green = Color.green()
+        transparent = Color.transparent()
+
+        # Create with alpha
+        semi_transparent = Color.rgba(1.0, 0.0, 0.0, 0.5)
+        ```
     """
 
     _type = "antioch/color"
-    r: float
-    g: float
-    b: float
-    a: float
+    r: float = Field(description="Red component [0.0, 1.0]")
+    g: float = Field(description="Green component [0.0, 1.0]")
+    b: float = Field(description="Blue component [0.0, 1.0]")
+    a: float = Field(description="Alpha (opacity) component [0.0, 1.0]")
 
     @field_validator("r", "g", "b", "a")
     @classmethod
@@ -137,3 +154,12 @@ class Color(Message):
         """
 
         return cls(r=0.0, g=0.0, b=0.0, a=0.0)
+
+    def to_foxglove(self) -> FoxgloveColor:
+        """
+        Convert to Foxglove Color for telemetry.
+
+        :return: Foxglove Color schema.
+        """
+
+        return FoxgloveColor(r=self.r, g=self.g, b=self.b, a=self.a)

common/message/detection.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from common.message.message import Message
+
+
+class DetectionDistances(Message):
+    """
+    Detection distances for Foxglove range-time plotting.
+
+    In Foxglove Plot panel, use Y = .distances[:] to see detections over time.
+
+    Example:
+        ```python
+        from common.message import DetectionDistances
+
+        # Detections at 3.5m and 4.5m
+        detections = DetectionDistances(distances=[3.5, 4.5])
+        sim.logger.telemetry("radar/detections/combined", detections)
+        ```
+    """
+
+    _type = "antioch/detection_distances"
+
+    distances: list[float] = Field(
+        default_factory=list,
+        description="Distances where detections occurred",
+    )
+
+    def to_foxglove(self) -> dict[str, Any]:
+        """
+        Convert to Foxglove-compatible dict.
+
+        :return: Dict with distances array.
+        """
+
+        return {"distances": self.distances}

common/message/foxglove.py

@@ -0,0 +1,20 @@
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FoxgloveConvertible(Protocol):
+    """
+    Protocol for messages that can be converted to Foxglove format.
+
+    Implement this protocol for any message type that has a corresponding Foxglove
+    schema. The protocol provides a conversion method that returns the Foxglove type.
+    """
+
+    def to_foxglove(self) -> Any | None:
+        """
+        Convert this message to its Foxglove representation.
+
+        :return: The Foxglove schema object, or None if this message should not be published.
+        """
+
+        ...

common/message/frame.py

@@ -1,6 +1,14 @@
+from __future__ import annotations
+
+from foxglove.schemas import (
+    FrameTransform as FoxgloveFrameTransform,
+    FrameTransforms as FoxgloveFrameTransforms,
+    Quaternion as FoxgloveQuaternion,
+    Vector3 as FoxgloveVector3,
+)
 from pydantic import Field
 
-from common.message.base import Message
+from common.message.message import Message
 from common.message.quaternion import Quaternion
 from common.message.vector import Vector3
 
@@ -9,10 +17,21 @@ 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.
+    Example:
+        ```python
+        from common.message import FrameTransform, Vector3, Quaternion
+
+        # Create a transform from world to robot base
+        transform = FrameTransform(
+            parent_frame_id="world",
+            child_frame_id="robot_base",
+            translation=Vector3(x=1.0, y=0.0, z=0.0),
+            rotation=Quaternion.identity(),
+        )
+
+        # Create an identity transform
+        identity = FrameTransform.identity("parent", "child")
+        ```
     """
 
     _type = "antioch/frame_transform"
@@ -22,7 +41,7 @@ class FrameTransform(Message):
     rotation: Quaternion = Field(description="Rotation component of the transform")
 
     @classmethod
-    def identity(cls, parent_frame_id: str, child_frame_id: str) -> "FrameTransform":
+    def identity(cls, parent_frame_id: str, child_frame_id: str) -> FrameTransform:
         """
         Create an identity transform between two frames.
 
@@ -38,13 +57,58 @@ class FrameTransform(Message):
             rotation=Quaternion.identity(),
         )
 
+    def to_foxglove(self) -> FoxgloveFrameTransform:
+        """
+        Convert to Foxglove FrameTransform for telemetry.
+
+        :return: Foxglove FrameTransform schema.
+        """
+
+        return FoxgloveFrameTransform(
+            timestamp=None,
+            parent_frame_id=self.parent_frame_id,
+            child_frame_id=self.child_frame_id,
+            translation=FoxgloveVector3(x=self.translation.x, y=self.translation.y, z=self.translation.z),
+            rotation=FoxgloveQuaternion(x=self.rotation.x, y=self.rotation.y, z=self.rotation.z, w=self.rotation.w),
+        )
+
 
 class FrameTransforms(Message):
     """
     An array of FrameTransform messages.
 
-    :param transforms: Array of transforms.
+    Example:
+        ```python
+        from common.message import FrameTransforms, FrameTransform, Vector3, Quaternion
+
+        # Create a collection of transforms for a robot
+        transforms = FrameTransforms(transforms=[
+            FrameTransform(
+                parent_frame_id="world",
+                child_frame_id="base_link",
+                translation=Vector3(x=0.0, y=0.0, z=0.1),
+                rotation=Quaternion.identity(),
+            ),
+            FrameTransform(
+                parent_frame_id="base_link",
+                child_frame_id="camera",
+                translation=Vector3(x=0.5, y=0.0, z=0.3),
+                rotation=Quaternion.identity(),
+            ),
+        ])
+        ```
     """
 
     _type = "antioch/frame_transforms"
     transforms: list[FrameTransform] = Field(default_factory=list, description="Array of transforms")
+
+    def to_foxglove(self) -> FoxgloveFrameTransforms:
+        """
+        Convert to Foxglove FrameTransforms for telemetry.
+
+        :return: Foxglove FrameTransforms schema.
+        """
+
+        return FoxgloveFrameTransforms(
+            transforms=[t.to_foxglove() for t in self.transforms],
+        )