Skip to content

Geometry

get_polygon_center

supervision.geometry.utils.get_polygon_center(polygon: npt.NDArray[np.number]) -> Point

Calculate the center of a polygon. The center is calculated as the center of the solid figure formed by the points of the polygon.

Parameters:

Name Type Description Default

polygon

NDArray[number]

A 2-dimensional numpy ndarray representing the vertices of the polygon.

 required

Returns:

Type Description
Point

The center of the polygon, represented as a Point object with x and y attributes.

Raises:

Type Description
ValueError

If the polygon has no vertices.

Examples:

>>> import numpy as np
>>> import supervision as sv
>>> polygon = np.array([[0, 0], [0, 2], [2, 2], [2, 0]])
>>> center = sv.get_polygon_center(polygon=polygon)
>>> float(center.x)
1.0
>>> float(center.y)
1.0
Source code in src/supervision/geometry/utils.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def get_polygon_center(polygon: npt.NDArray[np.number]) -> Point:
    """Calculate the center of a polygon. The center is calculated as the center of the
    solid figure formed by the points of the polygon.

    Args:
        polygon: A 2-dimensional numpy ndarray representing the vertices of the
            polygon.

    Returns:
        The center of the polygon, represented as a Point object with x and y
            attributes.

    Raises:
        ValueError: If the polygon has no vertices.

    Examples:
        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> polygon = np.array([[0, 0], [0, 2], [2, 2], [2, 0]])
        >>> center = sv.get_polygon_center(polygon=polygon)
        >>> float(center.x)
        1.0
        >>> float(center.y)
        1.0

        ```
    """

    # This is one of the 3 candidate algorithms considered for centroid calculation.
    # For a more detailed discussion, see PR #1084 and commit eb33176

    if len(polygon) == 0:
        raise ValueError("Polygon must have at least one vertex.")

    origin = polygon[0].astype(np.float64, copy=False)
    polygon = polygon.astype(np.float64, copy=False) - origin
    shift_polygon = np.roll(polygon, -1, axis=0)
    signed_areas = (
        polygon[..., 0] * shift_polygon[..., 1]
        - polygon[..., 1] * shift_polygon[..., 0]
    ) / 2
    if signed_areas.sum() == 0:
        center = (np.mean(polygon, axis=0) + origin).round()
        return Point(x=center[0], y=center[1])
    centroids = (polygon + shift_polygon) / 3.0
    center = (np.average(centroids, axis=0, weights=signed_areas) + origin).round()

    return Point(x=center[0], y=center[1])

Position

supervision.geometry.core.Position

Bases: Enum

Enum representing the position of an anchor point.

Source code in src/supervision/geometry/core.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class Position(Enum):
    """Enum representing the position of an anchor point."""

    CENTER = "CENTER"
    CENTER_LEFT = "CENTER_LEFT"
    CENTER_RIGHT = "CENTER_RIGHT"
    TOP_CENTER = "TOP_CENTER"
    TOP_LEFT = "TOP_LEFT"
    TOP_RIGHT = "TOP_RIGHT"
    BOTTOM_LEFT = "BOTTOM_LEFT"
    BOTTOM_CENTER = "BOTTOM_CENTER"
    BOTTOM_RIGHT = "BOTTOM_RIGHT"
    CENTER_OF_MASS = "CENTER_OF_MASS"

    @classmethod
    def list(cls) -> list[str]:
        """Return all position values in their definition order."""
        return [position.value for position in cls]

Methods:

list() -> list[str] classmethod

Return all position values in their definition order.

Source code in src/supervision/geometry/core.py 
27
28
29
30
@classmethod
def list(cls) -> list[str]:
    """Return all position values in their definition order."""
    return [position.value for position in cls]

Point

supervision.geometry.core.Point dataclass

Represents a point in 2D space.

Attributes:

Name Type Description
x float

The x-coordinate of the point.
y float

