Skip to content

Register now for

# Reference for `ultralytics/engine/results.py`

Note

This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/engine/results.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!

## `` ultralytics.engine.results.BaseTensor

    BaseTensor(data: Tensor | ndarray, orig_shape: tuple[int, int])

Bases: `SimpleClass`

Base tensor class with additional methods for easy manipulation and device handling.

This class provides a foundation for tensor-like objects with device management capabilities, supporting both PyTorch tensors and NumPy arrays. It includes methods for moving data between devices and converting between tensor types.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | Prediction data such as bounding boxes, masks, or keypoints.
`orig_shape` | `tuple[int, int]` | Original shape of the image, typically in the format (height, width).

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the tensor stored in CPU memory.
`numpy` | Return a copy of the tensor as a numpy array.
`cuda` | Move the tensor to GPU memory, returning a new instance if necessary.
`to` | Return a copy of the tensor with the specified device and dtype.

Examples:

    >>> import torch
    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> orig_shape = (720, 1280)
    >>> base_tensor = BaseTensor(data, orig_shape)
    >>> cpu_tensor = base_tensor.cpu()
    >>> numpy_array = base_tensor.numpy()
    >>> gpu_tensor = base_tensor.cuda()

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`data` | `Tensor | ndarray` | Prediction data such as bounding boxes, masks, or keypoints. | required
`orig_shape` | `tuple[int, int]` | Original shape of the image in (height, width) format. | required

Examples:

    >>> import torch
    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> orig_shape = (720, 1280)
    >>> base_tensor = BaseTensor(data, orig_shape)

Source code in `ultralytics/engine/results.py`

    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    def __init__(self, data: torch.Tensor | np.ndarray, orig_shape: tuple[int, int]) -> None:
        """
        Initialize BaseTensor with prediction data and the original shape of the image.

        Args:
            data (torch.Tensor | np.ndarray): Prediction data such as bounding boxes, masks, or keypoints.
            orig_shape (tuple[int, int]): Original shape of the image in (height, width) format.

        Examples:
            >>> import torch
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
            >>> orig_shape = (720, 1280)
            >>> base_tensor = BaseTensor(data, orig_shape)
        """
        assert isinstance(data, (torch.Tensor, np.ndarray)), "data must be torch.Tensor or np.ndarray"
        self.data = data
        self.orig_shape = orig_shape

### `` shape `property`

    shape: tuple[int, ...]

Return the shape of the underlying data tensor.

Returns:

Type | Description
--- | ---
`tuple[int, ...]` | The shape of the data tensor.

Examples:

    >>> data = torch.rand(100, 4)
    >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
    >>> print(base_tensor.shape)
    (100, 4)

### `` __getitem__

    __getitem__(idx)

Return a new BaseTensor instance containing the specified indexed elements of the data tensor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`idx` | `int | list[int] | Tensor` | Index or indices to select from the data tensor. | required

Returns:

Type | Description
--- | ---
`BaseTensor` | A new BaseTensor instance containing the indexed data.

Examples:

    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
    >>> result = base_tensor[0]  # Select the first row
    >>> print(result.data)
    tensor([1, 2, 3])

Source code in `ultralytics/engine/results.py`

    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    def __getitem__(self, idx):
        """
        Return a new BaseTensor instance containing the specified indexed elements of the data tensor.

        Args:
            idx (int | list[int] | torch.Tensor): Index or indices to select from the data tensor.

        Returns:
            (BaseTensor): A new BaseTensor instance containing the indexed data.

        Examples:
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
            >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
            >>> result = base_tensor[0]  # Select the first row
            >>> print(result.data)
            tensor([1, 2, 3])
        """
        return self.__class__(self.data[idx], self.orig_shape)

### `` __len__

    __len__() -> int

Return the length of the underlying data tensor.

Returns:

Type | Description
--- | ---
`int` | The number of elements in the first dimension of the data tensor.

Examples:

    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
    >>> len(base_tensor)
    2

Source code in `ultralytics/engine/results.py`

    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    def __len__(self) -> int:
        """
        Return the length of the underlying data tensor.

        Returns:
            (int): The number of elements in the first dimension of the data tensor.

        Examples:
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
            >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
            >>> len(base_tensor)
            2
        """
        return len(self.data)

### `` cpu

    cpu()

Return a copy of the tensor stored in CPU memory.

Returns:

Type | Description
--- | ---
`BaseTensor` | A new BaseTensor object with the data tensor moved to CPU memory.

Examples:

    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]]).cuda()
    >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
    >>> cpu_tensor = base_tensor.cpu()
    >>> isinstance(cpu_tensor, BaseTensor)
    True
    >>> cpu_tensor.data.device
    device(type='cpu')

Source code in `ultralytics/engine/results.py`

     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    def cpu(self):
        """
        Return a copy of the tensor stored in CPU memory.

        Returns:
            (BaseTensor): A new BaseTensor object with the data tensor moved to CPU memory.

        Examples:
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]]).cuda()
            >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
            >>> cpu_tensor = base_tensor.cpu()
            >>> isinstance(cpu_tensor, BaseTensor)
            True
            >>> cpu_tensor.data.device
            device(type='cpu')
        """
        return self if isinstance(self.data, np.ndarray) else self.__class__(self.data.cpu(), self.orig_shape)

### `` cuda

    cuda()

Move the tensor to GPU memory.

Returns:

Type | Description
--- | ---
`BaseTensor` | A new BaseTensor instance with the data moved to GPU memory if it's not already a numpy array, otherwise returns self.

Examples:

    >>> import torch
    >>> from ultralytics.engine.results import BaseTensor
    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
    >>> gpu_tensor = base_tensor.cuda()
    >>> print(gpu_tensor.data.device)
    cuda:0

Source code in `ultralytics/engine/results.py`

    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    def cuda(self):
        """
        Move the tensor to GPU memory.

        Returns:
            (BaseTensor): A new BaseTensor instance with the data moved to GPU memory if it's not already a
                numpy array, otherwise returns self.

        Examples:
            >>> import torch
            >>> from ultralytics.engine.results import BaseTensor
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
            >>> base_tensor = BaseTensor(data, orig_shape=(720, 1280))
            >>> gpu_tensor = base_tensor.cuda()
            >>> print(gpu_tensor.data.device)
            cuda:0
        """
        return self.__class__(torch.as_tensor(self.data).cuda(), self.orig_shape)

### `` numpy

    numpy()

Return a copy of the tensor as a numpy array.

Returns:

Type | Description
--- | ---
`ndarray` | A numpy array containing the same data as the original tensor.

Examples:

    >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
    >>> orig_shape = (720, 1280)
    >>> base_tensor = BaseTensor(data, orig_shape)
    >>> numpy_array = base_tensor.numpy()
    >>> print(type(numpy_array))
    <class 'numpy.ndarray'>

Source code in `ultralytics/engine/results.py`

    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    def numpy(self):
        """
        Return a copy of the tensor as a numpy array.

        Returns:
            (np.ndarray): A numpy array containing the same data as the original tensor.

        Examples:
            >>> data = torch.tensor([[1, 2, 3], [4, 5, 6]])
            >>> orig_shape = (720, 1280)
            >>> base_tensor = BaseTensor(data, orig_shape)
            >>> numpy_array = base_tensor.numpy()
            >>> print(type(numpy_array))
            <class 'numpy.ndarray'>
        """
        return self if isinstance(self.data, np.ndarray) else self.__class__(self.data.numpy(), self.orig_shape)

### `` to

    to(*args, **kwargs)

