# Camera 模块使用文档

## 概述

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

模块主要功能包括：
- 相机设备初始化和配置
- 实时视频流捕获
- 高效的帧缓冲管理
- 视频事件存储和处理
- 相机健康监控

## 核心组件

### 1. CameraController

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

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

### 2. OpenCVCamera 

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

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

### 3. Frame 和 FrameBuffer

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

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

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

## 关键数据结构

### CameraSettings

```rust
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

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

### ExposureMode

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

### MeteorEvent

```rust
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的广播通道实现了实时帧通知机制：

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

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

### 事件存储

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

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

### 健康监控

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

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

## 故障排除

### 常见问题

1. **无法打开相机设备**
   - 检查设备路径或索引是否正确
   - 确认设备有适当的访问权限
   - 验证设备未被其他应用程序使用

2. **分辨率/帧率设置无效**
   - 不是所有相机都支持所有分辨率和帧率组合
   - 检查相机规格和支持的格式
   - 使用更保守的值或尝试自定义分辨率

3. **帧捕获停止或间歇性失败**
   - 可能是相机硬件问题
   - 检查USB连接或电源问题
   - 考虑重新初始化或重启相机

4. **内存使用过高**
   - 减小帧缓冲区容量
   - 降低分辨率或帧率
   - 确保正确处理和释放不再需要的帧

### 诊断工具

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

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

## 性能优化建议

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