Overlap Filter¶

Class: OverlapBlockV1

Source: inference.core.workflows.core_steps.analytics.overlap.v1.OverlapBlockV1

Filter detection predictions to keep only objects that overlap with instances of a specified class, enabling spatial relationship filtering to identify objects that are positioned relative to other objects (e.g., people on bicycles, items on pallets, objects in containers).

How This Block Works¶

This block filters detections based on spatial overlap relationships with a specified overlap class. The block:

Takes detection predictions (object detection or instance segmentation) and an overlap class name as input
Separates detections into two groups:
Overlap class detections: Objects matching the specified overlap_class_name (e.g., "bicycle", "pallet", "car")
Other detections: All remaining objects that may overlap with the overlap class
For each overlap class detection, identifies other detections that spatially overlap with it using one of two overlap modes:
Center Overlap: Checks if the center point of other detections falls within the overlap class bounding box (more precise, requires the center to be inside)
Any Overlap: Checks if there's any spatial intersection between bounding boxes (more lenient, any overlap counts)
Collects all detections that overlap with any overlap class instance
Filters out the overlap class detections themselves from the output
Returns only the overlapping detections (objects that are positioned relative to the overlap class)

The block effectively answers: "Which objects are overlapping with instances of class X?" For example, if you specify "bicycle" as the overlap class, the block finds people or other objects that overlap with bicycles, but removes the bicycles themselves from the output. This enables workflows to identify objects that have spatial relationships with specific reference classes, such as identifying items on surfaces, objects in containers, or people on vehicles.

Common Use Cases¶

Person-on-Vehicle Detection: Identify people on bicycles, motorcycles, or other vehicles by using the vehicle class as the overlap class (e.g., filter for people overlapping with "bicycle" detections), enabling detection of riders, passengers, or people using vehicles
Items on Surfaces: Find objects positioned on pallets, tables, or shelves by using the surface class as the overlap class (e.g., filter for items overlapping with "pallet" detections), enabling inventory tracking, object counting on surfaces, or surface occupancy analysis
Objects in Containers: Identify items inside containers, boxes, or vehicles by using the container class as the overlap class (e.g., filter for objects overlapping with "container" detections), enabling content detection, loading verification, or container monitoring
Spatial Relationship Filtering: Filter detections based on proximity or containment relationships (e.g., find all objects that are inside or overlapping with a specific class), enabling conditional processing based on spatial arrangements
Nested Object Detection: Identify objects that are part of or attached to other objects (e.g., find equipment attached to vehicles, accessories on people), enabling detection of composite objects or object relationships
Zone-Based Filtering: Use overlap class as a reference zone to find objects that intersect with specific regions (e.g., filter objects overlapping with "parking_space" class), enabling zone-based analysis and conditional detection filtering

Connecting to Other Blocks¶

The filtered overlapping detections from this block can be connected to:

Detection model blocks (e.g., Object Detection Model, Instance Segmentation Model) to receive predictions that are filtered to show only objects overlapping with a specified reference class, enabling spatial relationship analysis
Visualization blocks (e.g., Bounding Box Visualization, Polygon Visualization, Label Visualization) to display only the overlapping objects, highlighting objects that have spatial relationships with the reference class
Counting and analytics blocks (e.g., Line Counter, Time in Zone, Velocity) to count or analyze only overlapping objects (e.g., count people on bicycles, track items on pallets), providing metrics for spatially related objects
Data storage blocks (e.g., Local File Sink, CSV Formatter, Roboflow Dataset Upload, Webhook Sink) to save or transmit filtered overlapping detection results, storing data about objects with specific spatial relationships
Filtering blocks (e.g., Detections Filter) to apply additional filtering criteria to the overlapping detections, enabling multi-stage filtering workflows
Flow control blocks (e.g., Continue If) to conditionally trigger downstream processing based on whether overlapping objects are detected, enabling workflows that respond to spatial relationships

Type identifier¶

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

Properties¶

Name	Type	Description	Refs
`name`	`str`	Enter a unique identifier for this step..	❌
`overlap_type`	`str`	Method for determining spatial overlap between detections. 'Center Overlap' checks if the center point of other detections falls within the overlap class bounding box (more precise, requires center to be inside). 'Any Overlap' checks if there's any spatial intersection between bounding boxes (more lenient, any overlap counts). Center Overlap is stricter and better for containment relationships, while Any Overlap is more inclusive and better for detecting any proximity or partial overlap..	❌
`overlap_class_name`	`str`	Class name of the reference objects used for overlap detection. Detections matching this class name are used as reference points, and other detections that overlap with these reference objects are kept in the output. The overlap class detections themselves are removed from the results. Example: Use 'bicycle' to find people or objects overlapping with bicycles; use 'pallet' to find items on pallets..	❌

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

Available Connections¶

Compatible Blocks

Check what blocks you can connect to Overlap Filter in version v1.

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Overlap Filter in version v1 has.

Bindings

input
- predictions (Union[instance_segmentation_prediction, object_detection_prediction]): Detection predictions (object detection or instance segmentation) containing objects that may overlap with the specified overlap class. The block identifies detections matching the overlap_class_name and finds other detections that spatially overlap with them. Only the overlapping detections (not the overlap class itself) are returned in the output..
output
- overlaps (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.

Example JSON definition of step Overlap Filter in version v1

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/overlap@v1",
    "predictions": "$steps.object_detection_model.predictions",
    "overlap_type": "Center Overlap",
    "overlap_class_name": "<block_does_not_provide_example>"
}