# 流星探测器配置指南

本文档详细介绍了如何配置和选择使用不同的流星探测器。系统支持两种类型的探测器：

1. **亮度探测器 (BrightnessDetector)** - 基于帧间亮度对比的简单探测器
2. **CAMS探测器 (CamsDetector)** - 基于CAMS FTP格式的帧堆叠探测器

## 亮度探测器 (BrightnessDetector)

亮度探测器通过分析连续视频帧之间的亮度变化来检测流星。当亮度变化超过特定阈值且持续一定的帧数时，它会触发检测事件。

### 配置参数

亮度探测器有以下配置参数：

| 参数                  | 类型  | 默认值 | 说明                                  |
|-----------------------|-------|--------|-------------------------------------|
| `min_brightness_delta` | f32  | 30.0   | 最小亮度变化阈值 (0-255)              |
| `min_pixel_change`     | u32  | 10     | 触发检测的最小像素变化数              |
| `min_frames`           | u32  | 3      | 最小连续帧数要求                      |
| `sensitivity`          | f32  | 0.7    | 灵敏度系数 (0.0-1.0)                 |
| `id`                   | String | 自动生成 | 探测器唯一标识                   |

### 参数建议

1. **城市光害环境**:
   - `min_brightness_delta`: 40-50 (更高的阈值减少误报)
   - `min_pixel_change`: 15-20 
   - `min_frames`: 4-5 (更多帧确认减少闪光和噪声误报)
   - `sensitivity`: 0.6-0.7

2. **郊外黑暗环境**:
   - `min_brightness_delta`: 20-30 (较低的阈值捕获较暗的流星)
   - `min_pixel_change`: 8-10
   - `min_frames`: 2-3 (较少帧确认捕获快速流星)
   - `sensitivity`: 0.8-0.9

### 适用场景

亮度探测器适合以下场景：
- 资源受限的设备（如树莓派）
- 需要实时检测的场景
- 检测明亮、快速的流星
- 当系统内存有限，无法进行256帧的堆叠时

## CAMS探测器 (CamsDetector)

CAMS探测器基于CAMS (Cameras for Allsky Meteor Surveillance) FTP格式，通过收集256帧视频并生成4种特征图像（maxpixel、avepixel、stdpixel、maxframe）来检测流星。这种方法可以检测出非常暗的流星，但需要更多的计算资源和内存。

### 配置参数

CAMS探测器有以下配置参数：

| 参数                        | 类型    | 默认值 | 说明                               |
|-----------------------------|---------|--------|----------------------------------|
| `brightness_threshold`       | u8      | 30     | maxpixel图像亮度阈值 (0-255)       |
| `std_to_avg_ratio_threshold` | f32     | 1.5    | stdpixel与avepixel的比率阈值       |
| `min_pixel_count`            | u32     | 10     | 满足条件的最小像素数               |
| `min_trajectory_length`      | u32     | 5      | 最小轨迹长度                       |
| `save_all_feature_images`    | bool    | false  | 是否保存所有特征图像（不仅是检测到的） |
| `output_dir`                 | PathBuf | "output" | 输出目录                         |
| `file_prefix`                | String  | "meteor" | 文件前缀                         |
| `id`                         | String  | 自动生成 | 探测器唯一标识                   |

### 参数建议

1. **城市光害环境**:
   - `brightness_threshold`: 35-45
   - `std_to_avg_ratio_threshold`: 1.8-2.0 (更高的比率减少光害影响)
   - `min_pixel_count`: 12-15
   - `min_trajectory_length`: 6-8

2. **郊外黑暗环境**:
   - `brightness_threshold`: 20-30
   - `std_to_avg_ratio_threshold`: 1.3-1.5
   - `min_pixel_count`: 8-10
   - `min_trajectory_length`: 4-5

### 适用场景

CAMS探测器适合以下场景：
- 资源充足的设备（如台式机或高性能单板机）
- 科学研究级别的流星检测
- 需要检测暗弱流星的场景
- 对检测准确性要求较高的场景

## 在配置文件中设置探测器