Return a copy of the tensor with the specified device and dtype.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*args` | `Any` | Variable length argument list to be passed to torch.Tensor.to(). | `()`
`**kwargs` | `Any` | Arbitrary keyword arguments to be passed to torch.Tensor.to(). | `{}`

Returns:

Type | Description
--- | ---
`BaseTensor` | A new BaseTensor instance with the data moved to the specified device and/or dtype.

Examples:

    >>> base_tensor = BaseTensor(torch.randn(3, 4), orig_shape=(480, 640))
    >>> cuda_tensor = base_tensor.to("cuda")
    >>> float16_tensor = base_tensor.to(dtype=torch.float16)

Source code in `ultralytics/engine/results.py`

    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    def to(self, *args, **kwargs):
        """
        Return a copy of the tensor with the specified device and dtype.

        Args:
            *args (Any): Variable length argument list to be passed to torch.Tensor.to().
            **kwargs (Any): Arbitrary keyword arguments to be passed to torch.Tensor.to().

        Returns:
            (BaseTensor): A new BaseTensor instance with the data moved to the specified device and/or dtype.

        Examples:
            >>> base_tensor = BaseTensor(torch.randn(3, 4), orig_shape=(480, 640))
            >>> cuda_tensor = base_tensor.to("cuda")
            >>> float16_tensor = base_tensor.to(dtype=torch.float16)
        """
        return self.__class__(torch.as_tensor(self.data).to(*args, **kwargs), self.orig_shape)

## `` ultralytics.engine.results.Results

    Results(
        orig_img: ndarray,
        path: str,
        names: dict[int, str],
        boxes: Tensor | None = None,
        masks: Tensor | None = None,
        probs: Tensor | None = None,
        keypoints: Tensor | None = None,
        obb: Tensor | None = None,
        speed: dict[str, float] | None = None,
    )

Bases: `SimpleClass`, `DataExportMixin`

A class for storing and manipulating inference results.

This class provides comprehensive functionality for handling inference results from various Ultralytics models, including detection, segmentation, classification, and pose estimation. It supports visualization, data export, and various coordinate transformations.

Attributes:

Name | Type | Description
--- | --- | ---
`orig_img` | `ndarray` | The original image as a numpy array.
`orig_shape` | `tuple[int, int]` | Original image shape in (height, width) format.
`boxes` | `Boxes | None` | Detected bounding boxes.
`masks` | `Masks | None` | Segmentation masks.
`probs` | `Probs | None` | Classification probabilities.
`keypoints` | `Keypoints | None` | Detected keypoints.
`obb` | `OBB | None` | Oriented bounding boxes.
`speed` | `dict` | Dictionary containing inference speed information.
`names` | `dict` | Dictionary mapping class indices to class names.
`path` | `str` | Path to the input image file.
`save_dir` | `str | None` | Directory to save results.

Methods:

Name | Description
--- | ---
`update` | Update the Results object with new detection data.
`cpu` | Return a copy of the Results object with all tensors moved to CPU memory.
`numpy` | Convert all tensors in the Results object to numpy arrays.
`cuda` | Move all tensors in the Results object to GPU memory.
`to` | Move all tensors to the specified device and dtype.
`new` | Create a new Results object with the same image, path, names, and speed attributes.
`plot` | Plot detection results on an input RGB image.
`show` | Display the image with annotated inference results.
`save` | Save annotated inference results image to file.
`verbose` | Return a log string for each task in the results.
`save_txt` | Save detection results to a text file.
`save_crop` | Save cropped detection images to specified directory.
`summary` | Convert inference results to a summarized dictionary.
`to_df` | Convert detection results to a Polars Dataframe.
`to_json` | Convert detection results to JSON format.
`to_csv` | Convert detection results to a CSV format.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> result = results[0]  # Get the first result
    >>> boxes = result.boxes  # Get the boxes for the first result
    >>> masks = result.masks  # Get the masks for the first result
    >>> for result in results:
    >>>     result.plot()  # Plot detection results

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`orig_img` | `ndarray` | The original image as a numpy array. | required
`path` | `str` | The path to the image file. | required
`names` | `dict` | A dictionary of class names. | required
`boxes` | `Tensor | None` | A 2D tensor of bounding box coordinates for each detection. | `None`
`masks` | `Tensor | None` | A 3D tensor of detection masks, where each mask is a binary image. | `None`
`probs` | `Tensor | None` | A 1D tensor of probabilities of each class for classification task. | `None`
`keypoints` | `Tensor | None` | A 2D tensor of keypoint coordinates for each detection. | `None`
`obb` | `Tensor | None` | A 2D tensor of oriented bounding box coordinates for each detection. | `None`
`speed` | `dict | None` | A dictionary containing preprocess, inference, and postprocess speeds (ms/image). | `None`

Examples:

    >>> results = model("path/to/image.jpg")
    >>> result = results[0]  # Get the first result
    >>> boxes = result.boxes  # Get the boxes for the first result
    >>> masks = result.masks  # Get the masks for the first result

Notes

For the default pose model, keypoint indices for human body pose estimation are: 0: Nose, 1: Left Eye, 2: Right Eye, 3: Left Ear, 4: Right Ear 5: Left Shoulder, 6: Right Shoulder, 7: Left Elbow, 8: Right Elbow 9: Left Wrist, 10: Right Wrist, 11: Left Hip, 12: Right Hip 13: Left Knee, 14: Right Knee, 15: Left Ankle, 16: Right Ankle

Source code in `ultralytics/engine/results.py`

    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
    def __init__(
        self,
        orig_img: np.ndarray,
        path: str,
        names: dict[int, str],
        boxes: torch.Tensor | None = None,
        masks: torch.Tensor | None = None,
        probs: torch.Tensor | None = None,
        keypoints: torch.Tensor | None = None,
        obb: torch.Tensor | None = None,
        speed: dict[str, float] | None = None,
    ) -> None:
        """
        Initialize the Results class for storing and manipulating inference results.

        Args:
            orig_img (np.ndarray): The original image as a numpy array.
            path (str): The path to the image file.
            names (dict): A dictionary of class names.
            boxes (torch.Tensor | None): A 2D tensor of bounding box coordinates for each detection.
            masks (torch.Tensor | None): A 3D tensor of detection masks, where each mask is a binary image.
            probs (torch.Tensor | None): A 1D tensor of probabilities of each class for classification task.
            keypoints (torch.Tensor | None): A 2D tensor of keypoint coordinates for each detection.
            obb (torch.Tensor | None): A 2D tensor of oriented bounding box coordinates for each detection.
            speed (dict | None): A dictionary containing preprocess, inference, and postprocess speeds (ms/image).

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> result = results[0]  # Get the first result
            >>> boxes = result.boxes  # Get the boxes for the first result
            >>> masks = result.masks  # Get the masks for the first result

        Notes:
            For the default pose model, keypoint indices for human body pose estimation are:
            0: Nose, 1: Left Eye, 2: Right Eye, 3: Left Ear, 4: Right Ear
            5: Left Shoulder, 6: Right Shoulder, 7: Left Elbow, 8: Right Elbow
            9: Left Wrist, 10: Right Wrist, 11: Left Hip, 12: Right Hip
            13: Left Knee, 14: Right Knee, 15: Left Ankle, 16: Right Ankle
        """
        self.orig_img = orig_img
        self.orig_shape = orig_img.shape[:2]
        self.boxes = Boxes(boxes, self.orig_shape) if boxes is not None else None  # native size boxes
        self.masks = Masks(masks, self.orig_shape) if masks is not None else None  # native size or imgsz masks
        self.probs = Probs(probs) if probs is not None else None
        self.keypoints = Keypoints(keypoints, self.orig_shape) if keypoints is not None else None
        self.obb = OBB(obb, self.orig_shape) if obb is not None else None
        self.speed = speed if speed is not None else {"preprocess": None, "inference": None, "postprocess": None}
        self.names = names
        self.path = path
        self.save_dir = None
        self._keys = "boxes", "masks", "probs", "keypoints", "obb"

### `` __getitem__

    __getitem__(idx)

Return a Results object for a specific index of inference results.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`idx` | `int | slice` | Index or slice to retrieve from the Results object. | required

Returns:

Type | Description
--- | ---
`Results` | A new Results object containing the specified subset of inference results.

Examples:

    >>> results = model("path/to/image.jpg")  # Perform inference
    >>> single_result = results[0]  # Get the first result
    >>> subset_results = results[1:4]  # Get a slice of results

Source code in `ultralytics/engine/results.py`

    292
    293
    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    def __getitem__(self, idx):
        """
        Return a Results object for a specific index of inference results.

        Args:
            idx (int | slice): Index or slice to retrieve from the Results object.

        Returns:
            (Results): A new Results object containing the specified subset of inference results.

        Examples:
            >>> results = model("path/to/image.jpg")  # Perform inference
            >>> single_result = results[0]  # Get the first result
            >>> subset_results = results[1:4]  # Get a slice of results
        """
        return self._apply("__getitem__", idx)

### `` __len__

    __len__() -> int

Return the number of detections in the Results object.

Returns:

Type | Description
--- | ---
`int` | The number of detections, determined by the length of the first non-empty attribute in (masks, probs, keypoints, or obb).

Examples:

    >>> results = Results(orig_img, path, names, boxes=torch.rand(5, 4))
    >>> len(results)
    5

Source code in `ultralytics/engine/results.py`

    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    def __len__(self) -> int:
        """
        Return the number of detections in the Results object.

        Returns:
            (int): The number of detections, determined by the length of the first non-empty
                attribute in (masks, probs, keypoints, or obb).

        Examples:
            >>> results = Results(orig_img, path, names, boxes=torch.rand(5, 4))
            >>> len(results)
            5
        """
        for k in self._keys:
            v = getattr(self, k)
            if v is not None:
                return len(v)

### `` cpu

    cpu()

Return a copy of the Results object with all its tensors moved to CPU memory.

This method creates a new Results object with all tensor attributes (boxes, masks, probs, keypoints, obb) transferred to CPU memory. It's useful for moving data from GPU to CPU for further processing or saving.

Returns:

Type | Description
--- | ---
`Results` | A new Results object with all tensor attributes on CPU memory.

Examples:

    >>> results = model("path/to/image.jpg")  # Perform inference
    >>> cpu_result = results[0].cpu()  # Move the first result to CPU
    >>> print(cpu_result.boxes.device)  # Output: cpu

Source code in `ultralytics/engine/results.py`

    392
    393
    394
    395
    396
    397
    398
    399
    400
    401
    402
    403
    404
    405
    406
    407
    def cpu(self):
        """
        Return a copy of the Results object with all its tensors moved to CPU memory.

        This method creates a new Results object with all tensor attributes (boxes, masks, probs, keypoints, obb)
        transferred to CPU memory. It's useful for moving data from GPU to CPU for further processing or saving.

        Returns:
            (Results): A new Results object with all tensor attributes on CPU memory.

        Examples:
            >>> results = model("path/to/image.jpg")  # Perform inference
            >>> cpu_result = results[0].cpu()  # Move the first result to CPU
            >>> print(cpu_result.boxes.device)  # Output: cpu
        """
        return self._apply("cpu")

### `` cuda

    cuda()

Move all tensors in the Results object to GPU memory.

Returns:

Type | Description
--- | ---
`Results` | A new Results object with all tensors moved to CUDA device.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> cuda_results = results[0].cuda()  # Move first result to GPU
    >>> for result in results:
    ...     result_cuda = result.cuda()  # Move each result to GPU

Source code in `ultralytics/engine/results.py`

    428
    429
    430
    431
    432
    433
    434
    435
    436
    437
    438
    439
    440
    441
    def cuda(self):
        """
        Move all tensors in the Results object to GPU memory.

        Returns:
            (Results): A new Results object with all tensors moved to CUDA device.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> cuda_results = results[0].cuda()  # Move first result to GPU
            >>> for result in results:
            ...     result_cuda = result.cuda()  # Move each result to GPU
        """
        return self._apply("cuda")

### `` new

    new()

Create a new Results object with the same image, path, names, and speed attributes.

Returns:

Type | Description
--- | ---
`Results` | A new Results object with copied attributes from the original instance.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> new_result = results[0].new()

Source code in `ultralytics/engine/results.py`

    462
    463
    464
    465
    466
    467
    468
    469
    470
    471
    472
    473
    def new(self):
        """
        Create a new Results object with the same image, path, names, and speed attributes.

        Returns:
            (Results): A new Results object with copied attributes from the original instance.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> new_result = results[0].new()
        """
        return Results(orig_img=self.orig_img, path=self.path, names=self.names, speed=self.speed)

### `` numpy

    numpy()

Convert all tensors in the Results object to numpy arrays.

Returns:

Type | Description
--- | ---
`Results` | A new Results object with all tensors converted to numpy arrays.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> numpy_result = results[0].numpy()
    >>> type(numpy_result.boxes.data)
    <class 'numpy.ndarray'>

Notes

This method creates a new Results object, leaving the original unchanged. It's useful for interoperability with numpy-based libraries or when CPU-based operations are required.

Source code in `ultralytics/engine/results.py`

    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419
    420
    421
    422
    423
    424
    425
    426
    def numpy(self):
        """
        Convert all tensors in the Results object to numpy arrays.

        Returns:
            (Results): A new Results object with all tensors converted to numpy arrays.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> numpy_result = results[0].numpy()
            >>> type(numpy_result.boxes.data)
            <class 'numpy.ndarray'>

        Notes:
            This method creates a new Results object, leaving the original unchanged. It's useful for
            interoperability with numpy-based libraries or when CPU-based operations are required.
        """
        return self._apply("numpy")

### `` plot

    plot(
        conf: bool = True,
        line_width: float | None = None,
        font_size: float | None = None,
        font: str = "Arial.ttf",
        pil: bool = False,
        img: ndarray | None = None,
        im_gpu: Tensor | None = None,
        kpt_radius: int = 5,
        kpt_line: bool = True,
        labels: bool = True,
        boxes: bool = True,
        masks: bool = True,
        probs: bool = True,
        show: bool = False,
        save: bool = False,
        filename: str | None = None,
        color_mode: str = "class",
        txt_color: tuple[int, int, int] = (255, 255, 255),
    ) -> np.ndarray

Plot detection results on an input RGB image.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`conf` | `bool` | Whether to plot detection confidence scores. | `True`
`line_width` | `float | None` | Line width of bounding boxes. If None, scaled to image size. | `None`
`font_size` | `float | None` | Font size for text. If None, scaled to image size. | `None`
`font` | `str` | Font to use for text. | `'Arial.ttf'`
`pil` | `bool` | Whether to return the image as a PIL Image. | `False`
`img` | `ndarray | None` | Image to plot on. If None, uses original image. | `None`
`im_gpu` | `Tensor | None` | Normalized image on GPU for faster mask plotting. | `None`
`kpt_radius` | `int` | Radius of drawn keypoints. | `5`
`kpt_line` | `bool` | Whether to draw lines connecting keypoints. | `True`
`labels` | `bool` | Whether to plot labels of bounding boxes. | `True`
`boxes` | `bool` | Whether to plot bounding boxes. | `True`
`masks` | `bool` | Whether to plot masks. | `True`
`probs` | `bool` | Whether to plot classification probabilities. | `True`
`show` | `bool` | Whether to display the annotated image. | `False`
`save` | `bool` | Whether to save the annotated image. | `False`
`filename` | `str | None` | Filename to save image if save is True. | `None`
`color_mode` | `str` | Specify the color mode, e.g., 'instance' or 'class'. | `'class'`
`txt_color` | `tuple[int, int, int]` | Specify the RGB text color for classification task. | `(255, 255, 255)`

Returns:

Type | Description
--- | ---
`ndarray` | Annotated image as a numpy array.

Examples:

    >>> results = model("image.jpg")
    >>> for result in results:
    >>>     im = result.plot()
    >>>     im.show()

Source code in `ultralytics/engine/results.py`

    475
    476
    477
    478
    479
    480
    481
    482
    483
    484
    485
    486
    487
    488
    489
    490
    491
    492
    493
    494
    495
    496
    497
    498
    499
    500
    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    520
    521
    522
    523
    524
    525
    526
    527
    528
    529
    530
    531
    532
    533
    534
    535
    536
    537
    538
    539
    540
    541
    542
    543
    544
    545
    546
    547
    548
    549
    550
    551
    552
    553
    554
    555
    556
    557
    558
    559
    560
    561
    562
    563
    564
    565
    566
    567
    568
    569
    570
    571
    572
    573
    574
    575
    576
    577
    578
    579
    580
    581
    582
    583
    584
    585
    586
    587
    588
    589
    590
    591
    592
    593
    594
    595
    596
    597
    598
    599
    600
    601
    602
    603
    604
    605
    606
    607
    608
    609
    610
    611
    612
    613
    def plot(
        self,
        conf: bool = True,
        line_width: float | None = None,
        font_size: float | None = None,
        font: str = "Arial.ttf",
        pil: bool = False,
        img: np.ndarray | None = None,
        im_gpu: torch.Tensor | None = None,
        kpt_radius: int = 5,
        kpt_line: bool = True,
        labels: bool = True,
        boxes: bool = True,
        masks: bool = True,
        probs: bool = True,
        show: bool = False,
        save: bool = False,
        filename: str | None = None,
        color_mode: str = "class",
        txt_color: tuple[int, int, int] = (255, 255, 255),
    ) -> np.ndarray:
        """
        Plot detection results on an input RGB image.

        Args:
            conf (bool): Whether to plot detection confidence scores.
            line_width (float | None): Line width of bounding boxes. If None, scaled to image size.
            font_size (float | None): Font size for text. If None, scaled to image size.
            font (str): Font to use for text.
            pil (bool): Whether to return the image as a PIL Image.
            img (np.ndarray | None): Image to plot on. If None, uses original image.
            im_gpu (torch.Tensor | None): Normalized image on GPU for faster mask plotting.
            kpt_radius (int): Radius of drawn keypoints.
            kpt_line (bool): Whether to draw lines connecting keypoints.
            labels (bool): Whether to plot labels of bounding boxes.
            boxes (bool): Whether to plot bounding boxes.
            masks (bool): Whether to plot masks.
            probs (bool): Whether to plot classification probabilities.
            show (bool): Whether to display the annotated image.
            save (bool): Whether to save the annotated image.
            filename (str | None): Filename to save image if save is True.
            color_mode (str): Specify the color mode, e.g., 'instance' or 'class'.
            txt_color (tuple[int, int, int]): Specify the RGB text color for classification task.

        Returns:
            (np.ndarray): Annotated image as a numpy array.

        Examples:
            >>> results = model("image.jpg")
            >>> for result in results:
            >>>     im = result.plot()
            >>>     im.show()
        """
        assert color_mode in {"instance", "class"}, f"Expected color_mode='instance' or 'class', not {color_mode}."
        if img is None and isinstance(self.orig_img, torch.Tensor):
            img = (self.orig_img[0].detach().permute(1, 2, 0).contiguous() * 255).to(torch.uint8).cpu().numpy()

        names = self.names
        is_obb = self.obb is not None
        pred_boxes, show_boxes = self.obb if is_obb else self.boxes, boxes
        pred_masks, show_masks = self.masks, masks
        pred_probs, show_probs = self.probs, probs
        annotator = Annotator(
            deepcopy(self.orig_img if img is None else img),
            line_width,
            font_size,
            font,
            pil or (pred_probs is not None and show_probs),  # Classify tasks default to pil=True
            example=names,
        )

        # Plot Segment results
        if pred_masks and show_masks:
            if im_gpu is None:
                img = LetterBox(pred_masks.shape[1:])(image=annotator.result())
                im_gpu = (
                    torch.as_tensor(img, dtype=torch.float16, device=pred_masks.data.device)
                    .permute(2, 0, 1)
                    .flip(0)
                    .contiguous()
                    / 255
                )
            idx = (
                pred_boxes.id
                if pred_boxes.is_track and color_mode == "instance"
                else pred_boxes.cls
                if pred_boxes and color_mode == "class"
                else reversed(range(len(pred_masks)))
            )
            annotator.masks(pred_masks.data, colors=[colors(x, True) for x in idx], im_gpu=im_gpu)

        # Plot Detect results
        if pred_boxes is not None and show_boxes:
            for i, d in enumerate(reversed(pred_boxes)):
                c, d_conf, id = int(d.cls), float(d.conf) if conf else None, int(d.id.item()) if d.is_track else None
                name = ("" if id is None else f"id:{id} ") + names[c]
                label = (f"{name} {d_conf:.2f}" if conf else name) if labels else None
                box = d.xyxyxyxy.squeeze() if is_obb else d.xyxy.squeeze()
                annotator.box_label(
                    box,
                    label,
                    color=colors(
                        c
                        if color_mode == "class"
                        else id
                        if id is not None
                        else i
                        if color_mode == "instance"
                        else None,
                        True,
                    ),
                )

        # Plot Classify results
        if pred_probs is not None and show_probs:
            text = "\n".join(f"{names[j] if names else j} {pred_probs.data[j]:.2f}" for j in pred_probs.top5)
            x = round(self.orig_shape[0] * 0.03)
            annotator.text([x, x], text, txt_color=txt_color, box_color=(64, 64, 64, 128))  # RGBA box

        # Plot Pose results
        if self.keypoints is not None:
            for i, k in enumerate(reversed(self.keypoints.data)):
                annotator.kpts(
                    k,
                    self.orig_shape,
                    radius=kpt_radius,
                    kpt_line=kpt_line,
                    kpt_color=colors(i, True) if color_mode == "instance" else None,
                )

        # Show results
        if show:
            annotator.show(self.path)

        # Save results
        if save:
            annotator.save(filename or f"results_{Path(self.path).name}")

        return annotator.im if pil else annotator.result()

### `` save

    save(filename: str | None = None, *args, **kwargs) -> str

Save annotated inference results image to file.

This method plots the detection results on the original image and saves the annotated image to a file. It utilizes the `plot` method to generate the annotated image and then saves it to the specified filename.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`filename` | `str | Path | None` | The filename to save the annotated image. If None, a default filename is generated based on the original image path. | `None`
`*args` | `Any` | Variable length argument list to be passed to the `plot` method. | `()`
`**kwargs` | `Any` | Arbitrary keyword arguments to be passed to the `plot` method. | `{}`

Returns:

Type | Description
--- | ---
`str` | The filename where the image was saved.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> for result in results:
    >>>     result.save("annotated_image.jpg")
    >>> # Or with custom plot arguments
    >>> for result in results:
    >>>     result.save("annotated_image.jpg", conf=False, line_width=2)

Source code in `ultralytics/engine/results.py`

    634
    635
    636
    637
    638
    639
    640
    641
    642
    643
    644
    645
    646
    647
    648
    649
    650
    651
    652
    653
    654
    655
    656
    657
    658
    659
    660
    661
    def save(self, filename: str | None = None, *args, **kwargs) -> str:
        """
        Save annotated inference results image to file.

        This method plots the detection results on the original image and saves the annotated image to a file. It
        utilizes the `plot` method to generate the annotated image and then saves it to the specified filename.

        Args:
            filename (str | Path | None): The filename to save the annotated image. If None, a default filename
                is generated based on the original image path.
            *args (Any): Variable length argument list to be passed to the `plot` method.
            **kwargs (Any): Arbitrary keyword arguments to be passed to the `plot` method.

        Returns:
            (str): The filename where the image was saved.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> for result in results:
            >>>     result.save("annotated_image.jpg")
            >>> # Or with custom plot arguments
            >>> for result in results:
            >>>     result.save("annotated_image.jpg", conf=False, line_width=2)
        """
        if not filename:
            filename = f"results_{Path(self.path).name}"
        self.plot(save=True, filename=filename, *args, **kwargs)
        return filename

### `` save_crop

    save_crop(save_dir: str | Path, file_name: str | Path = Path('im.jpg'))

Save cropped detection images to specified directory.

This method saves cropped images of detected objects to a specified directory. Each crop is saved in a subdirectory named after the object's class, with the filename based on the input file_name.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`save_dir` | `str | Path` | Directory path where cropped images will be saved. | required
`file_name` | `str | Path` | Base filename for the saved cropped images. | `Path('im.jpg')`

Notes

- This method does not support Classify or Oriented Bounding Box (OBB) tasks.
- Crops are saved as 'save_dir/class_name/file_name.jpg'.
- The method will create necessary subdirectories if they don't exist.
- Original image is copied before cropping to avoid modifying the original.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> for result in results:
    >>>     result.save_crop(save_dir="path/to/crops", file_name="detection")

Source code in `ultralytics/engine/results.py`

    752
    753
    754
    755
    756
    757
    758
    759
    760
    761
    762
    763
    764
    765
    766
    767
    768
    769
    770
    771
    772
    773
    774
    775
    776
    777
    778
    779
    780
    781
    782
    783
    784
    785
    786
    def save_crop(self, save_dir: str | Path, file_name: str | Path = Path("im.jpg")):
        """
        Save cropped detection images to specified directory.

        This method saves cropped images of detected objects to a specified directory. Each crop is saved in a
        subdirectory named after the object's class, with the filename based on the input file_name.

        Args:
            save_dir (str | Path): Directory path where cropped images will be saved.
            file_name (str | Path): Base filename for the saved cropped images.

        Notes:
            - This method does not support Classify or Oriented Bounding Box (OBB) tasks.
            - Crops are saved as 'save_dir/class_name/file_name.jpg'.
            - The method will create necessary subdirectories if they don't exist.
            - Original image is copied before cropping to avoid modifying the original.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> for result in results:
            >>>     result.save_crop(save_dir="path/to/crops", file_name="detection")
        """
        if self.probs is not None:
            LOGGER.warning("Classify task do not support `save_crop`.")
            return
        if self.obb is not None:
            LOGGER.warning("OBB task do not support `save_crop`.")
            return
        for d in self.boxes:
            save_one_box(
                d.xyxy,
                self.orig_img.copy(),
                file=Path(save_dir) / self.names[int(d.cls)] / Path(file_name).with_suffix(".jpg"),
                BGR=True,
            )

### `` save_txt

    save_txt(txt_file: str | Path, save_conf: bool = False) -> str

Save detection results to a text file.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`txt_file` | `str | Path` | Path to the output text file. | required
`save_conf` | `bool` | Whether to include confidence scores in the output. | `False`

Returns:

Type | Description
--- | ---
`str` | Path to the saved text file.

Examples:

    >>> from ultralytics import YOLO
    >>> model = YOLO("yolo11n.pt")
    >>> results = model("path/to/image.jpg")
    >>> for result in results:
    >>>     result.save_txt("output.txt")

Notes

- The file will contain one line per detection or classification with the following structure:
- For detections: `class confidence x_center y_center width height`
- For classifications: `confidence class_name`
- For masks and keypoints, the specific formats will vary accordingly.
- The function will create the output directory if it does not exist.
- If save_conf is False, the confidence scores will be excluded from the output.
- Existing contents of the file will not be overwritten; new results will be appended.

Source code in `ultralytics/engine/results.py`

    695
    696
    697
    698
    699
    700
    701
    702
    703
    704
    705
    706
    707
    708
    709
    710
    711
    712
    713
    714
    715
    716
    717
    718
    719
    720
    721
    722
    723
    724
    725
    726
    727
    728
    729
    730
    731
    732
    733
    734
    735
    736
    737
    738
    739
    740
    741
    742
    743
    744
    745
    746
    747
    748
    749
    750
    def save_txt(self, txt_file: str | Path, save_conf: bool = False) -> str:
        """
        Save detection results to a text file.

        Args:
            txt_file (str | Path): Path to the output text file.
            save_conf (bool): Whether to include confidence scores in the output.

        Returns:
            (str): Path to the saved text file.

        Examples:
            >>> from ultralytics import YOLO
            >>> model = YOLO("yolo11n.pt")
            >>> results = model("path/to/image.jpg")
            >>> for result in results:
            >>>     result.save_txt("output.txt")

        Notes:
            - The file will contain one line per detection or classification with the following structure:
              - For detections: `class confidence x_center y_center width height`
              - For classifications: `confidence class_name`
              - For masks and keypoints, the specific formats will vary accordingly.
            - The function will create the output directory if it does not exist.
            - If save_conf is False, the confidence scores will be excluded from the output.
            - Existing contents of the file will not be overwritten; new results will be appended.
        """
        is_obb = self.obb is not None
        boxes = self.obb if is_obb else self.boxes
        masks = self.masks
        probs = self.probs
        kpts = self.keypoints
        texts = []
        if probs is not None:
            # Classify
            [texts.append(f"{probs.data[j]:.2f} {self.names[j]}") for j in probs.top5]
        elif boxes:
            # Detect/segment/pose
            for j, d in enumerate(boxes):
                c, conf, id = int(d.cls), float(d.conf), int(d.id.item()) if d.is_track else None
                line = (c, *(d.xyxyxyxyn.view(-1) if is_obb else d.xywhn.view(-1)))
                if masks:
                    seg = masks[j].xyn[0].copy().reshape(-1)  # reversed mask.xyn, (n,2) to (n*2)
                    line = (c, *seg)
                if kpts is not None:
                    kpt = torch.cat((kpts[j].xyn, kpts[j].conf[..., None]), 2) if kpts[j].has_visible else kpts[j].xyn
                    line += (*kpt.reshape(-1).tolist(),)
                line += (conf,) * save_conf + (() if id is None else (id,))
                texts.append(("%g " * len(line)).rstrip() % line)

        if texts:
            Path(txt_file).parent.mkdir(parents=True, exist_ok=True)  # make directory
            with open(txt_file, "a", encoding="utf-8") as f:
                f.writelines(text + "\n" for text in texts)

        return str(txt_file)

### `` show

    show(*args, **kwargs)

Display the image with annotated inference results.

This method plots the detection results on the original image and displays it. It's a convenient way to visualize the model's predictions directly.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*args` | `Any` | Variable length argument list to be passed to the `plot()` method. | `()`
`**kwargs` | `Any` | Arbitrary keyword arguments to be passed to the `plot()` method. | `{}`

