adsist-cms/python-detector-worker
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Chore: update arch md

Browse source
This commit is contained in:
ziesorx 2025-09-12 20:18:14 +07:00
parent 9e8c6804a7
commit aacc5145d4
2 changed files with 1626 additions and 103 deletions
Download patch file Download diff file Expand all files Collapse all files

1286
ARCHITECTURE.md Normal file
View file

File diff suppressed because it is too large Load diff

443
CLAUDE.md
View file

@ -3,6 +3,8 @@
## Project Overview ## Project Overview
This is a FastAPI-based computer vision detection worker that processes video streams from RTSP/HTTP sources and runs advanced YOLO-based machine learning pipelines for multi-class object detection and parallel classification. The system features comprehensive database integration, Redis support, and hierarchical pipeline execution designed to work within a larger CMS (Content Management System) architecture. This is a FastAPI-based computer vision detection worker that processes video streams from RTSP/HTTP sources and runs advanced YOLO-based machine learning pipelines for multi-class object detection and parallel classification. The system features comprehensive database integration, Redis support, and hierarchical pipeline execution designed to work within a larger CMS (Content Management System) architecture.
**IMPORTANT**: This project has been completely refactored from a monolithic 4,000+ line codebase into a modular, maintainable architecture with dependency injection, comprehensive testing, and clear separation of concerns.
### Key Features ### Key Features
- **Multi-Class Detection**: Simultaneous detection of multiple object classes (e.g., Car + Frontal) - **Multi-Class Detection**: Simultaneous detection of multiple object classes (e.g., Car + Frontal)
- **Parallel Processing**: Concurrent execution of classification branches using ThreadPoolExecutor - **Parallel Processing**: Concurrent execution of classification branches using ThreadPoolExecutor
@ -10,77 +12,241 @@ This is a FastAPI-based computer vision detection worker that processes video st
- **Redis Actions**: Image storage with region cropping and pub/sub messaging - **Redis Actions**: Image storage with region cropping and pub/sub messaging
- **Pipeline Synchronization**: Branch coordination with `waitForBranches` functionality - **Pipeline Synchronization**: Branch coordination with `waitForBranches` functionality
- **Dynamic Field Mapping**: Template-based field resolution for database operations - **Dynamic Field Mapping**: Template-based field resolution for database operations
- **Modular Architecture**: Clean separation of concerns with dependency injection
- **Thread-Safe Operations**: Singleton managers for global state management
- **Comprehensive Testing**: Unit, integration, and performance test suites
## Architecture & Technology Stack ## Architecture & Technology Stack
- **Framework**: FastAPI with WebSocket support - **Framework**: FastAPI with WebSocket support and modern async patterns
- **ML/CV**: PyTorch, Ultralytics YOLO, OpenCV - **ML/CV**: PyTorch, Ultralytics YOLO, OpenCV with BoT-SORT tracking
- **Containerization**: Docker (Python 3.13-bookworm base) - **Containerization**: Docker (Python 3.13-bookworm base)
- **Data Storage**: Redis integration for action handling + PostgreSQL for persistent storage - **Data Storage**: Redis integration for action handling + PostgreSQL for persistent storage
- **Database**: Automatic schema management with gas_station_1 database - **Database**: Automatic schema management with gas_station_1 database
- **Parallel Processing**: ThreadPoolExecutor for concurrent classification - **Parallel Processing**: ThreadPoolExecutor for concurrent classification
- **Communication**: WebSocket-based real-time protocol - **Communication**: WebSocket-based real-time protocol
- **Design Patterns**: Dependency Injection, Singleton, Repository patterns
- **Testing**: Pytest with asyncio, mocking, and benchmarking support
## Core Components ## New Modular Architecture
### Core Directory Structure
```
detector_worker/
├── core/ # Core infrastructure components
│ ├── config.py # Multi-source configuration management
│ ├── constants.py # Application constants
│ ├── exceptions.py # Custom exception hierarchy
│ ├── singleton_managers.py # Thread-safe singleton managers
│ └── dependency_injection.py # IoC container implementation
├── detection/ # Computer vision and ML components
│ ├── yolo_detector.py # YOLO model inference
│ ├── tracking_manager.py # BoT-SORT multi-object tracking
│ └── stability_validator.py # Detection stability validation
├── pipeline/ # ML pipeline execution
│ ├── pipeline_executor.py # Main pipeline orchestration
│ ├── action_executor.py # Redis/DB action execution
│ └── field_mapper.py # Template-based field mapping
├── streams/ # Video stream management
│ ├── stream_manager.py # Stream lifecycle management
│ ├── frame_reader.py # RTSP/HTTP frame reading
│ └── camera_monitor.py # Connection state monitoring
├── communication/ # WebSocket and messaging
│ ├── websocket_handler.py # WebSocket connection management
│ ├── message_processor.py # Message routing and processing
│ └── response_formatter.py # Response formatting
├── storage/ # Data persistence
│ ├── database_manager.py # PostgreSQL operations
│ ├── redis_client.py # Redis operations
│ └── session_cache.py # Session and cache management
├── models/ # Model and pipeline management
│ ├── model_manager.py # YOLO model loading/caching
│ └── pipeline_loader.py # MPTA pipeline loading
└── utils/ # Utility functions
├── logging_utils.py # Structured logging setup
├── image_utils.py # Image processing utilities
└── system_utils.py # System monitoring utilities
```
### Main Application (`app.py`) ### Main Application (`app.py`)
- **FastAPI WebSocket server** for real-time communication - **FastAPI application** with modern lifespan management (replacing deprecated @app.on_event)
- **Multi-camera stream management** with shared stream optimization - **Dependency injection container** initialization and service registration
- **WebSocket endpoint** delegation to communication layer
- **HTTP REST endpoint** for image retrieval (`/camera/{camera_id}/image`) - **HTTP REST endpoint** for image retrieval (`/camera/{camera_id}/image`)
- **Threading-based frame readers** for RTSP streams and HTTP snapshots - **Clean separation** between framework code and business logic
- **Model loading and inference** using MPTA (Machine Learning Pipeline Archive) format - **Resource monitoring** integrated with singleton managers
- **Session management** with display identifier mapping
- **Resource monitoring** (CPU, memory, GPU usage via psutil)
### Pipeline System (`siwatsystem/pympta.py`) ### Core Infrastructure (`core/`)
- **MPTA file handling** - ZIP archives containing model configurations
- **Hierarchical pipeline execution** with detection → classification branching
- **Multi-class detection** - Simultaneous detection of multiple classes (Car + Frontal)
- **Parallel processing** - Concurrent classification branches with ThreadPoolExecutor
- **Redis action system** - Image saving with region cropping and message publishing
- **PostgreSQL integration** - Automatic table creation and combined updates
- **Dynamic model loading** with GPU optimization
- **Configurable trigger classes and confidence thresholds**
- **Branch synchronization** - waitForBranches coordination for database updates
### Database System (`siwatsystem/database.py`) #### Configuration Management (`core/config.py`)
- **DatabaseManager class** for PostgreSQL operations - **Multi-source configuration** with environment variables, JSON files, and defaults
- **Automatic table creation** with gas_station_1.car_frontal_info schema - **Type-safe configuration** with proper validation and error handling
- **Combined update operations** with field mapping from branch results - **Development/production** environment support
- **Session management** with UUID generation - **Configuration providers** pattern for extensible config sources
- **Error handling** and connection management
### Testing & Debugging #### Singleton Managers (`core/singleton_managers.py`)
- **Protocol test script** (`test_protocol.py`) for WebSocket communication validation - **Thread-safe singleton implementation** using metaclass pattern
- **Pipeline webcam utility** (`pipeline_webcam.py`) for local testing with visual output - **Six specialized managers**:
- **RTSP streaming debug tool** (`debug/rtsp_webcam.py`) using GStreamer - `SubscriptionManager`: WebSocket subscription lifecycle
- `StreamManager`: RTSP/HTTP stream management with reference counting
- `ModelManager`: YOLO model loading and caching
- `PipelineManager`: MPTA pipeline loading and management
- `SessionManager`: Session tracking and management
- `SessionCacheManager`: Redis-backed session caching
- **Replaces global dictionaries** for thread-safe state management
## Code Conventions & Patterns #### Dependency Injection (`core/dependency_injection.py`)
- **Full IoC container** with automatic constructor injection
- **Three service lifetimes**: Singleton, Transient, Scoped
- **Interface-based registration** supporting both concrete types and factories
- **Circular dependency detection** and resolution
- **Scope management** for request-scoped services
### Logging ### Detection System (`detection/`)
- **Structured logging** using Python's logging module
- **File + console output** to `detector_worker.log`
- **Debug level separation** for detailed troubleshooting
- **Context-aware messages** with camera IDs and model information
### Error Handling #### YOLO Detector (`detection/yolo_detector.py`)
- **Graceful failure handling** with retry mechanisms (configurable max_retries) - **YOLODetector class** for inference management
- **Thread-safe operations** using locks for streams and models - **Multi-class detection** support (Car + Frontal simultaneously)
- **WebSocket disconnect handling** with proper cleanup - **GPU/CPU optimization** with automatic device selection
- **Model loading validation** with detailed error reporting - **Confidence filtering** and NMS post-processing
- **Integration with tracking system**
### Configuration #### Tracking Manager (`detection/tracking_manager.py`)
- **JSON configuration** (`config.json`) for runtime parameters: - **BoT-SORT implementation** for multi-object tracking
- `poll_interval_ms`: Frame processing interval - **Track lifecycle management** with unique ID assignment
- `max_streams`: Concurrent stream limit - **Stability validation** integration for reliable detections
- `target_fps`: Target frame rate - **Performance optimization** with configurable parameters
- `reconnect_interval_sec`: Stream reconnection delay
- `max_retries`: Maximum retry attempts (-1 for unlimited)
### Threading Model #### Stability Validator (`detection/stability_validator.py`)
- **Frame reader threads** for each camera stream (RTSP/HTTP) - **Detection stability analysis** over time windows
- **Shared stream optimization** - multiple subscriptions can reuse the same camera stream - **Confidence trend analysis** for reliable object detection
- **Async WebSocket handling** with concurrent task management - **Configurable thresholds** for stability determination
- **Thread-safe data structures** with proper locking mechanisms - **Integration with tracking and pipeline systems**
### Pipeline System (`pipeline/`)
#### Pipeline Executor (`pipeline/pipeline_executor.py`)
- **PipelineExecutor class** for orchestrating MPTA pipeline execution
- **Hierarchical execution** with detection → classification branching
- **Parallel processing** using ThreadPoolExecutor for classification branches
- **Branch synchronization** with `waitForBranches` coordination
- **Error handling** and retry mechanisms
#### Action Executor (`pipeline/action_executor.py`)
- **ActionExecutor class** for Redis and database actions
- **Redis image storage** with region cropping and expiration
- **PostgreSQL operations** with automatic schema management
- **Pub/sub messaging** for real-time notifications
- **Template-based configuration** for dynamic action parameters
#### Field Mapper (`pipeline/field_mapper.py`)
- **FieldMapper class** for template-based field resolution
- **Dynamic field mapping** from classification results to database fields
- **Template syntax**: `{model_id.field_name}` → actual values
- **Type-safe field resolution** with error handling
### Stream Management (`streams/`)
#### Stream Manager (`streams/stream_manager.py`)
- **StreamManager class** for RTSP/HTTP stream lifecycle management
- **Reference counting** for shared stream optimization
- **Automatic reconnection** with exponential backoff
- **Thread-safe operations** with proper locking mechanisms
#### Frame Reader (`streams/frame_reader.py`)
- **FrameReader class** for RTSP stream processing
- **SnapshotReader class** for HTTP snapshot capture
- **Queue-based buffering** with latest frame optimization
- **Error handling** and connection recovery
#### Camera Monitor (`streams/camera_monitor.py`)
- **CameraMonitor class** for connection state tracking
- **Health monitoring** and status reporting
- **Integration with stream management** for failure detection
### Communication Layer (`communication/`)
#### WebSocket Handler (`communication/websocket_handler.py`)
- **WebSocketHandler class** for connection lifecycle management
- **Message routing** to appropriate processors
- **Error handling** and graceful disconnection
- **Integration with subscription management**
#### Message Processor (`communication/message_processor.py`)
- **MessageProcessor class** for message routing and handling
- **Type-safe message processing** with validation
- **Integration with detection pipeline** and state management
- **Real-time response formatting**
#### Response Formatter (`communication/response_formatter.py`)
- **ResponseFormatter class** for consistent message formatting
- **Detection result formatting** with timestamp and metadata
- **State report generation** with system metrics
- **JSON serialization** with type safety
### Storage Layer (`storage/`)
#### Database Manager (`storage/database_manager.py`)
- **DatabaseManager class** with Repository pattern implementation
- **Automatic schema management** for gas_station_1.car_frontal_info
- **Connection pooling** and transaction management
- **Combined update operations** with field mapping
- **Error handling** and retry mechanisms
#### Redis Client (`storage/redis_client.py`)
- **RedisClient class** for Redis operations
- **Image storage** with automatic expiration
- **Pub/sub messaging** for real-time notifications
- **Connection management** with retry logic
- **Type-safe operations** with proper error handling
#### Session Cache (`storage/session_cache.py`)
- **SessionCacheManager class** for session and cache management
- **Redis-backed caching** with configurable expiration
- **Session tracking** with UUID generation
- **Thread-safe operations** with singleton pattern
### Model Management (`models/`)
#### Model Manager (`models/model_manager.py`)
- **ModelManager class** for YOLO model lifecycle management
- **Model caching** with memory optimization
- **GPU/CPU device management** with automatic selection
- **Thread-safe model loading** and inference preparation
#### Pipeline Loader (`models/pipeline_loader.py`)
- **PipelineLoader class** for MPTA archive handling
- **ZIP archive extraction** and validation
- **Configuration parsing** with schema validation
- **Model file management** and loading coordination
## System Workflow
### Application Startup (app.py)
1. **Configuration Loading** - Multi-source configuration initialization
2. **Dependency Container Setup** - Service registration and IoC container configuration
3. **Singleton Manager Initialization** - Thread-safe global state managers
4. **FastAPI Application Creation** - Modern lifespan management setup
5. **Service Registration** - All components registered with dependency injection
6. **Server Launch** - Uvicorn server startup with WebSocket support
### WebSocket Connection Flow
1. **Client Connection** (`communication/websocket_handler.py:35`)
2. **Message Reception** (`communication/message_processor.py:42`)
3. **Subscription Processing** (`communication/message_processor.py:78`)
4. **Stream Initialization** (`streams/stream_manager.py:156`)
5. **Model Loading** (`models/model_manager.py:89`)
6. **Pipeline Setup** (`pipeline/pipeline_executor.py:67`)
### Detection Pipeline Flow
1. **Frame Capture** (`streams/frame_reader.py:123`)
2. **YOLO Detection** (`detection/yolo_detector.py:145`)
3. **Multi-Object Tracking** (`detection/tracking_manager.py:178`)
4. **Stability Validation** (`detection/stability_validator.py:92`)
5. **Pipeline Execution** (`pipeline/pipeline_executor.py:234`)
6. **Action Execution** (`pipeline/action_executor.py:189`)
7. **Field Mapping** (`pipeline/field_mapper.py:67`)
8. **Database Update** (`storage/database_manager.py:234`)
9. **Response Formatting** (`communication/response_formatter.py:89`)
## WebSocket Protocol ## WebSocket Protocol
@ -171,66 +337,111 @@ This is a FastAPI-based computer vision detection worker that processes video st
} }
``` ```
## Stream Management ## Testing Infrastructure
### Shared Streams ### Test Structure
- Multiple subscriptions can share the same camera URL ```
- Reference counting prevents premature stream termination tests/
- Automatic cleanup when last subscription ends ├── unit/ # Unit tests for individual components
│ ├── core/ # Core infrastructure tests
│ ├── detection/ # Computer vision component tests
│ ├── pipeline/ # Pipeline execution tests
│ ├── streams/ # Stream management tests
│ ├── communication/ # WebSocket and messaging tests
│ ├── storage/ # Database and Redis tests
│ └── models/ # Model management tests
├── integration/ # End-to-end workflow tests
├── performance/ # Performance benchmarks and load tests
└── fixtures/ # Test data and mock objects
```
### Frame Processing ### Test Commands
- **Queue-based buffering** with single frame capacity (latest frame only) ```bash
- **Configurable polling interval** based on target FPS # Run all tests
- **Automatic reconnection** with exponential backoff make test
## Development & Testing # Run specific test categories
make test-unit
make test-integration
make test-performance
### Local Development # Run with coverage reporting
make test-coverage
# Run code quality checks
make lint
make format
```
## Development & Deployment
### Local Development Setup
```bash ```bash
# Install dependencies # Install dependencies
pip install -r requirements.txt make install-dev
# Run the worker # Run the application
python app.py make run
# Test protocol compliance # Run with debug mode
python test_protocol.py make run-debug
# Test pipeline with webcam # Run tests
python pipeline_webcam.py --mpta-file path/to/model.mpta --video 0 make test
# Format code
make format
# Run quality checks
make quality
``` ```
### Docker Deployment ### Docker Deployment
```bash ```bash
# Build container # Build container
docker build -t detector-worker . make docker-build
# Run with volume mounts for models # Run container
docker run -p 8000:8000 -v ./models:/app/models detector-worker make docker-run
# Development container with volume mounts
make docker-dev
``` ```
### Testing Commands ### Configuration Management
- **Protocol testing**: `python test_protocol.py` - **Environment Variables**: Override default configuration
- **Pipeline validation**: `python pipeline_webcam.py --mpta-file <path> --video 0` - **config.json**: Development and production settings
- **RTSP debugging**: `python debug/rtsp_webcam.py` - **DETECTOR_WORKER_ENV**: Environment selection (dev/test/prod)
## Dependencies ## Code Conventions & Patterns
- **fastapi[standard]**: Web framework with WebSocket support
- **uvicorn**: ASGI server ### Design Patterns Used
- **torch, torchvision**: PyTorch for ML inference - **Dependency Injection**: IoC container with automatic constructor injection
- **ultralytics**: YOLO implementation - **Singleton Pattern**: Thread-safe implementation using metaclass
- **opencv-python**: Computer vision operations - **Repository Pattern**: Database operations with interface abstraction
- **websockets**: WebSocket client/server - **Factory Pattern**: Model and pipeline loading with configurable factories
- **redis**: Redis client for action execution - **Observer Pattern**: WebSocket communication and event handling
- **psycopg2-binary**: PostgreSQL database adapter
- **scipy**: Scientific computing for advanced algorithms ### Code Quality Standards
- **filterpy**: Kalman filtering and state estimation - **Type Hints**: Comprehensive type annotations throughout codebase
- **Error Handling**: Structured exception hierarchy with proper propagation
- **Logging**: Structured logging with context-aware messages
- **Testing**: Unit, integration, and performance tests with high coverage
- **Documentation**: Comprehensive docstrings and inline documentation
### Performance Optimizations
- **GPU Acceleration**: CUDA support with automatic fallback to CPU
- **Memory Management**: Model caching with automatic cleanup
- **Thread Safety**: Proper locking mechanisms for concurrent operations
- **Resource Monitoring**: CPU, memory, and GPU usage tracking
- **Connection Pooling**: Database and Redis connection optimization
## Security Considerations ## Security Considerations
- Model files are loaded from trusted sources only - **Input Validation**: All WebSocket messages and configuration validated
- Redis connections use authentication when configured - **Resource Limits**: Configurable limits for streams, models, and connections
- WebSocket connections handle disconnects gracefully - **Error Handling**: Graceful failure handling without information leakage
- Resource usage is monitored to prevent DoS - **Authentication**: Redis and PostgreSQL connection security
- **Model Security**: MPTA file validation and secure model loading
## Database Integration ## Database Integration
@ -264,14 +475,40 @@ Templates like `{car_brand_cls_v1.brand}` are resolved to actual classification
- `car_brand_cls_v1.brand` → "Honda" - `car_brand_cls_v1.brand` → "Honda"
- `car_bodytype_cls_v1.body_type` → "Sedan" - `car_bodytype_cls_v1.body_type` → "Sedan"
## Performance Optimizations ## Migration from Legacy Code
- GPU acceleration when CUDA is available
- Shared camera streams reduce resource usage ### Key Changes
- Frame queue optimization (single latest frame) - **Monolithic to Modular**: 4,000+ lines split into 30+ focused modules
- Model caching across subscriptions - **Global State Elimination**: Replaced with thread-safe singleton managers
- Trigger class filtering for faster inference - **Dependency Injection**: Automatic constructor injection with IoC container
- Parallel processing with ThreadPoolExecutor for classification branches - **Modern FastAPI**: Deprecated patterns replaced with current best practices
- Multi-class detection reduces inference passes - **Comprehensive Testing**: Full test suite with unit, integration, and performance tests
- Region-based cropping minimizes processing overhead
- Database connection pooling and prepared statements ### Breaking Changes
- Redis image storage with automatic expiration - **Import Paths**: All imports now use `detector_worker.` prefix
- **Configuration**: New multi-source configuration system
- **Dependencies**: New dependency injection requirements
- **Testing**: New test infrastructure and commands
## Dependencies
- **fastapi[standard]**: Web framework with WebSocket support
- **uvicorn**: ASGI server
- **torch, torchvision**: PyTorch for ML inference
- **ultralytics**: YOLO implementation
- **opencv-python**: Computer vision operations
- **websockets**: WebSocket client/server
- **redis**: Redis client for action execution
- **psycopg2-binary**: PostgreSQL database adapter
- **scipy**: Scientific computing for advanced algorithms
- **filterpy**: Kalman filtering and state estimation
- **pytest**: Testing framework with asyncio support
- **black, isort**: Code formatting tools
- **mypy**: Static type checking
- **flake8**: Code quality analysis
## References
- **ARCHITECTURE.md**: Comprehensive technical documentation with flow diagrams
- **test_protocol.py**: WebSocket communication validation
- **pipeline_webcam.py**: Local testing with visual output
- **Makefile**: Development workflow commands
- **tox.ini**: Multi-environment testing configuration