ultralytics 8.3.88__py3-none-any.whl → 8.3.90__py3-none-any.whl

ultralytics/utils/downloads.py

@@ -48,10 +48,8 @@ def is_url(url, check=False):
         (bool): Returns True for a valid URL. If 'check' is True, also returns True if the URL exists online.
             Returns False otherwise.
 
-    Example:
-        ```python
-        valid = is_url("https://www.example.com")
-        ```
+    Examples:
+        >>> valid = is_url("https://www.example.com")
     """
     try:
         url = str(url)
@@ -67,20 +65,17 @@ def is_url(url, check=False):
 
 def delete_dsstore(path, files_to_delete=(".DS_Store", "__MACOSX")):
     """
-    Deletes all ".DS_store" files under a specified directory.
+    Delete all ".DS_store" files in a specified directory.
 
     Args:
         path (str, optional): The directory path where the ".DS_store" files should be deleted.
         files_to_delete (tuple): The files to be deleted.
 
-    Example:
-        ```python
-        from ultralytics.utils.downloads import delete_dsstore
+    Examples:
+        >>> from ultralytics.utils.downloads import delete_dsstore
+        >>> delete_dsstore("path/to/dir")
 
-        delete_dsstore("path/to/dir")
-        ```
-
-    Note:
+    Notes:
         ".DS_store" files are created by the Apple operating system and contain metadata about folders and files. They
         are hidden system files and can cause issues when transferring files between different operating systems.
     """
@@ -105,12 +100,9 @@ def zip_directory(directory, compress=True, exclude=(".DS_Store", "__MACOSX"), p
     Returns:
         (Path): The path to the resulting zip file.
 
-    Example:
-        ```python
-        from ultralytics.utils.downloads import zip_directory
-
-        file = zip_directory("path/to/dir")
-        ```
+    Examples:
+        >>> from ultralytics.utils.downloads import zip_directory
+        >>> file = zip_directory("path/to/dir")
     """
     from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
 
@@ -140,7 +132,7 @@ def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=Fals
 
     Args:
         file (str | Path): The path to the zipfile to be extracted.
-        path (str, optional): The path to extract the zipfile to. Defaults to None.
+        path (str | Path, optional): The path to extract the zipfile to. Defaults to None.
         exclude (tuple, optional): A tuple of filename strings to be excluded. Defaults to ('.DS_Store', '__MACOSX').
         exist_ok (bool, optional): Whether to overwrite existing contents if they exist. Defaults to False.
         progress (bool, optional): Whether to display a progress bar. Defaults to True.
@@ -151,12 +143,9 @@ def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=Fals
     Returns:
         (Path): The path to the directory where the zipfile was extracted.
 
-    Example:
-        ```python
-        from ultralytics.utils.downloads import unzip_file
-
-        dir = unzip_file("path/to/file.zip")
-        ```
+    Examples:
+        >>> from ultralytics.utils.downloads import unzip_file
+        >>> directory = unzip_file("path/to/file.zip")
     """
     from zipfile import BadZipFile, ZipFile, is_zipfile
 
@@ -245,13 +234,10 @@ def get_google_drive_file_info(link):
         (str): Direct download URL for the Google Drive file.
         (str): Original filename of the Google Drive file. If filename extraction fails, returns None.
 
-    Example:
-        ```python
-        from ultralytics.utils.downloads import get_google_drive_file_info
-
-        link = "https://drive.google.com/file/d/1cqT-cJgANNrhIHCrEufUYhQ4RqiWG_lJ/view?usp=drive_link"
-        url, filename = get_google_drive_file_info(link)
-        ```
+    Examples:
+        >>> from ultralytics.utils.downloads import get_google_drive_file_info
+        >>> link = "https://drive.google.com/file/d/1cqT-cJgANNrhIHCrEufUYhQ4RqiWG_lJ/view?usp=drive_link"
+        >>> url, filename = get_google_drive_file_info(link)
     """
     file_id = link.split("/d/")[1].split("/view")[0]
     drive_url = f"https://drive.google.com/uc?export=download&id={file_id}"