Examples:

    >>> results = model("path/to/image.jpg")
    >>> results[0].show()  # Display the first result
    >>> for result in results:
    >>>     result.show()  # Display all results

Source code in `ultralytics/engine/results.py`

    615
    616
    617
    618
    619
    620
    621
    622
    623
    624
    625
    626
    627
    628
    629
    630
    631
    632
    def show(self, *args, **kwargs):
        """
        Display the image with annotated inference results.

        This method plots the detection results on the original image and displays it. It's a convenient way to
        visualize the model's predictions directly.

        Args:
            *args (Any): Variable length argument list to be passed to the `plot()` method.
            **kwargs (Any): Arbitrary keyword arguments to be passed to the `plot()` method.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> results[0].show()  # Display the first result
            >>> for result in results:
            >>>     result.show()  # Display all results
        """
        self.plot(show=True, *args, **kwargs)

### `` summary

    summary(normalize: bool = False, decimals: int = 5) -> list[dict[str, Any]]

Convert inference results to a summarized dictionary with optional normalization for box coordinates.

This method creates a list of detection dictionaries, each containing information about a single detection or classification result. For classification tasks, it returns the top class and its confidence. For detection tasks, it includes class information, bounding box coordinates, and optionally mask segments and keypoints.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`normalize` | `bool` | Whether to normalize bounding box coordinates by image dimensions. | `False`
`decimals` | `int` | Number of decimal places to round the output values to. | `5`

