Skip to content

docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py #2425

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 2 commits into
base: develop
Choose a base branch
from
+67 −114
Draft

docs: convert fenced pycon examples to doctests in boxes.py and draw/utils.py #2425

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bb605e5
docs: convert fenced code examples to doctests in draw/utils.py
shaoming11 Jul 12, 2026
6185339
docs: convert fenced pycon examples to doctests in boxes.py
shaoming11 Jul 12, 2026
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
31 changes: 0 additions & 31 deletions src/supervision/detection/utils/boxes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ def clip_boxes(
within the frame resolution.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> xyxy = np.array([
Expand All @@ -43,8 +42,6 @@ def clip_boxes(
array([[ 10, 20, 300, 200],
[ 15, 25, 320, 240],
[ 0, 0, 30, 40]])

```
"""
result: npt.NDArray[np.number] = np.copy(xyxy)
width, height = resolution_wh
Expand Down Expand Up @@ -77,7 +74,6 @@ def pad_boxes(
values.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> xyxy = np.array([
Expand All @@ -87,8 +83,6 @@ def pad_boxes(
>>> sv.pad_boxes(xyxy=xyxy, px=5, py=10)
array([[ 5, 10, 35, 50],
[10, 15, 40, 55]])

```
"""
if py is None:
py = px
Expand Down Expand Up @@ -132,7 +126,6 @@ def denormalize_boxes(
`(x_min, y_min, x_max, y_max)` format.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> xyxy = np.array([
Expand All @@ -144,17 +137,11 @@ def denormalize_boxes(
array([[128., 144., 640., 432.],
[384., 288., 896., 576.],
[256., 72., 768., 360.]])

```

```pycon
>>> xyxy = np.array([
... [256., 128., 768., 640.]
... ])
>>> sv.denormalize_boxes(xyxy, (1280, 720), normalization_factor=1024.0)
array([[320., 90., 960., 450.]])

```
"""
width, height = resolution_wh
result = cast(npt.NDArray[Any], xyxy.copy())
Expand All @@ -179,7 +166,6 @@ def move_boxes(
Repositioned bounding boxes.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> xyxy = np.array([
Expand All @@ -190,8 +176,6 @@ def move_boxes(
>>> sv.move_boxes(xyxy=xyxy, offset=offset)
array([[15, 15, 25, 25],
[35, 35, 45, 45]])

```
"""
return xyxy + np.hstack([offset, offset])

Expand All @@ -211,7 +195,6 @@ def move_oriented_boxes(
Repositioned bounding boxes.

Examples:
```pycon
>>> import numpy as np
>>> from supervision.detection.utils.boxes import move_oriented_boxes
>>> xyxyxyxy = np.array([
Expand Down Expand Up @@ -239,8 +222,6 @@ def move_oriented_boxes(
[25, 45],
[35, 55],
[45, 45]]])

```
"""
return xyxyxyxy + offset

Expand Down Expand Up @@ -290,7 +271,6 @@ def xyxyxyxy_to_xyxy(
ValueError: If `xyxyxyxy` does not have shape `(N, 4, 2)`.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> corners = np.array([
Expand All @@ -300,8 +280,6 @@ def xyxyxyxy_to_xyxy(
>>> sv.xyxyxyxy_to_xyxy(corners)
array([[ 0., 0., 10., 5.],
[ 5., 5., 15., 10.]], dtype=float32)

```
"""
xyxyxyxy = cast(npt.NDArray[np.number], np.asarray(xyxyxyxy))
if xyxyxyxy.ndim != 3 or xyxyxyxy.shape[-2:] != (4, 2):
Expand Down Expand Up @@ -365,7 +343,6 @@ def _oriented_box_anchors(
images but visible on rotating objects in video.

Examples:
```pycon
>>> import numpy as np
>>> from supervision.detection.utils.boxes import _oriented_box_anchors
>>> from supervision.geometry.core import Position
Expand All @@ -374,8 +351,6 @@ def _oriented_box_anchors(
... )
>>> _oriented_box_anchors(corners, Position.BOTTOM_CENTER)
array([[5., 4.]])

```
"""
corners = np.asarray(xyxyxyxy, dtype=np.float64)
if corners.ndim != 3 or corners.shape[-2:] != (4, 2):
Expand Down Expand Up @@ -419,7 +394,6 @@ def scale_boxes(
Scaled bounding boxes.

Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> xyxy = np.array([
Expand All @@ -429,8 +403,6 @@ def scale_boxes(
>>> sv.scale_boxes(xyxy=xyxy, factor=1.5)
array([[ 7.5, 7.5, 22.5, 22.5],
[27.5, 27.5, 42.5, 42.5]])

```
"""
centers = (xyxy[:, :2] + xyxy[:, 2:]) / 2
new_sizes = (xyxy[:, 2:] - xyxy[:, :2]) * factor
Expand All @@ -449,7 +421,6 @@ def spread_out_boxes(
max_iterations: Maximum number of iterations to run the algorithm for.

Example:
```pycon
>>> import numpy as np
>>> from supervision.detection.utils.boxes import spread_out_boxes
>>> xyxy = np.array([
Expand All @@ -462,8 +433,6 @@ def spread_out_boxes(
True
>>> bool(spread_out[1, 0] > 12 and spread_out[1, 1] > 12)
True

```
"""
if len(xyxy) == 0:
return xyxy
Expand Down
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
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