Skip to main content

Visitor Entry Counting

The Visitor Entry Counting action is an advanced AI-powered people counter that tracks individuals crossing entry and exit lines, with optional demographic analysis (age and gender estimation).

Overview​

This action provides comprehensive footfall analytics by:

  • Counting entries and exits with high accuracy
  • Tracking individual people to prevent double-counting
  • Estimating demographic information for market analysis
  • Storing detailed records for reporting and business intelligence

It's designed for retail stores, malls, offices, and any location where understanding visitor traffic is valuable.

What It Does​

1. Continuous Monitoring​

The action monitors the camera stream continuously (or for the configured runtime), analyzing every frame for people movement.

2. Person Detection and Tracking​

Using AI object detection, the action:

  • Detects all people in the camera view
  • Assigns unique tracking IDs to each person
  • Follows their movement across frames
  • Maintains tracking even when people are briefly obscured

3. Line Crossing Detection​

You define virtual "Entry" and "Exit" lines in the Zone Editor. The action watches for people crossing these lines:

  • Entry Count: Person crosses Entry line, then Exit line (moving into the space)
  • Exit Count: Person crosses Exit line, then Entry line (leaving the space)

This direction-aware counting prevents simple "line touch" errors.

4. Demographic Analysis (Optional)​

When a person enters, the action can:

  • Capture a cropped image of the person
  • Send it to the AI analysis service
  • Estimate age range (child, young adult, adult, senior)
  • Estimate gender (male, female)

This data is stored with the entry record for demographic reporting.

5. Database Storage​

All entry and exit events are stored in the local database with:

  • Timestamp
  • Direction (entry or exit)
  • Stream/camera information
  • Demographic data (if enabled)
  • Tracking information

Configuration​

Required: Line Setup​

Before using this action, you must configure zones in the Zone Editor:

Zone TypePurposeTips
Entry LineMarks the boundary for entriesDraw perpendicular to the expected path of traffic
Exit LineMarks the boundary for exitsPlace parallel to or overlapping with Entry Line

For simple doorway counting, Entry and Exit lines can be the same line—the action determines direction by movement trajectory.

Parameters​

ParameterTypeDefaultDescription
StreamsTable SelectionRequiredCamera(s) to monitor
Stream ZonesTable SelectionRequiredEntry/Exit lines to use
Confidence ThresholdNumber (0-1)0.4Minimum detection confidence
Entry Frame ThresholdNumber2Frames a person must be tracked before counting
Max Missed FramesNumber10How long to maintain tracking if person disappears
Max Runtime SecondsNumber900How long to run (0 for continuous with rule scheduling)
Enable DemographicsBooleanFalseWhether to estimate age/gender

Parameter Details​

Confidence Threshold: Lower values (0.3) detect more people but may have false positives. Higher values (0.5+) are more selective but may miss some detections.

Entry Frame Threshold: Prevents counting people who briefly appear at the edge of frame. Value of 2-3 filters noise while still catching real entries.

Max Missed Frames: Handles temporary occlusions. If a person is blocked by a pillar for 5 frames, tracking continues. If blocked for more than this value, they're treated as a new person.

Understanding Results​

Action Results​

ResultMeaning
processing_completeAction ran for full duration
stream_errorCould not connect to camera

Data Output​

The action provides summary data:

  • Total Entries: Number of people who entered
  • Total Exits: Number of people who exited
  • Net Change: Entries minus Exits (current occupancy change)

Detailed records are stored in the visitor_entries database table.

Common Use Cases​

Retail Footfall Counting​

  • Setup: Camera above store entrance pointing down, entry/exit lines at doorway
  • Schedule: Continuous during business hours
  • Use: Track daily, weekly, seasonal traffic patterns

Occupancy Management​

  • Setup: Cameras at all entrances/exits
  • Schedule: Continuous
  • Use: Monitor real-time occupancy against capacity limits

Marketing Analytics​

  • Setup: Enable demographic analysis
  • Schedule: Continuous during campaigns
  • Use: Understand visitor demographics to optimize marketing

Conversion Rate Analysis​

  • Setup: Camera at store entrance
  • Integration: Combine entry counts with POS transaction data
  • Use: Calculate browse-to-buy conversion rates

Mall Traffic Distribution​

  • Setup: Cameras at each store entrance
  • Schedule: Continuous
  • Use: Understand traffic flow and identify high/low traffic areas

Troubleshooting​

Missed Counts​

  1. Lower Confidence Threshold: Try reducing to 0.3 or even 0.25 to catch more detections.

  2. Adjust Line Position: Move entry/exit lines further into the space so people fully cross before the detection zone ends.

  3. Camera Coverage: Ensure the camera covers the entire width of the entrance. People walking at edges may not be detected.

  4. Lighting: Ensure adequate lighting. Low-light conditions reduce detection accuracy.

  5. Camera Angle: Top-down angles work best. Extreme angles may cause people to overlap and be missed.

Double Counts​

  1. Increase Entry Frame Threshold: Raise from 2 to 3 or 4 to require more consistent tracking before counting.

  2. Adjust Max Missed Frames: If people are stopping in the detection area and being re-counted, try reducing this value.

  3. Line Placement: Move lines closer together or use a single line. Large gaps between entry/exit lines can cause issues.

  4. Check for Reflections: Glass doors or windows may create reflection-based false detections.

Demographics Not Working​

  1. Service Availability: Demographic analysis requires the RunPod or AI analysis service. Verify it's accessible from the ResEngine server.

  2. Network: Check internet connectivity for cloud-based analysis services.

  3. Image Quality: Blurry or small person crops may fail demographic analysis. Ensure camera provides clear images.

  4. Feature Enabled: Verify "Enable Demographics" is turned on in the configuration.

Counts Not Appearing in Reports​

  1. Check Database: Verify records are being written to the visitor_entries table.

  2. Upload Schedule: Data may need to sync to cloud via the Visitor Summary Uploader action. Ensure this is scheduled.

  3. Time Zone: Verify timestamps and ensure reporting is using the correct time zone.

High CPU Usage​

  1. Reduce Resolution: Lower the input resolution if the camera supports it.

  2. Single Camera: If running on limited hardware, monitor one camera per action instance.

  3. Frame Skip: Some configurations allow processing every Nth frame to reduce load.

Best Practices​

Camera Placement​

  • Height: Mount cameras 2.5-3.5 meters high for optimal top-down view
  • Angle: Aim for 45-60 degree downward angle
  • Coverage: Ensure entire entrance width is visible
  • Lighting: Ensure consistent, adequate lighting

Line Configuration​

  • Perpendicular: Draw lines perpendicular to the main traffic flow
  • Full Width: Lines should span the entire entrance width
  • Buffer Space: Leave some space between lines and frame edges

Data Management​

  • Regular Uploads: Schedule Visitor Summary Uploader to sync data to cloud regularly
  • Data Retention: Configure appropriate local data retention policies
  • Backup: Ensure database backups are configured

Accuracy Optimization​

  • Calibration Period: Run the action for several hours and manually verify counts against actual traffic
  • Adjust Parameters: Fine-tune confidence and frame thresholds based on calibration results
  • Periodic Verification: Regularly spot-check counts to ensure ongoing accuracy
  • Visitor Summary Uploader: Aggregates and uploads visitor data to cloud database
  • Line Crossing Events Reader: Reads stored visitor records for processing
  • Zone Dwell Summary Uploader: Uploads zone occupancy data