Skip to content

Bounding Box

BBox

Bases: DataModel

A data model representing a bounding box.

Attributes:

  • title (str) –

    The title or label associated with the bounding box.

  • coords (list[int]) –

    A list of four bounding box coordinates.

The bounding box follows the PASCAL VOC format, where: - (x1, y1) represents the pixel coordinates of the top-left corner. - (x2, y2) represents the pixel coordinates of the bottom-right corner.

from_albumentations staticmethod 

from_albumentations(
    coords: Sequence[float],
    img_size: Sequence[int],
    title: str = "",
) -> BBox

Create a bounding box from Albumentations format.

Albumentations represents bounding boxes as [x_min, y_min, x_max, y_max] with normalized coordinates (values between 0 and 1) relative to the image size.

Parameters:

  • coords (Sequence[float]) –

    The bounding box coordinates in Albumentations format.

  • img_size (Sequence[int]) –

    The reference image size as [width, height].

  • title (str, default: '' ) –

    The title or label of the bounding box. Defaults to an empty string.

Returns:

  • BBox ( BBox ) –

    The bounding box data model.

Source code in datachain/model/bbox.py 
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
@staticmethod
def from_albumentations(
    coords: Sequence[float],
    img_size: Sequence[int],
    title: str = "",
) -> "BBox":
    """
    Create a bounding box from Albumentations format.

    Albumentations represents bounding boxes as `[x_min, y_min, x_max, y_max]`
    with normalized coordinates (values between 0 and 1) relative to the image size.

    Args:
        coords (Sequence[float]): The bounding box coordinates in
            Albumentations format.
        img_size (Sequence[int]): The reference image size as `[width, height]`.
        title (str, optional): The title or label of the bounding box.
            Defaults to an empty string.

    Returns:
        BBox: The bounding box data model.
    """
    validate_bbox(coords, float)
    bbox_coords = convert_bbox(coords, img_size, "albumentations", "voc")
    return BBox(title=title, coords=list(map(round, bbox_coords)))

from_coco staticmethod 

from_coco(coords: Sequence[float], title: str = '') -> BBox

Create a bounding box from COCO format.

COCO format represents bounding boxes as [x_min, y_min, width, height], where: - (x_min, y_min) are the pixel coordinates of the top-left corner. - width and height define the size of the bounding box in pixels.

Parameters:

  • coords (Sequence[float]) –

    The bounding box coordinates in COCO format.

  • title (str, default: '' ) –

    The title of the bounding box.

Returns:

  • BBox ( BBox ) –

    The bounding box data model.

Source code in datachain/model/bbox.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@staticmethod
def from_coco(
    coords: Sequence[float],
    title: str = "",
) -> "BBox":
    """
    Create a bounding box from COCO format.

    COCO format represents bounding boxes as [x_min, y_min, width, height], where:
    - (x_min, y_min) are the pixel coordinates of the top-left corner.
    - width and height define the size of the bounding box in pixels.

    Args:
        coords (Sequence[float]): The bounding box coordinates in COCO format.
        title (str): The title of the bounding box.

    Returns:
        BBox: The bounding box data model.
    """
    validate_bbox(coords, float, int)
    bbox_coords = convert_bbox(coords, [], "coco", "voc")
    return BBox(title=title, coords=list(map(round, bbox_coords)))

from_voc staticmethod 

from_voc(coords: Sequence[float], title: str = '') -> BBox

Create a bounding box from PASCAL VOC format.

PASCAL VOC format represents bounding boxes as [x_min, y_min, x_max, y_max], where: - (x_min, y_min) are the pixel coordinates of the top-left corner. - (x_max, y_max) are the pixel coordinates of the bottom-right corner.

Parameters:

  • coords (Sequence[float]) –

    The bounding box coordinates in VOC format.

  • title (str, default: '' ) –

    The title of the bounding box.

Returns:

  • BBox ( BBox ) –

    The bounding box data model.

Source code in datachain/model/bbox.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@staticmethod
def from_voc(
    coords: Sequence[float],
    title: str = "",
) -> "BBox":
    """
    Create a bounding box from PASCAL VOC format.

    PASCAL VOC format represents bounding boxes as [x_min, y_min, x_max, y_max],
    where:
    - (x_min, y_min) are the pixel coordinates of the top-left corner.
    - (x_max, y_max) are the pixel coordinates of the bottom-right corner.

    Args:
        coords (Sequence[float]): The bounding box coordinates in VOC format.
        title (str): The title of the bounding box.

    Returns:
        BBox: The bounding box data model.
    """
    validate_bbox(coords, float, int)
    return BBox(title=title, coords=list(map(round, coords)))

from_yolo staticmethod 

from_yolo(
    coords: Sequence[float],
    img_size: Sequence[int],
    title: str = "",
) -> BBox

Create a bounding box from YOLO format.

YOLO format represents bounding boxes as [x_center, y_center, width, height], where: - (x_center, y_center) are the normalized coordinates of the box center. - width and height normalized values define the size of the bounding box.

Parameters:

  • coords (Sequence[float]) –

    The bounding box coordinates in YOLO format.

  • img_size (Sequence[int]) –

    The reference image size as [width, height].

  • title (str, default: '' ) –

    The title of the bounding box.

Returns:

  • BBox ( BBox ) –

    The bounding box data model.

Source code in datachain/model/bbox.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
@staticmethod
def from_yolo(
    coords: Sequence[float],
    img_size: Sequence[int],
    title: str = "",
) -> "BBox":
    """
    Create a bounding box from YOLO format.

    YOLO format represents bounding boxes as [x_center, y_center, width, height],
    where:
    - (x_center, y_center) are the normalized coordinates of the box center.
    - width and height normalized values define the size of the bounding box.

    Args:
        coords (Sequence[float]): The bounding box coordinates in YOLO format.
        img_size (Sequence[int]): The reference image size as `[width, height]`.
        title (str): The title of the bounding box.

    Returns:
        BBox: The bounding box data model.
    """
    validate_bbox(coords, float)
    bbox_coords = convert_bbox(coords, img_size, "yolo", "voc")
    return BBox(title=title, coords=list(map(round, bbox_coords)))