可以在`config.toml`文件中配置探测管道及其使用的探测器：

```toml
# 基本检测参数（用于兼容老版本）
[detection]
min_brightness_delta = 30.0
min_pixel_change = 10
min_frames = 3
event_buffer_seconds = 10
sensitivity = 0.7

# 探测管道配置
[detection.pipeline]
max_parallel_workers = 4
# 聚合策略：any (任一探测器), all (所有探测器), majority (多数探测器)
aggregation_strategy = "any"  

# 亮度探测器配置
[[detection.pipeline.detectors]]
type = "brightness"
min_brightness_delta = 30.0
min_pixel_change = 10
min_frames = 3
sensitivity = 0.7
id = "brightness-main"

# CAMS探测器配置
[[detection.pipeline.detectors]]
type = "cams"
brightness_threshold = 30
std_to_avg_ratio_threshold = 1.5
min_pixel_count = 10
min_trajectory_length = 5
save_all_feature_images = false
output_dir = "output/cams"
file_prefix = "meteor"
id = "cams-main"
```

## 在命令行中使用示例程序

示例程序`cams_detector_demo`提供了一个灵活的命令行界面，可以测试不同的探测器：

```bash
# 使用亮度探测器
cargo run --example cams_detector_demo -- \
    --input your_video.mp4 \
    --detector brightness \
    --min-brightness-delta 35.0 \
    --min-pixel-change 12 \
    --min-frames 4 \
    --sensitivity 0.8 \
    --display

# 使用CAMS探测器
cargo run --example cams_detector_demo -- \
    --input your_video.mp4 \
    --detector cams \
    --brightness-threshold 30 \
    --std-ratio-threshold 1.5 \
    --min-pixel-count 10 \
    --min-trajectory-length 5 \
    --save-all \
    --display

# 同时使用两种探测器（并行处理）
cargo run --example cams_detector_demo -- \
    --input your_video.mp4 \
    --detector both \
    --parallel \
    --aggregation majority \
    --display
```

## 如何选择探测器

以下是选择探测器的建议：

1. **根据硬件资源**:
   - 对于资源受限的设备（如树莓派），优先使用亮度探测器
   - 对于高性能设备，可以使用CAMS探测器或同时使用两者

2. **根据观测环境**:
   - 在光污染严重的城市环境，亮度探测器可能产生较多误报，CAMS探测器更稳定
   - 在暗黑的郊外环境，两种探测器都能有效工作

3. **根据探测目标**:
   - 如果主要关注明亮的火流星，亮度探测器足够
   - 如果希望捕获微弱流星或进行科学统计，CAMS探测器更合适

4. **最佳做法**:
   - 如果资源允许，建议同时使用两种探测器并设置为"any"聚合策略提高捕获率
   - 如果需要减少误报，可以设置为"all"聚合策略
   - 使用"majority"策略在增加更多探测器时提供平衡

## 检查当前配置

可以查看系统日志了解当前使用的探测器配置：

```bash
# 查看日志中的探测器信息
grep "detector" meteor_detect.log

# 运行示例程序时使用更详细的日志级别
RUST_LOG=debug cargo run --example cams_detector_demo -- --input video.mp4
```

也可以编写一个简单的脚本来检查当前配置：

```rust
// 打印当前探测器配置
for detector in pipeline.get_detector_configs() {
    match detector {
        DetectorConfig::Brightness(params) => {
            println!("Brightness detector: {}", params.id);
            println!("  min_brightness_delta: {}", params.min_brightness_delta);
            println!("  min_pixel_change: {}", params.min_pixel_change);
            println!("  min_frames: {}", params.min_frames);
            println!("  sensitivity: {}", params.sensitivity);
        },
        DetectorConfig::Cams(params) => {
            println!("CAMS detector: {}", params.id);
            println!("  brightness_threshold: {}", params.brightness_threshold);
            println!("  std_to_avg_ratio_threshold: {}", params.std_to_avg_ratio_threshold);
            println!("  min_pixel_count: {}", params.min_pixel_count);
            println!("  min_trajectory_length: {}", params.min_trajectory_length);
        }
    }
}