Line Counter¶

v2¶

Count objects crossing a defined line segment in video using tracked detections, maintaining separate counts for objects crossing in opposite directions (in and out), and outputting both count values and the actual detection objects that crossed the line for traffic analysis, people counting, entry/exit monitoring, and directional flow measurement workflows.

How This Block Works¶

This block counts objects that cross a line segment by tracking their movement across video frames. The block:

1. Receives tracked detection predictions with unique tracker IDs and an image with embedded video metadata
2. Extracts video metadata from the image:
3. Accesses video_metadata from the WorkflowImageData object
4. Extracts video_identifier to maintain separate counting state for different videos
5. Uses video metadata to initialize and manage line zone state per video
6. Validates that detections have tracker IDs (required for tracking object movement across frames)
7. Initializes or retrieves a line zone for the video:
8. Creates a LineZone from two coordinate points defining the line segment
9. Configures triggering anchor point if specified (optional - if not specified, uses default anchor behavior)
10. Stores line zone configuration per video using video_identifier
11. Maintains separate counting state for each video
12. Monitors object positions across frames:
13. Tracks each object's position using its unique tracker_id
14. Detects when an object's triggering anchor point (if specified) or default anchor crosses the line
15. Determines crossing direction based on which side of the line the object approaches from
16. Counts line crossings:
17. In Direction: Objects crossing the line in one direction increment the count_in counter
18. Out Direction: Objects crossing the line in the opposite direction increment the count_out counter
19. Each unique tracker_id is counted only once per crossing (prevents duplicate counting if object oscillates near line)
20. Identifies crossing detections:
21. Creates masks identifying which detections crossed in each direction in the current frame
22. Filters detections to separate those that crossed "in" from those that crossed "out"
23. Returns the actual detection objects (not just counts) for further processing
24. Maintains persistent counting state:
25. Counts accumulate across frames for the entire video
26. State persists for each video until workflow execution completes
27. Separate counters for each unique video_identifier
28. Returns four outputs:
29. count_in: Total number of objects that crossed the line in the "in" direction (cumulative across video)
30. count_out: Total number of objects that crossed the line in the "out" direction (cumulative across video)
31. detections_in: Detection objects that crossed the line in the "in" direction (current frame crossings)
32. detections_out: Detection objects that crossed the line in the "out" direction (current frame crossings)

The line segment defines a virtual boundary in the video frame. The direction (in/out) is determined by which side of the line objects approach from - for a horizontal line, objects coming from above might count as "in" while objects from below count as "out" (or vice versa, depending on line orientation). The triggering anchor (if specified) determines which point on the bounding box must cross the line for the crossing to be counted - if not specified, the line zone uses its default anchor behavior. The count outputs provide cumulative totals across the video, while the detection outputs provide the actual objects that crossed in the current frame, enabling further analysis or visualization of crossing events.

Common Use Cases¶

• People Counting: Count people entering and exiting buildings, stores, or events (e.g., count visitors entering store, track people entering/exiting building, monitor event attendance), enabling entry/exit counting workflows
• Traffic Analysis: Count vehicles passing through intersections or road segments (e.g., count vehicles crossing intersection, track traffic flow in specific directions, monitor vehicle passage at checkpoints), enabling traffic flow analysis workflows
• Retail Analytics: Track customer movement and foot traffic in retail spaces (e.g., count customers entering store sections, track movement between departments, monitor shopping flow patterns), enabling retail foot traffic analytics workflows
• Security Monitoring: Monitor entry and exit at secure areas or checkpoints (e.g., track entries to restricted areas, count people at access points, monitor checkpoint crossings), enabling security access monitoring workflows
• Occupancy Management: Track occupancy changes by counting objects entering and leaving spaces (e.g., count entries/exits to manage room capacity, track vehicle arrivals/departures in parking, monitor space occupancy changes), enabling occupancy tracking workflows
• Wildlife Monitoring: Count animals crossing defined paths or boundaries (e.g., track animal migration patterns, count wildlife crossing roads, monitor animal movement in habitats), enabling wildlife behavior analysis workflows