Returns:

Type | Description
--- | ---
`list[dict[str, Any]]` | A list of dictionaries, each containing summarized information for a single detection or classification result. The structure of each dictionary varies based on the task type (classification or detection) and available information (boxes, masks, keypoints).

Examples:

    >>> results = model("image.jpg")
    >>> for result in results:
    >>>     summary = result.summary()
    >>>     print(summary)

Source code in `ultralytics/engine/results.py`

    788
    789
    790
    791
    792
    793
    794
    795
    796
    797
    798
    799
    800
    801
    802
    803
    804
    805
    806
    807
    808
    809
    810
    811
    812
    813
    814
    815
    816
    817
    818
    819
    820
    821
    822
    823
    824
    825
    826
    827
    828
    829
    830
    831
    832
    833
    834
    835
    836
    837
    838
    839
    840
    841
    842
    843
    844
    845
    846
    847
    848
    849
    850
    851
    852
    def summary(self, normalize: bool = False, decimals: int = 5) -> list[dict[str, Any]]:
        """
        Convert inference results to a summarized dictionary with optional normalization for box coordinates.

        This method creates a list of detection dictionaries, each containing information about a single
        detection or classification result. For classification tasks, it returns the top class and its
        confidence. For detection tasks, it includes class information, bounding box coordinates, and
        optionally mask segments and keypoints.

        Args:
            normalize (bool): Whether to normalize bounding box coordinates by image dimensions.
            decimals (int): Number of decimal places to round the output values to.

        Returns:
            (list[dict[str, Any]]): A list of dictionaries, each containing summarized information for a single detection
                or classification result. The structure of each dictionary varies based on the task type
                (classification or detection) and available information (boxes, masks, keypoints).

        Examples:
            >>> results = model("image.jpg")
            >>> for result in results:
            >>>     summary = result.summary()
            >>>     print(summary)
        """
        # Create list of detection dictionaries
        results = []
        if self.probs is not None:
            class_id = self.probs.top1
            results.append(
                {
                    "name": self.names[class_id],
                    "class": class_id,
                    "confidence": round(self.probs.top1conf.item(), decimals),
                }
            )
            return results

        is_obb = self.obb is not None
        data = self.obb if is_obb else self.boxes
        h, w = self.orig_shape if normalize else (1, 1)
        for i, row in enumerate(data):  # xyxy, track_id if tracking, conf, class_id
            class_id, conf = int(row.cls), round(row.conf.item(), decimals)
            box = (row.xyxyxyxy if is_obb else row.xyxy).squeeze().reshape(-1, 2).tolist()
            xy = {}
            for j, b in enumerate(box):
                xy[f"x{j + 1}"] = round(b[0] / w, decimals)
                xy[f"y{j + 1}"] = round(b[1] / h, decimals)
            result = {"name": self.names[class_id], "class": class_id, "confidence": conf, "box": xy}
            if data.is_track:
                result["track_id"] = int(row.id.item())  # track ID
            if self.masks:
                result["segments"] = {
                    "x": (self.masks.xy[i][:, 0] / w).round(decimals).tolist(),
                    "y": (self.masks.xy[i][:, 1] / h).round(decimals).tolist(),
                }
            if self.keypoints is not None:
                x, y, visible = self.keypoints[i].data[0].cpu().unbind(dim=1)  # torch Tensor
                result["keypoints"] = {
                    "x": (x / w).numpy().round(decimals).tolist(),  # decimals named argument required
                    "y": (y / h).numpy().round(decimals).tolist(),
                    "visible": visible.numpy().round(decimals).tolist(),
                }
            results.append(result)

        return results

