Content trigger (not one directory). Load when a diff does any of:
-
Coordinate frames stay consistent. Every geometry channel of a detection — xyxy, mask, data[POLYGON_KEY_IN_SV_DETECTIONS], keypoints_xy — is transformed together by the same shift/scale. sv_detections_to_root_coordinates and scale_sv_detections in common/utils.py are the canonical seam: both apply the shift/scale to POLYGON_KEY_IN_SV_DETECTIONS after xyxy/mask (polygon shift in root recovery #2473; polygon scale #1268). Failure mode: masks/polygons drawn or uploaded at the wrong location, invisible to a test that only checks xyxy.
-
Response shape is a contract. Block outputs match the manifest's declared keys on every branch, including empty/zero-area. Guard len(detections) == 0 before any index-0 ([0]) access into metadata arrays. (dynamic_crop's early return emitted {"crops": None} but omitted "predictions" — #2346.)
-
Serialization round-trips the promised representation. serialise_sv_detections/serialise_rle_sv_detections/mask_to_polygon in common/serializers.py are the response-shape contract: masks emit the polygon/RLE the schema promises with int rounding (.astype(float).round().astype(int).tolist(), #1236) and prefer a stored POLYGON_KEY_IN_SV_DETECTIONS over regenerating via mask_to_polygon; keypoints emit class, class_id, confidence, x, y per point. RLE ↔ dense mask abstraction lives in inference_models/models/base/instance_segmentation.py (supported_mask_formats, coco_rle_masks_to_numpy_mask); the enforce_dense_masks_in_inference_models toggle is a manifest bool field on the instance-segmentation v1/v2 blocks (core_steps/models/roboflow/instance_segmentation/{v1,v2}.py), threaded into the request — not an adapter function (#2384, #2260, #2484).
-
Reference-backend parity. ONNX / TRT / TorchScript paths and legacy-inference vs inference_models paths produce the same predictions within numerical tolerance. When one backend's post-processing changes, every sibling changes too — e.g. the keypoint slice offset fix touched yolov8_key_points_detection_onnx.py, _trt.py, _torch_script.py together (#1626). Failure mode: a model "works" but boxes/scores subtly differ per backend.
-
Threshold / activation / index conventions justified against the reference. New default threshold, sigmoid vs raw logits, background/class index offset, or tensor column slice must match the reference implementation and be config-gated if it shifts scores. The keypoint slice is fixed at image_detections[:, 6:] in run_nms_for_key_points_detection (inference_models/models/common/roboflow/post_processing.py) — not 5 + num_classes (#1626). The YOLO-ultralytics mask default mask_binarization_threshold was set to 0.5 via env const INFERENCE_MODELS_YOLO_ULTRALYTICS_DEFAULT_MASK_BINARIZATION_THRESHOLD (#2212, #2217); note align_instance_segmentation_results's own binarization_threshold parameter default stays 0.0. Class remapping / background-index off-by-one bit RF-DETR seg (#2075, #1619, #1920, #1590). Perspective anchor/extension math (#1234, #1287, #1310, #972). Preprocessing must not silently swap BGR/RGB or introduce PIL-vs-CV2 resize drift.
-
Array shape/dtype discipline in sv.Detections. Ragged object-dtype arrays break supervision's indexing/comparison. add_inference_keypoints_to_sv_detections in common/utils.py pads keypoints to fixed-shape numeric arrays (padded_xy/padded_conf/padded_class_id, uniform max length) rather than dtype=object (#2170).
-
supervision bumps are load-bearing. On any version change, verify annotators, mask_to_polygons, keypoint edge maps, and indexing still behave (#2467, #1725, #1424/#1425 pin history).
