antioch-py 2.0.6__py3-none-any.whl → 3.0.12__py3-none-any.whl

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,16 +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")
-    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)")
+    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,
+        )

common/message/pose.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 from typing import Any
 
 import numpy as np
+from foxglove.schemas import Pose as FoxglovePose, Quaternion as FoxgloveQuaternion, Vector3 as FoxgloveVector3
 from pydantic import Field, field_validator, model_validator
 
-from common.message.base import Message
+from common.message.message import Message
 from common.message.vector import Vector3
 
 
@@ -19,11 +20,31 @@ class Pose(Message):
     Automatically converts from common Python types:
     - Lists/tuples: Pose(position=[1.0, 2.0, 3.0], orientation=[0.0, 0.0, 1.57])
     - Dicts: Pose(position={"x": 1.0, "y": 2.0, "z": 3.0}, orientation={"x": 0.0, "y": 0.0, "z": 1.57})
+
+    Example:
+        ```python
+        from common.message import Pose, Vector3
+
+        # Create a pose with position and orientation
+        pose = Pose(
+            position=[1.0, 2.0, 0.5],
+            orientation=[0.0, 0.0, 1.57],  # 90 degrees yaw
+        )
+
+        # Create from identity
+        identity = Pose.identity()
+
+        # Translate a pose
+        translated = pose.translate(Vector3(x=1.0, y=0.0, z=0.0))
+
+        # Access position components
+        print(f"Position: ({pose.position.x}, {pose.position.y}, {pose.position.z})")
+        ```
     """
 
     _type = "antioch/pose"
-    position: Vector3 = Field(default_factory=lambda: Vector3.zeros())
-    orientation: Vector3 = Field(default_factory=lambda: Vector3.zeros())
+    position: Vector3 = Field(default_factory=lambda: Vector3.zeros(), description="Position in 3D space as (x, y, z)")
+    orientation: Vector3 = Field(default_factory=lambda: Vector3.zeros(), description="Orientation as (roll, pitch, yaw) in radians")
 
     def __add__(self, other: Vector3) -> Pose:
         """
@@ -71,7 +92,7 @@ class Pose(Message):
         """
 
         if isinstance(v, (list, tuple, np.ndarray)):
-            return Vector3.convert_iterables.__func__(Vector3, v)
+            return Vector3._convert_input.__func__(Vector3, v)
         return v
 
     @field_validator("orientation", mode="before")
@@ -82,29 +103,34 @@ class Pose(Message):
         """
 
         if isinstance(v, (list, tuple, np.ndarray)):
-            return Vector3.convert_iterables.__func__(Vector3, v)
+            return Vector3._convert_input.__func__(Vector3, v)
         return v
 
     @classmethod
-    def from_any(cls, data: Any) -> Pose:
+    def from_any(cls, value: Pose | dict | tuple | list | None) -> Pose:
         """
-        Create Pose from a dict or Pose instance.
+        Create Pose from any compatible type.
+
+        Accepts:
+        - Pose instance (returned as-is)
+        - Dict with 'position' and/or 'orientation' keys
+        - Tuple/list of 3 floats (treated as position only)
+        - None (returns identity pose)
 
-        :param data: Dict with position/orientation fields, or a Pose instance.
+        :param value: Any compatible input type.
         :return: A Pose instance.
-        :raises ValueError: If conversion fails.
         """
 
-        # Already a Pose - return as-is
-        if isinstance(data, cls):
-            return data
-
-        try:
-            if isinstance(data, dict):
-                return cls(**data)
-            raise ValueError("Pose requires a dict with position and orientation fields")
-        except Exception as e:
-            raise ValueError(f"Cannot convert to Pose: {e}") from None
+        if value is None:
+            return cls.identity()
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, dict):
+            return cls.model_validate(value)
+        if isinstance(value, (tuple, list)):
+            # Treat as position only
+            return cls(position=Vector3.from_any(value))
+        raise ValueError(f"Cannot convert {type(value).__name__} to Pose")
 
     @classmethod
     def identity(cls) -> Pose:
@@ -146,3 +172,17 @@ class Pose(Message):
         """
 
         return Pose(position=self.position, orientation=self.orientation + rotation)
+
+    def to_foxglove(self) -> FoxglovePose:
+        """
+        Convert to Foxglove Pose for telemetry.
+
+        :return: Foxglove Pose schema.
+        """
+
+        # Convert RPY orientation to quaternion for Foxglove
+        quat = self.orientation.to_quat()
+        return FoxglovePose(
+            position=FoxgloveVector3(x=self.position.x, y=self.position.y, z=self.position.z),
+            orientation=FoxgloveQuaternion(x=quat.x, y=quat.y, z=quat.z, w=quat.w),
+        )