### `` to

    to(*args, **kwargs)

Move all tensors in the Results object to the specified device and dtype.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*args` | `Any` | Variable length argument list to be passed to torch.Tensor.to(). | `()`
`**kwargs` | `Any` | Arbitrary keyword arguments to be passed to torch.Tensor.to(). | `{}`

Returns:

Type | Description
--- | ---
`Results` | A new Results object with all tensors moved to the specified device and dtype.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> result_cuda = results[0].to("cuda")  # Move first result to GPU
    >>> result_cpu = results[0].to("cpu")  # Move first result to CPU
    >>> result_half = results[0].to(dtype=torch.float16)  # Convert first result to half precision

Source code in `ultralytics/engine/results.py`

    443
    444
    445
    446
    447
    448
    449
    450
    451
    452
    453
    454
    455
    456
    457
    458
    459
    460
    def to(self, *args, **kwargs):
        """
        Move all tensors in the Results object to the specified device and dtype.

        Args:
            *args (Any): Variable length argument list to be passed to torch.Tensor.to().
            **kwargs (Any): Arbitrary keyword arguments to be passed to torch.Tensor.to().

        Returns:
            (Results): A new Results object with all tensors moved to the specified device and dtype.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> result_cuda = results[0].to("cuda")  # Move first result to GPU
            >>> result_cpu = results[0].to("cpu")  # Move first result to CPU
            >>> result_half = results[0].to(dtype=torch.float16)  # Convert first result to half precision
        """
        return self._apply("to", *args, **kwargs)

### `` update

    update(
        boxes: Tensor | None = None,
        masks: Tensor | None = None,
        probs: Tensor | None = None,
        obb: Tensor | None = None,
        keypoints: Tensor | None = None,
    )

Update the Results object with new detection data.

This method allows updating the boxes, masks, probabilities, and oriented bounding boxes (OBB) of the Results object. It ensures that boxes are clipped to the original image shape.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`boxes` | `Tensor | None` | A tensor of shape (N, 6) containing bounding box coordinates and confidence scores. The format is (x1, y1, x2, y2, conf, class). | `None`
`masks` | `Tensor | None` | A tensor of shape (N, H, W) containing segmentation masks. | `None`
`probs` | `Tensor | None` | A tensor of shape (num_classes,) containing class probabilities. | `None`
`obb` | `Tensor | None` | A tensor of shape (N, 5) containing oriented bounding box coordinates. | `None`
`keypoints` | `Tensor | None` | A tensor of shape (N, 17, 3) containing keypoints. | `None`

Examples:

    >>> results = model("image.jpg")
    >>> new_boxes = torch.tensor([[100, 100, 200, 200, 0.9, 0]])
    >>> results[0].update(boxes=new_boxes)

Source code in `ultralytics/engine/results.py`

    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339
    340
    341
    342
    343
    344
    345
    346
    347
    348
    349
    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    def update(
        self,
        boxes: torch.Tensor | None = None,
        masks: torch.Tensor | None = None,
        probs: torch.Tensor | None = None,
        obb: torch.Tensor | None = None,
        keypoints: torch.Tensor | None = None,
    ):
        """
        Update the Results object with new detection data.

        This method allows updating the boxes, masks, probabilities, and oriented bounding boxes (OBB) of the
        Results object. It ensures that boxes are clipped to the original image shape.

        Args:
            boxes (torch.Tensor | None): A tensor of shape (N, 6) containing bounding box coordinates and
                confidence scores. The format is (x1, y1, x2, y2, conf, class).
            masks (torch.Tensor | None): A tensor of shape (N, H, W) containing segmentation masks.
            probs (torch.Tensor | None): A tensor of shape (num_classes,) containing class probabilities.
            obb (torch.Tensor | None): A tensor of shape (N, 5) containing oriented bounding box coordinates.
            keypoints (torch.Tensor | None): A tensor of shape (N, 17, 3) containing keypoints.

        Examples:
            >>> results = model("image.jpg")
            >>> new_boxes = torch.tensor([[100, 100, 200, 200, 0.9, 0]])
            >>> results[0].update(boxes=new_boxes)
        """
        if boxes is not None:
            self.boxes = Boxes(ops.clip_boxes(boxes, self.orig_shape), self.orig_shape)
        if masks is not None:
            self.masks = Masks(masks, self.orig_shape)
        if probs is not None:
            self.probs = probs
        if obb is not None:
            self.obb = OBB(obb, self.orig_shape)
        if keypoints is not None:
            self.keypoints = Keypoints(keypoints, self.orig_shape)

### `` verbose

    verbose() -> str

Return a log string for each task in the results, detailing detection and classification outcomes.

This method generates a human-readable string summarizing the detection and classification results. It includes the number of detections for each class and the top probabilities for classification tasks.

Returns:

Type | Description
--- | ---
`str` | A formatted string containing a summary of the results. For detection tasks, it includes the number of detections per class. For classification tasks, it includes the top 5 class probabilities.

Examples:

    >>> results = model("path/to/image.jpg")
    >>> for result in results:
    >>>     print(result.verbose())
    2 persons, 1 car, 3 traffic lights,
    dog 0.92, cat 0.78, horse 0.64,

Notes

- If there are no detections, the method returns "(no detections), " for detection tasks.
- For classification tasks, it returns the top 5 class probabilities and their corresponding class names.
- The returned string is comma-separated and ends with a comma and a space.

Source code in `ultralytics/engine/results.py`

    663
    664
    665
    666
    667
    668
    669
    670
    671
    672
    673
    674
    675
    676
    677
    678
    679
    680
    681
    682
    683
    684
    685
    686
    687
    688
    689
    690
    691
    692
    693
    def verbose(self) -> str:
        """
        Return a log string for each task in the results, detailing detection and classification outcomes.

        This method generates a human-readable string summarizing the detection and classification results. It includes
        the number of detections for each class and the top probabilities for classification tasks.

        Returns:
            (str): A formatted string containing a summary of the results. For detection tasks, it includes the
                number of detections per class. For classification tasks, it includes the top 5 class probabilities.

        Examples:
            >>> results = model("path/to/image.jpg")
            >>> for result in results:
            >>>     print(result.verbose())
            2 persons, 1 car, 3 traffic lights,
            dog 0.92, cat 0.78, horse 0.64,

        Notes:
            - If there are no detections, the method returns "(no detections), " for detection tasks.
            - For classification tasks, it returns the top 5 class probabilities and their corresponding class names.
            - The returned string is comma-separated and ends with a comma and a space.
        """
        boxes = self.obb if self.obb is not None else self.boxes
        if len(self) == 0:
            return "" if self.probs is not None else "(no detections), "
        if self.probs is not None:
            return f"{', '.join(f'{self.names[j]} {self.probs.data[j]:.2f}' for j in self.probs.top5)}, "
        if boxes:
            counts = boxes.cls.int().bincount()
            return "".join(f"{n} {self.names[i]}{'s' * (n > 1)}, " for i, n in enumerate(counts) if n > 0)

## `` ultralytics.engine.results.Boxes

    Boxes(boxes: Tensor | ndarray, orig_shape: tuple[int, int])

Bases: `BaseTensor`

A class for managing and manipulating detection boxes.

This class provides comprehensive functionality for handling detection boxes, including their coordinates, confidence scores, class labels, and optional tracking IDs. It supports various box formats and offers methods for easy manipulation and conversion between different coordinate systems.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | The raw tensor containing detection boxes and associated data.
`orig_shape` | `tuple[int, int]` | The original image dimensions (height, width).
`is_track` | `bool` | Indicates whether tracking IDs are included in the box data.
`xyxy` | `Tensor | ndarray` | Boxes in [x1, y1, x2, y2] format.
`conf` | `Tensor | ndarray` | Confidence scores for each box.
`cls` | `Tensor | ndarray` | Class labels for each box.
`id` | `Tensor | None` | Tracking IDs for each box (if available).
`xywh` | `Tensor | ndarray` | Boxes in [x, y, width, height] format.
`xyxyn` | `Tensor | ndarray` | Normalized [x1, y1, x2, y2] boxes relative to orig_shape.
`xywhn` | `Tensor | ndarray` | Normalized [x, y, width, height] boxes relative to orig_shape.

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the object with all tensors on CPU memory.
`numpy` | Return a copy of the object with all tensors as numpy arrays.
`cuda` | Return a copy of the object with all tensors on GPU memory.
`to` | Return a copy of the object with tensors on specified device and dtype.

Examples:

    >>> import torch
    >>> boxes_data = torch.tensor([[100, 50, 150, 100, 0.9, 0], [200, 150, 300, 250, 0.8, 1]])
    >>> orig_shape = (480, 640)  # height, width
    >>> boxes = Boxes(boxes_data, orig_shape)
    >>> print(boxes.xyxy)
    >>> print(boxes.conf)
    >>> print(boxes.cls)
    >>> print(boxes.xywhn)

This class manages detection boxes, providing easy access and manipulation of box coordinates, confidence scores, class identifiers, and optional tracking IDs. It supports multiple formats for box coordinates, including both absolute and normalized forms.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`boxes` | `Tensor | ndarray` | A tensor or numpy array with detection boxes of shape (num_boxes, 6) or (num_boxes, 7). Columns should contain [x1, y1, x2, y2, (optional) track_id, confidence, class]. | required
`orig_shape` | `tuple[int, int]` | The original image shape as (height, width). Used for normalization. | required

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor` | The raw tensor containing detection boxes and their associated data.
`orig_shape` | `tuple[int, int]` | The original image size, used for normalization.
`is_track` | `bool` | Indicates whether tracking IDs are included in the box data.

