plexus-python 0.1.0__py3-none-any.whl

plexus/cameras/base.py

@@ -0,0 +1,189 @@
+"""
+Base camera class and utilities for Plexus camera drivers.
+
+All camera drivers inherit from BaseCamera and implement the capture() method.
+"""
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CameraFrame:
+    """A single camera frame with JPEG-encoded image data."""
+    data: bytes
+    width: int
+    height: int
+    timestamp: float = field(default_factory=time.time)
+    camera_id: str = ""
+    tags: Dict[str, str] = field(default_factory=dict)
+
+
+class BaseCamera(ABC):
+    """
+    Base class for all camera drivers.
+
+    Subclasses must implement:
+    - capture() -> Optional[CameraFrame]: Capture a single frame
+    - name: Human-readable camera name
+
+    Optional overrides:
+    - setup(): Initialize the camera (called once)
+    - cleanup(): Clean up resources (called on stop)
+    - is_available(): Check if camera is connected
+    """
+
+    name: str = "Unknown Camera"
+    description: str = ""
+
+    def __init__(
+        self,
+        frame_rate: float = 10.0,
+        resolution: Tuple[int, int] = (640, 480),
+        quality: int = 80,
+        camera_id: str = "",
+        tags: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize the camera driver.
+
+        Args:
+            frame_rate: Target frames per second. Default 10 fps.
+            resolution: (width, height) tuple. Default (640, 480).
+            quality: JPEG quality 1-100. Default 80.
+            camera_id: Unique identifier for this camera.
+            tags: Tags to add to all frames from this camera.
+        """
+        self.frame_rate = frame_rate
+        self.resolution = resolution
+        self.quality = max(1, min(100, quality))
+        self.camera_id = camera_id
+        self.tags = tags or {}
+        self._running = False
+        self._error: Optional[str] = None
+
+    @abstractmethod
+    def capture(self) -> Optional[CameraFrame]:
+        """
+        Capture a single frame from the camera.
+
+        Returns:
+            CameraFrame with JPEG-encoded image data, or None if capture failed.
+        """
+        pass
+
+    def setup(self) -> None:
+        """
+        Initialize the camera hardware.
+        Called once before capturing starts.
+        Override in subclass if needed.
+        """
+        pass
+
+    def cleanup(self) -> None:
+        """
+        Clean up camera resources.
+        Called when camera is stopped.
+        Override in subclass if needed.
+        """
+        pass
+
+    def is_available(self) -> bool:
+        """
+        Check if the camera is connected and responding.
+
+        Returns:
+            True if camera is available.
+        """
+        try:
+            frame = self.capture()
+            return frame is not None
+        except Exception:
+            return False
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get camera information for display."""
+        return {
+            "camera_id": self.camera_id,
+            "name": self.name,
+            "description": self.description,
+            "frame_rate": self.frame_rate,
+            "resolution": list(self.resolution),
+            "quality": self.quality,
+            "available": self.is_available(),
+        }
+
+
+class CameraHub:
+    """
+    Manages multiple cameras.
+
+    Usage:
+        from plexus.cameras import CameraHub, USBCamera
+
+        hub = CameraHub()
+        hub.add(USBCamera(device_index=0))
+        hub.add(USBCamera(device_index=1))
+
+        # Capture from all cameras
+        frames = hub.capture_all()
+    """
+
+    def __init__(self):
+        self.cameras: List[BaseCamera] = []
+
+    def add(self, camera: BaseCamera) -> "CameraHub":
+        """Add a camera to the hub."""
+        self.cameras.append(camera)
+        return self
+
+    def remove(self, camera: BaseCamera) -> "CameraHub":
+        """Remove a camera from the hub."""
+        self.cameras.remove(camera)
+        return self
+
+    def setup(self) -> None:
+        """Initialize all cameras."""
+        for camera in self.cameras:
+            try:
+                camera.setup()
+            except Exception as e:
+                logger.warning(f"Failed to setup {camera.name}: {e}")
+                camera._error = str(e)
+
+    def cleanup(self) -> None:
+        """Clean up all cameras."""
+        for camera in self.cameras:
+            try:
+                camera.cleanup()
+            except Exception:
+                pass
+
+    def capture_all(self) -> List[CameraFrame]:
+        """Capture from all cameras once."""
+        frames = []
+        for camera in self.cameras:
+            try:
+                frame = camera.capture()
+                if frame:
+                    frames.append(frame)
+            except Exception as e:
+                camera._error = str(e)
+        return frames
+
+    def get_camera(self, camera_id: str) -> Optional[BaseCamera]:
+        """Get a camera by ID."""
+        for camera in self.cameras:
+            if camera.camera_id == camera_id:
+                return camera
+        return None
+
+    def get_info(self) -> List[Dict[str, Any]]:
+        """Get info about all cameras."""
+        return [c.get_info() for c in self.cameras]
+

plexus/cameras/picamera.py

@@ -0,0 +1,171 @@
+"""
+Raspberry Pi Camera Module driver using picamera2.
+
+Supports Pi Camera Module v1, v2, v3, and HQ Camera.
+"""
+
+import logging
+import time
+from typing import Optional, Tuple
+
+from plexus.cameras.base import BaseCamera, CameraFrame
+
+logger = logging.getLogger(__name__)
+
+# picamera2 is optional - only imported when PiCamera is used
+try:
+    from picamera2 import Picamera2
+    import io
+    PICAMERA_AVAILABLE = True
+except ImportError:
+    PICAMERA_AVAILABLE = False
+
+
+class PiCamera(BaseCamera):
+    """
+    Raspberry Pi Camera Module driver using picamera2.
+
+    Works with Pi Camera Module v1, v2, v3, and HQ Camera on
+    Raspberry Pi devices running Raspberry Pi OS.
+
+    Usage:
+        from plexus.cameras import PiCamera
+
+        camera = PiCamera(camera_num=0)
+        camera.setup()
+        frame = camera.capture()
+        camera.cleanup()
+    """
+
+    name = "Pi Camera"
+    description = "Raspberry Pi Camera Module via picamera2"
+
+    def __init__(
+        self,
+        camera_num: int = 0,
+        frame_rate: float = 30.0,
+        resolution: Tuple[int, int] = (1280, 720),
+        quality: int = 85,
+        camera_id: Optional[str] = None,
+        **kwargs,
+    ):
+        """
+        Initialize Pi Camera driver.
+
+        Args:
+            camera_num: Camera number (0 = first camera, 1 = second, etc.)
+            frame_rate: Target frames per second. Default 30 fps.
+            resolution: (width, height) tuple. Default (1280, 720).
+            quality: JPEG quality 1-100. Default 85.
+            camera_id: Unique identifier. Defaults to "picam:{camera_num}".
+        """
+        if not PICAMERA_AVAILABLE:
+            raise ImportError(
+                "picamera2 is required for Pi Camera support. "
+                "Install with: pip install plexus-python[picamera]"
+            )
+
+        super().__init__(
+            frame_rate=frame_rate,
+            resolution=resolution,
+            quality=quality,
+            camera_id=camera_id or f"picam:{camera_num}",
+            **kwargs,
+        )
+        self.camera_num = camera_num
+        self._picam: Optional[Picamera2] = None
+
+    def setup(self) -> None:
+        """Initialize the camera."""
+        if self._picam is not None:
+            self.cleanup()
+        self._picam = Picamera2(camera_num=self.camera_num)
+
+        # Configure for still capture with specified resolution
+        config = self._picam.create_still_configuration(
+            main={"size": self.resolution, "format": "RGB888"},
+        )
+        self._picam.configure(config)
+        self._picam.start()
+
+    def cleanup(self) -> None:
+        """Stop and close the camera."""
+        if self._picam is not None:
+            self._picam.stop()
+            self._picam.close()
+            self._picam = None
+
+    def capture(self) -> Optional[CameraFrame]:
+        """
+        Capture a single frame.
+
+        Returns:
+            CameraFrame with JPEG-encoded image, or None if capture failed.
+        """
+        if self._picam is None:
+            self.setup()
+
+        try:
+            # Capture to numpy array
+            frame = self._picam.capture_array()
+
+            if frame is None:
+                return None
+
+            # Encode to JPEG using OpenCV if available, otherwise use PIL
+            try:
+                import cv2
+                encode_params = [cv2.IMWRITE_JPEG_QUALITY, self.quality]
+                # Convert RGB to BGR for OpenCV
+                frame_bgr = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
+                success, jpeg_data = cv2.imencode('.jpg', frame_bgr, encode_params)
+                if not success:
+                    return None
+                data = jpeg_data.tobytes()
+            except ImportError:
+                # Fallback to PIL
+                from PIL import Image
+                img = Image.fromarray(frame)
+                buffer = io.BytesIO()
+                img.save(buffer, format='JPEG', quality=self.quality)
+                data = buffer.getvalue()
+
+            return CameraFrame(
+                data=data,
+                width=frame.shape[1],
+                height=frame.shape[0],
+                timestamp=time.time(),
+                camera_id=self.camera_id,
+                tags=self.tags.copy(),
+            )
+
+        except Exception as e:
+            logger.debug(f"Pi camera capture failed: {e}")
+            return None
+
+    def is_available(self) -> bool:
+        """Check if camera is available."""
+        if not PICAMERA_AVAILABLE:
+            return False
+
+        try:
+            camera_info = Picamera2.global_camera_info()
+            return len(camera_info) > self.camera_num
+        except Exception:
+            return False
+
+    def get_info(self) -> dict:
+        """Get camera information."""
+        info = super().get_info()
+        info["camera_num"] = self.camera_num
+
+        # Get model info if available
+        if PICAMERA_AVAILABLE:
+            try:
+                camera_info = Picamera2.global_camera_info()
+                if len(camera_info) > self.camera_num:
+                    info["model"] = camera_info[self.camera_num].get("Model", "Unknown")
+            except Exception:
+                pass
+
+        return info

plexus/cameras/usb.py

@@ -0,0 +1,143 @@
+"""
+USB webcam driver using OpenCV.
+
+Supports any camera compatible with cv2.VideoCapture (USB webcams, built-in cameras).
+"""
+
+import time
+from typing import Optional, Tuple
+
+from plexus.cameras.base import BaseCamera, CameraFrame
+
+# OpenCV is optional - only imported when USBCamera is used
+try:
+    import cv2
+    OPENCV_AVAILABLE = True
+except ImportError:
+    OPENCV_AVAILABLE = False
+
+
+class USBCamera(BaseCamera):
+    """
+    USB webcam driver using OpenCV VideoCapture.
+
+    Works with USB webcams, built-in laptop cameras, and other
+    video capture devices supported by OpenCV.
+
+    Usage:
+        from plexus.cameras import USBCamera
+
+        camera = USBCamera(device_index=0)
+        camera.setup()
+        frame = camera.capture()
+        camera.cleanup()
+    """
+
+    name = "USB Camera"
+    description = "USB webcam via OpenCV VideoCapture"
+
+    def __init__(
+        self,
+        device_index: int = 0,
+        frame_rate: float = 15.0,
+        resolution: Tuple[int, int] = (640, 480),
+        quality: int = 80,
+        camera_id: Optional[str] = None,
+        **kwargs,
+    ):
+        """
+        Initialize USB camera driver.
+
+        Args:
+            device_index: Camera device index (0 = first camera, 1 = second, etc.)
+            frame_rate: Target frames per second. Default 15 fps.
+            resolution: (width, height) tuple. Default (640, 480).
+            quality: JPEG quality 1-100. Default 80.
+            camera_id: Unique identifier. Defaults to "usb:{device_index}".
+        """
+        if not OPENCV_AVAILABLE:
+            raise ImportError(
+                "OpenCV is required for USB camera support. "
+                "Install with: pip install plexus-python[camera]"
+            )
+
+        super().__init__(
+            frame_rate=frame_rate,
+            resolution=resolution,
+            quality=quality,
+            camera_id=camera_id or f"usb:{device_index}",
+            **kwargs,
+        )
+        self.device_index = device_index
+        self._cap: Optional[cv2.VideoCapture] = None
+
+    def setup(self) -> None:
+        """Initialize the camera."""
+        self._cap = cv2.VideoCapture(self.device_index)
+
+        if not self._cap.isOpened():
+            raise RuntimeError(f"Failed to open camera at index {self.device_index}")
+
+        # Set resolution
+        self._cap.set(cv2.CAP_PROP_FRAME_WIDTH, self.resolution[0])
+        self._cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self.resolution[1])
+
+        # Set frame rate if supported
+        self._cap.set(cv2.CAP_PROP_FPS, self.frame_rate)
+
+        # Read actual values (camera may not support requested settings)
+        actual_width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        actual_height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        self.resolution = (actual_width, actual_height)
+
+    def cleanup(self) -> None:
+        """Release the camera."""
+        if self._cap is not None:
+            self._cap.release()
+            self._cap = None
+
+    def capture(self) -> Optional[CameraFrame]:
+        """
+        Capture a single frame.
+
+        Returns:
+            CameraFrame with JPEG-encoded image, or None if capture failed.
+        """
+        if self._cap is None:
+            self.setup()
+
+        ret, frame = self._cap.read()
+        if not ret or frame is None:
+            return None
+
+        # Encode to JPEG
+        encode_params = [cv2.IMWRITE_JPEG_QUALITY, self.quality]
+        success, jpeg_data = cv2.imencode('.jpg', frame, encode_params)
+
+        if not success:
+            return None
+
+        return CameraFrame(
+            data=jpeg_data.tobytes(),
+            width=frame.shape[1],
+            height=frame.shape[0],
+            timestamp=time.time(),
+            camera_id=self.camera_id,
+            tags=self.tags.copy(),
+        )
+
+    def is_available(self) -> bool:
+        """Check if camera is available without fully initializing."""
+        if not OPENCV_AVAILABLE:
+            return False
+
+        cap = cv2.VideoCapture(self.device_index)
+        available = cap.isOpened()
+        cap.release()
+        return available
+
+    def get_info(self) -> dict:
+        """Get camera information."""
+        info = super().get_info()
+        info["device_index"] = self.device_index
+        return info