reachy-mini 1.2.5rc1__py3-none-any.whl → 1.2.11__py3-none-any.whl

reachy_mini/media/camera_constants.py

@@ -1,4 +1,27 @@
-"""Camera constants for Reachy Mini."""
+r"""Camera constants for Reachy Mini.
+
+This module defines camera specifications and resolutions for various camera models
+used with the Reachy Mini robot. It includes camera calibration parameters,
+supported resolutions, and camera identification information.
+
+The module provides:
+- CameraResolution enum: Standardized resolutions and frame rates
+- CameraSpecs dataclass: Base camera specifications with calibration data
+- Specific camera specifications for different camera models
+
+Example usage:
+    >>> from reachy_mini.media.camera_constants import CameraResolution, ReachyMiniLiteCamSpecs
+    >>>
+    >>> # Get available resolutions for Reachy Mini Lite Camera
+    >>> print("Available resolutions:")
+    >>> for res in ReachyMiniLiteCamSpecs.available_resolutions:
+    ...     width, height, fps = res.value
+    ...     print(f"  {width}x{height}@{fps}fps")
+    >>>
+    >>> # Access camera calibration parameters
+    >>> print(f"Camera matrix:\\n{ReachyMiniLiteCamSpecs.K}")
+    >>> print(f"Distortion coefficients: {ReachyMiniLiteCamSpecs.D}")
+"""
 
 from dataclasses import dataclass, field
 from enum import Enum
@@ -9,7 +32,48 @@ import numpy.typing as npt
 
 
 class CameraResolution(Enum):
-    """Base class for camera resolutions."""
+    """Base class for camera resolutions.
+
+    Enumeration of standardized camera resolutions and frame rates supported
+    by Reachy Mini cameras. Each enum value contains a tuple of (width, height, fps).
+
+    Attributes:
+        R1536x864at40fps: 1536x864 resolution at 40 fps
+        R1280x720at60fps: 1280x720 resolution at 60 fps (HD)
+        R1280x720at30fps: 1280x720 resolution at 30 fps (HD)
+        R1920x1080at30fps: 1920x1080 resolution at 30 fps (Full HD)
+        R1920x1080at60fps: 1920x1080 resolution at 60 fps (Full HD)
+        R2304x1296at30fps: 2304x1296 resolution at 30 fps
+        R1600x1200at30fps: 1600x1200 resolution at 30 fps
+        R3264x2448at30fps: 3264x2448 resolution at 30 fps
+        R3264x2448at10fps: 3264x2448 resolution at 10 fps
+        R3840x2592at30fps: 3840x2592 resolution at 30 fps
+        R3840x2592at10fps: 3840x2592 resolution at 10 fps
+        R3840x2160at30fps: 3840x2160 resolution at 30 fps (4K UHD)
+        R3840x2160at10fps: 3840x2160 resolution at 10 fps (4K UHD)
+        R3072x1728at10fps: 3072x1728 resolution at 10 fps
+        R4608x2592at10fps: 4608x2592 resolution at 10 fps
+
+    Note:
+        The enum values are tuples containing (width, height, frames_per_second).
+        Not all resolutions are supported by all camera models - check the specific
+        camera specifications for available resolutions.
+
+    Example:
+        >>> from reachy_mini.media.camera_constants import CameraResolution
+        >>>
+        >>> # Get resolution information
+        >>> res = CameraResolution.R1280x720at30fps
+        >>> width, height, fps = res.value
+        >>> print(f"Resolution: {width}x{height}@{fps}fps")
+        >>>
+        >>> # Check if a resolution is supported by a camera
+        >>> from reachy_mini.media.camera_constants import ReachyMiniLiteCamSpecs
+        >>> res = CameraResolution.R1920x1080at60fps
+        >>> if res in ReachyMiniLiteCamSpecs.available_resolutions:
+        ...     print("This resolution is supported")
+
+    """
 
     R1536x864at40fps = (1536, 864, 40)
 
@@ -37,7 +101,48 @@ class CameraResolution(Enum):
 
 @dataclass
 class CameraSpecs:
-    """Base camera specifications."""
+    """Base camera specifications.
+
+    Dataclass containing specifications for a camera model, including supported
+    resolutions, calibration parameters, and USB identification information.
+
+    Attributes:
+        name (str): Human-readable name of the camera model.
+        available_resolutions (List[CameraResolution]): List of supported resolutions
+            and frame rates for this camera model.
+        default_resolution (CameraResolution): Default resolution used when the camera
+            is initialized.
+        vid (int): USB Vendor ID for identifying this camera model.
+        pid (int): USB Product ID for identifying this camera model.
+        K (npt.NDArray[np.float64]): 3x3 camera intrinsic matrix containing focal
+            lengths and principal point coordinates.
+        D (npt.NDArray[np.float64]): 5-element array containing distortion coefficients
+            (k1, k2, p1, p2, k3) for radial and tangential distortion.
+
+    Note:
+        The intrinsic matrix K has the format:
+        [[fx,  0, cx],
+         [ 0, fy, cy],
+         [ 0,  0,  1]]
+
+        Where fx, fy are focal lengths in pixels, and cx, cy are the principal
+        point coordinates (typically near the image center).
+
+    Example:
+        >>> from reachy_mini.media.camera_constants import CameraSpecs
+        >>>
+        >>> # Create a custom camera specification
+        >>> custom_specs = CameraSpecs(
+        ...     name="custom_camera",
+        ...     available_resolutions=[CameraResolution.R1280x720at30fps],
+        ...     default_resolution=CameraResolution.R1280x720at30fps,
+        ...     vid=0x1234,
+        ...     pid=0x5678,
+        ...     K=np.array([[800, 0, 640], [0, 800, 360], [0, 0, 1]]),
+        ...     D=np.zeros(5)
+        ... )
+
+    """
 
     name: str = ""
     available_resolutions: List[CameraResolution] = field(default_factory=list)
@@ -106,6 +211,7 @@ class ReachyMiniWirelessCamSpecs(ReachyMiniLiteCamSpecs):
 
     name = "wireless"
     available_resolutions = [
+        CameraResolution.R1280x720at30fps,  # Default for H264 Level 3.1 (Safari/WebKit)
         CameraResolution.R1920x1080at30fps,
         CameraResolution.R1280x720at60fps,
         CameraResolution.R3840x2592at10fps,
@@ -113,7 +219,8 @@ class ReachyMiniWirelessCamSpecs(ReachyMiniLiteCamSpecs):
         CameraResolution.R3264x2448at10fps,
         CameraResolution.R3072x1728at10fps,
     ]
-    default_resolution = CameraResolution.R1920x1080at30fps
+    # 720p@30fps for H264 Level 3.1 compatibility (Safari/WebKit)
+    default_resolution = CameraResolution.R1280x720at30fps
 
 
 @dataclass
@@ -150,3 +257,24 @@ class MujocoCameraSpecs(CameraSpecs):
         ]
     )
     D = np.zeros((5,))  # no distortion
+
+
+@dataclass
+class GenericWebcamSpecs(CameraSpecs):
+    """Generic webcam specifications (fallback for any webcam)."""
+
+    name = "generic"
+    available_resolutions = [
+        CameraResolution.R1280x720at30fps,
+        CameraResolution.R1920x1080at30fps,
+    ]
+    default_resolution = CameraResolution.R1280x720at30fps
+    # Approximate camera matrix for generic 720p webcam
+    K = np.array(
+        [
+            [640.0, 0.0, 640.0],
+            [0.0, 640.0, 360.0],
+            [0.0, 0.0, 1.0],
+        ]
+    )
+    D = np.zeros((5,))  # assume no distortion

reachy_mini/media/camera_gstreamer.py

@@ -1,7 +1,42 @@
 """GStreamer camera backend.
 
 This module provides an implementation of the CameraBase class using GStreamer.
-By default the module directly returns JPEG images as output by the camera.
+It offers advanced video processing capabilities including hardware-accelerated
+decoding, image format conversion, and support for various camera models.
+
+The GStreamer camera backend features:
+- Hardware-accelerated video decoding
+- Support for multiple camera models (Reachy Mini Lite, Arducam, etc.)
+- Advanced image processing pipelines
+- Automatic camera detection and configuration
+- Multiple resolution and frame rate support
+- JPEG and raw image format support
+
+Example usage:
+    >>> from reachy_mini.media.camera_gstreamer import GStreamerCamera
+    >>> from reachy_mini.media.camera_constants import CameraResolution
+    >>>
+    >>> # Create GStreamer camera instance
+    >>> camera = GStreamerCamera(log_level="INFO")
+    >>>
+    >>> # Open the camera
+    >>> camera.open()
+    >>>
+    >>> # Set resolution (optional)
+    >>> camera.set_resolution(CameraResolution.R1280x720at30fps)
+    >>>
+    >>> # Capture frames
+    >>> frame = camera.read()
+    >>> if frame is not None:
+    ...     print(f"Captured frame with shape: {frame.shape}")
+    >>>
+    >>> # Get camera information
+    >>> width, height = camera.resolution
+    >>> fps = camera.framerate
+    >>> print(f"Camera: {width}x{height}@{fps}fps")
+    >>>
+    >>> # Clean up
+    >>> camera.close()
 """
 
 import os