Examples:

    >>> import torch
    >>> boxes = torch.tensor([[100, 50, 150, 100, 0.9, 0]])
    >>> orig_shape = (480, 640)
    >>> detection_boxes = Boxes(boxes, orig_shape)
    >>> print(detection_boxes.xyxy)
    tensor([[100.,  50., 150., 100.]])

Source code in `ultralytics/engine/results.py`

    892
    893
    894
    895
    896
    897
    898
    899
    900
    901
    902
    903
    904
    905
    906
    907
    908
    909
    910
    911
    912
    913
    914
    915
    916
    917
    918
    919
    920
    921
    922
    923
    924
    925
    def __init__(self, boxes: torch.Tensor | np.ndarray, orig_shape: tuple[int, int]) -> None:
        """
        Initialize the Boxes class with detection box data and the original image shape.

        This class manages detection boxes, providing easy access and manipulation of box coordinates,
        confidence scores, class identifiers, and optional tracking IDs. It supports multiple formats
        for box coordinates, including both absolute and normalized forms.

        Args:
            boxes (torch.Tensor | np.ndarray): A tensor or numpy array with detection boxes of shape
                (num_boxes, 6) or (num_boxes, 7). Columns should contain
                [x1, y1, x2, y2, (optional) track_id, confidence, class].
            orig_shape (tuple[int, int]): The original image shape as (height, width). Used for normalization.

        Attributes:
            data (torch.Tensor): The raw tensor containing detection boxes and their associated data.
            orig_shape (tuple[int, int]): The original image size, used for normalization.
            is_track (bool): Indicates whether tracking IDs are included in the box data.

        Examples:
            >>> import torch
            >>> boxes = torch.tensor([[100, 50, 150, 100, 0.9, 0]])
            >>> orig_shape = (480, 640)
            >>> detection_boxes = Boxes(boxes, orig_shape)
            >>> print(detection_boxes.xyxy)
            tensor([[100.,  50., 150., 100.]])
        """
        if boxes.ndim == 1:
            boxes = boxes[None, :]
        n = boxes.shape[-1]
        assert n in {6, 7}, f"expected 6 or 7 values but got {n}"  # xyxy, track_id, conf, cls
        super().__init__(boxes, orig_shape)
        self.is_track = n == 7
        self.orig_shape = orig_shape

### `` cls `property`

    cls: Tensor | ndarray

Return the class ID tensor representing category predictions for each bounding box.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or numpy array containing the class IDs for each detection box. The shape is (N,), where N is the number of boxes.

Examples:

    >>> results = model("image.jpg")
    >>> boxes = results[0].boxes
    >>> class_ids = boxes.cls
    >>> print(class_ids)  # tensor([0., 2., 1.])

### `` conf `property`

    conf: Tensor | ndarray

Return the confidence scores for each detection box.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A 1D tensor or array containing confidence scores for each detection, with shape (N,) where N is the number of detections.

Examples:

    >>> boxes = Boxes(torch.tensor([[10, 20, 30, 40, 0.9, 0]]), orig_shape=(100, 100))
    >>> conf_scores = boxes.conf
    >>> print(conf_scores)
    tensor([0.9000])

### `` id `property`

    id: Tensor | ndarray | None

Return the tracking IDs for each detection box if available.

Returns:

Type | Description
--- | ---
`Tensor | None` | A tensor containing tracking IDs for each box if tracking is enabled, otherwise None. Shape is (N,) where N is the number of boxes.

Examples:

    >>> results = model.track("path/to/video.mp4")
    >>> for result in results:
    ...     boxes = result.boxes
    ...     if boxes.is_track:
    ...         track_ids = boxes.id
    ...         print(f"Tracking IDs: {track_ids}")
    ...     else:
    ...         print("Tracking is not enabled for these boxes.")

Notes

- This property is only available when tracking is enabled (i.e., when `is_track` is True).
- The tracking IDs are typically used to associate detections across multiple frames in video analysis.

### `` xywh `cached` `property`

    xywh: Tensor | ndarray

Convert bounding boxes from [x1, y1, x2, y2] format to [x, y, width, height] format.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Boxes in [x_center, y_center, width, height] format, where x_center, y_center are the coordinates of the center point of the bounding box, width, height are the dimensions of the bounding box and the shape of the returned tensor is (N, 4), where N is the number of boxes.

Examples:

    >>> boxes = Boxes(torch.tensor([[100, 50, 150, 100], [200, 150, 300, 250]]), orig_shape=(480, 640))
    >>> xywh = boxes.xywh
    >>> print(xywh)
    tensor([[100.0000,  50.0000,  50.0000,  50.0000],
            [200.0000, 150.0000, 100.0000, 100.0000]])

### `` xywhn `cached` `property`

    xywhn: Tensor | ndarray

Return normalized bounding boxes in [x, y, width, height] format.

This property calculates and returns the normalized bounding box coordinates in the format [x_center, y_center, width, height], where all values are relative to the original image dimensions.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Normalized bounding boxes with shape (N, 4), where N is the number of boxes. Each row contains [x_center, y_center, width, height] values normalized to [0, 1] based on the original image dimensions.

Examples:

    >>> boxes = Boxes(torch.tensor([[100, 50, 150, 100, 0.9, 0]]), orig_shape=(480, 640))
    >>> normalized = boxes.xywhn
    >>> print(normalized)
    tensor([[0.1953, 0.1562, 0.0781, 0.1042]])

### `` xyxy `property`

    xyxy: Tensor | ndarray

Return bounding boxes in [x1, y1, x2, y2] format.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or numpy array of shape (n, 4) containing bounding box coordinates in [x1, y1, x2, y2] format, where n is the number of boxes.

Examples:

    >>> results = model("image.jpg")
    >>> boxes = results[0].boxes
    >>> xyxy = boxes.xyxy
    >>> print(xyxy)

### `` xyxyn `cached` `property`

    xyxyn: Tensor | ndarray

Return normalized bounding box coordinates relative to the original image size.

This property calculates and returns the bounding box coordinates in [x1, y1, x2, y2] format, normalized to the range [0, 1] based on the original image dimensions.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Normalized bounding box coordinates with shape (N, 4), where N is the number of boxes. Each row contains [x1, y1, x2, y2] values normalized to [0, 1].

Examples:

    >>> boxes = Boxes(torch.tensor([[100, 50, 300, 400, 0.9, 0]]), orig_shape=(480, 640))
    >>> normalized = boxes.xyxyn
    >>> print(normalized)
    tensor([[0.1562, 0.1042, 0.4688, 0.8333]])

## `` ultralytics.engine.results.Masks

    Masks(masks: Tensor | ndarray, orig_shape: tuple[int, int])

Bases: `BaseTensor`

A class for storing and manipulating detection masks.

This class extends BaseTensor and provides functionality for handling segmentation masks, including methods for converting between pixel and normalized coordinates.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | The raw tensor or array containing mask data.
`orig_shape` | `tuple` | Original image shape in (height, width) format.
`xy` | `list[ndarray]` | A list of segments in pixel coordinates.
`xyn` | `list[ndarray]` | A list of normalized segments.

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the Masks object with the mask tensor on CPU memory.
`numpy` | Return a copy of the Masks object with the mask tensor as a numpy array.
`cuda` | Return a copy of the Masks object with the mask tensor on GPU memory.
`to` | Return a copy of the Masks object with the mask tensor on specified device and dtype.

Examples:

    >>> masks_data = torch.rand(1, 160, 160)
    >>> orig_shape = (720, 1280)
    >>> masks = Masks(masks_data, orig_shape)
    >>> pixel_coords = masks.xy
    >>> normalized_coords = masks.xyn

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`masks` | `Tensor | ndarray` | Detection masks with shape (num_masks, height, width). | required
`orig_shape` | `tuple` | The original image shape as (height, width). Used for normalization. | required

Examples:

    >>> import torch
    >>> from ultralytics.engine.results import Masks
    >>> masks = torch.rand(10, 160, 160)  # 10 masks of 160x160 resolution
    >>> orig_shape = (720, 1280)  # Original image shape
    >>> mask_obj = Masks(masks, orig_shape)

Source code in `ultralytics/engine/results.py`

    1101
    1102
    1103
    1104
    1105
    1106
    1107
    1108
    1109
    1110
    1111
    1112
    1113
    1114
    1115
    1116
    1117
    1118
    def __init__(self, masks: torch.Tensor | np.ndarray, orig_shape: tuple[int, int]) -> None:
        """
        Initialize the Masks class with detection mask data and the original image shape.

        Args:
            masks (torch.Tensor | np.ndarray): Detection masks with shape (num_masks, height, width).
            orig_shape (tuple): The original image shape as (height, width). Used for normalization.

        Examples:
            >>> import torch
            >>> from ultralytics.engine.results import Masks
            >>> masks = torch.rand(10, 160, 160)  # 10 masks of 160x160 resolution
            >>> orig_shape = (720, 1280)  # Original image shape
            >>> mask_obj = Masks(masks, orig_shape)
        """
        if masks.ndim == 2:
            masks = masks[None, :]
        super().__init__(masks, orig_shape)

### `` xy `cached` `property`

    xy: list[ndarray]

Return the [x, y] pixel coordinates for each segment in the mask tensor.

This property calculates and returns a list of pixel coordinates for each segmentation mask in the Masks object. The coordinates are scaled to match the original image dimensions.

Returns:

Type | Description
--- | ---
`list[ndarray]` | A list of numpy arrays, where each array contains the [x, y] pixel coordinates for a single segmentation mask. Each array has shape (N, 2), where N is the number of points in the segment.

Examples:

    >>> results = model("image.jpg")
    >>> masks = results[0].masks
    >>> xy_coords = masks.xy
    >>> print(len(xy_coords))  # Number of masks
    >>> print(xy_coords[0].shape)  # Shape of first mask's coordinates

### `` xyn `cached` `property`

    xyn: list[ndarray]

Return normalized xy-coordinates of the segmentation masks.

This property calculates and caches the normalized xy-coordinates of the segmentation masks. The coordinates are normalized relative to the original image shape.

Returns:

Type | Description
--- | ---
`list[ndarray]` | A list of numpy arrays, where each array contains the normalized xy-coordinates of a single segmentation mask. Each array has shape (N, 2), where N is the number of points in the mask contour.

Examples:

    >>> results = model("image.jpg")
    >>> masks = results[0].masks
    >>> normalized_coords = masks.xyn
    >>> print(normalized_coords[0])  # Normalized coordinates of the first mask

