Skip to content

docs: convert fenced examples to doctests in draw/utils.py #2424

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
shaoming11 wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft

docs: convert fenced examples to doctests in draw/utils.py #2424

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 67 additions & 83 deletions src/supervision/draw/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,16 @@ def draw_line(
The scene with the line drawn on it

Example:
```python
import numpy as np
from supervision.draw.utils import draw_line
from supervision.draw.color import Color
from supervision.geometry.core import Point

scene = np.zeros((100, 100, 3), dtype=np.uint8)
scene = draw_line(
scene, start=Point(x=10, y=10), end=Point(x=90, y=90), color=Color.RED
)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_line
>>> from supervision.draw.color import Color
>>> from supervision.geometry.core import Point
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> result = draw_line(
... scene, start=Point(x=10, y=10), end=Point(x=90, y=90), color=Color.RED
... )
>>> result.shape
(100, 100, 3)
"""
cv2.line(
scene,
Expand Down Expand Up @@ -71,16 +70,15 @@ def draw_rectangle(
The scene with the rectangle drawn on it

Example:
```python
import numpy as np
from supervision.draw.utils import draw_rectangle
from supervision.draw.color import Color
from supervision.geometry.core import Rect

scene = np.zeros((100, 100, 3), dtype=np.uint8)
rect = Rect(x=10, y=10, width=50, height=30)
scene = draw_rectangle(scene, rect, color=Color.RED)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_rectangle
>>> from supervision.draw.color import Color
>>> from supervision.geometry.core import Rect
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> rect = Rect(x=10, y=10, width=50, height=30)
>>> result = draw_rectangle(scene, rect, color=Color.RED)
>>> result.shape
(100, 100, 3)
"""
cv2.rectangle(
scene,
Expand Down Expand Up @@ -111,16 +109,15 @@ def draw_filled_rectangle(
The scene with the rectangle drawn on it

Example:
```python
import numpy as np
from supervision.draw.utils import draw_filled_rectangle
from supervision.draw.color import Color
from supervision.geometry.core import Rect

scene = np.zeros((100, 100, 3), dtype=np.uint8)
rect = Rect(x=10, y=10, width=50, height=30)
scene = draw_filled_rectangle(scene, rect, color=Color.RED, opacity=0.5)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_filled_rectangle
>>> from supervision.draw.color import Color
>>> from supervision.geometry.core import Rect
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> rect = Rect(x=10, y=10, width=50, height=30)
>>> result = draw_filled_rectangle(scene, rect, color=Color.RED, opacity=0.5)
>>> result.shape
(100, 100, 3)
"""
if opacity == 1:
cv2.rectangle(
Expand Down Expand Up @@ -169,16 +166,15 @@ def draw_rounded_rectangle(
The image with the rounded rectangle drawn on it.

Example:
```python
import numpy as np
from supervision.draw.utils import draw_rounded_rectangle
from supervision.draw.color import Color
from supervision.geometry.core import Rect

scene = np.zeros((200, 300, 3), dtype=np.uint8)
rect = Rect(x=20, y=30, width=120, height=80)
scene = draw_rounded_rectangle(scene, rect, Color.RED, border_radius=0)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_rounded_rectangle
>>> from supervision.draw.color import Color
>>> from supervision.geometry.core import Rect
>>> scene = np.zeros((200, 300, 3), dtype=np.uint8)
>>> rect = Rect(x=20, y=30, width=120, height=80)
>>> result = draw_rounded_rectangle(scene, rect, Color.RED, border_radius=0)
>>> result.shape
(200, 300, 3)
"""
x1, y1, x2, y2 = rect.as_xyxy_int_tuple()
width, height = x2 - x1, y2 - y1
Expand Down Expand Up @@ -244,15 +240,14 @@ def draw_polygon(
The scene with the polygon drawn on it.

Example:
```python
import numpy as np
from supervision.draw.utils import draw_polygon
from supervision.draw.color import Color

scene = np.zeros((100, 100, 3), dtype=np.uint8)
polygon = np.array([[10, 10], [90, 10], [90, 90], [10, 90]])
scene = draw_polygon(scene, polygon, color=Color.RED)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_polygon
>>> from supervision.draw.color import Color
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> polygon = np.array([[10, 10], [90, 10], [90, 90], [10, 90]])
>>> result = draw_polygon(scene, polygon, color=Color.RED)
>>> result.shape
(100, 100, 3)
"""
cv2.polylines(
scene, [polygon], isClosed=True, color=color.as_bgr(), thickness=thickness
Expand All @@ -278,15 +273,14 @@ def draw_filled_polygon(
The scene with the polygon drawn on it.

Example:
```python
import numpy as np
from supervision.draw.utils import draw_filled_polygon
from supervision.draw.color import Color

scene = np.zeros((100, 100, 3), dtype=np.uint8)
polygon = np.array([[10, 10], [90, 10], [90, 90], [10, 90]])
scene = draw_filled_polygon(scene, polygon, color=Color.RED, opacity=0.5)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_filled_polygon
>>> from supervision.draw.color import Color
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> polygon = np.array([[10, 10], [90, 10], [90, 90], [10, 90]])
>>> result = draw_filled_polygon(scene, polygon, color=Color.RED, opacity=0.5)
>>> result.shape
(100, 100, 3)
"""
if opacity == 1:
cv2.fillPoly(scene, [polygon], color=color.as_bgr())
Expand Down Expand Up @@ -334,20 +328,17 @@ def draw_text(
Returns:
The input scene with the text drawn on it.

Examples:
```pycon
Example:
>>> import numpy as np
>>> from supervision.geometry.core import Point
>>> from supervision.draw.utils import draw_text
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> text_anchor = Point(x=50, y=50)
>>> scene = draw_text(
>>> result = draw_text(
... scene=scene, text="Hello, world!", text_anchor=text_anchor
... )
>>> scene.shape
>>> result.shape
(100, 100, 3)

```
"""
text_width, text_height = cv2.getTextSize(
text=text,
Expand Down Expand Up @@ -407,16 +398,15 @@ def draw_image(
ValueError: For invalid opacity or rectangle dimensions.

Example:
```python
import numpy as np
from supervision.draw.utils import draw_image
from supervision.geometry.core import Rect

scene = np.zeros((100, 100, 3), dtype=np.uint8)
image = np.full((40, 40, 3), 255, dtype=np.uint8)
rect = Rect(x=10, y=10, width=40, height=40)
scene = draw_image(scene, image, opacity=0.8, rect=rect)
```
>>> import numpy as np
>>> from supervision.draw.utils import draw_image
>>> from supervision.geometry.core import Rect
>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> image = np.full((40, 40, 3), 255, dtype=np.uint8)
>>> rect = Rect(x=10, y=10, width=40, height=40)
>>> result = draw_image(scene, image, opacity=0.8, rect=rect)
>>> result.shape
(100, 100, 3)
"""

# Validate and load image
Expand Down Expand Up @@ -487,15 +477,12 @@ def calculate_optimal_text_scale(resolution_wh: tuple[int, int]) -> float:
Returns:
Recommended font scale factor.

Examples:
```pycon
Example:
>>> import supervision as sv
>>> sv.calculate_optimal_text_scale((1920, 1080))
1.08
>>> sv.calculate_optimal_text_scale((640, 480))
0.48

```
"""
return min(resolution_wh) * 1e-3

Expand All @@ -512,15 +499,12 @@ def calculate_optimal_line_thickness(resolution_wh: tuple[int, int]) -> int:
Returns:
Recommended line thickness in pixels.

Examples:
```pycon

@Borda Borda Jul 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is how it ends up when you remove it

Image

Example:
>>> import supervision as sv
>>> sv.calculate_optimal_line_thickness((1920, 1080))
4
>>> sv.calculate_optimal_line_thickness((640, 480))
2

```
"""
if min(resolution_wh) < 1080:
return 2
Expand Down
Loading