Merge branch 'develop' into min-ver-settings

.github/workflows/clear-cache.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Clear cache
-        uses: actions/github-script@v6
+        uses: actions/github-script@v7
         with:
           script: |
             console.log("About to clear")

.pre-commit-config.yaml

@@ -11,6 +11,7 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
+        exclude: test/.*\.py
       - id: check-yaml
       - id: check-docstring-first
       - id: check-executables-have-shebangs
@@ -65,12 +66,12 @@ repos:
 
 
   -   repo: https://github.com/psf/black
-      rev: 23.10.1
+      rev: 23.11.0
       hooks:
       -   id: black
 
   -   repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.1.3
+      rev: v0.1.5
       hooks:
       -   id: ruff
           args: [--fix, --exit-non-zero-on-fix]

README.md

@@ -24,10 +24,6 @@
 
 </div>
 
-<a href="https://github.com/roboflow/supervision/issues?q=is%3Aissue+label%3Ahacktoberfest+">
-  <img width="100%" src="https://media.roboflow.com/open-source/supervision/hacktoberfest-banner-3.png">
-</a>
-
 ## 👋 hello
 
 **We write your reusable computer vision tools.** Whether you need to load your dataset from your hard drive, draw detections on an image or video, or count how many detections are in a zone. You can count on us! 🤝

docs/annotators.md

@@ -166,6 +166,27 @@
 
     </div>
 
+=== "Polygon"
+
+    ```python
+    >>> import supervision as sv
+
+    >>> image = ...
+    >>> detections = sv.Detections(...)
+
+    >>> polygon_annotator = sv.PolygonAnnotator()
+    >>> annotated_frame = polygon_annotator.annotate(
+    ...     scene=image.copy(),
+    ...     detections=detections
+    ... )
+    ```
+
+    <div class="result" markdown>
+
+    ![polygon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/polygon-annotator-example-purple.png){ align=center width="800" }
+
+    </div>
+
 === "Label"
 
     ```python
@@ -304,6 +325,10 @@
 
 :::supervision.annotators.core.MaskAnnotator
 
+## PolygonAnnotator
+
+:::supervision.annotators.core.PolygonAnnotator
+
 ## LabelAnnotator
 
 :::supervision.annotators.core.LabelAnnotator

pyproject.toml

@@ -57,7 +57,7 @@ pytest = "^7.2.2"
 wheel = ">=0.40,<0.42"
 notebook = ">=6.5.3,<8.0.0"
 build = ">=0.10,<1.1"
-ruff = ">=0.0.280,<0.1.4"
+ruff = ">=0.0.280,<0.1.6"
 isort = "^5.12.0"
 black = "^23.7.0"
 mypy = "^1.4.1"
@@ -67,7 +67,7 @@ flake8 = { version = "*", python = ">=3.8.1,<3.12.0" }
 
 [tool.poetry.group.docs.dependencies]
 mkdocs-material = "^9.1.4"
-mkdocstrings = {extras = ["python"], version = ">=0.20,<0.24"}
+mkdocstrings = {extras = ["python"], version = ">=0.20,<0.25"}
 
 [tool.flake8]
 exclude = ".venv"
@@ -173,6 +173,7 @@ convention = "google"
 "__init__.py" = ["E402","F401"]
 "supervision/assets/list.py" = ["E501"]
 
+
 [tool.ruff.pylint]
 max-args = 20
 

supervision/__init__.py

@@ -18,6 +18,7 @@
     HeatMapAnnotator,
     LabelAnnotator,
     MaskAnnotator,
+    PolygonAnnotator,
     TraceAnnotator,
 )
 from supervision.annotators.utils import ColorLookup

supervision/annotators/core.py

@@ -7,8 +7,9 @@
 from supervision.annotators.base import BaseAnnotator
 from supervision.annotators.utils import ColorLookup, Trace, resolve_color
 from supervision.detection.core import Detections
-from supervision.detection.utils import clip_boxes
+from supervision.detection.utils import clip_boxes, mask_to_polygons
 from supervision.draw.color import Color, ColorPalette
+from supervision.draw.utils import draw_polygon
 from supervision.geometry.core import Position
 
 
@@ -51,7 +52,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -93,6 +94,10 @@ def annotate(
 class MaskAnnotator(BaseAnnotator):
     """
     A class for drawing masks on an image using provided detections.
+
+    !!! warning
+
+        This annotator utilizes the `sv.Detections.mask`.
     """
 
     def __init__(
@@ -129,7 +134,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -170,6 +175,92 @@ def annotate(
         return scene
 
 
+class PolygonAnnotator(BaseAnnotator):
+    """
+    A class for drawing polygons on an image using provided detections.
+
+    !!! warning
+
+        This annotator utilizes the `sv.Detections.mask`.
+    """
+
+    def __init__(
+        self,
+        color: Union[Color, ColorPalette] = ColorPalette.default(),
+        thickness: int = 2,
+        color_lookup: ColorLookup = ColorLookup.CLASS,
+    ):
+        """
+        Args:
+            color (Union[Color, ColorPalette]): The color or color palette to use for
+                annotating detections.
+            thickness (int): Thickness of the polygon lines.
+            color_lookup (str): Strategy for mapping colors to annotations.
+                Options are `INDEX`, `CLASS`, `TRACE`.
+        """
+        self.color: Union[Color, ColorPalette] = color
+        self.thickness: int = thickness
+        self.color_lookup: ColorLookup = color_lookup
+
+    def annotate(
+        self,
+        scene: np.ndarray,
+        detections: Detections,
+        custom_color_lookup: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """
+        Annotates the given scene with polygons based on the provided detections.
+
+        Args:
+            scene (np.ndarray): The image where polygons will be drawn.
+            detections (Detections): Object detections to annotate.
+            custom_color_lookup (Optional[np.ndarray]): Custom color lookup array.
+                Allows to override the default color mapping strategy.
+
+        Returns:
+            The annotated image.
+
+        Example:
+            ```python
+            >>> import supervision as sv
+
+            >>> image = ...
+            >>> detections = sv.Detections(...)
+
+            >>> polygon_annotator = sv.PolygonAnnotator()
+            >>> annotated_frame = polygon_annotator.annotate(
+            ...     scene=image.copy(),
+            ...     detections=detections
+            ... )
+            ```
+
+        ![polygon-annotator-example](https://media.roboflow.com/
+        supervision-annotator-examples/polygon-annotator-example-purple.png)
+        """
+        if detections.mask is None:
+            return scene
+
+        for detection_idx in range(len(detections)):
+            mask = detections.mask[detection_idx]
+            color = resolve_color(
+                color=self.color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=self.color_lookup
+                if custom_color_lookup is None
+                else custom_color_lookup,
+            )
+            for polygon in mask_to_polygons(mask=mask):
+                scene = draw_polygon(
+                    scene=scene,
+                    polygon=polygon,
+                    color=color,
+                    thickness=self.thickness,
+                )
+
+        return scene
+
+
 class BoxMaskAnnotator(BaseAnnotator):
     """
     A class for drawing box masks on an image using provided detections.
@@ -209,7 +300,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -255,6 +346,10 @@ def annotate(
 class HaloAnnotator(BaseAnnotator):
     """
     A class for drawing Halos on an image using provided detections.
+
+    !!! warning
+
+        This annotator utilizes the `sv.Detections.mask`.
     """
 
     def __init__(
@@ -295,7 +390,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -389,7 +484,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -476,7 +571,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -560,7 +655,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -646,7 +741,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -776,7 +871,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -873,7 +968,7 @@ def annotate(
             detections (Detections): Object detections to annotate.
 
         Returns:
-            np.ndarray: The annotated image.
+            The annotated image.
 
         Example:
             ```python
