From 6c846976f5582c997a3a09ebf333f61903cabfff Mon Sep 17 00:00:00 2001 From: grabbit Date: Wed, 7 Jan 2026 01:03:59 +0800 Subject: [PATCH] docs: update project documentation with Vida detection algorithm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 107 +++++++++++++++++++++++++++++++---- README.md | 160 ++++++++++++++++++++++++++++++++++++++++------------- TESTING.md | 28 +++++++++- 3 files changed, 244 insertions(+), 51 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d8962bc..3c3cce0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,6 +77,10 @@ cargo build --release # Native build cargo build --target=aarch64-unknown-linux-gnu # ARM64 build for Pi ./build.sh # Cross-compile for Raspberry Pi +# Vida Meteor Detection Testing +./target/debug/meteor-edge-client test-vida # Test Vida detection on video +./target/debug/meteor-edge-client run --camera file:video.mp4 # Run with video file + # Advanced Memory Management Testing ./target/debug/meteor-edge-client test # Core frame pool tests ./target/debug/meteor-edge-client test-adaptive # Adaptive pool management @@ -382,16 +386,11 @@ Camera Features: - Health monitoring with diagnostic recommendations #### Real-Time Meteor Detection Pipeline -- **Multi-Algorithm Detection**: Brightness, motion, background subtraction algorithms -- **Consensus-Based Detection**: Combines multiple algorithms for higher accuracy +- **Vida Algorithm**: Scientific meteor detection based on Vida et al. 2016 paper +- **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 -- **Real-Time Performance**: Sub-30ms processing latency for real-time detection - -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 +- **Real-Time Performance**: ~100ms/block processing latency #### Production-Ready Features - **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 3. Provide production-grade observability and monitoring 4. Maintain high performance on resource-constrained Raspberry Pi devices -5. Support real-time meteor detection with sub-millisecond processing latency \ No newline at end of file +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 (优化后) +- **内存效率**: 在线统计，无需存储原始帧 \ No newline at end of file diff --git a/README.md b/README.md index 31204dc..0c4acc9 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,133 @@ # Meteor Fullstack - Distributed Monitoring Network ## Overview -Meteor Fullstack 是一个覆盖边缘设备、云端 API、数据处理和 Web 前端的完整流星监测网络。仓库采用 npm workspace 管理前后端，并通过 Go、Rust 等多语言组件连接实时观测、事件验证和观测结果展示。 -## System Topology -- `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 等资源，为各服务提供统一云端环境。 +Meteor Fullstack 是一个覆盖边缘设备、云端 API、数据处理和 Web 前端的完整流星监测网络。采用 npm workspace 管理前后端，通过 Go、Rust 等多语言组件连接实时观测、事件验证和结果展示。 -## Execution Entry Points -- **边缘采集**：`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` 动态加载检测策略。 +### Key Features -## Data Flow Summary -1. 边缘设备通过 `meteor-edge-client run --camera …` 捕获帧，`storage` 模块归档事件，`communication` 模块将打包结果上传后端。 -2. NestJS 后端在 `events` 与 `devices` 模块中接收上传，写入事件表并向 SQS 推送需要进一步分析的数据。 -3. Go 计算服务从 SQS 获取消息，调用验证提供者生成分析结果，再回写数据库并发送 CloudWatch 指标。 -4. 前端通过 React Query 请求 NestJS API，展示仪表盘、图库与分析视图，实现实时监控闭环。 +- **Vida Detection Algorithm**: 基于 Vida et al. 2016 论文的科学级流星检测 +- **Advanced Memory Management**: 零拷贝架构、分层帧池、自适应内存管理 +- **Real-time Processing**: ~100ms/block 处理延迟 +- **Full Stack**: 边缘客户端 → 后端 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 -- 前端：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`。 +## Project Structure -## Infrastructure & Operations -- Terraform 输出的 S3/SQS/CloudWatch 资源需同步到 `.env` 与部署配置，细节参见 `infrastructure/README.md`。 -- Pino + CloudWatch 提供日志链路，`metrics` 模块和 Go `metrics` 包推送业务指标。 -- CI/CD 可利用 `meteor-edge-client/.github/workflows/` 示例以及 repo 根目录的 npm scripts。 +| 目录 | 技术栈 | 说明 | +|------|--------|------| +| `meteor-edge-client/` | Rust, Tokio | 边缘客户端，摄像头采集 + Vida 检测 | +| `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 -- 贡献者指南：`AGENTS.md` -- 测试细节：`TESTING.md` -- 边缘摄像模拟：`meteor-edge-client/CAMERA_SIMULATION_USAGE.md` -- 基础设施：`infrastructure/README.md` +## Quick Start + +```bash +# 安装依赖 +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 diff --git a/TESTING.md b/TESTING.md index 2a34526..b6bc681 100644 --- a/TESTING.md +++ b/TESTING.md @@ -2,7 +2,7 @@ ## 📋 测试架构概览 -本项目实现了完整的三层测试架构： +本项目实现了完整的四层测试架构： ### 🏗️ 测试环境组件 - **PostgreSQL (测试库)**: 端口 5433 @@ -15,6 +15,7 @@ 2. **API集成测试**: 后端完整工作流 3. **E2E测试**: 前端用户交互 4. **全栈集成测试**: 端到端业务流程 +5. **边缘客户端测试**: Rust 内存管理和 Vida 检测算法 ## 🚀 快速开始 @@ -80,6 +81,27 @@ cd meteor-frontend && npm run test:e2e:ui 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* -*🚀 版本: 1.0.0* \ No newline at end of file +*📝 最后更新: 2026-01-07* +*🚀 版本: 2.0.0* \ No newline at end of file