mecha10_controllers/

camera.rs

//! Camera controller trait and types

use crate::Controller;
use async_trait::async_trait;
use mecha10_core::sensor::{CameraInfo, DepthImage, RgbImage};
use serde::{Deserialize, Serialize};

/// Camera controller trait
///
/// Provides a unified interface for different camera types including:
/// - RGB cameras (webcams, CSI cameras)
/// - Depth cameras (RealSense, structured light)
/// - RGBD cameras (RealSense D400 series)
/// - Network cameras (RTSP streams)
#[async_trait]
pub trait CameraController: Controller {
    /// Frame type produced by this camera
    type Frame: Send + Sync;

    /// Capture a single frame from the camera
    ///
    /// This will block until a frame is available or an error occurs.
    async fn capture_frame(&mut self) -> Result<Self::Frame, Self::Error>;

    /// Get camera intrinsics if available
    ///
    /// Returns calibration data including focal length, principal point,
    /// and distortion coefficients. May return None if not calibrated.
    fn intrinsics(&self) -> Option<CameraIntrinsics>;

    /// Set camera parameters
    ///
    /// Adjust camera settings like exposure, gain, white balance, etc.
    /// Not all parameters may be supported by all cameras.
    async fn set_parameters(&mut self, params: CameraParameters) -> Result<(), Self::Error>;

    /// Get current camera parameters
    async fn get_parameters(&self) -> Result<CameraParameters, Self::Error>;

    /// Get camera information
    fn info(&self) -> CameraInfo;

    /// Check if the camera supports depth
    fn supports_depth(&self) -> bool {
        self.capabilities().features.get("depth").copied().unwrap_or(false)
    }

    /// Check if the camera supports infrared
    fn supports_infrared(&self) -> bool {
        self.capabilities().features.get("infrared").copied().unwrap_or(false)
    }
}

// ============================================================================
// Camera Types
// ============================================================================

/// Camera frame types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum CameraFrame {
    /// RGB color image only
    Rgb(RgbImage),

    /// Depth image only
    Depth(DepthImage),

    /// Combined RGB + Depth (RGBD cameras)
    Rgbd {
        color: RgbImage,
        depth: DepthImage,
        aligned: bool,
    },

    /// Infrared image
    Infrared {
        timestamp: u64,
        frame_id: u64,
        width: u32,
        height: u32,
        data: Vec<u8>,
    },
}

/// Camera intrinsics (calibration parameters)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CameraIntrinsics {
    /// Image width in pixels
    pub width: u32,

    /// Image height in pixels
    pub height: u32,

    /// Focal length in X (pixels)
    pub fx: f64,

    /// Focal length in Y (pixels)
    pub fy: f64,

    /// Principal point X (pixels)
    pub cx: f64,

    /// Principal point Y (pixels)
    pub cy: f64,

    /// Distortion coefficients [k1, k2, p1, p2, k3]
    pub distortion: Vec<f64>,

    /// Distortion model ("plumb_bob", "fisheye", etc.)
    pub distortion_model: String,
}

impl Default for CameraIntrinsics {
    fn default() -> Self {
        Self {
            width: 640,
            height: 480,
            fx: 500.0,
            fy: 500.0,
            cx: 320.0,
            cy: 240.0,
            distortion: vec![0.0; 5],
            distortion_model: "plumb_bob".to_string(),
        }
    }
}

/// Camera parameters that can be adjusted
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CameraParameters {
    /// Auto exposure enabled
    pub auto_exposure: Option<bool>,

    /// Exposure time in microseconds (if manual exposure)
    pub exposure_us: Option<u32>,

    /// Auto white balance enabled
    pub auto_white_balance: Option<bool>,

    /// White balance temperature in Kelvin (if manual)
    pub white_balance_k: Option<u32>,

    /// Gain (0.0 - 1.0)
    pub gain: Option<f32>,

    /// Brightness (0.0 - 1.0)
    pub brightness: Option<f32>,

    /// Contrast (0.0 - 1.0)
    pub contrast: Option<f32>,

    /// Saturation (0.0 - 1.0)
    pub saturation: Option<f32>,

    /// Sharpness (0.0 - 1.0)
    pub sharpness: Option<f32>,

    /// Gamma (0.0 - 1.0)
    pub gamma: Option<f32>,

    /// Frame rate (fps)
    pub frame_rate: Option<u32>,

    /// Enable depth post-processing filters (for depth cameras)
    pub depth_filtering: Option<bool>,

    /// Depth units in meters per unit
    pub depth_scale: Option<f32>,
}

// ============================================================================
// Helper Types
// ============================================================================

/// Camera streaming state
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum CameraStreamState {
    /// Camera is not streaming
    Stopped,

    /// Camera is streaming
    Streaming,

    /// Camera stream is paused
    Paused,

    /// Camera encountered an error
    Error,
}

/// Camera resolution
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Resolution {
    pub width: u32,
    pub height: u32,
}

impl Resolution {
    pub fn new(width: u32, height: u32) -> Self {
        Self { width, height }
    }

    /// VGA resolution (640x480)
    pub const VGA: Self = Self {
        width: 640,
        height: 480,
    };

    /// HD resolution (1280x720)
    pub const HD: Self = Self {
        width: 1280,
        height: 720,
    };

    /// Full HD resolution (1920x1080)
    pub const FULL_HD: Self = Self {
        width: 1920,
        height: 1080,
    };

    /// 4K resolution (3840x2160)
    pub const UHD_4K: Self = Self {
        width: 3840,
        height: 2160,
    };
}

/// Pixel format
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PixelFormat {
    /// 8-bit RGB
    Rgb8,

    /// 8-bit RGBA
    Rgba8,

    /// 8-bit BGR
    Bgr8,

    /// 8-bit BGRA
    Bgra8,

    /// Grayscale 8-bit
    Gray8,

    /// Grayscale 16-bit
    Gray16,

    /// Motion JPEG
    Mjpeg,

    /// H.264
    H264,

    /// YUV 4:2:2
    Yuyv,
}