Skip to content

Commit 9f058d0

Browse files
solderzzcsolderzzc
committed
Add comprehensive documentation for DeepCamera integration and architecture
Create three new documentation files: - Home Assistant integration guide - DeepCamera pipeline architecture overview - Supported AI models documentation These documents provide in-depth technical details about DeepCamera's capabilities, integration methods, and underlying technical architecture, enhancing project documentation and user understanding.
1 parent 2f174af commit 9f058d0

File tree

3 files changed

+454
-0
lines changed

3 files changed

+454
-0
lines changed

‎docs/home_assistant_integration.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Home Assistant Integration Guide
2+
3+
## Overview
4+
DeepCamera can be seamlessly integrated with Home Assistant to provide advanced AI-powered camera features in your smart home setup. This guide will walk you through the complete integration process.
5+
6+
## Prerequisites
7+
- Home Assistant installed and running
8+
- DeepCamera installed and configured
9+
- A compatible camera set up in your network
10+
11+
## Integration Steps
12+
13+
### 1. Install DeepCamera Component
14+
First, ensure DeepCamera is properly installed and running on your system. You can verify this by checking if the DeepCamera service is active:
15+
16+
```bash
17+
docker ps | grep deepcamera
18+
```
19+
20+
### 2. Configure Home Assistant
21+
22+
#### 2.1 Add Required Configuration
23+
Edit your Home Assistant `configuration.yaml` file and add the following configuration:
24+
25+
```yaml
26+
# Enable streaming support
27+
stream:
28+
ll_hls: true
29+
part_duration: 0.75
30+
segment_duration: 6
31+
32+
# Configure DeepCamera integration
33+
image_processing:
34+
- platform: sharpai
35+
source:
36+
- entity_id: camera.<your_camera_entity_id>
37+
scan_interval: 6
38+
```
39+
40+
#### 2.2 Configure Camera Entity
41+
Make sure your camera is properly configured in Home Assistant. Add the following to your `configuration.yaml` if not already present:
42+
43+
```yaml
44+
camera:
45+
- platform: generic
46+
name: My Camera
47+
still_image_url: http://<camera_ip>/snapshot
48+
stream_source: rtsp://<camera_ip>/stream
49+
```
50+
51+
### 3. Set Up Notifications (Optional)
52+
To receive notifications when DeepCamera detects events:
53+
54+
```yaml
55+
automation:
56+
- alias: "DeepCamera Detection Notification"
57+
trigger:
58+
platform: event
59+
event_type: sharpai_detection
60+
action:
61+
- service: notify.notify
62+
data:
63+
title: "DeepCamera Detection"
64+
message: "{{ trigger.event.data.detection_type }} detected"
65+
```
66+
67+
### 4. Restart and Verify
68+
1. Save all configuration changes
69+
2. Restart Home Assistant
70+
3. Check the Home Assistant logs for any errors
71+
4. Verify that the integration appears in your Home Assistant dashboard
72+
73+
## Advanced Configuration
74+
75+
### Custom Detection Settings
76+
You can customize detection settings for different scenarios:
77+
78+
```yaml
79+
image_processing:
80+
- platform: sharpai
81+
source:
82+
- entity_id: camera.front_door
83+
scan_interval: 6
84+
confidence: 80
85+
detection_types:
86+
- person
87+
- vehicle
88+
- animal
89+
```
90+
91+
### Multiple Camera Setup
92+
For multiple cameras:
93+
94+
```yaml
95+
image_processing:
96+
- platform: sharpai
97+
source:
98+
- entity_id: camera.front_door
99+
- entity_id: camera.back_door
100+
- entity_id: camera.garage
101+
scan_interval: 6
102+
```
103+
104+
## Troubleshooting
105+
106+
### Common Issues and Solutions
107+
108+
1. **Integration Not Appearing**
109+
- Verify DeepCamera service is running
110+
- Check Home Assistant logs for errors
111+
- Ensure camera entity is correctly configured
112+
113+
2. **No Detections**
114+
- Verify camera stream is accessible
115+
- Check scan_interval settings
116+
- Verify detection confidence settings
117+
118+
3. **Performance Issues**
119+
- Adjust scan_interval to balance performance
120+
- Check network bandwidth
121+
- Monitor system resources
122+
123+
## Additional Resources
124+
- [DeepCamera Documentation](https://github.com/SharpAI/DeepCamera)
125+
- [Home Assistant Documentation](https://www.home-assistant.io/integrations/)
126+
- [Community Support Forum](https://community.home-assistant.io/)

‎docs/pipeline.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# DeepCamera Pipeline
2+
3+
## Overview
4+
The DeepCamera pipeline is a sophisticated system that processes video streams in real-time for various AI-powered detection and recognition tasks. This document explains the complete pipeline from video input to event notification.
5+
6+
## Pipeline Architecture
7+
8+
```mermaid
9+
graph TD
10+
A[Video Input] --> B[Frame Extraction]
11+
B --> C[Pre-processing]
12+
C --> D[Object Detection]
13+
D --> E[Specialized Processing]
14+
E --> F[Post-processing]
15+
F --> G[Event Generation]
16+
G --> H[Notification System]
17+
18+
subgraph "Pre-processing"
19+
C1[Resize] --> C2[Normalization]
20+
C2 --> C3[Color Space Conversion]
21+
end
22+
23+
subgraph "Specialized Processing"
24+
E1[Face Recognition]
25+
E2[Person ReID]
26+
E3[Fall Detection]
27+
E4[Parking Detection]
28+
end
29+
```
30+
31+
## Pipeline Components
32+
33+
### 1. Video Input
34+
- Supports multiple input sources:
35+
- RTSP streams
36+
- HTTP streams
37+
- Local camera devices
38+
- Video files
39+
- Handles multiple streams concurrently
40+
- Automatic reconnection on stream failure
41+
42+
### 2. Frame Extraction
43+
- Efficient frame sampling
44+
- Frame rate adjustment
45+
- Buffer management
46+
- Frame quality assessment
47+
48+
### 3. Pre-processing
49+
- Image resizing
50+
- Normalization
51+
- Color space conversion
52+
- Aspect ratio handling
53+
- ROI (Region of Interest) cropping
54+
55+
### 4. Object Detection
56+
- Primary detection using YOLOv5
57+
- Multiple object class support
58+
- Confidence thresholding
59+
- Non-maximum suppression
60+
- ROI filtering
61+
62+
### 5. Specialized Processing
63+
64+
#### Face Recognition Pipeline
65+
1. Face detection (RetinaFace)
66+
2. Face alignment
67+
3. Feature extraction (ArcFace)
68+
4. Feature matching
69+
5. Identity verification
70+
71+
#### Person ReID Pipeline
72+
1. Person detection
73+
2. Feature extraction (OSNet)
74+
3. Track association
75+
4. Cross-camera matching
76+
77+
#### Fall Detection Pipeline
78+
1. Person detection
79+
2. Pose estimation
80+
3. Fall event analysis
81+
4. Alert generation
82+
83+
#### Parking Detection Pipeline
84+
1. Parking space definition
85+
2. Vehicle detection
86+
3. Space occupancy analysis
87+
4. State change detection
88+
89+
### 6. Post-processing
90+
- Result filtering
91+
- Event aggregation
92+
- Data formatting
93+
- Metadata enrichment
94+
95+
### 7. Event Generation
96+
- Event classification
97+
- Priority assignment
98+
- Duplicate detection
99+
- Event correlation
100+
101+
### 8. Notification System
102+
- Multiple notification channels:
103+
- Home Assistant events
104+
- Webhooks
105+
- MQTT messages
106+
- Push notifications
107+
- Event persistence
108+
- Rate limiting
109+
110+
## Data Flow
111+
112+
### Input Processing
113+
```
114+
Video Stream → Frame Buffer → Pre-processing Queue → Detection Queue
115+
```
116+
117+
### Detection Flow
118+
```
119+
Detection Queue → Object Detection → Specialized Processing → Event Generation
120+
```
121+
122+
### Output Flow
123+
```
124+
Event Generation → Event Queue → Notification System → External Systems
125+
```
126+
127+
## Performance Optimization
128+
129+
### Pipeline Optimizations
130+
1. **Parallel Processing**
131+
- Multi-threading for frame extraction
132+
- GPU acceleration for detection
133+
- Asynchronous event handling
134+
135+
2. **Memory Management**
136+
- Frame buffer optimization
137+
- Batch processing
138+
- Resource pooling
139+
140+
3. **Load Balancing**
141+
- Dynamic frame rate adjustment
142+
- Priority queue management
143+
- Resource allocation
144+
145+
### Hardware Utilization
146+
- GPU acceleration
147+
- CPU optimization
148+
- Memory usage control
149+
- Disk I/O management
150+
151+
## Configuration Options
152+
153+
### Pipeline Settings
154+
```yaml
155+
pipeline:
156+
input:
157+
frame_rate: 10
158+
buffer_size: 30
159+
quality_threshold: 0.8
160+
161+
processing:
162+
batch_size: 4
163+
gpu_memory: 2GB
164+
thread_count: 4
165+
166+
output:
167+
event_buffer: 100
168+
notification_rate: 1
169+
```
170+
171+
### Model Settings
172+
```yaml
173+
models:
174+
detection:
175+
confidence: 0.4
176+
nms_threshold: 0.5
177+
178+
recognition:
179+
face_confidence: 0.9
180+
reid_threshold: 0.7
181+
```
182+
183+
## Error Handling
184+
185+
### Recovery Mechanisms
186+
1. Stream reconnection
187+
2. Model reloading
188+
3. Memory cleanup
189+
4. Error logging
190+
191+
### Monitoring
192+
- Pipeline health checks
193+
- Performance metrics
194+
- Resource utilization
195+
- Error tracking
196+
197+
## Integration Points
198+
199+
### Input Integration
200+
- Camera systems
201+
- NVR systems
202+
- Video management systems
203+
204+
### Output Integration
205+
- Home Assistant
206+
- Custom webhooks
207+
- Database systems
208+
- Cloud services
209+
210+
## Future Enhancements
211+
1. Dynamic pipeline configuration
212+
2. Advanced scheduling
213+
3. Improved error recovery
214+
4. Enhanced monitoring
215+
5. Additional AI models
216+
217+
For detailed implementation examples and configuration options, please refer to our [Configuration Guide](configuration_guide.md).

0 commit comments

Comments
 (0)