People Flow Design

Goal

Build a standalone project under Documents/人流检测/people_flow_project that analyzes street videos and produces:

unique people-flow counts
one mutually exclusive age bucket per counted person
one mutually exclusive gender bucket per counted person
annotated videos plus machine-readable summaries

Approved Decisions

Runtime target: Linux with NVIDIA GPU
Entry points: both single-video mode and batch-directory mode
Count logic: one track_id is counted once when it crosses a configured line
Age buckets:
- minor: age < 18
- adult: age 18-59
- senior: age >= 60
Gender buckets:
- male
- female
Unknown face attributes:
- If a counted person does not yield a reliable face result, count that person only in total_people
- Also increment unknown_attributes

Architecture

The pipeline uses Ultralytics YOLO for person detection and tracking, then DeepFace for face attribute analysis. Person tracking and counting stay separate from attribute inference so the demographic model can be replaced later without touching the counting core.

The application stores votes per track_id. When the video finishes, each counted track is resolved to at most one final age bucket and one final gender bucket by majority voting.

Modules

main.py: CLI parsing and mode dispatch
src/people_flow/config.py: config loading and overrides
src/people_flow/tracking.py: track extraction from YOLO results
src/people_flow/counting.py: line-crossing logic and unique counting
src/people_flow/attributes.py: DeepFace integration and voting
src/people_flow/io_utils.py: video, JSON, and CSV output helpers
src/people_flow/pipeline.py: process orchestration

Outputs

For each video:

annotated MP4
JSON summary

For batch runs:

one CSV summary with one row per video

Error Handling

Missing dependencies should raise clear installation guidance.
If a video cannot be opened, fail that video with a readable error.
If face inference fails for a sample, continue processing and treat that sample as unavailable.
If no video files are found in batch mode, fail fast with a clear message.

Limitations

Age and gender quality depend on clear, sufficiently large faces.
Street scenes with strong occlusion, side views, masks, or low light will increase unknown_attributes and lower reliability.
The default line is a placeholder and should be adjusted per camera view.

2.4 KiB Raw Blame History