145 lines
3.9 KiB
Markdown
145 lines
3.9 KiB
Markdown
# 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`
|