point_inside 

point_inside(x: int, y: int) -> bool

Return True if the point is inside the bounding box.

Assumes that if the point is on the edge of the bounding box, it is considered inside.

Source code in datachain/model/bbox.py 
188
189
190
191
192
193
194
195
196
def point_inside(self, x: int, y: int) -> bool:
    """
    Return True if the point is inside the bounding box.

    Assumes that if the point is on the edge of the bounding box,
    it is considered inside.
    """
    x1, y1, x2, y2 = self.coords
    return x1 <= x <= x2 and y1 <= y <= y2

pose_inside 

pose_inside(pose: Union[Pose, Pose3D]) -> bool

Return True if the pose is inside the bounding box.

Source code in datachain/model/bbox.py 
198
199
200
201
202
def pose_inside(self, pose: Union["Pose", "Pose3D"]) -> bool:
    """Return True if the pose is inside the bounding box."""
    return all(
        self.point_inside(x, y) for x, y in zip(pose.x, pose.y) if x > 0 or y > 0
    )

to_albumentations 

to_albumentations(img_size: Sequence[int]) -> list[float]

Convert the bounding box coordinates to Albumentations format.

Albumentations represents bounding boxes as [x_min, y_min, x_max, y_max] with normalized coordinates (values between 0 and 1) relative to the image size.

Parameters:

  • img_size (Sequence[int]) –

    The reference image size as [width, height].

Returns:

  • list[float] –

    list[float]: The bounding box coordinates in Albumentations format.

Source code in datachain/model/bbox.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def to_albumentations(self, img_size: Sequence[int]) -> list[float]:
    """
    Convert the bounding box coordinates to Albumentations format.

    Albumentations represents bounding boxes as `[x_min, y_min, x_max, y_max]`
    with normalized coordinates (values between 0 and 1) relative to the image size.

    Args:
        img_size (Sequence[int]): The reference image size as `[width, height]`.

    Returns:
        list[float]: The bounding box coordinates in Albumentations format.
    """
    return convert_bbox(self.coords, img_size, "voc", "albumentations")

to_coco 

to_coco() -> list[int]

Return the bounding box coordinates in COCO format.

COCO format represents bounding boxes as [x_min, y_min, width, height], where: - (x_min, y_min) are the pixel coordinates of the top-left corner. - width and height define the size of the bounding box in pixels.

Returns:

  • list[int] –

    list[int]: The bounding box coordinates in COCO format.

Source code in datachain/model/bbox.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def to_coco(self) -> list[int]:
    """
    Return the bounding box coordinates in COCO format.

    COCO format represents bounding boxes as [x_min, y_min, width, height], where:
    - (x_min, y_min) are the pixel coordinates of the top-left corner.
    - width and height define the size of the bounding box in pixels.

    Returns:
        list[int]: The bounding box coordinates in COCO format.
    """
    res = convert_bbox(self.coords, [], "voc", "coco")
    return list(map(round, res))

to_voc 

to_voc() -> list[int]

Return the bounding box coordinates in PASCAL VOC format.

PASCAL VOC format represents bounding boxes as [x_min, y_min, x_max, y_max], where: - (x_min, y_min) are the pixel coordinates of the top-left corner. - (x_max, y_max) are the pixel coordinates of the bottom-right corner.

Returns:

  • list[int] –

    list[int]: The bounding box coordinates in VOC format.

Source code in datachain/model/bbox.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
def to_voc(self) -> list[int]:
    """
    Return the bounding box coordinates in PASCAL VOC format.

    PASCAL VOC format represents bounding boxes as [x_min, y_min, x_max, y_max],
    where:
    - (x_min, y_min) are the pixel coordinates of the top-left corner.
    - (x_max, y_max) are the pixel coordinates of the bottom-right corner.

    Returns:
        list[int]: The bounding box coordinates in VOC format.
    """
    return self.coords

to_yolo 

to_yolo(img_size: Sequence[int]) -> list[float]

Return the bounding box coordinates in YOLO format.

YOLO format represents bounding boxes as [x_center, y_center, width, height], where: - (x_center, y_center) are the normalized coordinates of the box center. - width and height normalized values define the size of the bounding box.

Parameters:

  • img_size (Sequence[int]) –

    The reference image size as [width, height].

Returns:

  • list[float] –

    list[float]: The bounding box coordinates in YOLO format.

Source code in datachain/model/bbox.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
def to_yolo(self, img_size: Sequence[int]) -> list[float]:
    """
    Return the bounding box coordinates in YOLO format.

    YOLO format represents bounding boxes as [x_center, y_center, width, height],
    where:
    - (x_center, y_center) are the normalized coordinates of the box center.
    - width and height normalized values define the size of the bounding box.

    Args:
        img_size (Sequence[int]): The reference image size as `[width, height]`.

    Returns:
        list[float]: The bounding box coordinates in YOLO format.
    """
    return convert_bbox(self.coords, img_size, "voc", "yolo")

OBBox

Bases: DataModel

A data model for representing oriented bounding boxes.

Attributes:

  • title (str) –

    The title of the oriented bounding box.

  • coords (list[int]) –

    The coordinates of the oriented bounding box.

The oriented bounding box is defined by four points
  • (x1, y1): The first corner of the box.
  • (x2, y2): The second corner of the box.
  • (x3, y3): The third corner of the box.
  • (x4, y4): The fourth corner of the box.