The y-coordinate of the point.
Example 
>>> from supervision.geometry.core import Point
>>> point = Point(x=10.0, y=20.0)
>>> point.as_xy_int_tuple()
(10, 20)
>>> point.as_xy_float_tuple()
(10.0, 20.0)
Source code in src/supervision/geometry/core.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
@dataclass
class Point:
    """Represents a point in 2D space.

    Attributes:
        x: The x-coordinate of the point.
        y: The y-coordinate of the point.

    Example:
        ```pycon
        >>> from supervision.geometry.core import Point
        >>> point = Point(x=10.0, y=20.0)
        >>> point.as_xy_int_tuple()
        (10, 20)
        >>> point.as_xy_float_tuple()
        (10.0, 20.0)

        ```
    """

    x: float
    y: float

    def as_xy_int_tuple(self) -> tuple[int, int]:
        """Returns the point as a tuple of integers.

        Returns:
            The point as (x, y) integers.
        """
        return int(self.x), int(self.y)

    def as_xy_float_tuple(self) -> tuple[float, float]:
        """Returns the point as a tuple of floats.

        Returns:
            The point as (x, y) floats.
        """
        return self.x, self.y

Methods:

as_xy_float_tuple() -> tuple[float, float]

Returns the point as a tuple of floats.

Returns:

Type Description
tuple[float, float]

The point as (x, y) floats.
Source code in src/supervision/geometry/core.py 
64
65
66
67
68
69
70
def as_xy_float_tuple(self) -> tuple[float, float]:
    """Returns the point as a tuple of floats.

    Returns:
        The point as (x, y) floats.
    """
    return self.x, self.y

as_xy_int_tuple() -> tuple[int, int]

Returns the point as a tuple of integers.

Returns:

Type Description
tuple[int, int]

The point as (x, y) integers.
Source code in src/supervision/geometry/core.py 
56
57
58
59
60
61
62
def as_xy_int_tuple(self) -> tuple[int, int]:
    """Returns the point as a tuple of integers.

    Returns:
        The point as (x, y) integers.
    """
    return int(self.x), int(self.y)

Rect

supervision.geometry.core.Rect dataclass

Represents a rectangle in 2D space.

Attributes:

Name Type Description
x float

The x-coordinate of the top-left corner of the rectangle.
y float

The y-coordinate of the top-left corner of the rectangle.
width float

The width of the rectangle.
height float

The height of the rectangle.
Example 
>>> from supervision.geometry.core import Rect
>>> rect = Rect(x=10.0, y=20.0, width=30.0, height=40.0)
>>> rect.top_left
Point(x=10.0, y=20.0)
>>> rect.bottom_right
Point(x=40.0, y=60.0)
>>> rect.as_xyxy_int_tuple()
(10, 20, 40, 60)
Source code in src/supervision/geometry/core.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
@dataclass
class Rect:
    """Represents a rectangle in 2D space.

    Attributes:
        x: The x-coordinate of the top-left corner of the rectangle.
        y: The y-coordinate of the top-left corner of the rectangle.
        width: The width of the rectangle.
        height: The height of the rectangle.

    Example:
        ```pycon
        >>> from supervision.geometry.core import Rect
        >>> rect = Rect(x=10.0, y=20.0, width=30.0, height=40.0)
        >>> rect.top_left
        Point(x=10.0, y=20.0)
        >>> rect.bottom_right
        Point(x=40.0, y=60.0)
        >>> rect.as_xyxy_int_tuple()
        (10, 20, 40, 60)

        ```
    """

    x: float
    y: float
    width: float
    height: float

    @classmethod
    def from_xyxy(cls, xyxy: tuple[float, float, float, float]) -> Rect:
        """Create a rectangle from `(x_min, y_min, x_max, y_max)` coordinates."""
        x1, y1, x2, y2 = xyxy
        return cls(x=x1, y=y1, width=x2 - x1, height=y2 - y1)

    @property
    def top_left(self) -> Point:
        """Return the top-left corner as a :class:`~supervision.geometry.core.Point`."""
        return Point(x=self.x, y=self.y)

    @property
    def bottom_right(self) -> Point:
        """Return the bottom-right corner as a
        :class:`~supervision.geometry.core.Point`."""
        return Point(x=self.x + self.width, y=self.y + self.height)

    def pad(self, padding: int) -> Rect:
        """Return a rectangle expanded by `padding` pixels on every side."""
        return Rect(
            x=self.x - padding,
            y=self.y - padding,
            width=self.width + 2 * padding,
            height=self.height + 2 * padding,
        )

    def as_xyxy_int_tuple(self) -> tuple[int, int, int, int]:
        """Return `(x_min, y_min, x_max, y_max)` coordinates as integers."""
        return (
            int(self.x),
            int(self.y),
            int(self.x + self.width),
            int(self.y + self.height),
        )