## `` ultralytics.engine.results.Keypoints

    Keypoints(keypoints: Tensor | ndarray, orig_shape: tuple[int, int])

Bases: `BaseTensor`

A class for storing and manipulating detection keypoints.

This class encapsulates functionality for handling keypoint data, including coordinate manipulation, normalization, and confidence values. It supports keypoint detection results with optional visibility information.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor` | The raw tensor containing keypoint data.
`orig_shape` | `tuple[int, int]` | The original image dimensions (height, width).
`has_visible` | `bool` | Indicates whether visibility information is available for keypoints.
`xy` | `Tensor` | Keypoint coordinates in [x, y] format.
`xyn` | `Tensor` | Normalized keypoint coordinates in [x, y] format, relative to orig_shape.
`conf` | `Tensor` | Confidence values for each keypoint, if available.

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the keypoints tensor on CPU memory.
`numpy` | Return a copy of the keypoints tensor as a numpy array.
`cuda` | Return a copy of the keypoints tensor on GPU memory.
`to` | Return a copy of the keypoints tensor with specified device and dtype.

Examples:

    >>> import torch
    >>> from ultralytics.engine.results import Keypoints
    >>> keypoints_data = torch.rand(1, 17, 3)  # 1 detection, 17 keypoints, (x, y, conf)
    >>> orig_shape = (480, 640)  # Original image shape (height, width)
    >>> keypoints = Keypoints(keypoints_data, orig_shape)
    >>> print(keypoints.xy.shape)  # Access xy coordinates
    >>> print(keypoints.conf)  # Access confidence values
    >>> keypoints_cpu = keypoints.cpu()  # Move keypoints to CPU

This method processes the input keypoints tensor, handling both 2D and 3D formats. For 3D tensors (x, y, confidence), it masks out low-confidence keypoints by setting their coordinates to zero.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`keypoints` | `Tensor` | A tensor containing keypoint data. Shape can be either: - (num_objects, num_keypoints, 2) for x, y coordinates only - (num_objects, num_keypoints, 3) for x, y coordinates and confidence scores | required
`orig_shape` | `tuple[int, int]` | The original image dimensions (height, width). | required

Examples:

    >>> kpts = torch.rand(1, 17, 3)  # 1 object, 17 keypoints (COCO format), x,y,conf
    >>> orig_shape = (720, 1280)  # Original image height, width
    >>> keypoints = Keypoints(kpts, orig_shape)

Source code in `ultralytics/engine/results.py`

    1205
    1206
    1207
    1208
    1209
    1210
    1211
    1212
    1213
    1214
    1215
    1216
    1217
    1218
    1219
    1220
    1221
    1222
    1223
    1224
    1225
    1226
    def __init__(self, keypoints: torch.Tensor | np.ndarray, orig_shape: tuple[int, int]) -> None:
        """
        Initialize the Keypoints object with detection keypoints and original image dimensions.

        This method processes the input keypoints tensor, handling both 2D and 3D formats. For 3D tensors
        (x, y, confidence), it masks out low-confidence keypoints by setting their coordinates to zero.

        Args:
            keypoints (torch.Tensor): A tensor containing keypoint data. Shape can be either:
                - (num_objects, num_keypoints, 2) for x, y coordinates only
                - (num_objects, num_keypoints, 3) for x, y coordinates and confidence scores
            orig_shape (tuple[int, int]): The original image dimensions (height, width).

        Examples:
            >>> kpts = torch.rand(1, 17, 3)  # 1 object, 17 keypoints (COCO format), x,y,conf
            >>> orig_shape = (720, 1280)  # Original image height, width
            >>> keypoints = Keypoints(kpts, orig_shape)
        """
        if keypoints.ndim == 2:
            keypoints = keypoints[None, :]
        super().__init__(keypoints, orig_shape)
        self.has_visible = self.data.shape[-1] == 3

### `` conf `cached` `property`

    conf: Tensor | ndarray | None

Return confidence values for each keypoint.

Returns:

Type | Description
--- | ---
`Tensor | None` | A tensor containing confidence scores for each keypoint if available, otherwise None. Shape is (num_detections, num_keypoints) for batched data or (num_keypoints,) for single detection.

Examples:

    >>> keypoints = Keypoints(torch.rand(1, 17, 3), orig_shape=(640, 640))  # 1 detection, 17 keypoints
    >>> conf = keypoints.conf
    >>> print(conf.shape)  # torch.Size([1, 17])

### `` xy `cached` `property`

    xy: Tensor | ndarray

Return x, y coordinates of keypoints.

Returns:

Type | Description
--- | ---
`Tensor` | A tensor containing the x, y coordinates of keypoints with shape (N, K, 2), where N is the number of detections and K is the number of keypoints per detection.

Examples:

    >>> results = model("image.jpg")
    >>> keypoints = results[0].keypoints
    >>> xy = keypoints.xy
    >>> print(xy.shape)  # (N, K, 2)
    >>> print(xy[0])  # x, y coordinates of keypoints for first detection

Notes

- The returned coordinates are in pixel units relative to the original image dimensions.
- If keypoints were initialized with confidence values, only keypoints with confidence >= 0.5 are returned.
- This property uses LRU caching to improve performance on repeated access.

### `` xyn `cached` `property`

    xyn: Tensor | ndarray

Return normalized coordinates (x, y) of keypoints relative to the original image size.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or array of shape (N, K, 2) containing normalized keypoint coordinates, where N is the number of instances, K is the number of keypoints, and the last dimension contains [x, y] values in the range [0, 1].

Examples:

    >>> keypoints = Keypoints(torch.rand(1, 17, 2), orig_shape=(480, 640))
    >>> normalized_kpts = keypoints.xyn
    >>> print(normalized_kpts.shape)
    torch.Size([1, 17, 2])

## `` ultralytics.engine.results.Probs

    Probs(probs: Tensor | ndarray, orig_shape: tuple[int, int] | None = None)

Bases: `BaseTensor`

A class for storing and manipulating classification probabilities.

This class extends BaseTensor and provides methods for accessing and manipulating classification probabilities, including top-1 and top-5 predictions.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | The raw tensor or array containing classification probabilities.
`orig_shape` | `tuple | None` | The original image shape as (height, width). Not used in this class.
`top1` | `int` | Index of the class with the highest probability.
`top5` | `list[int]` | Indices of the top 5 classes by probability.
`top1conf` | `Tensor | ndarray` | Confidence score of the top 1 class.
`top5conf` | `Tensor | ndarray` | Confidence scores of the top 5 classes.

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the probabilities tensor on CPU memory.
`numpy` | Return a copy of the probabilities tensor as a numpy array.
`cuda` | Return a copy of the probabilities tensor on GPU memory.
`to` | Return a copy of the probabilities tensor with specified device and dtype.

Examples:

    >>> probs = torch.tensor([0.1, 0.3, 0.6])
    >>> p = Probs(probs)
    >>> print(p.top1)
    2
    >>> print(p.top5)
    [2, 1, 0]
    >>> print(p.top1conf)
    tensor(0.6000)
    >>> print(p.top5conf)
    tensor([0.6000, 0.3000, 0.1000])

This class stores and manages classification probabilities, providing easy access to top predictions and their confidences.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`probs` | `Tensor | ndarray` | A 1D tensor or array of classification probabilities. | required
`orig_shape` | `tuple | None` | The original image shape as (height, width). Not used in this class but kept for consistency with other result classes. | `None`

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | The raw tensor or array containing classification probabilities.
`top1` | `int` | Index of the top 1 class.
`top5` | `list[int]` | Indices of the top 5 classes.
`top1conf` | `Tensor | ndarray` | Confidence of the top 1 class.
`top5conf` | `Tensor | ndarray` | Confidences of the top 5 classes.

Examples:

    >>> import torch
    >>> probs = torch.tensor([0.1, 0.3, 0.2, 0.4])
    >>> p = Probs(probs)
    >>> print(p.top1)
    3
    >>> print(p.top1conf)
    tensor(0.4000)
    >>> print(p.top5)
    [3, 1, 2, 0]

Source code in `ultralytics/engine/results.py`

    1327
    1328
    1329
    1330
    1331
    1332
    1333
    1334
    1335
    1336
    1337
    1338
    1339
    1340
    1341
    1342
    1343
    1344
    1345
    1346
    1347
    1348
    1349
    1350
    1351
    1352
    1353
    1354
    1355
    1356
    1357
    def __init__(self, probs: torch.Tensor | np.ndarray, orig_shape: tuple[int, int] | None = None) -> None:
        """
        Initialize the Probs class with classification probabilities.

        This class stores and manages classification probabilities, providing easy access to top predictions and their
        confidences.

        Args:
            probs (torch.Tensor | np.ndarray): A 1D tensor or array of classification probabilities.
            orig_shape (tuple | None): The original image shape as (height, width). Not used in this class but kept
                for consistency with other result classes.

        Attributes:
            data (torch.Tensor | np.ndarray): The raw tensor or array containing classification probabilities.
            top1 (int): Index of the top 1 class.
            top5 (list[int]): Indices of the top 5 classes.
            top1conf (torch.Tensor | np.ndarray): Confidence of the top 1 class.
            top5conf (torch.Tensor | np.ndarray): Confidences of the top 5 classes.

        Examples:
            >>> import torch
            >>> probs = torch.tensor([0.1, 0.3, 0.2, 0.4])
            >>> p = Probs(probs)
            >>> print(p.top1)
            3
            >>> print(p.top1conf)
            tensor(0.4000)
            >>> print(p.top5)
            [3, 1, 2, 0]
        """
        super().__init__(probs, orig_shape)

### `` top1 `cached` `property`

    top1: int

Return the index of the class with the highest probability.

Returns:

Type | Description
--- | ---
`int` | Index of the class with the highest probability.

Examples:

    >>> probs = Probs(torch.tensor([0.1, 0.3, 0.6]))
    >>> probs.top1
    2

### `` top1conf `cached` `property`

    top1conf: Tensor | ndarray

Return the confidence score of the highest probability class.

This property retrieves the confidence score (probability) of the class with the highest predicted probability from the classification results.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor containing the confidence score of the top 1 class.

Examples:

    >>> results = model("image.jpg")  # classify an image
    >>> probs = results[0].probs  # get classification probabilities
    >>> top1_confidence = probs.top1conf  # get confidence of top 1 class
    >>> print(f"Top 1 class confidence: {top1_confidence.item():.4f}")

### `` top5 `cached` `property`

    top5: list[int]

Return the indices of the top 5 class probabilities.

Returns:

Type | Description
--- | ---
`list[int]` | A list containing the indices of the top 5 class probabilities, sorted in descending order.

Examples:

    >>> probs = Probs(torch.tensor([0.1, 0.2, 0.3, 0.4, 0.5]))
    >>> print(probs.top5)
    [4, 3, 2, 1, 0]

### `` top5conf `cached` `property`

    top5conf: Tensor | ndarray

Return confidence scores for the top 5 classification predictions.

This property retrieves the confidence scores corresponding to the top 5 class probabilities predicted by the model. It provides a quick way to access the most likely class predictions along with their associated confidence levels.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or array containing the confidence scores for the top 5 predicted classes, sorted in descending order of probability.

Examples:

    >>> results = model("image.jpg")
    >>> probs = results[0].probs
    >>> top5_conf = probs.top5conf
    >>> print(top5_conf)  # Prints confidence scores for top 5 classes

## `` ultralytics.engine.results.OBB

    OBB(boxes: Tensor | ndarray, orig_shape: tuple[int, int])

Bases: `BaseTensor`

A class for storing and manipulating Oriented Bounding Boxes (OBB).

This class provides functionality to handle oriented bounding boxes, including conversion between different formats, normalization, and access to various properties of the boxes. It supports both tracking and non-tracking scenarios.

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor` | The raw OBB tensor containing box coordinates and associated data.
`orig_shape` | `tuple` | Original image size as (height, width).
`is_track` | `bool` | Indicates whether tracking IDs are included in the box data.
`xywhr` | `Tensor | ndarray` | Boxes in [x_center, y_center, width, height, rotation] format.
`conf` | `Tensor | ndarray` | Confidence scores for each box.
`cls` | `Tensor | ndarray` | Class labels for each box.
`id` | `Tensor | ndarray` | Tracking IDs for each box, if available.
`xyxyxyxy` | `Tensor | ndarray` | Boxes in 8-point [x1, y1, x2, y2, x3, y3, x4, y4] format.
`xyxyxyxyn` | `Tensor | ndarray` | Normalized 8-point coordinates relative to orig_shape.
`xyxy` | `Tensor | ndarray` | Axis-aligned bounding boxes in [x1, y1, x2, y2] format.