Connecting to Other Blocks¶

This block receives tracked detections and an image with embedded video metadata, and produces count_in, count_out, detections_in, and detections_out:

• After Byte Tracker blocks to count tracked objects crossing lines (e.g., count tracked people crossing line, track vehicle crossings with consistent IDs, monitor tracked object movements), enabling tracking-to-counting workflows
• After object detection or instance segmentation blocks with tracking enabled to count detected objects (e.g., count detected vehicles, track people crossings, monitor object movements), enabling detection-to-counting workflows
• Using detections_in or detections_out outputs to process or visualize objects that crossed the line (e.g., visualize objects that crossed, analyze crossing objects, filter for crossing events), enabling crossing object analysis workflows
• Before visualization blocks to display line counter information and crossing objects (e.g., visualize line and counts, display crossing statistics, show crossing objects with annotations), enabling counting visualization workflows
• Before data storage blocks to record counting data and crossing events (e.g., log entry/exit counts, store traffic statistics, record crossing objects with metadata), enabling counting data logging workflows
• Before notification blocks to alert on count thresholds or crossing events (e.g., alert when count exceeds limit, notify on specific object crossings, trigger actions based on counts), enabling count-based notification workflows

Version Differences¶

Enhanced from v1:

• Detection Outputs: Adds two new outputs (detections_in and detections_out) that provide the actual detection objects that crossed the line in each direction, not just count totals, enabling downstream processing and visualization of crossing objects
• Simplified Input: Uses image input that contains embedded video metadata instead of requiring a separate metadata field, simplifying workflow connections and reducing input complexity
• Optional Triggering Anchor: Makes triggering_anchor optional (default None) instead of required, allowing the line zone to use its default anchor behavior when no specific anchor is needed
• Improved Integration: Better integration with image-based workflows since video metadata is accessed directly from the image object rather than requiring separate metadata input

Requirements¶

This block requires tracked detections with tracker_id information (detections must come from a tracking block like Byte Tracker). The line must be defined as a list of exactly 2 points, where each point is a list or tuple of exactly 2 coordinates (x, y). The image's video_metadata should include video_identifier to maintain separate counting state for different videos. The block maintains persistent counting state across frames for each video, so it should be used in video workflows where frames are processed sequentially. For accurate counting, detections should be provided consistently across frames with valid tracker IDs.

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/line_counter@v2to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility¶

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video

Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in an InferencePipeline for stable cross-frame results.

soft — input image

Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Line Counter in version v2 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/line_counter@v2",
    "image": "<block_does_not_provide_example>",
    "detections": "$steps.object_detection_model.predictions",
    "line_segment": [
        [
            0,
            50
        ],
        [
            500,
            50
        ]
    ],
    "triggering_anchor": "CENTER"
}

v1¶

Count objects crossing a defined line segment in video using tracked detections, maintaining separate counts for objects crossing in opposite directions (in and out) for traffic analysis, people counting, entry/exit monitoring, and directional flow measurement workflows.

How This Block Works¶

This block counts objects that cross a line segment by tracking their movement across video frames. The block:

1. Receives tracked detection predictions with unique tracker IDs and video metadata
2. Validates that detections have tracker IDs (required for tracking object movement across frames)
3. Initializes or retrieves a line zone for the video:
4. Creates a LineZone from two coordinate points defining the line segment
5. Stores line zone configuration per video using video_identifier
6. Maintains separate counting state for each video
7. Monitors object positions across frames:
8. Tracks each object's position using its unique tracker_id
9. Detects when an object's triggering anchor point (default: CENTER of bounding box) crosses the line
10. Determines crossing direction based on which side of the line the object approaches from
11. Counts line crossings:
12. In Direction: Objects crossing the line in one direction increment the count_in counter
13. Out Direction: Objects crossing the line in the opposite direction increment the count_out counter
14. Each unique tracker_id is counted only once per crossing (prevents duplicate counting if object oscillates near line)
15. Maintains persistent counting state:
16. Counts accumulate across frames for the entire video
17. State persists for each video until workflow execution completes
18. Separate counters for each unique video_identifier
19. Returns two count values:
20. count_in: Total number of objects that crossed the line in the "in" direction
21. count_out: Total number of objects that crossed the line in the "out" direction

