# 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.