@@ -911,7 +1006,7 @@ class TraceAnnotator:
 
     !!! warning
 
-        This annotator utilizes the `tracker_id`. Read
+        This annotator utilizes the `sv.Detections.tracker_id`. Read
         [here](https://supervision.roboflow.com/trackers/) to learn how to plug
         tracking into your inference pipeline.
     """
@@ -959,7 +1054,7 @@ def annotate(
                 Allows to override the default color mapping strategy.
 
         Returns:
-            np.ndarray: The image with the trace paths drawn on it.
+            The annotated image.
 
         Example:
             ```python
@@ -1055,7 +1150,7 @@ def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
             detections (Detections): Object detections to annotate.
 
         Returns:
-            np.ndarray: Annotated image.
+            Annotated image.
 
         Example:
             ```python

supervision/dataset/formats/yolo.py

@@ -149,7 +149,7 @@ def load_yolo_annotations(
             annotations[image_path] = Detections.empty()
             continue
 
-        lines = read_txt_file(str(annotation_path))
+        lines = read_txt_file(file_path=annotation_path, skip_empty=True)
         h, w, _ = image.shape
         resolution_wh = (w, h)
 

supervision/utils/file.py

@@ -57,19 +57,24 @@ def list_files_with_extensions(
     return files_with_extensions
 
 
-def read_txt_file(file_path: str) -> List[str]:
+def read_txt_file(file_path: str, skip_empty: bool = False) -> List[str]:
     """
     Read a text file and return a list of strings without newline characters.
+    Optionally skip empty lines.
 
     Args:
         file_path (str): The path to the text file.
+        skip_empty (bool): If True, skip lines that are empty or contain only
+            whitespace. Default is False.
 
     Returns:
         List[str]: A list of strings representing the lines in the text file.
     """
     with open(file_path, "r") as file:
-        lines = file.readlines()
-        lines = [line.rstrip("\n") for line in lines]
+        if skip_empty:
+            lines = [line.rstrip("\n") for line in file if line.strip()]
+        else:
+            lines = [line.rstrip("\n") for line in file]
 
     return lines