feat: initialize managed portal
This commit is contained in:
Yoilun
144
managed/people_flow_project/README.md
Normal file
144
managed/people_flow_project/README.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# People Flow Project
|
||||
|
||||
People flow analysis for street videos using YOLO tracking and face-based demographic estimation.
|
||||
|
||||
## What it does
|
||||
|
||||
- Counts unique people when they cross a configured line
|
||||
- Estimates one age bucket per counted track: `minor`, `adult`, or `senior`
|
||||
- Estimates one gender bucket per counted track: `male` or `female`
|
||||
- Writes an annotated output video, per-video JSON, and batch summary CSV
|
||||
|
||||
## Pipeline
|
||||
|
||||
1. Detect and track `person` objects with Ultralytics YOLO.
|
||||
2. Assign a stable `track_id` with BoT-SORT or ByteTrack.
|
||||
3. Count each track once when it crosses the configured line.
|
||||
4. Sample person crops for each track and run DeepFace age/gender analysis.
|
||||
5. Use track-level voting so each counted person lands in only one age bucket and one gender bucket.
|
||||
|
||||
## Project Layout
|
||||
|
||||
- `main.py`: CLI entrypoint
|
||||
- `src/people_flow/`: application modules
|
||||
- `configs/default_config.yaml`: default runtime settings
|
||||
- `outputs/`: generated result files
|
||||
- `docs/plans/`: design and implementation notes
|
||||
|
||||
## Recommended Environment
|
||||
|
||||
- Linux
|
||||
- NVIDIA GPU with CUDA
|
||||
- Python `3.10` or `3.11`
|
||||
|
||||
`deepface` and its transitive dependencies are not a good fit for Python `3.14`, so do not build this environment on the current local interpreter version.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
python3.11 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Single Video
|
||||
|
||||
```bash
|
||||
python main.py video \
|
||||
--input "/path/to/video.mp4" \
|
||||
--line "0.1,0.55,0.9,0.55"
|
||||
```
|
||||
|
||||
## Batch Directory
|
||||
|
||||
```bash
|
||||
python main.py batch \
|
||||
--input-dir "/path/to/videos" \
|
||||
--line "0.1,0.55,0.9,0.55"
|
||||
```
|
||||
|
||||
## RTSP Stream
|
||||
|
||||
```bash
|
||||
python main.py --output-dir outputs rtsp \
|
||||
--input "rtsp://user:password@host:554/stream"
|
||||
```
|
||||
|
||||
RTSP mode behaves differently from offline video mode:
|
||||
|
||||
- The stream is sampled at one processed frame per second
|
||||
- Statistics are isolated into 30-minute windows
|
||||
- Each completed window writes one JSON file
|
||||
- `latest.json` is overwritten on every completed window
|
||||
- RTSP mode does not save annotated video by default
|
||||
|
||||
## Output Files
|
||||
|
||||
Each processed video produces:
|
||||
|
||||
- `outputs/<video_stem>/<video_stem>.annotated.mp4`
|
||||
- `outputs/<video_stem>/<video_stem>.json`
|
||||
|
||||
Batch mode also produces:
|
||||
|
||||
- `outputs/batch_summary.csv`
|
||||
|
||||
RTSP mode produces:
|
||||
|
||||
- `outputs/rtsp_stream/latest.json`
|
||||
- `outputs/rtsp_stream/windows/stats_YYYY-MM-DD_HH-MM-SS.json`
|
||||
|
||||
## Docker On Ubuntu 24.04 x86_64
|
||||
|
||||
The project can be packaged for an x86_64 NVIDIA host with Docker. The expected weight layout is:
|
||||
|
||||
- `weights/yolo11n.pt`
|
||||
- `weights/deepface/age_model_weights.h5`
|
||||
- `weights/deepface/gender_model_weights.h5`
|
||||
- `weights/deepface/retinaface.h5`
|
||||
|
||||
Build the image:
|
||||
|
||||
```bash
|
||||
docker build -t people-flow-project:test .
|
||||
```
|
||||
|
||||
The Docker image uses [`requirements-docker.txt`](/Users/zxmacmini1/Documents/人流检测/people_flow_project/requirements-docker.txt) so the container installs `opencv-python-headless` instead of the desktop OpenCV wheel.
|
||||
|
||||
The image bakes in all runtime weights and copies the DeepFace `.h5` files into `~/.deepface/weights` during build.
|
||||
|
||||
Run the management API container:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name people-flow-project \
|
||||
--restart unless-stopped \
|
||||
--gpus all \
|
||||
--shm-size 1g \
|
||||
-p 18082:18082 \
|
||||
-e RTSP_URL="rtsp://user:password@host:554/stream" \
|
||||
-v /path/to/config:/opt/people-flow/config \
|
||||
-v /path/to/outputs:/opt/people-flow/outputs \
|
||||
people-flow-project:test
|
||||
```
|
||||
|
||||
Or use Compose:
|
||||
|
||||
```bash
|
||||
docker compose up --build people-flow-project
|
||||
```
|
||||
|
||||
Container behavior:
|
||||
|
||||
- Seeds `config/local.yaml` from `config/config.example.yaml` when needed
|
||||
- Writes RTSP updates through the child API to `runtime.rtsp_url`
|
||||
- Exposes `GET /api/manage/health` on `http://127.0.0.1:18082`
|
||||
- Persists config and outputs through mounted `./config` and `./outputs`
|
||||
|
||||
## Notes
|
||||
|
||||
- `minor` means age `< 18`
|
||||
- `adult` means age `18-59`
|
||||
- `senior` means age `>= 60`
|
||||
- Tracks without a reliable face result are counted only in `total_people` and `unknown_attributes`
|
||||
Reference in New Issue
Block a user