The line segment defines a virtual boundary in the video frame. The direction (in/out) is determined by which side of the line objects approach from - for a horizontal line, objects coming from above might count as "in" while objects from below count as "out" (or vice versa, depending on line orientation). The triggering anchor determines which point on the bounding box must cross the line for the crossing to be counted - using CENTER ensures the object is substantially across the line before counting.

Common Use Cases¶

• People Counting: Count people entering and exiting buildings, stores, or events (e.g., count visitors entering store, track people entering/exiting building, monitor event attendance), enabling entry/exit counting workflows
• Traffic Analysis: Count vehicles passing through intersections or road segments (e.g., count vehicles crossing intersection, track traffic flow in specific directions, monitor vehicle passage at checkpoints), enabling traffic flow analysis workflows
• Retail Analytics: Track customer movement and foot traffic in retail spaces (e.g., count customers entering store sections, track movement between departments, monitor shopping flow patterns), enabling retail foot traffic analytics workflows
• Security Monitoring: Monitor entry and exit at secure areas or checkpoints (e.g., track entries to restricted areas, count people at access points, monitor checkpoint crossings), enabling security access monitoring workflows
• Occupancy Management: Track occupancy changes by counting objects entering and leaving spaces (e.g., count entries/exits to manage room capacity, track vehicle arrivals/departures in parking, monitor space occupancy changes), enabling occupancy tracking workflows
• Wildlife Monitoring: Count animals crossing defined paths or boundaries (e.g., track animal migration patterns, count wildlife crossing roads, monitor animal movement in habitats), enabling wildlife behavior analysis workflows

Connecting to Other Blocks¶

This block receives tracked detections and video metadata, and produces count_in and count_out values:

• After Byte Tracker blocks to count tracked objects crossing lines (e.g., count tracked people crossing line, track vehicle crossings with consistent IDs, monitor tracked object movements), enabling tracking-to-counting workflows
• After object detection or instance segmentation blocks with tracking enabled to count detected objects (e.g., count detected vehicles, track people crossings, monitor object movements), enabling detection-to-counting workflows
• Before visualization blocks to display line counter information (e.g., visualize line and counts, display crossing statistics, show counting results), enabling counting visualization workflows
• Before data storage blocks to record counting data (e.g., log entry/exit counts, store traffic statistics, record occupancy metrics), enabling counting data logging workflows
• Before notification blocks to alert on count thresholds or events (e.g., alert when count exceeds limit, notify on occupancy changes, trigger actions based on counts), enabling count-based notification workflows
• Before analysis blocks to process counting metrics (e.g., analyze traffic patterns, process occupancy data, work with counting statistics), enabling counting analysis workflows

Requirements¶

This block requires tracked detections with tracker_id information (detections must come from a tracking block like Byte Tracker). The line must be defined as a list of exactly 2 points, where each point is a list or tuple of exactly 2 coordinates (x, y). The block requires video metadata with video_identifier to maintain separate counting state for different videos. The block maintains persistent counting state across frames for each video, so it should be used in video workflows where frames are processed sequentially. For accurate counting, detections should be provided consistently across frames with valid tracker IDs.

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/line_counter@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility¶

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video

Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in an InferencePipeline for stable cross-frame results.

soft — input image

Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Line Counter in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/line_counter@v1",
    "metadata": "<block_does_not_provide_example>",
    "detections": "$steps.object_detection_model.predictions",
    "line_segment": [
        [
            0,
            50
        ],
        [
            500,
            50
        ]
    ],
    "triggering_anchor": "CENTER"
}