[PolygonZone] - drop `frame_resolution_wh` requirement

[SkalskiP]

Description

Currently, the initialization of sv.PolygonZone requires passing frame_resolution_wh in the constructor. Upon further reflection, this seems totally unnecessary.

• Change the self.mask initialization located in the constructor. Instead of basing the shape of the mask on frame_resolution_wh, calculate the x_max and y_max of our polygon and create a mask of a size sufficient for the polygon to fit on it.

  x_max, y_max = np.max(polygon, axis=0)
  self.mask = polygon_to_mask(
      polygon=polygon, resolution_wh=(x_max + 1, y_max + 1)
  )

• Print an appropriate deprecation warning whenever someone sets the value of frame_resolution_wh, notifying that frame_resolution_wh is no longer required and will be dropped in version supervision-0.24.0.

• Drop frame_resolution_wh from docs.

API

Example usage after making the changes.

import numpy as np
import supervision as sv

from ultralytics import YOLO
from supervision.assets import download_assets, VideoAssets

download_assets(VideoAssets.VEHICLES)

polygon = np.array([[1252, 787], [2298, 803], [5039, 2159], [-550, 2159]])
zone = sv.PolygonZone(polygon=polygon)

model = YOLO("yolov8x.pt")

color = sv.Color.ROBOFLOW
color_annotator = sv.ColorAnnotator(color=color)

def callback(scene: np.ndarray, index: int) -> np.ndarray:
    result = model(scene)[0]
    detections = sv.Detections.from_ultralytics(result)
    detections_in_zone = detections[zone.trigger(detections=detections)]

    annotated_frame = scene.copy()
    annotated_frame = sv.draw_polygon(scene, polygon=polygon, color=color)
    annotated_frame = color_annotator.annotate(scene, detections=detections_in_zone)
    return annotated_frame

sv.process_video(
    source_path="vehicles.mp4",
    target_path="vehicles-result.mp4",
    callback=callback
)

Additional

• Note: Please share a Google Colab with minimal code to test the new feature. We know it's additional work, but it will speed up the review process. The reviewer must test each change. Setting up a local environment to do this is time-consuming. Please ensure that Google Colab can be accessed without any issues (make it public). Thank you! 🙏🏻

[jeslinpjames]

Hey, I'd like to take this one.

[onuralpszr]

Hey, I'd like to take this one.

Task is yours, good luck :)

[jeslinpjames]

Hi @onuralpszr,

I have a doubt regarding handling the deprecation warning for frame_resolution_wh. Should I use the deprecated() function like this:

class PolygonZone:
  
    @deprecated("The `frame_resolution_wh` parameter is deprecated and will be removed in supervision-0.24.0. The mask resolution is now calculated automatically based on the polygon coordinates.")
    def __init__(
        self,
        polygon: npt.NDArray[np.int64],
        triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
        frame_resolution_wh: Optional[Tuple[int, int]] = None,
    ):

This will issue warnings whenever frame_resolution_wh is passed or not as a parameter. However, if I have to use the deprecated_parameter() function, it expects new_parameter as a string, so I can't set it to None. Could you advise me on what to do?

[SkalskiP]

Hi @jeslinpjames, I have a simpler idea. Let's just check if frame_resolution_wh is set at the top of the function.

class PolygonZone:
  
    def __init__(
        self,
        polygon: npt.NDArray[np.int64],
        triggering_anchors: Iterable[Position] = (Position.BOTTOM_CENTER,),
        frame_resolution_wh: Optional[Tuple[int, int]] = None,
    ):
        if frame_resolution_wh is not None:
            ...

[SkalskiP]

Feature implemented via #1109