210 lines
5.8 KiB
Markdown
210 lines
5.8 KiB
Markdown
# 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. 对于长时间运行的应用，定期检查健康状态并实施自动恢复机制
|