Reference for ultralytics/utils/instance.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/instance.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.utils.instance.Bboxes
A class for handling bounding boxes.
The class supports various bounding box formats like 'xyxy', 'xywh', and 'ltwh'. Bounding box data should be provided in numpy arrays.
Attributes:
Name | Type | Description |
---|---|---|
bboxes |
ndarray
|
The bounding boxes stored in a 2D numpy array with shape (N, 4). |
format |
str
|
The format of the bounding boxes ('xyxy', 'xywh', or 'ltwh'). |
Note
This class does not handle normalization or denormalization of bounding boxes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
bboxes
|
ndarray
|
Array of bounding boxes with shape (N, 4) or (4,). |
required |
format
|
str
|
Format of the bounding boxes, one of 'xyxy', 'xywh', or 'ltwh'. |
'xyxy'
|
Source code in ultralytics/utils/instance.py
__getitem__
Retrieve a specific bounding box or a set of bounding boxes using indexing.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
index
|
int | slice | ndarray
|
The index, slice, or boolean array to select the desired bounding boxes. |
required |
Returns:
Type | Description |
---|---|
Bboxes
|
A new Bboxes object containing the selected bounding boxes. |
Raises:
Type | Description |
---|---|
AssertionError
|
If the indexed bounding boxes do not form a 2-dimensional matrix. |
Note
When using boolean indexing, make sure to provide a boolean array with the same length as the number of bounding boxes.
Source code in ultralytics/utils/instance.py
__len__
add
Add offset to bounding box coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
offset
|
int | tuple | list
|
Offset(s) for four coordinates. If int, the same offset is applied to all coordinates. |
required |
Source code in ultralytics/utils/instance.py
areas
Return box areas.
Source code in ultralytics/utils/instance.py
concatenate
classmethod
Concatenate a list of Bboxes objects into a single Bboxes object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
boxes_list
|
List[Bboxes]
|
A list of Bboxes objects to concatenate. |
required |
axis
|
int
|
The axis along which to concatenate the bounding boxes. |
0
|
Returns:
Type | Description |
---|---|
Bboxes
|
A new Bboxes object containing the concatenated bounding boxes. |
Note
The input should be a list or tuple of Bboxes objects.
Source code in ultralytics/utils/instance.py
convert
Convert bounding box format from one type to another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
format
|
str
|
Target format for conversion, one of 'xyxy', 'xywh', or 'ltwh'. |
required |
Source code in ultralytics/utils/instance.py
mul
Multiply bounding box coordinates by scale factor(s).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scale
|
int | tuple | list
|
Scale factor(s) for four coordinates. If int, the same scale is applied to all coordinates. |
required |
Source code in ultralytics/utils/instance.py
ultralytics.utils.instance.Instances
Container for bounding boxes, segments, and keypoints of detected objects in an image.
Attributes:
Name | Type | Description |
---|---|---|
_bboxes |
Bboxes
|
Internal object for handling bounding box operations. |
keypoints |
ndarray
|
Keypoints with shape (N, 17, 3) in format (x, y, visible). |
normalized |
bool
|
Flag indicating whether the bounding box coordinates are normalized. |
segments |
ndarray
|
Segments array with shape (N, M, 2) after resampling. |
Methods:
Name | Description |
---|---|
convert_bbox |
Convert bounding box format. |
scale |
Scale coordinates by given factors. |
denormalize |
Convert normalized coordinates to absolute coordinates. |
normalize |
Convert absolute coordinates to normalized coordinates. |
add_padding |
Add padding to coordinates. |
flipud |
Flip coordinates vertically. |
fliplr |
Flip coordinates horizontally. |
clip |
Clip coordinates to stay within image boundaries. |
remove_zero_area_boxes |
Remove boxes with zero area. |
update |
Update instance variables. |
concatenate |
Concatenate multiple Instances objects. |
Examples:
>>> instances = Instances(
... bboxes=np.array([[10, 10, 30, 30], [20, 20, 40, 40]]),
... segments=[np.array([[5, 5], [10, 10]]), np.array([[15, 15], [20, 20]])],
... keypoints=np.array([[[5, 5, 1], [10, 10, 1]], [[15, 15, 1], [20, 20, 1]]]),
... )
Parameters:
Name | Type | Description | Default |
---|---|---|---|
bboxes
|
ndarray
|
Bounding boxes, shape (N, 4). |
required |
segments
|
List | ndarray
|
Segmentation masks. |
None
|
keypoints
|
ndarray
|
Keypoints, shape (N, 17, 3) in format (x, y, visible). |
None
|
bbox_format
|
str
|
Format of bboxes. |
'xywh'
|
normalized
|
bool
|
Whether the coordinates are normalized. |
True
|
Source code in ultralytics/utils/instance.py
__getitem__
Retrieve a specific instance or a set of instances using indexing.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
index
|
int | slice | ndarray
|
The index, slice, or boolean array to select the desired instances. |
required |
Returns:
Type | Description |
---|---|
Instances
|
A new Instances object containing the selected boxes, segments, and keypoints if present. |
Note
When using boolean indexing, make sure to provide a boolean array with the same length as the number of instances.
Source code in ultralytics/utils/instance.py
__len__
add_padding
Add padding to coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
padw
|
int
|
Padding width. |
required |
padh
|
int
|
Padding height. |
required |
Source code in ultralytics/utils/instance.py
clip
Clip coordinates to stay within image boundaries.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
w
|
int
|
Image width. |
required |
h
|
int
|
Image height. |
required |
Source code in ultralytics/utils/instance.py
concatenate
classmethod
Concatenate a list of Instances objects into a single Instances object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
instances_list
|
List[Instances]
|
A list of Instances objects to concatenate. |
required |
axis
|
int
|
The axis along which the arrays will be concatenated. |
0
|
Returns:
Type | Description |
---|---|
Instances
|
A new Instances object containing the concatenated bounding boxes, segments, and keypoints if present. |
Note
The Instances
objects in the list should have the same properties, such as
the format of the bounding boxes, whether keypoints are present, and if the
coordinates are normalized.
Source code in ultralytics/utils/instance.py
convert_bbox
Convert bounding box format.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
format
|
str
|
Target format for conversion, one of 'xyxy', 'xywh', or 'ltwh'. |
required |
denormalize
Convert normalized coordinates to absolute coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
w
|
int
|
Image width. |
required |
h
|
int
|
Image height. |
required |
Source code in ultralytics/utils/instance.py
fliplr
Flip coordinates horizontally.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
w
|
int
|
Image width. |
required |
Source code in ultralytics/utils/instance.py
flipud
Flip coordinates vertically.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
h
|
int
|
Image height. |
required |
Source code in ultralytics/utils/instance.py
normalize
Convert absolute coordinates to normalized coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
w
|
int
|
Image width. |
required |
h
|
int
|
Image height. |
required |
Source code in ultralytics/utils/instance.py
remove_zero_area_boxes
Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height.
Returns:
Type | Description |
---|---|
ndarray
|
Boolean array indicating which boxes were kept. |
Source code in ultralytics/utils/instance.py
scale
Scale coordinates by given factors.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scale_w
|
float
|
Scale factor for width. |
required |
scale_h
|
float
|
Scale factor for height. |
required |
bbox_only
|
bool
|
Whether to scale only bounding boxes. |
False
|
Source code in ultralytics/utils/instance.py
update
Update instance variables.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
bboxes
|
ndarray
|
New bounding boxes. |
required |
segments
|
ndarray
|
New segments. |
None
|
keypoints
|
ndarray
|
New keypoints. |
None
|
Source code in ultralytics/utils/instance.py
ultralytics.utils.instance._ntuple
From PyTorch internals.