Zone Dwell Reader

The Zone Dwell Reader action retrieves stored zone dwell (loitering) events from the local database, enabling violation workflows and analysis of occupancy patterns.

---

Overview

When the Object Detection action runs with tracking enabled, it records events in the zone_dwell_events table whenever objects spend time in defined zones. The Zone Dwell Reader queries these records to:

• Find events that exceed configured dwell time thresholds
• Identify loitering incidents for violation creation
• Analyze zone occupancy patterns
• Feed data into reporting workflows

---

What It Does

1. Queries Database

The action executes a SELECT query against the zone_dwell_events table. This can be:

• A custom SQL query you provide
• An automatic query based on time parameters

2. Filters Events

The query filters events based on your criteria:

• Duration thresholds (e.g., dwell time > 300 seconds)
• Specific zones
• Time ranges
• Processing status

3. Returns Records

Matching records are returned to the workflow, making them available for:

• Violation creation (via Zone Dwell Violation Snapshot)
• Data upload (via Zone Dwell Summary Uploader)
• Custom processing

---

Configuration

Parameter	Type	Required	Description
Select Query	Text	No	Custom SQL SELECT query
Hours Back	Number	No	If no query, how many hours back to look (default: 24)
Limit	Number	No	Maximum records to return (default: 100)

Query vs. Parameters

You can either:

• Provide a custom query: Full control over filtering and selection
• Use automatic parameters: Hours Back and Limit generate a simple query

If you provide a query, the Hours Back and Limit parameters are ignored.

Available Table: zone_dwell_events

Column	Type	Description
id	Integer	Unique event identifier
track_id	Integer	Object tracking ID
stream_id	Integer	Camera that recorded this
zone_id	Integer	Zone where dwell occurred
start_time	DateTime	When object entered zone
end_time	DateTime	When object left zone
duration_seconds	Float	Total time in zone
label_id	Integer	Object type (person, vehicle, etc.)
processed	Boolean	Whether violation created
full_frame_path	Text	Path to captured image
extra_info	JSON	Additional data (e.g., plate numbers)

Example Queries

Loitering over 5 minutes:

SELECT * FROM zone_dwell_events WHERE duration_seconds > 300 AND processed = false ORDER BY start_time DESC

Specific zone in last 2 hours:

SELECT * FROM zone_dwell_events WHERE zone_id = 42 AND start_time > datetime('now', '-2 hours')

Unprocessed events for a camera:

SELECT * FROM zone_dwell_events WHERE stream_id = 10 AND processed = false LIMIT 50

---

Understanding Results

Result	Meaning	Data
records_found	Events matching criteria found	Records in action result
no_records	No matching events	Empty result set
query_error	SQL error	Check query syntax

---

Common Use Cases

Loitering Violation Workflow

The most common use case. Workflow:

1. Zone Dwell Reader: Find events > 5 minutes duration
2. Zone Dwell Violation Snapshot: Prepare annotated images
3. Create Violation: Record the incident

Schedule this workflow to run every 5-15 minutes.

Occupancy Analysis

• Query: Select all events from today grouped by zone
• Use: Understand which areas have highest dwell times
• Output: Feed into analytics dashboard

Security Monitoring

• Query: Select events in restricted zones
• Threshold: Any dwell (even brief) in forbidden areas
• Action: Immediate alert creation

Heatmap Generation

• Query: Aggregate dwell times by zone and hour
• Output: Visual representation of space utilization
• Use: Retail layout optimization, crowd management

---

Troubleshooting

No Records Found

1. Detection Running: Verify Object Detection with tracking is running and detecting objects.

2. Zone Configuration: Confirm Detection Zones (Type 1) are configured for the cameras.

3. Tracking Enabled: Zone dwell only records when "Enable Tracking and Zone Dwell" is on in Object Detection.

4. Time Range: Your query may be filtering out events. Try broadening the time range.

5. Duration Threshold: If filtering by duration, objects may not be staying long enough.

Query Errors

1. SQL Syntax: Verify query is valid SQL.

2. Column Names: Check column names match the table schema exactly.

3. Table Name: Ensure table is zone_dwell_events (exact spelling).

Missing Events

1. Object Detection: Verify detection is working and finding objects.

2. Zone Coverage: Ensure objects are entering the defined zones.

3. Confidence Threshold: Objects below threshold won't be tracked.

4. Processing Flag: Previously processed events won't appear if filtered by processed = false.

Duplicate Violations

1. Processing Flag: Ensure Zone Dwell Violation Snapshot marks events as processed.

2. Query Filter: Include processed = false in your query.

3. Run Frequency: Very frequent runs may catch events before processing completes.

---

Best Practices

1. Filter by Processed: Always include processed = false in violation workflows to prevent duplicates.

2. Set Appropriate Limits: Use LIMIT to prevent overwhelming subsequent actions with too many records.

3. Duration Thresholds: Set duration thresholds that match your definition of "loitering." Too low creates noise; too high misses incidents.

4. Regular Schedule: Run violation workflows frequently (every 5-15 minutes) for timely alerts.

5. Zone-Specific Rules: Different zones may need different thresholds (e.g., 30 seconds at an emergency exit vs. 5 minutes in a lobby).

---

Related Actions

• Object Detection: Creates the zone dwell events (with tracking enabled)
• Zone Dwell Violation Snapshot: Prepares evidence from these events
• Zone Dwell Summary Uploader: Uploads aggregated dwell statistics
• Create Violation: Records violations from dwell events