@@ -78,7 +113,7 @@ class GStreamerCamera(CameraBase):
             self.pipeline.add(camsrc)
             queue = Gst.ElementFactory.make("queue")
             self.pipeline.add(queue)
-            videoconvert = Gst.ElementFactory.make("videoconvert")
+            videoconvert = Gst.ElementFactory.make("v4l2convert")
             self.pipeline.add(videoconvert)
             camsrc.link(queue)
             queue.link(videoconvert)
@@ -96,6 +131,11 @@ class GStreamerCamera(CameraBase):
         else:
             camsrc = Gst.ElementFactory.make("v4l2src")
             camsrc.set_property("device", cam_path)
+            # examples of camera controls settings:
+            # extra_controls_structure = Gst.Structure.new_empty("extra-controls")
+            # extra_controls_structure.set_value("saturation", 64)
+            # extra_controls_structure.set_value("brightness", 50)
+            # camsrc.set_property("extra-controls", extra_controls_structure)
             self.pipeline.add(camsrc)
             queue = Gst.ElementFactory.make("queue")
             self.pipeline.add(queue)

reachy_mini/media/camera_opencv.py

@@ -1,6 +1,51 @@
-"""OpenCv camera backend.
+r"""OpenCV camera backend.
 
 This module provides an implementation of the CameraBase class using OpenCV.
+It offers cross-platform camera support with automatic camera detection and
+configuration for various Reachy Mini camera models.
+
+The OpenCV camera backend features:
+- Cross-platform compatibility (Windows, macOS, Linux)
+- Automatic camera detection and model identification
+- Support for multiple camera models (Reachy Mini Lite, Beta (Arducam), etc.)
+- Resolution and frame rate configuration
+- Camera calibration parameter access
+- Simulation mode support (Mujoco)
+
+Note:
+    This class is typically used internally by the MediaManager when the DEFAULT
+    backend is selected. Direct usage is possible but usually not necessary.
+
+Example usage via MediaManager:
+    >>> from reachy_mini.media.media_manager import MediaManager, MediaBackend
+    >>>
+    >>> # Create media manager with OpenCV backend (default)
+    >>> media = MediaManager(backend=MediaBackend.DEFAULT, log_level="INFO")
+    >>>
+    >>> # Capture frames
+    >>> frame = media.get_frame()
+    >>> if frame is not None:
+    ...     print(f"Captured frame with shape: {frame.shape}")
+    ...     cv2.imshow("Camera", frame)
+    ...     cv2.waitKey(1)
+    >>>
+    >>> # Get camera information
+    >>> if media.camera is not None:
+    ...     width, height = media.camera.resolution
+    ...     fps = media.camera.framerate
+    ...     print(f"Camera: {width}x{height}@{fps}fps")
+    ...
+    ...     # Access calibration information
+    ...     K = media.camera.K
+    ...     D = media.camera.D
+    ...     if K is not None:
+    ...         print(f"Camera matrix:\\n{K}")
+    ...     if D is not None:
+    ...         print(f"Distortion coefficients: {D}")
+    >>>
+    >>> # Clean up
+    >>> media.close()
+
 """
 
 from typing import Optional, cast
@@ -20,13 +65,33 @@ from .camera_base import CameraBase
 
 
 class OpenCVCamera(CameraBase):
-    """Camera implementation using OpenCV."""
+    """Camera implementation using OpenCV.
+
+    This class implements the CameraBase interface using OpenCV, providing
+    cross-platform camera support for Reachy Mini robots. It automatically
+    detects and configures supported camera models.
+
+    Attributes:
+        Inherits all attributes from CameraBase.
+        Additionally manages OpenCV VideoCapture objects and camera connections.
+
+    """
 
     def __init__(
         self,
         log_level: str = "INFO",
     ) -> None:
-        """Initialize the OpenCV camera."""
+        """Initialize the OpenCV camera.
+
+        Args:
+            log_level (str): Logging level for camera operations.
+                          Default: 'INFO'.
+
+        Note:
+            This constructor initializes the OpenCV camera system. The actual
+            camera device is opened when the open() method is called.
+
+        """
         super().__init__(log_level=log_level)
         self.cap: Optional[cv2.VideoCapture] = None
 
@@ -40,7 +105,10 @@ class OpenCVCamera(CameraBase):
             self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self._resolution.value[1])
 
     def open(self, udp_camera: Optional[str] = None) -> None:
-        """Open the camera using OpenCV VideoCapture."""
+        """Open the camera using OpenCV VideoCapture.
+
+        See CameraBase.open() for complete documentation.
+        """
         if udp_camera:
             self.cap = cv2.VideoCapture(udp_camera)
             self.camera_specs = cast(CameraSpecs, MujocoCameraSpecs)
@@ -57,6 +125,11 @@ class OpenCVCamera(CameraBase):
             self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, self._resolution.value[0])
             self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self._resolution.value[1])
 
+            # example of camera controls settings:
+            # self.cap.set(cv2.CAP_PROP_BRIGHTNESS, 0.5)
+            # self.cap.set(cv2.CAP_PROP_CONTRAST, 0.5)
+            # self.cap.set(cv2.CAP_PROP_SATURATION, 64)
+
         self.resized_K = self.camera_specs.K
 
         if not self.cap.isOpened():
@@ -65,6 +138,8 @@ class OpenCVCamera(CameraBase):
     def read(self) -> Optional[npt.NDArray[np.uint8]]:
         """Read a frame from the camera.
 
