grabbit/meteor_detection_system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update project documentation with Vida detection algorithm

Browse Source 
- Add comprehensive Vida detection algorithm documentation to CLAUDE.md
  - Detection architecture overview
  - Core module descriptions with line counts
  - Detection parameters (FireballDetector K1=4, MeteorDetector K1=1.5)
  - FTP compression format explanation
  - Detection pipeline workflow
  - Performance benchmarks (~100ms/block)

- Rewrite README.md with clearer structure
  - Add system architecture diagram
  - Add project structure table
  - Add quick start guide
  - Add Vida detection algorithm summary
  - Organize development commands by component

- Update TESTING.md
  - Add edge client testing section
  - Add Vida detection test commands
  - Add memory management test commands
  - Update version to 2.0.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
grabbit 2026-01-07 01:03:59 +08:00
parent 038f664449
commit 6c846976f5
3 changed files with 244 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
CLAUDE.md
View File

@ -77,6 +77,10 @@ cargo build --release # Native build
cargo build --target=aarch64-unknown-linux-gnu # ARM64 build for Pi cargo build --target=aarch64-unknown-linux-gnu # ARM64 build for Pi
./build.sh # Cross-compile for Raspberry Pi ./build.sh # Cross-compile for Raspberry Pi
# Vida Meteor Detection Testing
./target/debug/meteor-edge-client test-vida <video.mp4> # Test Vida detection on video
./target/debug/meteor-edge-client run --camera file:video.mp4 # Run with video file
# Advanced Memory Management Testing # Advanced Memory Management Testing
./target/debug/meteor-edge-client test # Core frame pool tests ./target/debug/meteor-edge-client test # Core frame pool tests
./target/debug/meteor-edge-client test-adaptive # Adaptive pool management ./target/debug/meteor-edge-client test-adaptive # Adaptive pool management
@ -382,16 +386,11 @@ Camera Features:
- Health monitoring with diagnostic recommendations - Health monitoring with diagnostic recommendations
#### Real-Time Meteor Detection Pipeline #### Real-Time Meteor Detection Pipeline
- **Multi-Algorithm Detection**: Brightness, motion, background subtraction algorithms - **Vida Algorithm**: Scientific meteor detection based on Vida et al. 2016 paper
- **Consensus-Based Detection**: Combines multiple algorithms for higher accuracy - **Dual Detection Paths**: FireballDetector (K1=4) and MeteorDetector (K1=1.5)
- **FTP Compression**: 256 frames → 4 statistical images (maxpixel, avepixel, stdpixel, maxframe)
- **Memory-Optimized Processing**: Integrated with zero-copy architecture - **Memory-Optimized Processing**: Integrated with zero-copy architecture
- **Real-Time Performance**: Sub-30ms processing latency for real-time detection - **Real-Time Performance**: ~100ms/block processing latency
Detection Algorithms:
- **Brightness Detector**: Threshold-based detection for bright meteors
- **Motion Detector**: Optical flow analysis for movement detection
- **Background Subtraction**: Adaptive background modeling for change detection
- **Consensus Detector**: Weighted algorithm combination for improved accuracy
#### Production-Ready Features #### Production-Ready Features
- **Raspberry Pi Optimization**: Conservative memory usage and CPU utilization - **Raspberry Pi Optimization**: Conservative memory usage and CPU utilization
@ -412,4 +411,92 @@ This advanced memory management system enables the meteor edge client to:
2. Adapt to varying system memory conditions automatically 2. Adapt to varying system memory conditions automatically
3. Provide production-grade observability and monitoring 3. Provide production-grade observability and monitoring
4. Maintain high performance on resource-constrained Raspberry Pi devices 4. Maintain high performance on resource-constrained Raspberry Pi devices
5. Support real-time meteor detection with sub-millisecond processing latency 5. Support real-time meteor detection with sub-millisecond processing latency
## Vida Meteor Detection Algorithm (Edge Client)
The edge client implements the Vida detection algorithm based on *"Open-source meteor detection software for low-cost single-board computers"* (Vida et al., 2016). This is the same algorithm used by the Croatian Meteor Network (CMN) and RMS project.
### Architecture Overview
```
输入帧流 (视频/摄像头)
↓
[FrameAccumulator] - 256帧 FTP 压缩
↓
[AccumulatedFrame] - maxpixel, avepixel, stdpixel, maxframe
├─→ [FireballDetector] - K1=4, 3D点云分析 → 火球检测
└─→ [MeteorDetector] - K1=1.5, Hough变换 → 流星检测
↓
[VidaDetectionController] - 协调和回调
↓
[FtpDetectWriter] - FTPdetectinfo 格式输出
```
### Core Modules (`src/detection/vida/`)
| 模块 | 功能 | 代码行数 |
|------|------|----------|
| `frame_accumulator.rs` | FTP 压缩引擎 | ~1200 |
| `accumulated_frame.rs` | FTP 数据结构 | ~700 |
| `fireball_detector.rs` | 火球检测 (K1=4) | ~800 |
| `meteor_detector.rs` | 流星检测 (K1=1.5) | ~1000 |
| `line_detector.rs` | Hough + 3D 线检测 | ~800 |
| `morphology.rs` | 形态学预处理 | ~950 |
| `star_extractor.rs` | 星点提取和天空质量 | ~1000 |
| `calibration.rs` | 测量校准 | ~1000 |
| `ftpdetect.rs` | FTPdetectinfo 输出 | ~450 |
| `controller.rs` | 主控制器 | ~470 |
| `config.rs` | 配置管理 | ~375 |
### Detection Parameters
**FireballDetector** (明亮火球):
- `k1_threshold`: 4.0 (标准差倍数)
- `min_intensity`: 40 (最小像素强度)
- 使用 3D 点云分析
**MeteorDetector** (普通流星):
- `k1_threshold`: 1.5 (标准差倍数，RMS 推荐)
- `j1_offset`: 9.0 (绝对强度偏移)
- `max_white_ratio`: 0.07 (最大白像素比例)
- 使用 Hough 变换 + 时间窗口
### FTP Compression Format
256帧压缩为4个统计图像：
- **maxpixel**: 每像素最大值 (流星轨迹可见)
- **avepixel**: 平均值 (排除前4大值，天空背景)
- **stdpixel**: 标准差 (变化区域)
- **maxframe**: 最大值出现的帧号 (时间信息)
### Detection Pipeline
1. **帧累积**: 收集256帧，实时计算统计
2. **阈值化**: 应用 K1×σ + J1 阈值
3. **形态学处理**: 清理 → 桥接 → 闭合 → 细化
4. **线检测**: Hough变换(2D) 或 点云分析(3D)
5. **时间传播**: 7个重叠窗口验证
6. **质心提取**: 亚像素精度定位
7. **输出**: FTPdetectinfo 格式
### Testing Commands
```bash
cd meteor-edge-client
# 在视频文件上测试 Vida 检测
./target/debug/meteor-edge-client test-vida video.mp4
# 使用摄像头运行
./target/debug/meteor-edge-client run --camera device:0
# 使用视频文件运行
./target/debug/meteor-edge-client run --camera file:video.mp4
```
### Performance
- **处理速度**: ~100ms/block (256帧)
- **误检率**: 0-2 个/block (优化后)
- **内存效率**: 在线统计，无需存储原始帧

