Reference for ultralytics/utils/ops.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/ops.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.utils.ops.Profile
Bases: ContextDecorator
YOLOv8 Profile class. Use as a decorator with @Profile() or as a context manager with 'with Profile():'.
Example
Parameters:
Name | Type | Description | Default |
---|---|---|---|
t
|
float
|
Initial time. Defaults to 0.0. |
0.0
|
device
|
device
|
Devices used for model inference. Defaults to None (cpu). |
None
|
Source code in ultralytics/utils/ops.py
__enter__
__exit__
__str__
ultralytics.utils.ops.segment2box
Convert 1 segment label to 1 box label, applying inside-image constraint, i.e. (xy1, xy2, ...) to (xyxy).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
segment
|
Tensor
|
the segment label |
required |
width
|
int
|
the width of the image. Defaults to 640 |
640
|
height
|
int
|
The height of the image. Defaults to 640 |
640
|
Returns:
Type | Description |
---|---|
ndarray
|
the minimum and maximum x and y values of the segment. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.scale_boxes
Rescales bounding boxes (in the format of xyxy by default) from the shape of the image they were originally specified in (img1_shape) to the shape of a different image (img0_shape).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
img1_shape
|
tuple
|
The shape of the image that the bounding boxes are for, in the format of (height, width). |
required |
boxes
|
Tensor
|
the bounding boxes of the objects in the image, in the format of (x1, y1, x2, y2) |
required |
img0_shape
|
tuple
|
the shape of the target image, in the format of (height, width). |
required |
ratio_pad
|
tuple
|
a tuple of (ratio, pad) for scaling the boxes. If not provided, the ratio and pad will be calculated based on the size difference between the two images. |
None
|
padding
|
bool
|
If True, assuming the boxes is based on image augmented by yolo style. If False then do regular rescaling. |
True
|
xywh
|
bool
|
The box format is xywh or not, default=False. |
False
|
Returns:
Name | Type | Description |
---|---|---|
boxes |
Tensor
|
The scaled bounding boxes, in the format of (x1, y1, x2, y2) |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.make_divisible
Returns the nearest number that is divisible by the given divisor.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
int
|
The number to make divisible. |
required |
divisor
|
int | Tensor
|
The divisor. |
required |
Returns:
Type | Description |
---|---|
int
|
The nearest number divisible by the divisor. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.nms_rotated
NMS for oriented bounding boxes using probiou and fast-nms.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
boxes
|
Tensor
|
Rotated bounding boxes, shape (N, 5), format xywhr. |
required |
scores
|
Tensor
|
Confidence scores, shape (N,). |
required |
threshold
|
float
|
IoU threshold. Defaults to 0.45. |
0.45
|
Returns:
Type | Description |
---|---|
Tensor
|
Indices of boxes to keep after NMS. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.non_max_suppression
non_max_suppression(
prediction,
conf_thres=0.25,
iou_thres=0.45,
classes=None,
agnostic=False,
multi_label=False,
labels=(),
max_det=300,
nc=0,
max_time_img=0.05,
max_nms=30000,
max_wh=7680,
in_place=True,
rotated=False,
)
Perform non-maximum suppression (NMS) on a set of boxes, with support for masks and multiple labels per box.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
prediction
|
Tensor
|
A tensor of shape (batch_size, num_classes + 4 + num_masks, num_boxes) containing the predicted boxes, classes, and masks. The tensor should be in the format output by a model, such as YOLO. |
required |
conf_thres
|
float
|
The confidence threshold below which boxes will be filtered out. Valid values are between 0.0 and 1.0. |
0.25
|
iou_thres
|
float
|
The IoU threshold below which boxes will be filtered out during NMS. Valid values are between 0.0 and 1.0. |
0.45
|
classes
|
List[int]
|
A list of class indices to consider. If None, all classes will be considered. |
None
|
agnostic
|
bool
|
If True, the model is agnostic to the number of classes, and all classes will be considered as one. |
False
|
multi_label
|
bool
|
If True, each box may have multiple labels. |
False
|
labels
|
List[List[Union[int, float, Tensor]]]
|
A list of lists, where each inner list contains the apriori labels for a given image. The list should be in the format output by a dataloader, with each label being a tuple of (class_index, x1, y1, x2, y2). |
()
|
max_det
|
int
|
The maximum number of boxes to keep after NMS. |
300
|
nc
|
int
|
The number of classes output by the model. Any indices after this will be considered masks. |
0
|
max_time_img
|
float
|
The maximum time (seconds) for processing one image. |
0.05
|
max_nms
|
int
|
The maximum number of boxes into torchvision.ops.nms(). |
30000
|
max_wh
|
int
|
The maximum box width and height in pixels. |
7680
|
in_place
|
bool
|
If True, the input prediction tensor will be modified in place. |
True
|
rotated
|
bool
|
If Oriented Bounding Boxes (OBB) are being passed for NMS. |
False
|
Returns:
Type | Description |
---|---|
List[Tensor]
|
A list of length batch_size, where each element is a tensor of shape (num_boxes, 6 + num_masks) containing the kept boxes, with columns (x1, y1, x2, y2, confidence, class, mask1, mask2, ...). |
Source code in ultralytics/utils/ops.py
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 224 225 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 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 |
|
ultralytics.utils.ops.clip_boxes
Takes a list of bounding boxes and a shape (height, width) and clips the bounding boxes to the shape.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
boxes
|
Tensor
|
The bounding boxes to clip. |
required |
shape
|
tuple
|
The shape of the image. |
required |
Returns:
Type | Description |
---|---|
Tensor | ndarray
|
The clipped boxes. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.clip_coords
Clip line coordinates to the image boundaries.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
coords
|
Tensor | ndarray
|
A list of line coordinates. |
required |
shape
|
tuple
|
A tuple of integers representing the size of the image in the format (height, width). |
required |
Returns:
Type | Description |
---|---|
Tensor | ndarray
|
Clipped coordinates |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.scale_image
Takes a mask, and resizes it to the original image size.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
masks
|
ndarray
|
Resized and padded masks/images, [h, w, num]/[h, w, 3]. |
required |
im0_shape
|
tuple
|
The original image shape. |
required |
ratio_pad
|
tuple
|
The ratio of the padding to the original image. |
None
|
Returns:
Name | Type | Description |
---|---|---|
masks |
ndarray
|
The masks that are being returned with shape [h, w, num]. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xyxy2xywh
Convert bounding box coordinates from (x1, y1, x2, y2) format to (x, y, width, height) format where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The input bounding box coordinates in (x1, y1, x2, y2) format. |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in (x, y, width, height) format. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xywh2xyxy
Convert bounding box coordinates from (x, y, width, height) format to (x1, y1, x2, y2) format where (x1, y1) is the top-left corner and (x2, y2) is the bottom-right corner. Note: ops per 2 channels faster than per channel.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The input bounding box coordinates in (x, y, width, height) format. |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in (x1, y1, x2, y2) format. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xywhn2xyxy
Convert normalized bounding box coordinates to pixel coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The bounding box coordinates. |
required |
w
|
int
|
Width of the image. Defaults to 640 |
640
|
h
|
int
|
Height of the image. Defaults to 640 |
640
|
padw
|
int
|
Padding width. Defaults to 0 |
0
|
padh
|
int
|
Padding height. Defaults to 0 |
0
|
Returns: y (np.ndarray | torch.Tensor): The coordinates of the bounding box in the format [x1, y1, x2, y2] where x1,y1 is the top-left corner, x2,y2 is the bottom-right corner of the bounding box.
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xyxy2xywhn
Convert bounding box coordinates from (x1, y1, x2, y2) format to (x, y, width, height, normalized) format. x, y, width and height are normalized to image dimensions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The input bounding box coordinates in (x1, y1, x2, y2) format. |
required |
w
|
int
|
The width of the image. Defaults to 640 |
640
|
h
|
int
|
The height of the image. Defaults to 640 |
640
|
clip
|
bool
|
If True, the boxes will be clipped to the image boundaries. Defaults to False |
False
|
eps
|
float
|
The minimum value of the box's width and height. Defaults to 0.0 |
0.0
|
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in (x, y, width, height, normalized) format |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xywh2ltwh
Convert the bounding box format from [x, y, w, h] to [x1, y1, w, h], where x1, y1 are the top-left coordinates.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The input tensor with the bounding box coordinates in the xywh format |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in the xyltwh format |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xyxy2ltwh
Convert nx4 bounding boxes from [x1, y1, x2, y2] to [x1, y1, w, h], where xy1=top-left, xy2=bottom-right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
The input tensor with the bounding boxes coordinates in the xyxy format |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in the xyltwh format. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.ltwh2xywh
Convert nx4 boxes from [x1, y1, w, h] to [x, y, w, h] where xy1=top-left, xy=center.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
Tensor
|
the input tensor |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
The bounding box coordinates in the xywh format. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xyxyxyxy2xywhr
Convert batched Oriented Bounding Boxes (OBB) from [xy1, xy2, xy3, xy4] to [xywh, rotation]. Rotation values are returned in radians from 0 to pi/2.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
Input box corners [xy1, xy2, xy3, xy4] of shape (n, 8). |
required |
Returns:
Type | Description |
---|---|
ndarray | Tensor
|
Converted data in [cx, cy, w, h, rotation] format of shape (n, 5). |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.xywhr2xyxyxyxy
Convert batched Oriented Bounding Boxes (OBB) from [xywh, rotation] to [xy1, xy2, xy3, xy4]. Rotation values should be in radians from 0 to pi/2.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
Boxes in [cx, cy, w, h, rotation] format of shape (n, 5) or (b, n, 5). |
required |
Returns:
Type | Description |
---|---|
ndarray | Tensor
|
Converted corner points of shape (n, 4, 2) or (b, n, 4, 2). |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.ltwh2xyxy
It converts the bounding box from [x1, y1, w, h] to [x1, y1, x2, y2] where xy1=top-left, xy2=bottom-right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
ndarray | Tensor
|
the input image |
required |
Returns:
Name | Type | Description |
---|---|---|
y |
ndarray | Tensor
|
the xyxy coordinates of the bounding boxes. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.segments2boxes
It converts segment labels to box labels, i.e. (cls, xy1, xy2, ...) to (cls, xywh).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
segments
|
list
|
list of segments, each segment is a list of points, each point is a list of x, y coordinates |
required |
Returns:
Type | Description |
---|---|
ndarray
|
the xywh coordinates of the bounding boxes. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.resample_segments
Inputs a list of segments (n,2) and returns a list of segments (n,2) up-sampled to n points each.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
segments
|
list
|
a list of (n,2) arrays, where n is the number of points in the segment. |
required |
n
|
int
|
number of points to resample the segment to. Defaults to 1000 |
1000
|
Returns:
Name | Type | Description |
---|---|---|
segments |
list
|
the resampled segments. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.crop_mask
It takes a mask and a bounding box, and returns a mask that is cropped to the bounding box.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
masks
|
Tensor
|
[n, h, w] tensor of masks |
required |
boxes
|
Tensor
|
[n, 4] tensor of bbox coordinates in relative point form |
required |
Returns:
Type | Description |
---|---|
Tensor
|
The masks are being cropped to the bounding box. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.process_mask
Apply masks to bounding boxes using the output of the mask head.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
protos
|
Tensor
|
A tensor of shape [mask_dim, mask_h, mask_w]. |
required |
masks_in
|
Tensor
|
A tensor of shape [n, mask_dim], where n is the number of masks after NMS. |
required |
bboxes
|
Tensor
|
A tensor of shape [n, 4], where n is the number of masks after NMS. |
required |
shape
|
tuple
|
A tuple of integers representing the size of the input image in the format (h, w). |
required |
upsample
|
bool
|
A flag to indicate whether to upsample the mask to the original image size. Default is False. |
False
|
Returns:
Type | Description |
---|---|
Tensor
|
A binary mask tensor of shape [n, h, w], where n is the number of masks after NMS, and h and w are the height and width of the input image. The mask is applied to the bounding boxes. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.process_mask_native
It takes the output of the mask head, and crops it after upsampling to the bounding boxes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
protos
|
Tensor
|
[mask_dim, mask_h, mask_w] |
required |
masks_in
|
Tensor
|
[n, mask_dim], n is number of masks after nms. |
required |
bboxes
|
Tensor
|
[n, 4], n is number of masks after nms. |
required |
shape
|
tuple
|
The size of the input image (h,w). |
required |
Returns:
Name | Type | Description |
---|---|---|
masks |
Tensor
|
The returned masks with dimensions [h, w, n]. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.scale_masks
Rescale segment masks to shape.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
masks
|
Tensor
|
(N, C, H, W). |
required |
shape
|
tuple
|
Height and width. |
required |
padding
|
bool
|
If True, assuming the boxes is based on image augmented by yolo style. If False then do regular rescaling. |
True
|
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.scale_coords
Rescale segment coordinates (xy) from img1_shape to img0_shape.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
img1_shape
|
tuple
|
The shape of the image that the coords are from. |
required |
coords
|
Tensor
|
the coords to be scaled of shape n,2. |
required |
img0_shape
|
tuple
|
the shape of the image that the segmentation is being applied to. |
required |
ratio_pad
|
tuple
|
the ratio of the image size to the padded image size. |
None
|
normalize
|
bool
|
If True, the coordinates will be normalized to the range [0, 1]. Defaults to False. |
False
|
padding
|
bool
|
If True, assuming the boxes is based on image augmented by yolo style. If False then do regular rescaling. |
True
|
Returns:
Name | Type | Description |
---|---|---|
coords |
Tensor
|
The scaled coordinates. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.regularize_rboxes
Regularize rotated boxes in range [0, pi/2].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
rboxes
|
Tensor
|
Input boxes of shape(N, 5) in xywhr format. |
required |
Returns:
Type | Description |
---|---|
Tensor
|
The regularized boxes. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.masks2segments
It takes a list of masks(n,h,w) and returns a list of segments(n,xy).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
masks
|
Tensor
|
the output of the model, which is a tensor of shape (batch_size, 160, 160) |
required |
strategy
|
str
|
'all' or 'largest'. Defaults to all |
'all'
|
Returns:
Name | Type | Description |
---|---|---|
segments |
List
|
list of segment masks |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.convert_torch2numpy_batch
Convert a batch of FP32 torch tensors (0.0-1.0) to a NumPy uint8 array (0-255), changing from BCHW to BHWC layout.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
batch
|
Tensor
|
Input tensor batch of shape (Batch, Channels, Height, Width) and dtype torch.float32. |
required |
Returns:
Type | Description |
---|---|
ndarray
|
Output NumPy array batch of shape (Batch, Height, Width, Channels) and dtype uint8. |
Source code in ultralytics/utils/ops.py
ultralytics.utils.ops.clean_str
Cleans a string by replacing special characters with '_' character.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
s
|
str
|
a string needing special characters replaced |
required |
Returns:
Type | Description |
---|---|
str
|
a string with special characters replaced by an underscore _ |