Attributes

bottom_right: Point property

Return the bottom-right corner as a :class:~supervision.geometry.core.Point.

top_left: Point property

Return the top-left corner as a :class:~supervision.geometry.core.Point.

Methods:

as_xyxy_int_tuple() -> tuple[int, int, int, int]

Return (x_min, y_min, x_max, y_max) coordinates as integers.

Source code in src/supervision/geometry/core.py 
216
217
218
219
220
221
222
223
def as_xyxy_int_tuple(self) -> tuple[int, int, int, int]:
    """Return `(x_min, y_min, x_max, y_max)` coordinates as integers."""
    return (
        int(self.x),
        int(self.y),
        int(self.x + self.width),
        int(self.y + self.height),
    )

from_xyxy(xyxy: tuple[float, float, float, float]) -> Rect classmethod

Create a rectangle from (x_min, y_min, x_max, y_max) coordinates.

Source code in src/supervision/geometry/core.py 
190
191
192
193
194
@classmethod
def from_xyxy(cls, xyxy: tuple[float, float, float, float]) -> Rect:
    """Create a rectangle from `(x_min, y_min, x_max, y_max)` coordinates."""
    x1, y1, x2, y2 = xyxy
    return cls(x=x1, y=y1, width=x2 - x1, height=y2 - y1)

pad(padding: int) -> Rect

Return a rectangle expanded by padding pixels on every side.

Source code in src/supervision/geometry/core.py 
207
208
209
210
211
212
213
214
def pad(self, padding: int) -> Rect:
    """Return a rectangle expanded by `padding` pixels on every side."""
    return Rect(
        x=self.x - padding,
        y=self.y - padding,
        width=self.width + 2 * padding,
        height=self.height + 2 * padding,
    )

Vector

supervision.geometry.core.Vector dataclass

Represents a vector in 2D space, defined by a start and an end point.

Attributes:

Name Type Description
start Point

The starting point of the vector.
end Point

