[Feature]: Add PolygonZone occupancy calculation

Search before asking

• I have searched the issues and discussions and found no similar feature request.

Feature Description

What:
Add a PolygonZone.get_occupancy(detections) method that returns how much of a polygon zone is covered by detections.

The method would return a value from 0.0 to 1.0, where 0.0 means no detection pixels overlap the zone and 1.0 means the zone is fully occupied.

Why:
PolygonZone.trigger() is useful for checking whether detections are inside a zone, but some workflows need to know how much of the zone is occupied, not just whether objects are present.

This would help with use cases like parking occupancy, shelf-space monitoring, restricted-area coverage, and general zone coverage analysis.

How:
I have already implemented a draft version that:

• Uses segmentation masks when detections include masks.
• Rasterizes bounding boxes when masks are unavailable.
• Counts overlapping detections only once.
• Supports dense masks and CompactMask.
• Adds unit tests, docs, a changelog entry, and an example script.

I am willing to open a PR for review.

Example Usage

No response

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!