Nearest Neighbor Detection Match¶

Perform a nearest-neighbor spatial join between two detection sets by finding, for each detection in a query set, the closest detection (or detections, on a tie) in a target set, using plain 2D Euclidean pixel distance between configurable anchor points.

How This Block Works¶

This block matches each detection in a query set to its nearest neighbor(s) in a target set. The block:

1. Receives query predictions and target predictions (object detection, instance segmentation, or keypoint detection) - the same set can be passed as both query and target
2. Resolves an anchor point for every detection in each set, based on the selected query_point and target_point options: the center, one of the four corners, one of the four edge midpoints of the bounding box, or a named keypoint (requires keypoint detection predictions and query_keypoint_name/target_keypoint_name)
3. Computes a full pairwise pixel-distance matrix between every query anchor point and every target anchor point (brute-force, not a spatial tree - appropriate for the tens-of-detections-per-frame scale this block targets)
4. For each query detection, excludes any target detection that shares its detection_id (self-match exclusion), so passing the same detections as both query and target does not match a detection against itself
5. If max_distance is set, discards any remaining candidate target farther than max_distance pixels from the query anchor point before ranking - a target beyond the limit is treated the same as an excluded self-match
6. Finds the minimum distance for each query detection, then includes every remaining target detection whose distance is within a fixed 1-pixel epsilon of that minimum, so exact or near-exact ties produce multiple matches instead of an arbitrary single winner
7. Attaches the nearest distance (in pixels) to each query detection's metadata; detections with no eligible target (empty target set, every target excluded as a self-match, or every remaining target farther than max_distance) get None
8. Returns three flat, aligned outputs: the enriched query predictions, and two same-length/same-order detection sets - matched_query_detections and matched_target_detections - with one row per query-target pairing. A query detection with a tie appears once per tied match (its row is duplicated); a query detection with no valid match is omitted from both, and only shows up in query_predictions (with nearest_target_distance set to None)

Distance is always plain, uncalibrated 2D Euclidean pixel distance - there is no real-world unit conversion, unlike the Distance Measurement block. This keeps the block simple for use cases that only need relative/pixel-space proximity.

Common Use Cases¶

• Zone/Anchor Assignment: Assign each detected object to its nearest reference point or anchor detection (e.g. match people to the nearest exit sign, match vehicles to the nearest parking spot marker), enabling proximity-based assignment workflows
• Cross-Class Association: Associate detections of one class with the nearest detection of another class (e.g. match detected hands to the nearest detected tool, match players to the nearest ball detection), enabling relationship analysis between different object types
• Duplicate/Overlap Analysis: Compare a detection set against itself to find each detection's closest neighbor (e.g. find the closest other person in a crowd, identify tightly clustered detections), enabling density and clustering analysis
• Tracking Handoff: Match detections between two model outputs on the same frame (e.g. match a fast general detector's output to a slower specialist model's output) to combine results, enabling multi-model fusion workflows

Connecting to Other Blocks¶

This block receives two detection sets and produces the enriched query predictions plus two flat, aligned detection sets representing every query-target pairing - no dimensionality tricks or intermediate merge step required, since matched_query_detections and matched_target_detections are ordinary detection sets of the same shape any detection-producing block returns:

• After object detection, instance segmentation, or keypoint detection model blocks to build the query and target sets to match, enabling detection-to-matching workflows
• Before logic blocks like Continue If or Detections Filter to make decisions based on nearest_target_distance (e.g. continue if the nearest match is within a threshold distance) or to filter matched_query_detections/matched_target_detections directly, enabling proximity-based decision workflows
• Before visualization blocks like Label Visualization or Bounding Box Visualization to display the enriched query_predictions, or matched_query_detections/matched_target_detections side by side to draw matched pairs, enabling distance-annotated visualizations
• Before data storage blocks like CSV Formatter to export every query-target pairing as a row, enabling matched-pair logging workflows

Requirements¶

This block requires two sets of detection predictions (object detection, instance segmentation, or keypoint detection); the same set can be used for both query_predictions and target_predictions. To use the KEYPOINT anchor option for either set, that set must be keypoint detection predictions and the corresponding query_keypoint_name/target_keypoint_name must be provided. Self-match exclusion relies on detection_id being present on both sets - this is populated automatically for all Roboflow object detection, instance segmentation, and keypoint detection model blocks. max_distance is optional; leave it unset to match every query detection to its nearest target regardless of distance.

Note that query_predictions is enriched in place - the same sv.Detections object passed in is mutated (a new nearest_target_distance field is added to its .data) and returned, the same convention used by blocks like Velocity and Time in Zone. Avoid feeding the same selector into two independent branches of a workflow if each branch needs to see its own, unmodified nearest_target_distance.

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/detections_nearest_neighbor@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.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Nearest Neighbor Detection Match in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/detections_nearest_neighbor@v1",
    "query_predictions": "$steps.model.predictions",
    "target_predictions": "$steps.model.predictions",
    "query_point": "CENTER",
    "target_point": "CENTER",
    "query_keypoint_name": "left_shoulder",
    "target_keypoint_name": "left_shoulder",
    "max_distance": 50
}