meteor_detect/docs/camera_module.md

Camera 模块使用文档

概述

Camera 模块是一个完整的相机控制和管理系统，提供了高级API用于配置、捕获、存储和处理相机帧。该模块主要用于天文观测系统，特别是流星检测，但它的设计足够灵活，可以用于任何需要视频捕获和处理的应用。

模块主要功能包括：

• 相机设备初始化和配置
• 实时视频流捕获
• 高效的帧缓冲管理
• 视频事件存储和处理
• 相机健康监控

核心组件

1. CameraController

CameraController 是主要的控制接口，它管理相机的整个生命周期和操作流程。

主要特性：

• 初始化和配置相机设备
• 启动和停止视频流捕获
• 管理帧缓冲
• 提供帧订阅机制
• 保存流星事件和相关视频
• 监控相机健康状态

2. OpenCVCamera

OpenCVCamera 是相机硬件的具体驱动实现，基于OpenCV库。

主要特性：

• 支持各种相机设备（通过路径或索引）
• 配置相机分辨率、帧率、曝光和增益
• 控制相机聚焦
• 视频流管理

3. Frame 和 FrameBuffer

Frame 表示单个捕获的视频帧，包含图像数据、时间戳和元数据。

FrameBuffer 是一个高效的循环缓冲区，用于存储最近捕获的视频帧。

主要特性：

• 管理固定容量的帧缓冲
• 提供索引和时间范围的帧检索
• 提取特定事件周围的帧

关键数据结构

CameraSettings

pub struct CameraSettings {
    pub device: String,        // 相机设备路径或索引
    pub resolution: Resolution, // 分辨率设置
    pub fps: u32,              // 每秒帧数
    pub exposure: ExposureMode, // 曝光模式
    pub gain: u8,              // 增益/ISO设置 (0-255)
    pub focus_locked: bool,    // 是否锁定无限远焦点
}

Resolution

pub enum Resolution {
    HD1080p,                   // 1920x1080
    HD720p,                    // 1280x720
    VGA,                       // 640x480
    Custom {                   // 自定义分辨率
        width: u32,
        height: u32,
    },
}

ExposureMode

pub enum ExposureMode {
    Auto,                      // 自动曝光控制
    Manual(u32),               // 手动曝光控制，以微秒为单位
}

MeteorEvent

pub struct MeteorEvent {
    pub id: uuid::Uuid,        // 事件唯一标识符
    pub timestamp: DateTime<Utc>, // 事件检测时间戳
    pub confidence: f32,       // 置信度分数 (0.0-1.0)
    pub bounding_box: (u32, u32, u32, u32), // 图像中的坐标 (左上x, 左上y, 宽度, 高度)
    pub video_path: String,    // 保存的视频剪辑路径
}

使用流程

典型的使用流程包括以下步骤：

1. 创建和配置相机控制器
2. 初始化相机设备
3. 启动视频捕获
4. 订阅帧更新（可选）
5. 处理捕获的帧
6. 保存检测到的事件
7. 停止捕获并清理资源

示例代码

请参考 examples/camera_demo.rs 示例，了解更详细的使用方法。

注意事项

1. 设备兼容性：该模块主要支持Linux和macOS上的相机设备。在其他平台上可能需要额外的配置。

2. 资源管理：由于视频捕获可能消耗大量内存，特别是在高分辨率和高帧率下，请确保合理配置帧缓冲区大小。

3. 依赖项：该模块依赖于OpenCV库进行图像处理和视频捕获，请确保系统已正确安装相应的依赖项。

4. 错误恢复：模块包含错误检测和恢复机制，但在关键应用中仍应实施额外的监控和故障恢复策略。

5. 性能考虑：考虑系统资源限制，特别是在嵌入式设备上，应谨慎选择分辨率、帧率和缓冲区大小。

高级特性

帧订阅

模块使用tokio的广播通道实现了实时帧通知机制：

// 订阅帧更新
let mut frame_receiver = camera_controller.subscribe_to_frames();

// 在单独的任务中处理帧
tokio::spawn(async move {
    while let Ok(frame) = frame_receiver.recv().await {
        // 处理新帧
    }
});

事件存储

当检测到流星时，可以保存相关视频剪辑：

let event = camera_controller.save_meteor_event(
    timestamp,      // 事件发生时间
    0.95,           // 置信度
    (100, 200, 50, 30), // 边界框 (x, y, 宽度, 高度)
    5,              // 事件前5秒
    3               // 事件后3秒
).await?;

健康监控

可以使用健康检查功能监控相机状态：

let is_healthy = camera_controller.check_health().await?;
if !is_healthy {
    // 实施恢复策略
}

故障排除

常见问题

1. 无法打开相机设备

   • 检查设备路径或索引是否正确
   • 确认设备有适当的访问权限
   • 验证设备未被其他应用程序使用

2. 分辨率/帧率设置无效

   • 不是所有相机都支持所有分辨率和帧率组合
   • 检查相机规格和支持的格式
   • 使用更保守的值或尝试自定义分辨率

3. 帧捕获停止或间歇性失败

   • 可能是相机硬件问题
   • 检查USB连接或电源问题
   • 考虑重新初始化或重启相机

4. 内存使用过高

   • 减小帧缓冲区容量
   • 降低分辨率或帧率
   • 确保正确处理和释放不再需要的帧

诊断工具

使用get_status()方法获取详细的相机状态信息：

let status = camera_controller.get_status().await?;
println!("Camera status: {}", status);

性能优化建议

1. 根据实际需求选择分辨率，无需使用高于实际需要的分辨率
2. 仅在必要时处理帧，避免冗余的图像处理操作
3. 使用帧订阅机制进行异步处理，避免阻塞主循环
4. 在资源受限的系统上，考虑使用区域感兴趣(ROI)处理帧子区域
5. 对于长时间运行的应用，定期检查健康状态并实施自动恢复机制