160
README.md
View File

@ -1,49 +1,133 @@
# Meteor Fullstack - Distributed Monitoring Network # Meteor Fullstack - Distributed Monitoring Network
## Overview ## Overview
Meteor Fullstack 是一个覆盖边缘设备、云端 API、数据处理和 Web 前端的完整流星监测网络。仓库采用 npm workspace 管理前后端，并通过 Go、Rust 等多语言组件连接实时观测、事件验证和观测结果展示。
## System Topology Meteor Fullstack 是一个覆盖边缘设备、云端 API、数据处理和 Web 前端的完整流星监测网络。采用 npm workspace 管理前后端，通过 Go、Rust 等多语言组件连接实时观测、事件验证和结果展示。
- `meteor-edge-client/`：Rust 编写的边缘客户端 CLI（命令在 `src/main.rs`），负责摄像头采集、事件检测与上传，核心运行循环位于 `src/app.rs::Application::run`。
- `meteor-web-backend/`：NestJS Web API，入口 `src/main.ts` 启动 `AppModule`，聚合认证、设备注册、事件存取、支付与指标等子模块，持久化通过 TypeORM/PostgreSQL。
- `meteor-frontend/`：Next.js 15 应用（App Router），入口 `src/app/layout.tsx`，主要页面位于 `src/app/dashboard|gallery|analysis` 等目录，使用 React Query 与自建服务交互。
- `meteor-compute-service/`：Go 处理服务，入口 `cmd/meteor-compute-service/main.go`，从 SQS 拉取事件、执行校验并写入数据库，辅以 CloudWatch 指标与健康检查。
- `infrastructure/`：Terraform 定义 S3、SQS、CloudWatch、RDS/VPC 等资源，为各服务提供统一云端环境。
## Execution Entry Points ### Key Features
- **边缘采集**：`meteor-edge-client/src/main.rs` 解析 CLI（`Run` 子命令），构造 `Application`，根据 `camera` 参数（例如 `sim:pattern:meteor`）覆盖配置并启动摄像头、检测、存储、心跳等控制器。
- **Web API**：`meteor-web-backend/src/main.ts` 通过 `NestFactory` 启动服务，`AppModule` 汇集 `devices`, `events`, `metrics` 等模块；Socket 网关与定时任务由 `ScheduleModule` 提供。
- **前端应用**：`meteor-frontend/src/app/page.tsx` 定义默认仪表盘；路由由 `app/` 目录自动生成，`services/` 封装 API 调用，`contexts/` 提供跨页面状态。
- **计算服务**：`meteor-compute-service/internal/processor` 中的 `Processor.Start` 协程消费 SQS 消息，配合 `internal/validation` 动态加载检测策略。
## Data Flow Summary - **Vida Detection Algorithm**: 基于 Vida et al. 2016 论文的科学级流星检测
1. 边缘设备通过 `meteor-edge-client run --camera …` 捕获帧，`storage` 模块归档事件，`communication` 模块将打包结果上传后端。 - **Advanced Memory Management**: 零拷贝架构、分层帧池、自适应内存管理
2. NestJS 后端在 `events` 与 `devices` 模块中接收上传，写入事件表并向 SQS 推送需要进一步分析的数据。 - **Real-time Processing**: ~100ms/block 处理延迟
3. Go 计算服务从 SQS 获取消息，调用验证提供者生成分析结果，再回写数据库并发送 CloudWatch 指标。 - **Full Stack**: 边缘客户端 → 后端 API → 前端展示完整链路
4. 前端通过 React Query 请求 NestJS API，展示仪表盘、图库与分析视图，实现实时监控闭环。
## System Architecture
## Development Workflow
```bash
npm run install:all # 初始化依赖
npm run dev # 并行启动前端(3001)与后端(3000)
npm run test:fullstack
./test-setup.sh # 启动 LocalStack + 测试数据库
``` ```
Rust 与 Go 组件分别使用 `cargo run`, `cargo test`, `go run`, `go test ./...`；详细测试矩阵参见 `TESTING.md`。 ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Edge Client │────▶│ Web Backend │────▶│ Frontend │
│ (Rust) │ │ (NestJS) │ │ (Next.js) │
└────────┬────────┘ └────────┬────────┘ └─────────────────┘
│ │
│ ▼
│ ┌─────────────────┐
│ │ Compute Service │
│ │ (Go) │
│ └────────┬────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Camera/Video │ │ PostgreSQL │
│ Input │ │ + AWS (S3/SQS)│
└─────────────────┘ └─────────────────┘
```
## Testing & Verification ## Project Structure
- 前端：Jest + Testing Library (`npm run test:frontend`)，Playwright E2E (`npm run test:e2e`).
- 后端：Jest 单元与集成测试 (`npm run test:backend`, `npm run test:integration`).
- 边缘客户端：`cargo check`、`cargo test`；模拟摄像机脚本位于 `meteor-edge-client/scripts/`。
- 组合流程：`npm run test:fullstack` 调用前后端及集成测试，配合 `docker-compose.test.yml`。
## Infrastructure & Operations | 目录 | 技术栈 | 说明 |
- Terraform 输出的 S3/SQS/CloudWatch 资源需同步到 `.env` 与部署配置，细节参见 `infrastructure/README.md`。 |------|--------|------|
- Pino + CloudWatch 提供日志链路，`metrics` 模块和 Go `metrics` 包推送业务指标。 | `meteor-edge-client/` | Rust, Tokio | 边缘客户端，摄像头采集 + Vida 检测 |
- CI/CD 可利用 `meteor-edge-client/.github/workflows/` 示例以及 repo 根目录的 npm scripts。 | `meteor-web-backend/` | NestJS, TypeORM | Web API，认证、设备、事件管理 |
| `meteor-frontend/` | Next.js 15, React 19 | 前端应用，仪表盘、图库、分析 |
| `meteor-compute-service/` | Go 1.24 | 事件处理服务，SQS 消费者 |
| `infrastructure/` | Terraform | AWS 基础设施 (RDS, S3, SQS) |
## Additional Documentation ## Quick Start
- 贡献者指南：`AGENTS.md`
- 测试细节：`TESTING.md` ```bash
- 边缘摄像模拟：`meteor-edge-client/CAMERA_SIMULATION_USAGE.md` # 安装依赖
- 基础设施：`infrastructure/README.md` npm install
# 启动开发服务器 (前端 + 后端)
npm run dev
# 构建边缘客户端
cd meteor-edge-client && cargo build --release
# 测试 Vida 流星检测
./target/release/meteor-edge-client test-vida video.mp4
```
## Vida Detection Algorithm
边缘客户端实现了 Vida 流星检测算法（与 RMS/克罗地亚流星网络兼容）：
- **FTP 压缩**: 256帧 → maxpixel, avepixel, stdpixel, maxframe
- **双路径检测**:
- FireballDetector (K1=4): 检测明亮火球
- MeteorDetector (K1=1.5): 检测普通流星
- **形态学处理**: 清理、桥接、闭合、Zhang-Suen 细化
- **Hough 变换**: 2D 直线检测 + 3D 点云分析
详见 `CLAUDE.md` 中的完整文档。
## Development Commands
### Full Stack
```bash
npm run dev # 启动前端和后端
npm run build # 构建所有服务
npm run test:fullstack # 运行完整测试套件
npm run lint # 代码检查
```
### Edge Client (Rust)
```bash
cd meteor-edge-client
cargo build --release
cargo test
./target/release/meteor-edge-client run --camera device:0 # 使用摄像头
./target/release/meteor-edge-client run --camera file:v.mp4 # 使用视频文件
./target/release/meteor-edge-client test-vida video.mp4 # 测试检测
```
### Backend (NestJS)
```bash
cd meteor-web-backend
npm run start:dev # 开发模式
npm run migrate:up # 运行迁移
npm run test # 单元测试
npm run test:integration # 集成测试
```
### Frontend (Next.js)
```bash
cd meteor-frontend
npm run dev # 开发服务器
npm run build # 生产构建
npm run test # Jest 测试
npm run test:e2e # Playwright E2E
```
## Testing
| 类型 | 命令 | 说明 |
|------|------|------|
| 单元测试 | `npm run test` | Jest (前端+后端) |
| 集成测试 | `npm run test:integration` | 后端 API + 数据库 |
| E2E 测试 | `npm run test:e2e` | Playwright |
| 边缘客户端 | `cargo test` | Rust 单元测试 |
| 全栈测试 | `npm run test:fullstack` | 完整测试套件 |
测试环境需要 Docker: `./test-setup.sh`
## Documentation
- `CLAUDE.md` - 完整技术文档和 Claude Code 指引
- `TESTING.md` - 详细测试矩阵
- `docs/EDGE_DEVICE_REGISTRATION_COMPLETE.md` - 设备注册规范
- `infrastructure/README.md` - 基础设施部署
## License
MIT

