managed-portal/managed/people_flow_project/docs/plans/2026-04-07-people-flow-implementation.md

People Flow Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Build a standalone Python project that counts unique line crossings in street videos and adds track-level age/gender summaries.

Architecture: Use Ultralytics YOLO to detect and track persons frame by frame, then run DeepFace on sampled person crops to infer face attributes. Keep counting, tracking, and attribute voting in separate modules so the demographic backend can be swapped later.

Tech Stack: Python, Ultralytics YOLO, OpenCV, DeepFace, PyYAML, pandas

---

Task 1: Scaffold the project

Files:

• Create: README.md
• Create: requirements.txt
• Create: pyproject.toml
• Create: configs/default_config.yaml
• Create: docs/plans/2026-04-07-people-flow-design.md

Step 1: Write the initial files

Add installation instructions, runtime expectations, and default settings.

Step 2: Verify structure

Run: find . -maxdepth 3 | sed -n '1,120p' Expected: project files and directories exist.

Step 3: Commit

This workspace is not a git repository. Skip the commit step unless the user later initializes git here.

Task 2: Build the CLI and config loader

Files:

• Create: main.py
• Create: src/people_flow/__init__.py
• Create: src/people_flow/config.py
• Create: src/people_flow/models.py

Step 1: Implement argument parsing

Support video and batch subcommands, config overrides, output directory selection, and line overrides.

Step 2: Implement config loading

Load YAML defaults and merge CLI overrides into typed dataclasses.

Step 3: Verify

Run: python3 -m compileall main.py src Expected: compile succeeds without syntax errors.

Task 3: Implement tracking and counting

Files:

• Create: src/people_flow/tracking.py
• Create: src/people_flow/counting.py

Step 1: Extract tracked person detections

Convert YOLO result objects into simple track observations with track_id, bounding box, confidence, and center point.

Step 2: Implement line-cross counting

Count one crossing per track by monitoring the sign change of the track center relative to the configured line.

Step 3: Verify

Run: python3 -m compileall src Expected: compile succeeds.

Task 4: Implement attribute voting and output helpers

Files:

• Create: src/people_flow/attributes.py
• Create: src/people_flow/io_utils.py

Step 1: Integrate DeepFace

Sample person crops, run age and gender analysis, normalize labels, and store per-track votes.

Step 2: Implement output helpers

Write JSON summaries, CSV summaries, and draw overlays onto frames.

Step 3: Verify

Run: python3 -m compileall src Expected: compile succeeds.

Task 5: Implement the processing pipeline

Files:

• Create: src/people_flow/pipeline.py

Step 1: Build the main loop

Open the video, run YOLO tracking on frames, update counters, sample attributes, draw overlays, and save artifacts.

Step 2: Build batch mode

Discover supported video files recursively and run the same pipeline per file, then write outputs/batch_summary.csv.

Step 3: Verify

Run: python3 -m compileall main.py src Expected: compile succeeds.

Task 6: Final verification

Files:

• Modify: README.md

Step 1: Smoke-check the CLI

Run: python3 main.py --help Expected: help text shows the video and batch commands.

Step 2: Document limitations

Make sure README notes Python version constraints and face-quality limitations.

Step 3: Commit

Skip commit because this workspace is not a git repository.