The end point of the vector.
Example 
>>> from supervision.geometry.core import Point, Vector
>>> start_point = Point(x=0.0, y=0.0)
>>> end_point = Point(x=3.0, y=4.0)
>>> vector = Vector(start=start_point, end=end_point)
>>> vector.magnitude
5.0
>>> vector.center
Point(x=1.5, y=2.0)
Source code in src/supervision/geometry/core.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@dataclass
class Vector:
    """Represents a vector in 2D space, defined by a start and an end point.

    Attributes:
        start: The starting point of the vector.
        end: The end point of the vector.

    Example:
        ```pycon
        >>> from supervision.geometry.core import Point, Vector
        >>> start_point = Point(x=0.0, y=0.0)
        >>> end_point = Point(x=3.0, y=4.0)
        >>> vector = Vector(start=start_point, end=end_point)
        >>> vector.magnitude
        5.0
        >>> vector.center
        Point(x=1.5, y=2.0)

        ```
    """

    start: Point
    end: Point

    @property
    def magnitude(self) -> float:
        """Calculate the magnitude (length) of the vector.

        Returns:
            The magnitude of the vector.
        """
        dx = self.end.x - self.start.x
        dy = self.end.y - self.start.y
        return sqrt(dx**2 + dy**2)

    @property
    def center(self) -> Point:
        """Calculate the center point of the vector.

        Returns:
            The center point of the vector.
        """
        return Point(
            x=(self.start.x + self.end.x) / 2,
            y=(self.start.y + self.end.y) / 2,
        )

    def cross_product(self, point: Point) -> float:
        """Calculate the 2D cross product (also known as the vector product or outer
        product) of the vector and a point, treated as vectors in 2D space.

        Args:
            point: The point to be evaluated, treated as the endpoint of a
                vector originating from the 'start' of the main vector.

        Returns:
            The scalar value of the cross product. It is positive if 'point'
                lies to the left of the vector (when moving from 'start' to 'end'),
                negative if it lies to the right, and 0 if it is collinear with the
                vector.

        Example:
            For a vector from ``start`` to ``end``, the cross product is positive
            for a point to its left, negative for a point to its right, and zero
            for a point on the same line.

            ```pycon
            >>> from supervision.geometry.core import Point, Vector
            >>> start = Point(x=10.0, y=10.0)
            >>> end = Point(x=12.0, y=10.0)
            >>> vector = Vector(start=start, end=end)
            >>> vector.cross_product(Point(x=11.0, y=11.0))
            2.0
            >>> vector.cross_product(Point(x=11.0, y=9.0))
            -2.0
            >>> vector.cross_product(Point(x=11.0, y=10.0))
            0.0

            ```
        """
        dx_vector = self.end.x - self.start.x
        dy_vector = self.end.y - self.start.y
        dx_point = point.x - self.start.x
        dy_point = point.y - self.start.y
        return (dx_vector * dy_point) - (dy_vector * dx_point)

Attributes

center: Point property

Calculate the center point of the vector.

Returns:

Type Description
Point

The center point of the vector.

magnitude: float property

Calculate the magnitude (length) of the vector.

Returns:

Type Description
float

The magnitude of the vector.

Methods:

cross_product(point: Point) -> float

Calculate the 2D cross product (also known as the vector product or outer product) of the vector and a point, treated as vectors in 2D space.

Parameters:

Name Type Description Default
point
Point

The point to be evaluated, treated as the endpoint of a vector originating from the 'start' of the main vector.

 required

Returns:

Type Description
float

The scalar value of the cross product. It is positive if 'point' lies to the left of the vector (when moving from 'start' to 'end'), negative if it lies to the right, and 0 if it is collinear with the vector.
Example

For a vector from start to end, the cross product is positive for a point to its left, negative for a point to its right, and zero for a point on the same line.

>>> from supervision.geometry.core import Point, Vector
>>> start = Point(x=10.0, y=10.0)
>>> end = Point(x=12.0, y=10.0)
>>> vector = Vector(start=start, end=end)
>>> vector.cross_product(Point(x=11.0, y=11.0))
2.0
>>> vector.cross_product(Point(x=11.0, y=9.0))
-2.0
>>> vector.cross_product(Point(x=11.0, y=10.0))
0.0
Source code in src/supervision/geometry/core.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def cross_product(self, point: Point) -> float:
    """Calculate the 2D cross product (also known as the vector product or outer
    product) of the vector and a point, treated as vectors in 2D space.

    Args:
        point: The point to be evaluated, treated as the endpoint of a
            vector originating from the 'start' of the main vector.

    Returns:
        The scalar value of the cross product. It is positive if 'point'
            lies to the left of the vector (when moving from 'start' to 'end'),
            negative if it lies to the right, and 0 if it is collinear with the
            vector.

    Example:
        For a vector from ``start`` to ``end``, the cross product is positive
        for a point to its left, negative for a point to its right, and zero
        for a point on the same line.

        ```pycon
        >>> from supervision.geometry.core import Point, Vector
        >>> start = Point(x=10.0, y=10.0)
        >>> end = Point(x=12.0, y=10.0)
        >>> vector = Vector(start=start, end=end)
        >>> vector.cross_product(Point(x=11.0, y=11.0))
        2.0
        >>> vector.cross_product(Point(x=11.0, y=9.0))
        -2.0
        >>> vector.cross_product(Point(x=11.0, y=10.0))
        0.0

        ```
    """
    dx_vector = self.end.x - self.start.x
    dy_vector = self.end.y - self.start.y
    dx_point = point.x - self.start.x
    dy_point = point.y - self.start.y
    return (dx_vector * dy_point) - (dy_vector * dx_point)

