dsh/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

施工现场安全行为智能识别系统 v2.0.0 - Construction site safety behavior intelligent recognition system.

A dual-camera coordinated capture system that:

• Uses panoramic cameras for real-time monitoring with YOLO11 person detection
• Controls PTZ dome cameras to scan preset positions and capture targets
• Saves paired panorama + PTZ images
• Pushes events to business platform

Running Commands

Scan-Polling Mode

cd dual_camera_system
python main.py
python main.py --demo

Common Parameters

--model-size {n,s,m,l,x}    # YOLO11 model size
--no-gpu                    # Disable GPU
--model /path/to/model.pt   # Explicit detection model

Dependencies

pip install opencv-python opencv-contrib-python ultralytics

Architecture

dual_camera_system/
├── main.py              # uvicorn service entry point
├── app.py               # FastAPI app factory and global service initialization
├── config/              # Modular configuration
│   ├── __init__.py      # Config aggregation
│   ├── system.py        # Feature toggles
│   ├── camera.py        # Camera IPs, credentials, SDK paths
│   ├── detection.py     # YOLO detection config
│   ├── coordinator.py   # Scan polling parameters
│   ├── ptz.py           # PTZ control parameters
│   ├── event.py         # Event push config
│   └── ...              # Other module configs
├── core/                # New architecture core modules
│   ├── capture_uploader.py   # Capture and upload logic
│   ├── coord_utils.py        # Coordinate/angle conversion
│   ├── detector_service.py   # Detector service wrapper
│   ├── group_state.py        # Per-group state management
│   ├── polling_scheduler.py  # PTZ scan polling scheduler
│   ├── scan_point_store.py   # Scan point storage
│   ├── spatial_scanner.py    # Spatial 360° scan modeling
│   └── stream_manager.py     # RTSP stream manager
├── web/                 # Web API service
│   ├── routes.py        # HTTP routes
│   └── state.py         # Web app state
├── web_static/          # Frontend static files
│   ├── index.html
│   ├── app.js
│   └── style.css
├── dahua_sdk.py         # Dahua SDK ctypes wrapper
├── panorama_camera.py   # Panoramic camera + person detection
├── ptz_camera.py        # PTZ dome camera control
└── inference_backend.py # RKNN/ONNX inference backend

Critical Technical Details

SDK Initialization Order (CRITICAL)

In app.py, YOLO/PyTorch MUST load before Dahua SDK. The SDK's CLIENT_Init modifies process memory mapping; if loaded before PyTorch, it causes segfault. The current code handles this correctly - do not change the order.

SDK Path Auto-Selection

config/camera.py auto-selects SDK path by CPU architecture:

• aarch64 → /home/admin/dsh/dh/arm/Bin (Orange Pi)
• x86_64 → /home/wen/dsh/dh/Bin (x86 Linux server)
• Other → ../dh/Bin (development reference)

Camera Ports

• SDK login: port 37777
• RTSP stream: port 554 (rtsp_port in config)

Working Mode

Current working mode is multi-group scan-polling mode via app.py:create_app(). All camera groups are configured in config/camera.py under CAMERA_GROUPS. main.py is only the uvicorn entry point.

Feature toggles in config/system.py:

• enable_panorama_camera
• enable_ptz_camera
• enable_detection
• enable_event_push

RKNN Test Environment

ssh admin@192.168.20.84
conda activate rknn
cd /home/admin/dsh/dual_camera_system

Model Paths

• Person detection model: configured in config/detection.py, default /home/wen/dsh/yolo/yolo11n.pt
• YOLO11 weights auto-download on first run

RTSP URL Pattern

rtsp://username:password@ip:554/cam/realmonitor?channel=0&subtype=0

Note: subtype=0 for main stream, subtype=1 for sub stream.