+        See CameraBase.read() for complete documentation.
+
         Returns:
             The frame as a uint8 numpy array, or None if no frame could be read.
 
@@ -83,7 +158,10 @@ class OpenCVCamera(CameraBase):
         return cast(npt.NDArray[np.uint8], frame)
 
     def close(self) -> None:
-        """Release the camera resource."""
+        """Release the camera resource.
+
+        See CameraBase.close() for complete documentation.
+        """
         if self.cap is not None:
             self.cap.release()
             self.cap = None

reachy_mini/media/camera_utils.py

@@ -1,4 +1,28 @@
-"""Camera utility for Reachy Mini."""
+"""Camera utility for Reachy Mini.
+
+This module provides utility functions for working with cameras on the Reachy Mini robot.
+It includes functions for detecting and identifying different camera models, managing
+camera connections, and handling camera-specific configurations.
+
+Supported camera types:
+- Reachy Mini Lite Camera
+- Arducam
+- Older Raspberry Pi Camera
+- Generic Webcams (fallback)
+
+Example usage:
+    >>> from reachy_mini.media.camera_utils import find_camera
+    >>>
+    >>> # Find and open the Reachy Mini camera
+    >>> cap, camera_specs = find_camera()
+    >>> if cap is not None:
+    ...     print(f"Found {camera_specs.name} camera")
+    ...     # Use the camera
+    ...     ret, frame = cap.read()
+    ...     cap.release()
+    ... else:
+    ...     print("No camera found")
+"""
 
 import platform
 from typing import Optional, Tuple, cast
@@ -9,6 +33,7 @@ from cv2_enumerate_cameras import enumerate_cameras
 from reachy_mini.media.camera_constants import (
     ArducamSpecs,
     CameraSpecs,
+    GenericWebcamSpecs,
     OlderRPiCamSpecs,
     ReachyMiniLiteCamSpecs,
 )
