Zone Dwell Summary Uploader

The Zone Dwell Summary Uploader action aggregates zone occupancy data and uploads it to the central cloud database, enabling heatmap visualizations and occupancy analytics.

---

Overview

Zone dwell data provides rich insights into how spaces are used:

• Which areas are most frequently occupied
• How long people spend in different zones
• Peak occupancy times
• Traffic flow patterns

This action takes the detailed local event data and creates summarized statistics suitable for dashboards and reports.

---

What It Does

1. Reads Local Events

The action queries the zone_dwell_events table for recent records that haven't been summarized.

2. Aggregates by Hour and Zone

For each hour and each zone, it calculates:

Metric	Description
Entry Count	How many times objects entered the zone
Average Dwell Time	Mean duration spent in zone
Min Dwell Time	Shortest recorded dwell
Max Dwell Time	Longest recorded dwell
Occupancy Minutes	Total minutes the zone was occupied

3. Uploads to Cloud

The aggregated summaries are inserted into the cloud table stream_zone_dwell_time. This enables:

• Cross-branch occupancy comparisons
• Historical trend analysis
• Heatmap visualizations
• Management reporting

4. Updates Status

Local records are marked to prevent duplicate processing in subsequent runs.

---

Configuration

Parameter	Type	Required	Default	Description
Summary Model Label ID	Number	No	All	Filter to summarize only specific object types
Hours Back	Number	No	24	How far back to look for unprocessed data

Model Label Filtering

If you only want to summarize people (not vehicles or other objects), specify the Model Label ID for "Person." This creates cleaner data for people-focused analytics.

---

Understanding Results

Result	Meaning
Uploaded zone dwell summaries	Data aggregated and uploaded successfully
No new data	No unprocessed events found
Upload failed	Check internet connectivity

---

Data Structure

Uploaded Summary Fields

Field	Description	Example
branch_id	Which branch	42
stream_id	Which camera	10
zone_id	Which zone	5
hour_timestamp	Hour being summarized	2024-01-15 14:00:00
entry_count	Objects that entered	45
avg_dwell_seconds	Average stay duration	127.5
min_dwell_seconds	Shortest stay	3.2
max_dwell_seconds	Longest stay	842.0
occupancy_minutes	Total occupied time	38.5

Occupancy Minutes Calculation

Occupancy Minutes represents how many minutes the zone had at least one object present. If 10 people each spent 1 minute in a zone, occupancy is still ~10 minutes (or less if they overlapped).

This metric is valuable for:

• Capacity planning
• Understanding busy vs. quiet zones
• Identifying bottlenecks

---

Common Use Cases

Retail Heatmaps

• Setup: Zones covering store sections (entrance, aisles, checkout)
• Schedule: Upload every 30 minutes
• Use: Visualize customer traffic patterns

Occupancy Monitoring

• Setup: Zones in meeting rooms or common areas
• Schedule: Upload hourly
• Use: Track space utilization for facility planning

Security Analytics

• Setup: Zones in restricted or sensitive areas
• Schedule: Upload frequently
• Use: Monitor for unusual occupancy patterns

Queue Analysis

• Setup: Zones at service counters or checkout areas
• Analysis: Average and max dwell times indicate wait times
• Use: Staff scheduling, service improvement

Traffic Flow

• Setup: Sequential zones along pathways
• Analysis: Compare entry counts between zones
• Use: Understand how people move through spaces

---

Troubleshooting

No New Data

1. Zone Dwell Recording: Verify Object Detection is running with tracking enabled and zones are recording events.

2. Already Processed: Previous runs may have processed all available data.

3. Time Range: Check Hours Back parameter isn't too restrictive.

Upload Failed

1. Internet: Verify server can reach internet.

2. Credentials: Check cloud database API credentials.

3. Service: Cloud service may be temporarily unavailable.

Incorrect Statistics

1. Zone Configuration: Verify zones are correctly defined and don't overlap unexpectedly.

2. Model Label Filter: If using Model Label ID filter, ensure correct ID is specified.

3. Time Zone: Timestamps may be affected by time zone differences.

Gaps in Data

1. Detection Interruption: Check if Object Detection had interruptions during the gap period.

2. Upload Failures: Previous upload failures may have left gaps.

3. No Activity: Gaps may reflect genuinely empty periods.

---

Best Practices

1. Regular Schedule: Run every 15-30 minutes for near-real-time dashboards.

2. Consistent Zones: Avoid frequently changing zone definitions, as this makes historical comparison difficult.

3. Model Label Filter: For people analytics, filter to people-only to exclude vehicles and other objects.

4. Zone Naming: Use descriptive zone names for clear reporting.

5. Dashboard Integration: Connect cloud data to visualization tools for meaningful insights.

---

Analytics Applications

Heatmap Generation

Aggregate entry_count by zone to create visual heatmaps showing:

• Hot spots (high traffic areas)
• Cold spots (underutilized areas)
• Changes over time

Dwell Time Analysis

Average dwell times reveal:

• Engagement levels (longer dwell = more engagement)
• Service efficiency (shorter dwell at service points = faster service)
• Problem areas (very long dwells may indicate confusion)

Peak Hour Identification

Entry counts by hour show:

• Busiest hours for staffing
• Quiet hours for maintenance
• Traffic patterns for marketing

Capacity Planning

Occupancy minutes indicate:

• How close zones are to capacity
• When additional space may be needed
• Which zones can absorb overflow

---

Related Actions

• Object Detection: Creates zone dwell events (source data)
• Zone Dwell Reader: Reads raw events for violation workflows
• Zone Dwell Violation Snapshot: Processes events for violations
• Visitor Summary Uploader: Similar uploader for entry/exit data