fix(dataset): preserve LabelMe instance grouping - #2640

Description

LabelMe export writes each disconnected region of a detection mask as a polygon, but previously left every group_id null. Import also ignored explicit groups, so one instance became multiple detections. This change exports shared IDs for disconnected components and imports shapes with the same (label, group_id) as one detection with a union mask and enclosing box.

Minimal reproduction on develop:

import numpy as np
import supervision as sv
from supervision.dataset.formats.labelme import (
    detections_to_labelme_shapes,
    labelme_shapes_to_detections,
)

mask = np.zeros((1, 48, 64), dtype=bool)
mask[0, 5:15, 5:15] = True
mask[0, 30:40, 30:40] = True
detections = sv.Detections(
    xyxy=np.array([[5, 5, 39, 39]], dtype=np.float32),
    class_id=np.array([0]),
    mask=mask,
)
shapes = detections_to_labelme_shapes(detections, ["dog"])
result = labelme_shapes_to_detections(shapes, {"dog": 0}, (64, 48), True)
len(result)  # Before: 2; after: 1

Motivation and Context

Instance membership must survive LabelMe conversion. LabelMe's own instance-segmentation converter groups by (label, group_id), unions masks, and treats only missing/null group IDs as ungrouped.

#2299 introduced LabelMe support; its multicomponent test checked polygon output without checking preserved instance count. Open #2637 concerns image copying into the source folder and addresses a separate failure.

Changes Made

• Import explicit groups, including group_id=0, using mask unions and enclosing component boxes. Missing/null IDs, different groups, and different labels remain independent.
• Export a shared numeric group ID for each mask with multiple polygon components. Existing single-polygon, rectangle, and empty-mask fallback behavior remains intact.
• Add focused grouping and round-trip regression coverage, update the affected public docstrings, and add an Unreleased changelog entry.

Testing

All commands ran in this branch's own worktree using Python 3.11 and the default NumPy fallback backend:

• Clean develop baseline, uv run pytest -q: 4316 passed, 24 skipped.

• New/updated tests against unmodified production code, uv run pytest tests/dataset/formats/test_labelme.py -q: 15 failed, 44 passed. Failures show explicit groups remaining split, missing export group IDs, and round trips producing two/four detections instead of one/two.

• With the fix, the same focused command: 59 passed.

• uv run pytest --cov=supervision: 4335 passed, 24 skipped, 91% total coverage.

• uv run pytest --doctest-modules src/supervision/dataset/formats/labelme.py src/supervision/dataset/core.py: 3 passed.

• uv run pre-commit run --all-files: all hooks passed, including mypy.

• git diff --check: passed.

• Added/updated tests, and the full suite passes locally

• Updated docs (docstrings / mkdocs entry) for new or changed public API

• Added a changelog entry in docs/changelog.md under Unreleased (skip for lint/type/format-only or pure doc changes)

Additional Notes

The base is 8c7df2388ce46f16139edc498c2bc3874493b4bc. Polygon rasterization fidelity is unchanged; numeric group IDs are regenerated on export because Detections stores instance membership, not LabelMe IDs. The 24 skips also occur on the clean baseline. Native OpenCV was not installed for these runs.