@@ -294,7 +280,7 @@ def safe_download(
         url (str): The URL of the file to be downloaded.
         file (str, optional): The filename of the downloaded file.
             If not provided, the file will be saved with the same name as the URL.
-        dir (str, optional): The directory to save the downloaded file.
+        dir (str | Path, optional): The directory to save the downloaded file.
             If not provided, the file will be saved in the current working directory.
         unzip (bool, optional): Whether to unzip the downloaded file. Default: True.
         delete (bool, optional): Whether to delete the downloaded file after unzipping. Default: False.
@@ -305,13 +291,13 @@ def safe_download(
         exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False.
         progress (bool, optional): Whether to display a progress bar during the download. Default: True.
 
-    Example:
-        ```python
-        from ultralytics.utils.downloads import safe_download
+    Returns:
+        (Path | str): The path to the downloaded file or extracted directory.
 
-        link = "https://ultralytics.com/assets/bus.jpg"
-        path = safe_download(link)
-        ```
+    Examples:
+        >>> from ultralytics.utils.downloads import safe_download
+        >>> link = "https://ultralytics.com/assets/bus.jpg"
+        >>> path = safe_download(link)
     """
     gdrive = url.startswith("https://drive.google.com/")  # check if the URL is a Google Drive link
     if gdrive:
@@ -376,6 +362,7 @@ def safe_download(
         if delete:
             f.unlink()  # remove zip
         return unzip_dir
+    return f
 
 
 def get_github_assets(repo="ultralytics/assets", version="latest", retry=False):
@@ -389,12 +376,11 @@ def get_github_assets(repo="ultralytics/assets", version="latest", retry=False):
         retry (bool, optional): Flag to retry the request in case of a failure. Defaults to False.
 
     Returns:
-        (tuple): A tuple containing the release tag and a list of asset names.
+        (str): The release tag.
+        (List[str]): A list of asset names.
 
-    Example:
-        ```python
-        tag, assets = get_github_assets(repo="ultralytics/assets", version="latest")
-        ```
+    Examples:
+        >>> tag, assets = get_github_assets(repo="ultralytics/assets", version="latest")
     """
     if version != "latest":
         version = f"tags/{version}"  # i.e. tags/v6.2
@@ -411,22 +397,19 @@ def get_github_assets(repo="ultralytics/assets", version="latest", retry=False):
 
 def attempt_download_asset(file, repo="ultralytics/assets", release="v8.3.0", **kwargs):
     """
-    Attempt to download a file from GitHub release assets if it is not found locally. The function checks for the file
-    locally first, then tries to download it from the specified GitHub repository release.
+    Attempt to download a file from GitHub release assets if it is not found locally.
 
     Args:
         file (str | Path): The filename or file path to be downloaded.
         repo (str, optional): The GitHub repository in the format 'owner/repo'. Defaults to 'ultralytics/assets'.
         release (str, optional): The specific release version to be downloaded. Defaults to 'v8.3.0'.
-        **kwargs (any): Additional keyword arguments for the download process.
+        **kwargs (Any): Additional keyword arguments for the download process.
 
     Returns:
         (str): The path to the downloaded file.
 
-    Example:
-        ```python
-        file_path = attempt_download_asset("yolo11n.pt", repo="ultralytics/assets", release="latest")
-        ```
+    Examples:
+        >>> file_path = attempt_download_asset("yolo11n.pt", repo="ultralytics/assets", release="latest")
     """
     from ultralytics.utils import SETTINGS  # scoped for circular import
 
@@ -469,7 +452,7 @@ def download(url, dir=Path.cwd(), unzip=True, delete=False, curl=False, threads=
     specified.
 
     Args:
-        url (str | list): The URL or list of URLs of the files to be downloaded.
+        url (str | List[str]): The URL or list of URLs of the files to be downloaded.
         dir (Path, optional): The directory where the files will be saved. Defaults to the current working directory.
         unzip (bool, optional): Flag to unzip the files after downloading. Defaults to True.
         delete (bool, optional): Flag to delete the zip files after extraction. Defaults to False.
@@ -478,10 +461,8 @@ def download(url, dir=Path.cwd(), unzip=True, delete=False, curl=False, threads=
         retry (int, optional): Number of retries in case of download failure. Defaults to 3.
         exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False.
 
-    Example:
-        ```python
-        download("https://ultralytics.com/assets/example.zip", dir="path/to/dir", unzip=True)
-        ```
+    Examples:
+        >>> download("https://ultralytics.com/assets/example.zip", dir="path/to/dir", unzip=True)
     """
     dir = Path(dir)
     dir.mkdir(parents=True, exist_ok=True)  # make directory

ultralytics/utils/files.py

@@ -18,7 +18,7 @@ class WorkingDirectory(contextlib.ContextDecorator):
     It ensures that the original working directory is restored after the context or decorated function completes.
 
     Attributes:
-        dir (Path): The new directory to switch to.
+        dir (Path | str): The new directory to switch to.
         cwd (Path): The original current working directory before the switch.
 
     Methods:
@@ -55,21 +55,21 @@ class WorkingDirectory(contextlib.ContextDecorator):
 @contextmanager
 def spaces_in_path(path):
     """
-    Context manager to handle paths with spaces in their names. If a path contains spaces, it replaces them with
-    underscores, copies the file/directory to the new path, executes the context code block, then copies the
-    file/directory back to its original location.
+    Context manager to handle paths with spaces in their names.
+
+    If a path contains spaces, it replaces them with underscores, copies the file/directory to the new path, executes
+    the context code block, then copies the file/directory back to its original location.
 
     Args:
         path (str | Path): The original path that may contain spaces.
 
     Yields:
-        (Path): Temporary path with spaces replaced by underscores if spaces were present, otherwise the original path.
+        (Path | str): Temporary path with spaces replaced by underscores if spaces were present, otherwise the original path.
 
     Examples:
-        Use the context manager to handle paths with spaces:
-        >>> from ultralytics.utils.files import spaces_in_path
         >>> with spaces_in_path('/path/with spaces') as new_path:
         >>> # Your code here
+        >>>     pass
     """
     # If path has spaces, replace them with underscores
     if " " in str(path):
@@ -106,21 +106,20 @@ def spaces_in_path(path):
 
 def increment_path(path, exist_ok=False, sep="", mkdir=False):
     """
-    Increments a file or directory path, i.e., runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc.
+    Increment a file or directory path, i.e., runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc.
 
     If the path exists and `exist_ok` is not True, the path will be incremented by appending a number and `sep` to
     the end of the path. If the path is a file, the file extension will be preserved. If the path is a directory, the
-    number will be appended directly to the end of the path. If `mkdir` is set to True, the path will be created as a
-    directory if it does not already exist.
+    number will be appended directly to the end of the path.
 
     Args:
-        path (str | pathlib.Path): Path to increment.
+        path (str | Path): Path to increment.
         exist_ok (bool): If True, the path will not be incremented and returned as-is.
         sep (str): Separator to use between the path and the incrementation number.
         mkdir (bool): Create a directory if it does not exist.
 
     Returns:
-        (pathlib.Path): Incremented path.
+        (Path): Incremented path.
 
     Examples:
         Increment a directory path:
@@ -185,7 +184,7 @@ def get_latest_run(search_dir="."):
 
 def update_models(model_names=("yolo11n.pt",), source_dir=Path("."), update_names=False):
     """
-    Updates and re-saves specified YOLO models in an 'updated_models' subdirectory.
+    Update and re-save specified YOLO models in an 'updated_models' subdirectory.
 
     Args:
         model_names (Tuple[str, ...]): Model filenames to update.

ultralytics/utils/instance.py

@@ -14,7 +14,7 @@ def _ntuple(n):
     """From PyTorch internals."""
 
     def parse(x):
-        """Parse bounding boxes format between XYWH and LTWH."""
+        """Parse input to return n-tuple by repeating singleton values n times."""
         return x if isinstance(x, abc.Iterable) else tuple(repeat(x, n))
 
     return parse
@@ -39,7 +39,7 @@ class Bboxes:
     Bounding box data should be provided in numpy arrays.
 
     Attributes:
-        bboxes (numpy.ndarray): The bounding boxes stored in a 2D numpy array.
+        bboxes (np.ndarray): The bounding boxes stored in a 2D numpy array with shape (N, 4).
         format (str): The format of the bounding boxes ('xyxy', 'xywh', or 'ltwh').
 
     Note:
@@ -47,7 +47,13 @@ class Bboxes:
     """
 
     def __init__(self, bboxes, format="xyxy") -> None:
-        """Initializes the Bboxes class with bounding box data in a specified format."""
+        """
+        Initialize the Bboxes class with bounding box data in a specified format.
+
+        Args:
+            bboxes (np.ndarray): Array of bounding boxes with shape (N, 4) or (4,).
+            format (str): Format of the bounding boxes, one of 'xyxy', 'xywh', or 'ltwh'.
+        """
         assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}"
         bboxes = bboxes[None, :] if bboxes.ndim == 1 else bboxes
         assert bboxes.ndim == 2
@@ -57,7 +63,12 @@ class Bboxes:
         # self.normalized = normalized
 
     def convert(self, format):
-        """Converts bounding box format from one type to another."""
+        """
+        Convert bounding box format from one type to another.
+
+        Args:
+            format (str): Target format for conversion, one of 'xyxy', 'xywh', or 'ltwh'.
+        """
         assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}"
         if self.format == format:
             return
@@ -140,10 +151,9 @@ class Bboxes:
         Args:
             boxes_list (List[Bboxes]): A list of Bboxes objects to concatenate.
             axis (int, optional): The axis along which to concatenate the bounding boxes.
-                                   Defaults to 0.
 
         Returns:
-            Bboxes: A new Bboxes object containing the concatenated bounding boxes.
+            (Bboxes): A new Bboxes object containing the concatenated bounding boxes.
 
         Note:
             The input should be a list or tuple of Bboxes objects.
@@ -162,11 +172,11 @@ class Bboxes:
         Retrieve a specific bounding box or a set of bounding boxes using indexing.
 
         Args:
-            index (int, slice, or np.ndarray): The index, slice, or boolean array to select
-                                               the desired bounding boxes.
+            index (int | slice | np.ndarray): The index, slice, or boolean array to select
+                                              the desired bounding boxes.
 
         Returns:
-            Bboxes: A new Bboxes object containing the selected bounding boxes.
+            (Bboxes): A new Bboxes object containing the selected bounding boxes.
 
         Raises:
             AssertionError: If the indexed bounding boxes do not form a 2-dimensional matrix.
@@ -188,30 +198,29 @@ class Instances:
 
     Attributes:
         _bboxes (Bboxes): Internal object for handling bounding box operations.
-        keypoints (np.ndarray): keypoints(x, y, visible) with shape [N, 17, 3]. Default is None.
+        keypoints (np.ndarray): Keypoints with shape (N, 17, 3) in format (x, y, visible).
         normalized (bool): Flag indicating whether the bounding box coordinates are normalized.
-        segments (np.ndarray): Segments array with shape [N, 1000, 2] after resampling.
-
-    Args:
-        bboxes (np.ndarray): An array of bounding boxes with shape [N, 4].
-        segments (list | ndarray, optional): A list or array of object segments. Default is None.
-        keypoints (ndarray, optional): An array of keypoints with shape [N, 17, 3]. Default is None.
-        bbox_format (str, optional): The format of bounding boxes ('xywh' or 'xyxy'). Default is 'xywh'.
-        normalized (bool, optional): Whether the bounding box coordinates are normalized. Default is True.
+        segments (np.ndarray): Segments array with shape (N, M, 2) after resampling.
+
+    Methods:
+        convert_bbox: Convert bounding box format.
+        scale: Scale coordinates by given factors.
+        denormalize: Convert normalized coordinates to absolute coordinates.
+        normalize: Convert absolute coordinates to normalized coordinates.
+        add_padding: Add padding to coordinates.
+        flipud: Flip coordinates vertically.
+        fliplr: Flip coordinates horizontally.
+        clip: Clip coordinates to stay within image boundaries.
+        remove_zero_area_boxes: Remove boxes with zero area.
+        update: Update instance variables.
+        concatenate: Concatenate multiple Instances objects.
 
     Examples:
-        ```python
-        # Create an Instances object
-        instances = Instances(
-            bboxes=np.array([[10, 10, 30, 30], [20, 20, 40, 40]]),
-            segments=[np.array([[5, 5], [10, 10]]), np.array([[15, 15], [20, 20]])],
-            keypoints=np.array([[[5, 5, 1], [10, 10, 1]], [[15, 15, 1], [20, 20, 1]]]),
-        )
-        ```
-
-    Note:
-        The bounding box format is either 'xywh' or 'xyxy', and is determined by the `bbox_format` argument.
-        This class does not perform input validation, and it assumes the inputs are well-formed.
+        >>> instances = Instances(
+        ...     bboxes=np.array([[10, 10, 30, 30], [20, 20, 40, 40]]),
+        ...     segments=[np.array([[5, 5], [10, 10]]), np.array([[15, 15], [20, 20]])],
+        ...     keypoints=np.array([[[5, 5, 1], [10, 10, 1]], [[15, 15, 1], [20, 20, 1]]]),
+        ... )
     """
 
     def __init__(self, bboxes, segments=None, keypoints=None, bbox_format="xywh", normalized=True) -> None:
@@ -219,11 +228,11 @@ class Instances:
         Initialize the object with bounding boxes, segments, and keypoints.
 
         Args:
-            bboxes (np.ndarray): Bounding boxes, shape [N, 4].
-            segments (list | np.ndarray, optional): Segmentation masks. Defaults to None.
-            keypoints (np.ndarray, optional): Keypoints, shape [N, 17, 3] and format (x, y, visible). Defaults to None.
-            bbox_format (str, optional): Format of bboxes. Defaults to "xywh".
-            normalized (bool, optional): Whether the coordinates are normalized. Defaults to True.
+            bboxes (np.ndarray): Bounding boxes, shape (N, 4).
+            segments (List | np.ndarray, optional): Segmentation masks.
+            keypoints (np.ndarray, optional): Keypoints, shape (N, 17, 3) in format (x, y, visible).
+            bbox_format (str, optional): Format of bboxes.
+            normalized (bool, optional): Whether the coordinates are normalized.
         """
         self._bboxes = Bboxes(bboxes=bboxes, format=bbox_format)
         self.keypoints = keypoints
@@ -231,7 +240,12 @@ class Instances:
         self.segments = segments
 
     def convert_bbox(self, format):
-        """Convert bounding box format."""
+        """
+        Convert bounding box format.
+
+        Args:
+            format (str): Target format for conversion, one of 'xyxy', 'xywh', or 'ltwh'.
+        """
         self._bboxes.convert(format=format)
 
     @property
@@ -240,7 +254,14 @@ class Instances:
         return self._bboxes.areas()
 
     def scale(self, scale_w, scale_h, bbox_only=False):
-        """Similar to denormalize func but without normalized sign."""
+        """
+        Scale coordinates by given factors.
+
+        Args:
+            scale_w (float): Scale factor for width.
+            scale_h (float): Scale factor for height.
+            bbox_only (bool, optional): Whether to scale only bounding boxes.
+        """
         self._bboxes.mul(scale=(scale_w, scale_h, scale_w, scale_h))
         if bbox_only:
             return
@@ -251,7 +272,13 @@ class Instances:
             self.keypoints[..., 1] *= scale_h
 
     def denormalize(self, w, h):
-        """Denormalizes boxes, segments, and keypoints from normalized coordinates."""
+        """
+        Convert normalized coordinates to absolute coordinates.
+
+        Args:
+            w (int): Image width.
+            h (int): Image height.
+        """
         if not self.normalized:
             return
         self._bboxes.mul(scale=(w, h, w, h))
@@ -263,7 +290,13 @@ class Instances:
         self.normalized = False
 
     def normalize(self, w, h):
-        """Normalize bounding boxes, segments, and keypoints to image dimensions."""
+        """
+        Convert absolute coordinates to normalized coordinates.
+
+        Args:
+            w (int): Image width.
+            h (int): Image height.
+        """
         if self.normalized:
             return
         self._bboxes.mul(scale=(1 / w, 1 / h, 1 / w, 1 / h))
@@ -275,7 +308,13 @@ class Instances:
         self.normalized = True
 
     def add_padding(self, padw, padh):
-        """Handle rect and mosaic situation."""
+        """
+        Add padding to coordinates.
+
+        Args:
+            padw (int): Padding width.
+            padh (int): Padding height.
+        """
         assert not self.normalized, "you should add padding with absolute coordinates."
         self._bboxes.add(offset=(padw, padh, padw, padh))
         self.segments[..., 0] += padw
@@ -289,12 +328,10 @@ class Instances:
         Retrieve a specific instance or a set of instances using indexing.
 
         Args:
-            index (int, slice, or np.ndarray): The index, slice, or boolean array to select
-                                               the desired instances.
+            index (int | slice | np.ndarray): The index, slice, or boolean array to select the desired instances.
 
         Returns:
-            Instances: A new Instances object containing the selected bounding boxes,
-                       segments, and keypoints if present.
+            (Instances): A new Instances object containing the selected boxes, segments, and keypoints if present.
 
         Note:
             When using boolean indexing, make sure to provide a boolean array with the same
@@ -313,7 +350,12 @@ class Instances:
         )
 
     def flipud(self, h):
-        """Flips the coordinates of bounding boxes, segments, and keypoints vertically."""
+        """
+        Flip coordinates vertically.
+
+        Args:
+            h (int): Image height.
+        """
         if self._bboxes.format == "xyxy":
             y1 = self.bboxes[:, 1].copy()
             y2 = self.bboxes[:, 3].copy()
@@ -326,7 +368,12 @@ class Instances:
             self.keypoints[..., 1] = h - self.keypoints[..., 1]
 
     def fliplr(self, w):
-        """Reverses the order of the bounding boxes and segments horizontally."""
+        """
+        Flip coordinates horizontally.
+
+        Args:
+            w (int): Image width.
+        """
         if self._bboxes.format == "xyxy":
             x1 = self.bboxes[:, 0].copy()
             x2 = self.bboxes[:, 2].copy()
@@ -339,7 +386,13 @@ class Instances:
             self.keypoints[..., 0] = w - self.keypoints[..., 0]
 
     def clip(self, w, h):
-        """Clips bounding boxes, segments, and keypoints values to stay within image boundaries."""
+        """
+        Clip coordinates to stay within image boundaries.
+
+        Args:
+            w (int): Image width.
+            h (int): Image height.
+        """
         ori_format = self._bboxes.format
         self.convert_bbox(format="xyxy")
         self.bboxes[:, [0, 2]] = self.bboxes[:, [0, 2]].clip(0, w)
@@ -353,7 +406,12 @@ class Instances:
             self.keypoints[..., 1] = self.keypoints[..., 1].clip(0, h)
 
     def remove_zero_area_boxes(self):
-        """Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height."""
+        """
+        Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height.
+
+        Returns:
+            (np.ndarray): Boolean array indicating which boxes were kept.
+        """
         good = self.bbox_areas > 0
         if not all(good):
             self._bboxes = self._bboxes[good]
@@ -364,7 +422,14 @@ class Instances:
         return good
 
     def update(self, bboxes, segments=None, keypoints=None):
-        """Updates instance variables."""
+        """
+        Update instance variables.
+
+        Args:
+            bboxes (np.ndarray): New bounding boxes.
+            segments (np.ndarray, optional): New segments.
+            keypoints (np.ndarray, optional): New keypoints.
+        """
         self._bboxes = Bboxes(bboxes, format=self._bboxes.format)
         if segments is not None:
             self.segments = segments
@@ -378,14 +443,14 @@ class Instances:
     @classmethod
     def concatenate(cls, instances_list: List["Instances"], axis=0) -> "Instances":
         """
-        Concatenates a list of Instances objects into a single Instances object.
+        Concatenate a list of Instances objects into a single Instances object.
 
         Args:
             instances_list (List[Instances]): A list of Instances objects to concatenate.
-            axis (int, optional): The axis along which the arrays will be concatenated. Defaults to 0.
+            axis (int, optional): The axis along which the arrays will be concatenated.
 
         Returns:
-            Instances: A new Instances object containing the concatenated bounding boxes,
+            (Instances): A new Instances object containing the concatenated bounding boxes,
                        segments, and keypoints if present.
 
         Note: