[FEATURE] — Build track event timeline visualizer

[Devnil434]

Description

Build an offline visualization tool that renders a timeline chart for
stored TrackSequence events.

The chart should help contributors analyze:

• dwell duration
• zone transitions
• suspicious activity timing
• action hints over time

---

File to Create

scripts/visualize_timeline.py

---

Example Usage

python scripts/visualize_timeline.py \
  --camera cam_01 \
  --output timeline.png

---

Visualization Requirements

X-axis

• time in seconds

Y-axis

• one row per track_id

Color Coding

• restricted zone → red
• safe zone → green

Action Hint Markers

• ⚡ ZONE_ENTRY
• 🔑 NEAR_KEYPAD
• ⏳ LINGERING

---

Technical Requirements

• Use matplotlib

• Support headless environments:

  matplotlib.use("Agg")

• Render PNG output

• Support synthetic test data without Redis

---

Acceptance Criteria

• PNG output generated correctly
• Works with at least 5 tracks
• Runs without display server
• Unit tests use synthetic TrackSequence data
• Existing tests remain green

---

Helpful Context

Relevant modules:

services/memory/
libs/schemas/memory.py
scripts/

[RamaMavuduru]

Hi, I’d like to work on this issue.

I plan to create scripts/visualize_timeline.py using Matplotlib in headless mode (Agg) to generate a PNG timeline chart from TrackSequence data. The script will plot time on the X-axis and track IDs on the Y-axis, apply color coding for zones (restricted/safe), and add clear markers for action hints such as ZONE_ENTRY, NEAR_KEYPAD, and LINGERING.

To keep it self-contained and testable, I will support synthetic TrackSequence data without Redis and add unit tests covering multiple tracks, edge cases, and invalid inputs. I’ll ensure the output works in headless environments and that all existing tests remain green.

Looking forward to your confirmation before I begin.

[Soha-b]

Hi @Devnil434, I would like to work on this issue under GSSoC 2026.

Implementation Plan:

Script Setup:
Create scripts/visualize_timeline.py using matplotlib
with matplotlib.use("Agg") for headless PNG output.

Visualization:

• X-axis: time in seconds
• Y-axis: one row per track_id
• Color coding: restricted zone in red, safe zone in green
• Markers for ZONE_ENTRY, NEAR_KEYPAD, and LINGERING events

Synthetic Data:
Build a data generator from the TrackSequence structure
in libs/schemas/memory.py so the script runs without
Redis, no external dependency needed for testing.

Acceptance Criteria Coverage:

• PNG output generated correctly via plt.savefig()
• Works with 5 or more tracks
• Runs without display server using Agg backend
• Unit tests use synthetic TrackSequence data
• Existing tests stay green

Testing:
Unit tests covering 5+ tracks, single event edge cases,
empty track handling and invalid inputs.

Files I will touch:

• scripts/visualize_timeline.py
• tests/test_visualize_timeline.py

I have gone through services/memory/ and
libs/schemas/memory.py to understand the TrackSequence
structure. Ready to start immediately and happy to
discuss any implementation details if needed.

Please assign this to me.

[RamaMavuduru]

Thanks for assigning this issue to me.I will start working on it shortly.