managed-portal/managed/people_flow_project/docs/plans/2026-04-08-rtsp-windowed-people-flow.md

RTSP Windowed People Flow Implementation Plan

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

Goal: Add an RTSP mode that samples one frame per second, emits independent 30-minute JSON summaries, and preserves the existing offline video and batch workflows.

Architecture: Keep the existing offline pipeline untouched and add a dedicated RTSP pipeline path that reuses the counting and attribute aggregation components. Introduce a small RTSP configuration model and window-summary writer so the stream loop can reconnect, flush windowed JSON files, and reset state cleanly.

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

---

Task 1: Add RTSP configuration models

Files:

• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/models.py
• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/config.py
• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/configs/default_config.yaml

Step 1: Add an RTSP config dataclass

• Add a dataclass with interval, window duration, reconnect delay, idle sleep, and output subdirectory fields.
• Attach it to AppConfig.

Step 2: Load RTSP config from YAML

• Update config loading to parse the new section.
• Keep backward compatibility when the section is absent.

Step 3: Set sensible defaults in YAML

• Add sample_interval_seconds: 1
• Add window_seconds: 1800
• Add reconnect and idle sleep defaults.

Step 4: Run a compile check

Run: python3 -m compileall main.py src Expected: PASS

Task 2: Add the RTSP CLI entrypoint

Files:

• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/main.py

Step 1: Add a new rtsp subcommand

• Accept --input as the RTSP URL.
• Reuse global config and output arguments.

Step 2: Wire the command to the pipeline

• Call a new process_rtsp() method.
• Print the output directory and latest JSON path once the command starts.

Step 3: Verify CLI help

Run: python3 main.py rtsp --help Expected: PASS and shows the RTSP input argument.

Task 3: Implement the RTSP processing loop

Files:

• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py
• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/io_utils.py

Step 1: Add RTSP output helpers

• Add a helper that creates /rtsp_stream/windows.
• Add a helper that writes a timestamped JSON file and refreshes latest.json.

Step 2: Add RTSP window summary generation

• Reuse the existing summary-building logic, but parameterize it with source, window_start, and window_end.
• Keep the same count keys and track payload structure.

Step 3: Add process_rtsp()

• Open the RTSP stream with OpenCV.
• Reconnect on open/read failures after a delay.
• Sample one frame per second based on wall-clock time.
• Reuse YOLO tracking, crossing detection, and DeepFace aggregation on sampled frames only.
• Flush a JSON summary every 30 minutes.
• Reset counting and attribute state after each flush.

Step 4: Keep long-running behavior explicit

• Do not save annotated RTSP video by default.
• Ensure zero-count windows still emit JSON.

Task 4: Preserve offline behavior

Files:

• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/src/people_flow/pipeline.py

Step 1: Refactor only shared summary code

• Extract helper methods where useful.
• Do not change the existing video/batch outputs or file naming.

Step 2: Re-run offline CLI smoke tests

Run: python3 main.py --help Expected: PASS

Run: python3 main.py video --help Expected: PASS

Run: python3 main.py batch --help Expected: PASS

Task 5: Update docs and validate

Files:

• Modify: /Users/zxmacmini1/Documents/人流检测/people_flow_project/README.md

Step 1: Document the new RTSP mode

• Add example commands.
• Explain the 1 FPS sampling and 30-minute window JSON behavior.

Step 2: Run final validation

Run: python3 -m compileall main.py src Expected: PASS

Run: python3 main.py rtsp --help Expected: PASS

Run: python3 main.py --help Expected: PASS