feat: add segmentation mask quality utilities

docs/detection/utils/mask_metrics.md

@@ -0,0 +1,59 @@
+---
+comments: true
+status: new
+---
+
+# Mask Metrics
+
+These utilities compare a predicted binary segmentation mask with a target mask.
+They are useful for segmentation model debugging, annotation QA, dataset
+inspection, and contour-sensitive evaluation workflows.
+
+Region-overlap metrics such as Dice and IoU focus on how much foreground area is
+shared. Boundary metrics focus on how well the mask contours align. The
+`tolerance` parameter controls how forgiving boundary matching is in pixel space.
+
+Empty-mask behavior is explicit across all functions:
+
+- both masks empty: `1.0`
+- one mask empty: `0.0`
+
+Current limitations:
+
+- single mask pair only
+- integer pixel tolerance only
+- no ratio-based tolerance
+- no spacing-aware tolerance
+- no visualization or report helpers in this PR
+
+Future work:
+
+- `compare_masks` quality report helper
+- false-positive / false-negative / true-positive mask decomposition
+- boundary error maps
+- visualization helper or `ComparisonAnnotator` integration
+- dataset-level segmentation QA cookbook
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.mask_metrics.mask_iou">mask_iou</a></h2>
+</div>
+
+:::supervision.detection.utils.mask_metrics.mask_iou
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.mask_metrics.dice_coefficient">dice_coefficient</a></h2>
+</div>
+
+:::supervision.detection.utils.mask_metrics.dice_coefficient
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.mask_metrics.boundary_iou">boundary_iou</a></h2>
+</div>
+
+:::supervision.detection.utils.mask_metrics.boundary_iou
+
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.mask_metrics.boundary_f_score">boundary_f_score</a></h2>
+</div>
+
+:::supervision.detection.utils.mask_metrics.boundary_f_score

mkdocs.yml

@@ -49,6 +49,7 @@ nav:
           - Compact Mask: detection/compact_mask.md
           - Converters: detection/utils/converters.md
           - IoU and NMS: detection/utils/iou_and_nms.md
+          - Mask Metrics: detection/utils/mask_metrics.md
           - Boxes: detection/utils/boxes.md
           - Masks: detection/utils/masks.md
           - Polygons: detection/utils/polygons.md

src/supervision/__init__.py

@@ -91,6 +91,12 @@
     mask_non_max_suppression,
     oriented_box_iou_batch,
 )
+from supervision.detection.utils.mask_metrics import (
+    boundary_f_score,
+    boundary_iou,
+    dice_coefficient,
+    mask_iou,
+)
 from supervision.detection.utils.masks import (
     calculate_masks_centroids,
     contains_holes,
@@ -208,6 +214,8 @@
     "VideoInfo",
     "VideoSink",
     "approximate_polygon",
+    "boundary_f_score",
+    "boundary_iou",
     "box_iou",
     "box_iou_batch",
     "box_iou_batch_with_jaccard",
@@ -221,6 +229,7 @@
     "contains_multiple_segments",
     "crop_image",
     "cv2_to_pillow",
+    "dice_coefficient",
     "draw_filled_polygon",
     "draw_filled_rectangle",
     "draw_image",
@@ -242,6 +251,7 @@
     "is_valid_hex",
     "letterbox_image",
     "list_files_with_extensions",
+    "mask_iou",
     "mask_iou_batch",
     "mask_non_max_merge",
     "mask_non_max_suppression",