@@ -19,14 +44,45 @@ def find_camera(
 ) -> Tuple[Optional[cv2.VideoCapture], Optional[CameraSpecs]]:
     """Find and return the Reachy Mini camera.
 
-    Looks for the Reachy Mini camera first, then Arducam, then older Raspberry Pi Camera. Returns None if no camera is found.
+    Looks for the Reachy Mini camera first, then Arducam, then older Raspberry Pi Camera.
+    Returns None if no camera is found. Falls back to generic webcam if no specific camera is detected.
 
     Args:
         apiPreference (int): Preferred API backend for the camera. Default is cv2.CAP_ANY.
-        no_cap (bool): If True, close the camera after finding it. Default is False.
+                           Options include cv2.CAP_V4L2 (Linux), cv2.CAP_DSHOW (Windows),
+                           cv2.CAP_MSMF (Windows), etc.
+        no_cap (bool): If True, close the camera after finding it. Useful for testing
+                      camera detection without keeping the camera open. Default is False.
 
     Returns:
-        cv2.VideoCapture | None: A VideoCapture object if the camera is found and opened successfully, otherwise None.
+        Tuple[Optional[cv2.VideoCapture], Optional[CameraSpecs]]: A tuple containing:
+            - cv2.VideoCapture: A VideoCapture object if the camera is found and opened
+              successfully, otherwise None.
+            - CameraSpecs: The camera specifications for the detected camera, or None if
+              no camera was found.
+
+    Note:
+        This function tries to detect cameras in the following order:
+        1. Reachy Mini Lite Camera (preferred)
+        2. Older Raspberry Pi Camera
+        3. Arducam
+        4. Generic Webcam (fallback)
+
+        The function automatically sets the appropriate video codec (MJPG) for
+        Reachy Mini and Raspberry Pi cameras to ensure compatibility.
+
+    Example:
+        >>> cap, specs = find_camera()
+        >>> if cap is not None:
+        ...     print(f"Found {specs.name} camera")
+        ...     # Set resolution
+        ...     cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280)
+        ...     cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720)
+        ...     # Capture a frame
+        ...     ret, frame = cap.read()
+        ...     cap.release()
+        ... else:
+        ...     print("No camera found")
 
     """
     cap = find_camera_by_vid_pid(
@@ -55,6 +111,13 @@ def find_camera(
             cap.release()
         return cap, cast(CameraSpecs, ArducamSpecs)
 
+    # Fallback: try to open any available webcam (useful for mockup-sim mode on desktop)
+    cap = cv2.VideoCapture(0)
+    if cap is not None and cap.isOpened():
+        if no_cap:
+            cap.release()
+        return cap, cast(CameraSpecs, GenericWebcamSpecs)
+
     return None, None
 
 
@@ -66,12 +129,37 @@ def find_camera_by_vid_pid(
     """Find and return a camera with the specified VID and PID.
 
     Args:
-        vid (int): Vendor ID of the camera. Default is ReachyMiniCamera
-        pid (int): Product ID of the camera. Default is ReachyMiniCamera
+        vid (int): Vendor ID of the camera. Default is ReachyMiniLiteCamSpecs.vid (0x38FB).
+        pid (int): Product ID of the camera. Default is ReachyMiniLiteCamSpecs.pid (0x1002).
         apiPreference (int): Preferred API backend for the camera. Default is cv2.CAP_ANY.
+                           On Linux, this automatically uses cv2.CAP_V4L2 for better compatibility.
 
     Returns:
-        cv2.VideoCapture | None: A VideoCapture object if the camera is found and opened successfully, otherwise None.
+        cv2.VideoCapture | None: A VideoCapture object if the camera with matching
+            VID/PID is found and opened successfully, otherwise None.
+
+    Note:
+        This function uses the cv2_enumerate_cameras package to enumerate available
+        cameras and find one with the specified USB Vendor ID and Product ID.
+        This is useful for selecting specific camera models when multiple cameras
+        are connected to the system.
+
+        The Arducam camera creates two /dev/videoX devices that enumerate_cameras
+        cannot differentiate, so this function tries to open each potential device
+        until it finds a working one.
+
+    Example:
+        >>> # Find Reachy Mini Lite Camera by its default VID/PID
+        >>> cap = find_camera_by_vid_pid()
+        >>> if cap is not None:
+        ...     print("Found Reachy Mini Lite Camera")
+        ...     cap.release()
+        >>>
+        >>> # Find a specific camera by custom VID/PID
+        >>> cap = find_camera_by_vid_pid(vid=0x0C45, pid=0x636D)  # Arducam
+        >>> if cap is not None:
+        ...     print("Found Arducam")
+        ...     cap.release()
 
     """
     if platform.system() == "Linux":