28
TESTING.md
View File

@ -2,7 +2,7 @@
## 📋 测试架构概览 ## 📋 测试架构概览
本项目实现了完整的三层测试架构： 本项目实现了完整的四层测试架构：
### 🏗️ 测试环境组件 ### 🏗️ 测试环境组件
- **PostgreSQL (测试库)**: 端口 5433 - **PostgreSQL (测试库)**: 端口 5433
@ -15,6 +15,7 @@
2. **API集成测试**: 后端完整工作流 2. **API集成测试**: 后端完整工作流
3. **E2E测试**: 前端用户交互 3. **E2E测试**: 前端用户交互
4. **全栈集成测试**: 端到端业务流程 4. **全栈集成测试**: 端到端业务流程
5. **边缘客户端测试**: Rust 内存管理和 Vida 检测算法
## 🚀 快速开始 ## 🚀 快速开始
@ -80,6 +81,27 @@ cd meteor-frontend && npm run test:e2e:ui
cd meteor-web-backend && npm run test:watch cd meteor-web-backend && npm run test:watch
``` ```
### Edge Client 测试 (Rust)
```bash
cd meteor-edge-client
# Rust 单元测试
cargo test
# Vida 检测算法测试
./target/debug/meteor-edge-client test-vida video.mp4
# 内存管理测试
./target/debug/meteor-edge-client test # 核心帧池
./target/debug/meteor-edge-client test-adaptive # 自适应管理
./target/debug/meteor-edge-client test-integration # 集成测试
./target/debug/meteor-edge-client test-ring-buffer # 环形缓冲
./target/debug/meteor-edge-client test-hierarchical-cache # 分层缓存
# 生产监控测试
./target/debug/meteor-edge-client monitor
```
## 📊 测试数据管理 ## 📊 测试数据管理
### 自动化测试数据生成 ### 自动化测试数据生成
@ -324,5 +346,5 @@ jobs:
--- ---
*📝 最后更新: 2025-01-31* *📝 最后更新: 2026-01-07*
*🚀 版本: 1.0.0* *🚀 版本: 2.0.0*