Detect zone entry/exit events for tracked objects

Use This When

• Building security systems that alert when people enter restricted zones
• Implementing retail analytics that count customers entering specific store areas
• Creating safety monitoring for detecting workers entering hazardous regions
• Tracking vehicle movements across different parking or traffic zones

What It Does

• Tracks per-object “inside zone?” status over time and detects transitions
• Keeps a short history per tracked ID to smooth boundary chatter
• Emits transition codes: 0=NoChange, 1=Entry, 2=Exit
• Forgets objects after time without observation to limit memory

Transition Codes → Labels

• 0 → NoChange (no label)
• 1 → Entry (object newly inside relative to its initial state)
• 2 → Exit (object newly outside relative to its initial state)

Notes on behavior

• First observation for an ID yields 0 (NoChange). The component compares the recent history window against the ID’s initial observed state to decide Entry vs Exit.
• History smoothing: a transition is reported once the majority of the recent frames disagree with the initial state (helps suppress flicker on boundaries).
• Forgetting: if an ID is not observed for a while, its history is discarded and the next observation behaves like first sighting.

Example timeline

1. First sighting outside → 0 (NoChange)
2. Next frames mostly inside → still 0 until a stable majority forms
3. Once inside is the stable majority → 1 (Entry)

How to label in UIs

• This component emits only numeric codes. Downstream stages convert codes to display labels, e.g. 1 → "Entry", 2 → "Exit".
• The visualize-zone-transition component expects these codes and renders labels accordingly.

Works Best With

• track-object → detect-object-containment (per zone) → this component → alerting/visualization
• Multi-zone setups where you run one containment + transition stream per zone
• visualize-zone-transition to debug transition detection visually
• evaluate-expression to combine multiple zone events into complex rules

Caveats

• Requires consistent tracking IDs; ID switches cause false entry/exit events
• Very short history windows can cause boundary chatter; very long windows can delay events
• Balance forgetting behavior to handle occlusions without retaining stale IDs
• Ensure coordinate frames align with the zone definition