Detections Difference

Match detections across before/after images and report removed, persisted and new objects.

Compare two sets of detections of the same scene taken at different times and report what was removed, what persisted, and what is new.

The canonical use case is cleanup verification: run a detector on a "before" photo of a littered area and again on an "after" photo taken from roughly the same viewpoint once cleanup is claimed. Detections from the "before" image that cannot be matched in the "after" image are removed - evidence the cleanup happened. The same pattern generalises to any before/after audit: shelf restocking checks (which products disappeared / appeared), construction-site or warehouse inspection rounds, parking-lot occupancy deltas, or comparing the output of two different models on the same image to see where they disagree at the object level.

reference_predictions is the "before" set, candidate_predictions the "after" set. Each reference detection is matched against at most one candidate detection (and vice versa) by minimising a pairwise cost:

cost = spatial_weight * spatial_term (+ class_mismatch_penalty)

where spatial_term is 1 - IoU for overlapping boxes; for disjoint boxes it falls back to 1 + d, with d the centre distance normalised by the diagonal of the pair's smallest enclosing box, so any overlapping pair is always cheaper than any disjoint pair while disjoint pairs still rank by proximity. The class penalty applies when the two detections carry different classes; with class_strict enabled cross-class matches are forbidden outright. Matched pairs whose cost exceeds reject_cost are discarded, turning both sides of the pair into an unmatched removal/appearance.

Outputs: removed_detections (unmatched reference detections, in the reference image's coordinates), persisted_detections and new_detections (matched / unmatched candidate detections, in the candidate image's coordinates), the corresponding counts, and a verified flag that is true when the reference set was non-empty and at least min_removed_to_verify detections were removed.

This block is the cross-time counterpart of roboflow_core/overlap_analysis@v1, which relates two detection sets from the same image geometrically; this block instead assigns detections one-to-one across two images of the same scene and reports the set difference.

Type identifier

Use the following identifier in step "type" field: roboflow_core/detections_difference@v1 to add the block as a step in your workflow.

Properties

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
spatial_weight	float	Weight of the spatial term in the matching cost. The spatial term is 1 - IoU for overlapping boxes and 1 + normalised centre distance for disjoint boxes, so it ranges over [0, 2)..	✅
class_mismatch_penalty	float	Cost added to a pair whose detections carry different classes. Ignored when class_strict is enabled (cross-class pairs are then forbidden entirely)..	✅
reject_cost	float	Pairs whose matching cost exceeds this value are not matched; both detections are then reported as removed / new respectively..	✅
class_strict	bool	When enabled, detections of different classes can never match, regardless of spatial proximity..	✅
min_removed_to_verify	int	Minimum number of removed detections required (together with a non-empty reference set) for the verified output to be true..	✅

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

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Detections Difference in version v1 has.

Input and output bindings

• input

  • reference_predictions (object_detection_prediction): Detections from the reference ("before") image. Reference detections that cannot be matched in candidate_predictions are reported as removed_detections..

  • candidate_predictions (object_detection_prediction): Detections from the candidate ("after") image. Candidate detections matched to a reference detection are reported as persisted_detections; unmatched ones as new_detections..

  • spatial_weight (float_zero_to_one): Weight of the spatial term in the matching cost. The spatial term is 1 - IoU for overlapping boxes and 1 + normalised centre distance for disjoint boxes, so it ranges over [0, 2)..

  • class_mismatch_penalty (float): Cost added to a pair whose detections carry different classes. Ignored when class_strict is enabled (cross-class pairs are then forbidden entirely)..

  • reject_cost (float): Pairs whose matching cost exceeds this value are not matched; both detections are then reported as removed / new respectively..

  • class_strict (boolean): When enabled, detections of different classes can never match, regardless of spatial proximity..

  • min_removed_to_verify (integer): Minimum number of removed detections required (together with a non-empty reference set) for the verified output to be true..

• output

  • removed_detections (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.

  • persisted_detections (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.

  • new_detections (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.

  • removed_count (integer): Integer value.

  • new_count (integer): Integer value.

  • verified (boolean): Boolean flag.

Example JSON definition

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/detections_difference@v1",
	    "reference_predictions": "$steps.before_model.predictions",
	    "candidate_predictions": "$steps.after_model.predictions",
	    "spatial_weight": 0.4,
	    "class_mismatch_penalty": 0.15,
	    "reject_cost": 0.75,
	    "class_strict": false,
	    "min_removed_to_verify": 1
	}