Methods:

Name | Description
--- | ---
`cpu` | Return a copy of the OBB object with all tensors on CPU memory.
`numpy` | Return a copy of the OBB object with all tensors as numpy arrays.
`cuda` | Return a copy of the OBB object with all tensors on GPU memory.
`to` | Return a copy of the OBB object with tensors on specified device and dtype.

Examples:

    >>> boxes = torch.tensor([[100, 50, 150, 100, 30, 0.9, 0]])  # xywhr, conf, cls
    >>> obb = OBB(boxes, orig_shape=(480, 640))
    >>> print(obb.xyxyxyxy)
    >>> print(obb.conf)
    >>> print(obb.cls)

This class stores and manipulates Oriented Bounding Boxes (OBB) for object detection tasks. It provides various properties and methods to access and transform the OBB data.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`boxes` | `Tensor | ndarray` | A tensor or numpy array containing the detection boxes, with shape (num_boxes, 7) or (num_boxes, 8). The last two columns contain confidence and class values. If present, the third last column contains track IDs, and the fifth column contains rotation. | required
`orig_shape` | `tuple[int, int]` | Original image size, in the format (height, width). | required

Attributes:

Name | Type | Description
--- | --- | ---
`data` | `Tensor | ndarray` | The raw OBB tensor.
`orig_shape` | `tuple[int, int]` | The original image shape.
`is_track` | `bool` | Whether the boxes include tracking IDs.

Raises:

Type | Description
--- | ---
`AssertionError` | If the number of values per box is not 7 or 8.

Examples:

    >>> import torch
    >>> boxes = torch.rand(3, 7)  # 3 boxes with 7 values each
    >>> orig_shape = (640, 480)
    >>> obb = OBB(boxes, orig_shape)
    >>> print(obb.xywhr)  # Access the boxes in xywhr format

Source code in `ultralytics/engine/results.py`

    1468
    1469
    1470
    1471
    1472
    1473
    1474
    1475
    1476
    1477
    1478
    1479
    1480
    1481
    1482
    1483
    1484
    1485
    1486
    1487
    1488
    1489
    1490
    1491
    1492
    1493
    1494
    1495
    1496
    1497
    1498
    1499
    1500
    1501
    1502
    def __init__(self, boxes: torch.Tensor | np.ndarray, orig_shape: tuple[int, int]) -> None:
        """
        Initialize an OBB (Oriented Bounding Box) instance with oriented bounding box data and original image shape.

        This class stores and manipulates Oriented Bounding Boxes (OBB) for object detection tasks. It provides
        various properties and methods to access and transform the OBB data.

        Args:
            boxes (torch.Tensor | np.ndarray): A tensor or numpy array containing the detection boxes,
                with shape (num_boxes, 7) or (num_boxes, 8). The last two columns contain confidence and class values.
                If present, the third last column contains track IDs, and the fifth column contains rotation.
            orig_shape (tuple[int, int]): Original image size, in the format (height, width).

        Attributes:
            data (torch.Tensor | np.ndarray): The raw OBB tensor.
            orig_shape (tuple[int, int]): The original image shape.
            is_track (bool): Whether the boxes include tracking IDs.

        Raises:
            AssertionError: If the number of values per box is not 7 or 8.

        Examples:
            >>> import torch
            >>> boxes = torch.rand(3, 7)  # 3 boxes with 7 values each
            >>> orig_shape = (640, 480)
            >>> obb = OBB(boxes, orig_shape)
            >>> print(obb.xywhr)  # Access the boxes in xywhr format
        """
        if boxes.ndim == 1:
            boxes = boxes[None, :]
        n = boxes.shape[-1]
        assert n in {7, 8}, f"expected 7 or 8 values but got {n}"  # xywh, rotation, track_id, conf, cls
        super().__init__(boxes, orig_shape)
        self.is_track = n == 8
        self.orig_shape = orig_shape

### `` cls `property`

    cls: Tensor | ndarray

Return the class values of the oriented bounding boxes.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or numpy array containing the class values for each oriented bounding box. The shape is (N,), where N is the number of boxes.

Examples:

    >>> results = model("image.jpg")
    >>> result = results[0]
    >>> obb = result.obb
    >>> class_values = obb.cls
    >>> print(class_values)

### `` conf `property`

    conf: Tensor | ndarray

Return the confidence scores for Oriented Bounding Boxes (OBBs).

This property retrieves the confidence values associated with each OBB detection. The confidence score represents the model's certainty in the detection.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or numpy array of shape (N,) containing confidence scores for N detections, where each score is in the range [0, 1].

Examples:

    >>> results = model("image.jpg")
    >>> obb_result = results[0].obb
    >>> confidence_scores = obb_result.conf
    >>> print(confidence_scores)

### `` id `property`

    id: Tensor | ndarray | None

Return the tracking IDs of the oriented bounding boxes (if available).

Returns:

Type | Description
--- | ---
`Tensor | ndarray | None` | A tensor or numpy array containing the tracking IDs for each oriented bounding box. Returns None if tracking IDs are not available.

Examples:

    >>> results = model("image.jpg", tracker=True)  # Run inference with tracking
    >>> for result in results:
    ...     if result.obb is not None:
    ...         track_ids = result.obb.id
    ...         if track_ids is not None:
    ...             print(f"Tracking IDs: {track_ids}")

### `` xywhr `property`

    xywhr: Tensor | ndarray

Return boxes in [x_center, y_center, width, height, rotation] format.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | A tensor or numpy array containing the oriented bounding boxes with format [x_center, y_center, width, height, rotation]. The shape is (N, 5) where N is the number of boxes.

Examples:

    >>> results = model("image.jpg")
    >>> obb = results[0].obb
    >>> xywhr = obb.xywhr
    >>> print(xywhr.shape)
    torch.Size([3, 5])

### `` xyxy `cached` `property`

    xyxy: Tensor | ndarray

Convert oriented bounding boxes (OBB) to axis-aligned bounding boxes in xyxy format.

This property calculates the minimal enclosing rectangle for each oriented bounding box and returns it in xyxy format (x1, y1, x2, y2). This is useful for operations that require axis-aligned bounding boxes, such as IoU calculation with non-rotated boxes.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Axis-aligned bounding boxes in xyxy format with shape (N, 4), where N is the number of boxes. Each row contains [x1, y1, x2, y2] coordinates.

Examples:

    >>> import torch
    >>> from ultralytics import YOLO
    >>> model = YOLO("yolo11n-obb.pt")
    >>> results = model("path/to/image.jpg")
    >>> for result in results:
    ...     obb = result.obb
    ...     if obb is not None:
    ...         xyxy_boxes = obb.xyxy
    ...         print(xyxy_boxes.shape)  # (N, 4)

Notes

- This method approximates the OBB by its minimal enclosing rectangle.
- The returned format is compatible with standard object detection metrics and visualization tools.
- The property uses caching to improve performance for repeated access.

### `` xyxyxyxy `cached` `property`

    xyxyxyxy: Tensor | ndarray

Convert OBB format to 8-point (xyxyxyxy) coordinate format for rotated bounding boxes.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Rotated bounding boxes in xyxyxyxy format with shape (N, 4, 2), where N is the number of boxes. Each box is represented by 4 points (x, y), starting from the top-left corner and moving clockwise.

Examples:

    >>> obb = OBB(torch.tensor([[100, 100, 50, 30, 0.5, 0.9, 0]]), orig_shape=(640, 640))
    >>> xyxyxyxy = obb.xyxyxyxy
    >>> print(xyxyxyxy.shape)
    torch.Size([1, 4, 2])

### `` xyxyxyxyn `cached` `property`

    xyxyxyxyn: Tensor | ndarray

Convert rotated bounding boxes to normalized xyxyxyxy format.

Returns:

Type | Description
--- | ---
`Tensor | ndarray` | Normalized rotated bounding boxes in xyxyxyxy format with shape (N, 4, 2), where N is the number of boxes. Each box is represented by 4 points (x, y), normalized relative to the original image dimensions.

Examples:

    >>> obb = OBB(torch.rand(10, 7), orig_shape=(640, 480))  # 10 random OBBs
    >>> normalized_boxes = obb.xyxyxyxyn
    >>> print(normalized_boxes.shape)
    torch.Size([10, 4, 2])

📅 Created 1 year ago ✏️ Updated 1 year ago