foodforthought-cli 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

ate/interfaces/detection.py

@@ -0,0 +1,282 @@
+"""
+Object detection interface for robot perception.
+
+This is a HIGHER-LEVEL interface that wraps camera interfaces
+and ML models to provide semantic understanding of the environment.
+
+Design principle: Models are pluggable - the interface abstracts
+away the specific ML framework (YOLO, Detectron2, etc.)
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any, Callable
+from enum import Enum, auto
+
+from .types import Vector3, Image, ActionResult
+
+
+@dataclass
+class BoundingBox:
+    """2D bounding box in image coordinates."""
+    x_min: float  # Left edge (pixels)
+    y_min: float  # Top edge (pixels)
+    x_max: float  # Right edge (pixels)
+    y_max: float  # Bottom edge (pixels)
+
+    @property
+    def width(self) -> float:
+        return self.x_max - self.x_min
+
+    @property
+    def height(self) -> float:
+        return self.y_max - self.y_min
+
+    @property
+    def center(self) -> tuple:
+        return ((self.x_min + self.x_max) / 2, (self.y_min + self.y_max) / 2)
+
+    @property
+    def area(self) -> float:
+        return self.width * self.height
+
+
+@dataclass
+class Detection:
+    """A detected object in an image."""
+    class_name: str              # e.g., "trash", "bottle", "can"
+    class_id: int               # Numeric class ID
+    confidence: float           # 0.0 to 1.0
+    bbox: BoundingBox           # 2D bounding box
+
+    # Optional 3D info (if depth available)
+    position_3d: Optional[Vector3] = None  # In camera frame
+    distance: Optional[float] = None       # Distance in meters
+
+    # Optional instance segmentation mask
+    mask: Optional[Any] = None
+
+    # Additional attributes (color, size estimates, etc.)
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "class_name": self.class_name,
+            "class_id": self.class_id,
+            "confidence": self.confidence,
+            "bbox": {
+                "x_min": self.bbox.x_min,
+                "y_min": self.bbox.y_min,
+                "x_max": self.bbox.x_max,
+                "y_max": self.bbox.y_max,
+            },
+            "position_3d": self.position_3d.to_dict() if self.position_3d else None,
+            "distance": self.distance,
+            "attributes": self.attributes,
+        }
+
+
+@dataclass
+class DetectionResult:
+    """Result of running object detection on an image."""
+    detections: List[Detection]
+    image: Optional[Image] = None  # Original image (optional)
+    inference_time_ms: float = 0.0
+    model_name: str = ""
+
+    def filter_by_class(self, class_name: str) -> List[Detection]:
+        """Get detections of a specific class."""
+        return [d for d in self.detections if d.class_name == class_name]
+
+    def filter_by_confidence(self, min_confidence: float) -> List[Detection]:
+        """Get detections above confidence threshold."""
+        return [d for d in self.detections if d.confidence >= min_confidence]
+
+    def get_closest(self) -> Optional[Detection]:
+        """Get the closest detected object (requires 3D info)."""
+        with_distance = [d for d in self.detections if d.distance is not None]
+        if not with_distance:
+            return None
+        return min(with_distance, key=lambda d: d.distance)
+
+
+class ObjectDetectionInterface(ABC):
+    """
+    Interface for object detection capabilities.
+
+    This abstracts the specific ML model and camera hardware,
+    providing a unified API for detecting objects in the environment.
+
+    Use cases:
+    - Trash detection for cleanup tasks
+    - Object manipulation (find and grasp)
+    - Obstacle detection for navigation
+    - Person detection for social robots
+    """
+
+    @abstractmethod
+    def detect(self, image: Optional[Image] = None) -> DetectionResult:
+        """
+        Run object detection.
+
+        Args:
+            image: Image to process. If None, capture from camera.
+
+        Returns:
+            DetectionResult with all detections
+        """
+        pass
+
+    @abstractmethod
+    def get_classes(self) -> List[str]:
+        """
+        Get list of classes this detector can recognize.
+
+        Returns:
+            List of class names
+        """
+        pass
+
+    def detect_class(self, class_name: str, min_confidence: float = 0.5) -> List[Detection]:
+        """
+        Detect objects of a specific class.
+
+        Args:
+            class_name: Class to detect (e.g., "bottle", "trash")
+            min_confidence: Minimum confidence threshold
+
+        Returns:
+            List of detections of that class
+        """
+        result = self.detect()
+        return [
+            d for d in result.detections
+            if d.class_name == class_name and d.confidence >= min_confidence
+        ]
+
+    def detect_any(self, class_names: List[str], min_confidence: float = 0.5) -> List[Detection]:
+        """
+        Detect objects of any of the specified classes.
+
+        Args:
+            class_names: List of classes to detect
+            min_confidence: Minimum confidence threshold
+
+        Returns:
+            List of detections matching any class
+        """
+        result = self.detect()
+        return [
+            d for d in result.detections
+            if d.class_name in class_names and d.confidence >= min_confidence
+        ]
+
+    def find_nearest(self, class_name: str) -> Optional[Detection]:
+        """
+        Find the nearest object of a class.
+
+        Args:
+            class_name: Class to find
+
+        Returns:
+            Detection of nearest object, or None
+        """
+        detections = self.detect_class(class_name)
+        with_distance = [d for d in detections if d.distance is not None]
+        if not with_distance:
+            # Fall back to largest bounding box (likely closest)
+            if detections:
+                return max(detections, key=lambda d: d.bbox.area)
+            return None
+        return min(with_distance, key=lambda d: d.distance)
+
+    # =========================================================================
+    # Model management
+    # =========================================================================
+
+    def load_model(self, model_path: str) -> ActionResult:
+        """Load a specific detection model."""
+        return ActionResult.error("Custom model loading not supported")
+
+    def get_model_info(self) -> Dict[str, Any]:
+        """Get information about the current model."""
+        return {"classes": self.get_classes()}
+
+    # =========================================================================
+    # Streaming detection
+    # =========================================================================
+
+    def start_detection_stream(
+        self,
+        callback: Callable[[DetectionResult], None],
+        min_confidence: float = 0.5
+    ) -> ActionResult:
+        """
+        Start continuous detection with callbacks.
+
+        Args:
+            callback: Function called with each detection result
+            min_confidence: Minimum confidence for callbacks
+        """
+        return ActionResult.error("Streaming detection not supported")
+
+    def stop_detection_stream(self) -> ActionResult:
+        """Stop the detection stream."""
+        return ActionResult.error("Streaming detection not supported")
+
+
+class TrashDetectionInterface(ObjectDetectionInterface):
+    """
+    Specialized detector for trash/litter.
+
+    Recognizes common trash items:
+    - Bottles (plastic, glass)
+    - Cans
+    - Paper/cardboard
+    - Wrappers/packaging
+    - Cigarette butts
+    - General debris
+    """
+
+    TRASH_CLASSES = [
+        "plastic_bottle",
+        "glass_bottle",
+        "can",
+        "paper",
+        "cardboard",
+        "wrapper",
+        "cigarette_butt",
+        "debris",
+        "trash",  # Generic
+    ]
+
+    def get_classes(self) -> List[str]:
+        return self.TRASH_CLASSES
+
+    def detect_trash(self, min_confidence: float = 0.5) -> List[Detection]:
+        """
+        Detect all trash items.
+
+        Returns:
+            List of trash detections
+        """
+        return self.detect_any(self.TRASH_CLASSES, min_confidence)
+
+    def find_nearest_trash(self) -> Optional[Detection]:
+        """
+        Find the nearest trash item.
+
+        Returns:
+            Detection of nearest trash, or None
+        """
+        detections = self.detect_trash()
+        with_distance = [d for d in detections if d.distance is not None]
+        if not with_distance:
+            if detections:
+                return max(detections, key=lambda d: d.bbox.area)
+            return None
+        return min(with_distance, key=lambda d: d.distance)
+
+    def is_trash_visible(self) -> bool:
+        """Check if any trash is visible."""
+        return len(self.detect_trash()) > 0

ate/interfaces/locomotion.py

@@ -0,0 +1,422 @@
+"""
+Locomotion interfaces for mobile robots.
+
+Supports:
+- Quadrupeds (MechDog, Spot, Unitree, ANYmal)
+- Bipeds (Humanoids, Digit, Atlas)
+- Wheeled robots (TurtleBot, AMRs)
+- Aerial (Drones)
+
+Each interface defines normalized actions that are hardware-agnostic.
+A "walk forward 0.5m" command works the same on MechDog and Spot.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, List, Callable
+from enum import Enum, auto
+
+from .types import (
+    Vector3,
+    Quaternion,
+    Pose,
+    Twist,
+    GaitType,
+    GaitParameters,
+    JointState,
+    ActionResult,
+)
+
+
+class LocomotionInterface(ABC):
+    """
+    Base interface for all locomotion.
+
+    All mobile robots share these concepts:
+    - Current pose in some frame
+    - Velocity control
+    - Stop
+    """
+
+    @abstractmethod
+    def get_pose(self) -> Pose:
+        """
+        Get current pose (position + orientation) in odometry frame.
+
+        Returns:
+            Pose in odom frame
+        """
+        pass
+
+    @abstractmethod
+    def get_velocity(self) -> Twist:
+        """
+        Get current velocity (linear + angular).
+
+        Returns:
+            Twist with linear (m/s) and angular (rad/s) velocity
+        """
+        pass
+
+    @abstractmethod
+    def stop(self) -> ActionResult:
+        """
+        Immediately stop all locomotion.
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    @abstractmethod
+    def is_moving(self) -> bool:
+        """
+        Check if robot is currently moving.
+
+        Returns:
+            True if any locomotion is active
+        """
+        pass
+
+
+class QuadrupedLocomotion(LocomotionInterface):
+    """
+    Interface for quadruped (4-legged) robots.
+
+    Implemented by: MechDog, Spot, Unitree Go1/Go2, ANYmal, etc.
+
+    Coordinate frame conventions:
+    - X: Forward (positive = front of robot)
+    - Y: Left (positive = left side of robot)
+    - Z: Up (positive = above robot)
+
+    All distances in meters, angles in radians.
+    """
+
+    # =========================================================================
+    # High-level movement commands
+    # =========================================================================
+
+    @abstractmethod
+    def walk(self, direction: Vector3, speed: float = 0.5) -> ActionResult:
+        """
+        Walk in a direction at given speed.
+
+        This is a continuous command - robot keeps walking until stop() is called.
+
+        Args:
+            direction: Unit vector for direction (in robot frame)
+                       Vector3(1, 0, 0) = forward
+                       Vector3(0, 1, 0) = left
+                       Vector3(-1, 0, 0) = backward
+            speed: Speed in m/s (clamped to robot's max)
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    @abstractmethod
+    def walk_to(self, target: Vector3, speed: float = 0.5) -> ActionResult:
+        """
+        Walk to a target position (blocking).
+
+        Args:
+            target: Target position in odometry frame
+            speed: Speed in m/s
+
+        Returns:
+            ActionResult (when target reached or failed)
+        """
+        pass
+
+    @abstractmethod
+    def turn(self, angle: float, speed: float = 0.5) -> ActionResult:
+        """
+        Turn in place by given angle (blocking).
+
+        Args:
+            angle: Angle in radians (positive = counterclockwise)
+            speed: Angular speed in rad/s
+
+        Returns:
+            ActionResult (when turn complete)
+        """
+        pass
+
+    @abstractmethod
+    def turn_continuous(self, angular_velocity: float) -> ActionResult:
+        """
+        Turn continuously at given angular velocity.
+
+        Args:
+            angular_velocity: rad/s (positive = counterclockwise)
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    # =========================================================================
+    # Posture commands
+    # =========================================================================
+
+    @abstractmethod
+    def stand(self) -> ActionResult:
+        """
+        Stand up from any position.
+
+        Returns:
+            ActionResult (when standing complete)
+        """
+        pass
+
+    @abstractmethod
+    def sit(self) -> ActionResult:
+        """
+        Sit down (lower body to ground).
+
+        Returns:
+            ActionResult (when sit complete)
+        """
+        pass
+
+    @abstractmethod
+    def lie_down(self) -> ActionResult:
+        """
+        Lie down completely (motors may turn off).
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    # =========================================================================
+    # Gait control
+    # =========================================================================
+
+    @abstractmethod
+    def set_gait(self, gait: GaitType) -> ActionResult:
+        """
+        Set the gait pattern.
+
+        Args:
+            gait: GaitType (WALK, TROT, BOUND, etc.)
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    @abstractmethod
+    def get_gait(self) -> GaitType:
+        """
+        Get current gait pattern.
+
+        Returns:
+            Current GaitType
+        """
+        pass
+
+    def set_gait_parameters(self, params: GaitParameters) -> ActionResult:
+        """
+        Set detailed gait parameters.
+
+        Default implementation just sets gait type.
+        Override for robots with fine-grained gait control.
+
+        Args:
+            params: GaitParameters with stride, step height, etc.
+
+        Returns:
+            ActionResult
+        """
+        return self.set_gait(params.gait_type)
+
+    # =========================================================================
+    # Leg control (for advanced use)
+    # =========================================================================
+
+    @abstractmethod
+    def get_foot_positions(self) -> List[Vector3]:
+        """
+        Get current foot positions relative to body.
+
+        Returns:
+            List of 4 Vector3 positions [front_left, front_right, back_left, back_right]
+        """
+        pass
+
+    def set_foot_position(self, leg_index: int, position: Vector3) -> ActionResult:
+        """
+        Set a single foot position using inverse kinematics.
+
+        Args:
+            leg_index: 0=front_left, 1=front_right, 2=back_left, 3=back_right
+            position: Target position relative to body
+
+        Returns:
+            ActionResult
+        """
+        # Default: not implemented
+        return ActionResult.error("set_foot_position not implemented for this robot")
+
+    # =========================================================================
+    # Joint-level access (for telemetry/recording)
+    # =========================================================================
+
+    @abstractmethod
+    def get_joint_state(self) -> JointState:
+        """
+        Get current state of all leg joints.
+
+        Returns:
+            JointState with positions, velocities, efforts
+        """
+        pass
+
+    def get_joint_names(self) -> List[str]:
+        """
+        Get names of all leg joints in order.
+
+        Default naming convention:
+        [FL_hip, FL_thigh, FL_calf, FR_hip, FR_thigh, FR_calf,
+         BL_hip, BL_thigh, BL_calf, BR_hip, BR_thigh, BR_calf]
+
+        Returns:
+            List of joint names
+        """
+        return [
+            "FL_hip", "FL_thigh", "FL_calf",
+            "FR_hip", "FR_thigh", "FR_calf",
+            "BL_hip", "BL_thigh", "BL_calf",
+            "BR_hip", "BR_thigh", "BR_calf",
+        ]
+
+
+class BipedLocomotion(LocomotionInterface):
+    """
+    Interface for biped (2-legged) robots.
+
+    Implemented by: Humanoids, Digit, Cassie, etc.
+    """
+
+    @abstractmethod
+    def walk(self, direction: Vector3, speed: float = 0.5) -> ActionResult:
+        """Walk in direction."""
+        pass
+
+    @abstractmethod
+    def walk_to(self, target: Vector3, speed: float = 0.5) -> ActionResult:
+        """Walk to target position."""
+        pass
+
+    @abstractmethod
+    def turn(self, angle: float, speed: float = 0.5) -> ActionResult:
+        """Turn by angle."""
+        pass
+
+    @abstractmethod
+    def stand(self) -> ActionResult:
+        """Stand up."""
+        pass
+
+    @abstractmethod
+    def crouch(self) -> ActionResult:
+        """Lower body while standing."""
+        pass
+
+    @abstractmethod
+    def get_joint_state(self) -> JointState:
+        """Get leg joint states."""
+        pass
+
+    # Biped-specific
+    @abstractmethod
+    def step_over(self, obstacle_height: float) -> ActionResult:
+        """Step over an obstacle of given height."""
+        pass
+
+    @abstractmethod
+    def climb_stairs(self, step_height: float, num_steps: int) -> ActionResult:
+        """Climb stairs."""
+        pass
+
+
+class WheeledLocomotion(LocomotionInterface):
+    """
+    Interface for wheeled robots.
+
+    Implemented by: TurtleBot, AMRs, differential drive, Ackermann, etc.
+    """
+
+    @abstractmethod
+    def drive(self, linear: float, angular: float) -> ActionResult:
+        """
+        Drive with given linear and angular velocity.
+
+        Args:
+            linear: Forward velocity in m/s
+            angular: Angular velocity in rad/s
+
+        Returns:
+            ActionResult
+        """
+        pass
+
+    @abstractmethod
+    def drive_to(self, target: Vector3, speed: float = 0.5) -> ActionResult:
+        """Drive to target position."""
+        pass
+
+    @abstractmethod
+    def turn(self, angle: float, speed: float = 0.5) -> ActionResult:
+        """Turn by angle."""
+        pass
+
+    @abstractmethod
+    def get_wheel_velocities(self) -> List[float]:
+        """Get current wheel velocities in rad/s."""
+        pass
+
+
+class AerialLocomotion(LocomotionInterface):
+    """
+    Interface for aerial robots (drones).
+
+    Implemented by: Quadcopters, fixed-wing, etc.
+    """
+
+    @abstractmethod
+    def takeoff(self, altitude: float = 1.0) -> ActionResult:
+        """Take off to given altitude."""
+        pass
+
+    @abstractmethod
+    def land(self) -> ActionResult:
+        """Land at current position."""
+        pass
+
+    @abstractmethod
+    def hover(self) -> ActionResult:
+        """Hover in place."""
+        pass
+
+    @abstractmethod
+    def fly_to(self, target: Vector3, speed: float = 1.0) -> ActionResult:
+        """Fly to target position."""
+        pass
+
+    @abstractmethod
+    def set_velocity(self, velocity: Vector3) -> ActionResult:
+        """Set 3D velocity."""
+        pass
+
+    @abstractmethod
+    def get_altitude(self) -> float:
+        """Get current altitude in meters."""
+        pass
+
+    @abstractmethod
+    def is_flying(self) -> bool:
+        """Check if currently airborne."""
+        pass