CoordinatesTransformation

supervision.geometry.core.CoordinatesTransformation

Bases: Protocol

Map points between a reference frame and the current frame.

Zones and lines are defined in the coordinates of a reference frame, the "absolute" frame. :meth:~supervision.geometry.core.CoordinatesTransformation.rel_to_abs maps current-frame points into it, and :meth:~supervision.geometry.core.CoordinatesTransformation.abs_to_rel maps them back. Any object with these two methods satisfies the protocol.

Example 
>>> import numpy as np
>>> class Shift:
...     def abs_to_rel(self, points): return points + [100, 0]
...     def rel_to_abs(self, points): return points - [100, 0]
>>> Shift().rel_to_abs(np.array([[150.0, 50.0]]))
array([[50., 50.]])
Source code in src/supervision/geometry/core.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
class CoordinatesTransformation(Protocol):
    """Map points between a reference frame and the current frame.

    Zones and lines are defined in the coordinates of a reference frame, the
    "absolute" frame.
    :meth:`~supervision.geometry.core.CoordinatesTransformation.rel_to_abs` maps
    current-frame points into it, and
    :meth:`~supervision.geometry.core.CoordinatesTransformation.abs_to_rel` maps
    them back. Any object with these two methods satisfies the protocol.

    Example:
        ```pycon
        >>> import numpy as np
        >>> class Shift:
        ...     def abs_to_rel(self, points): return points + [100, 0]
        ...     def rel_to_abs(self, points): return points - [100, 0]
        >>> Shift().rel_to_abs(np.array([[150.0, 50.0]]))
        array([[50., 50.]])

        ```
    """

    def abs_to_rel(self, points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
        """Map points from reference-frame to current-frame coordinates.

        Args:
            points: Points of shape `(N, 2)` in reference-frame coordinates.

        Returns:
            Points of shape `(N, 2)` in current-frame coordinates.
        """
        ...

    def rel_to_abs(self, points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
        """Map points from current-frame to reference-frame coordinates.

        Args:
            points: Points of shape `(N, 2)` in current-frame coordinates.

        Returns:
            Points of shape `(N, 2)` in reference-frame coordinates.
        """
        ...

Methods:

abs_to_rel(points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]

Map points from reference-frame to current-frame coordinates.

Parameters:

Name Type Description Default
points
NDArray[float64]

Points of shape (N, 2) in reference-frame coordinates.

 required

Returns:

Type Description
NDArray[float64]

Points of shape (N, 2) in current-frame coordinates.
Source code in src/supervision/geometry/core.py 
248
249
250
251
252
253
254
255
256
257
def abs_to_rel(self, points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
    """Map points from reference-frame to current-frame coordinates.

    Args:
        points: Points of shape `(N, 2)` in reference-frame coordinates.

    Returns:
        Points of shape `(N, 2)` in current-frame coordinates.
    """
    ...

rel_to_abs(points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]

Map points from current-frame to reference-frame coordinates.

Parameters:

Name Type Description Default
points
NDArray[float64]

Points of shape (N, 2) in current-frame coordinates.

 required

Returns:

Type Description
NDArray[float64]

Points of shape (N, 2) in reference-frame coordinates.
Source code in src/supervision/geometry/core.py 
259
260
261
262
263
264
265
266
267
268
def rel_to_abs(self, points: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
    """Map points from current-frame to reference-frame coordinates.

    Args:
        points: Points of shape `(N, 2)` in current-frame coordinates.

    Returns:
        Points of shape `(N, 2)` in reference-frame coordinates.
    """
    ...

Comments