Reference for ultralytics/utils/instance.py

def __getitem__(self, index) -> "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.

    Returns:
        Bboxes: A new Bboxes object containing the selected bounding boxes.

    Raises:
        AssertionError: If the indexed bounding boxes do not form a 2-dimensional matrix.

    Note:
        When using boolean indexing, make sure to provide a boolean array with the same
        length as the number of bounding boxes.
    """
    if isinstance(index, int):
        return Bboxes(self.bboxes[index].reshape(1, -1))
    b = self.bboxes[index]
    assert b.ndim == 2, f"Indexing on Bboxes with {index} failed to return a matrix!"
    return Bboxes(b)

def __len__(self):
    """Return the number of boxes."""
    return len(self.bboxes)

def add(self, offset):
    """
    Add offset to bounding box coordinates.

    Args:
        offset (int | tuple | list): Offset(s) for four coordinates.
            If int, the same offset is applied to all coordinates.
    """
    if isinstance(offset, Number):
        offset = to_4tuple(offset)
    assert isinstance(offset, (tuple, list))
    assert len(offset) == 4
    self.bboxes[:, 0] += offset[0]
    self.bboxes[:, 1] += offset[1]
    self.bboxes[:, 2] += offset[2]
    self.bboxes[:, 3] += offset[3]

def areas(self):
    """Return box areas."""
    return (
        (self.bboxes[:, 2] - self.bboxes[:, 0]) * (self.bboxes[:, 3] - self.bboxes[:, 1])  # format xyxy
        if self.format == "xyxy"
        else self.bboxes[:, 3] * self.bboxes[:, 2]  # format xywh or ltwh
    )

@classmethod
def concatenate(cls, boxes_list: List["Bboxes"], axis=0) -> "Bboxes":
    """
    Concatenate a list of Bboxes objects into a single Bboxes object.

    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.

    Note:
        The input should be a list or tuple of Bboxes objects.
    """
    assert isinstance(boxes_list, (list, tuple))
    if not boxes_list:
        return cls(np.empty(0))
    assert all(isinstance(box, Bboxes) for box in boxes_list)

    if len(boxes_list) == 1:
        return boxes_list[0]
    return cls(np.concatenate([b.bboxes for b in boxes_list], axis=axis))

def convert(self, format):
    """Converts bounding box format from one type to another."""
    assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}"
    if self.format == format:
        return
    elif self.format == "xyxy":
        func = xyxy2xywh if format == "xywh" else xyxy2ltwh
    elif self.format == "xywh":
        func = xywh2xyxy if format == "xyxy" else xywh2ltwh
    else:
        func = ltwh2xyxy if format == "xyxy" else ltwh2xywh
    self.bboxes = func(self.bboxes)
    self.format = format

def mul(self, scale):
    """
    Multiply bounding box coordinates by scale factor(s).

    Args:
        scale (int | tuple | list): Scale factor(s) for four coordinates.
            If int, the same scale is applied to all coordinates.
    """
    if isinstance(scale, Number):
        scale = to_4tuple(scale)
    assert isinstance(scale, (tuple, list))
    assert len(scale) == 4
    self.bboxes[:, 0] *= scale[0]
    self.bboxes[:, 1] *= scale[1]
    self.bboxes[:, 2] *= scale[2]
    self.bboxes[:, 3] *= scale[3]

def __getitem__(self, index) -> "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.

    Returns:
        Instances: A new Instances object containing the selected bounding boxes,
                   segments, and keypoints if present.

    Note:
        When using boolean indexing, make sure to provide a boolean array with the same
        length as the number of instances.
    """
    segments = self.segments[index] if len(self.segments) else self.segments
    keypoints = self.keypoints[index] if self.keypoints is not None else None
    bboxes = self.bboxes[index]
    bbox_format = self._bboxes.format
    return Instances(
        bboxes=bboxes,
        segments=segments,
        keypoints=keypoints,
        bbox_format=bbox_format,
        normalized=self.normalized,
    )

def __len__(self):
    """Return the length of the instance list."""
    return len(self.bboxes)

def add_padding(self, padw, padh):
    """Handle rect and mosaic situation."""
    assert not self.normalized, "you should add padding with absolute coordinates."
    self._bboxes.add(offset=(padw, padh, padw, padh))
    self.segments[..., 0] += padw
    self.segments[..., 1] += padh
    if self.keypoints is not None:
        self.keypoints[..., 0] += padw
        self.keypoints[..., 1] += padh

def clip(self, w, h):
    """Clips bounding boxes, segments, and keypoints values to stay within image boundaries."""
    ori_format = self._bboxes.format
    self.convert_bbox(format="xyxy")
    self.bboxes[:, [0, 2]] = self.bboxes[:, [0, 2]].clip(0, w)
    self.bboxes[:, [1, 3]] = self.bboxes[:, [1, 3]].clip(0, h)
    if ori_format != "xyxy":
        self.convert_bbox(format=ori_format)
    self.segments[..., 0] = self.segments[..., 0].clip(0, w)
    self.segments[..., 1] = self.segments[..., 1].clip(0, h)
    if self.keypoints is not None:
        self.keypoints[..., 0] = self.keypoints[..., 0].clip(0, w)
        self.keypoints[..., 1] = self.keypoints[..., 1].clip(0, h)

@classmethod
def concatenate(cls, instances_list: List["Instances"], axis=0) -> "Instances":
    """
    Concatenates 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.

    Returns:
        Instances: A new Instances object containing the concatenated bounding boxes,
                   segments, and keypoints if present.

    Note:
        The `Instances` objects in the list should have the same properties, such as
        the format of the bounding boxes, whether keypoints are present, and if the
        coordinates are normalized.
    """
    assert isinstance(instances_list, (list, tuple))
    if not instances_list:
        return cls(np.empty(0))
    assert all(isinstance(instance, Instances) for instance in instances_list)

    if len(instances_list) == 1:
        return instances_list[0]

    use_keypoint = instances_list[0].keypoints is not None
    bbox_format = instances_list[0]._bboxes.format
    normalized = instances_list[0].normalized

    cat_boxes = np.concatenate([ins.bboxes for ins in instances_list], axis=axis)
    seg_len = [b.segments.shape[1] for b in instances_list]
    if len(frozenset(seg_len)) > 1:  # resample segments if there's different length
        max_len = max(seg_len)
        cat_segments = np.concatenate(
            [
                resample_segments(list(b.segments), max_len)
                if len(b.segments)
                else np.zeros((0, max_len, 2), dtype=np.float32)  # re-generating empty segments
                for b in instances_list
            ],
            axis=axis,
        )
    else:
        cat_segments = np.concatenate([b.segments for b in instances_list], axis=axis)
    cat_keypoints = np.concatenate([b.keypoints for b in instances_list], axis=axis) if use_keypoint else None
    return cls(cat_boxes, cat_segments, cat_keypoints, bbox_format, normalized)

def convert_bbox(self, format):
    """Convert bounding box format."""
    self._bboxes.convert(format=format)

def denormalize(self, w, h):
    """Denormalizes boxes, segments, and keypoints from normalized coordinates."""
    if not self.normalized:
        return
    self._bboxes.mul(scale=(w, h, w, h))
    self.segments[..., 0] *= w
    self.segments[..., 1] *= h
    if self.keypoints is not None:
        self.keypoints[..., 0] *= w
        self.keypoints[..., 1] *= h
    self.normalized = False

def fliplr(self, w):
    """Reverses the order of the bounding boxes and segments horizontally."""
    if self._bboxes.format == "xyxy":
        x1 = self.bboxes[:, 0].copy()
        x2 = self.bboxes[:, 2].copy()
        self.bboxes[:, 0] = w - x2
        self.bboxes[:, 2] = w - x1
    else:
        self.bboxes[:, 0] = w - self.bboxes[:, 0]
    self.segments[..., 0] = w - self.segments[..., 0]
    if self.keypoints is not None:
        self.keypoints[..., 0] = w - self.keypoints[..., 0]

def flipud(self, h):
    """Flips the coordinates of bounding boxes, segments, and keypoints vertically."""
    if self._bboxes.format == "xyxy":
        y1 = self.bboxes[:, 1].copy()
        y2 = self.bboxes[:, 3].copy()
        self.bboxes[:, 1] = h - y2
        self.bboxes[:, 3] = h - y1
    else:
        self.bboxes[:, 1] = h - self.bboxes[:, 1]
    self.segments[..., 1] = h - self.segments[..., 1]
    if self.keypoints is not None:
        self.keypoints[..., 1] = h - self.keypoints[..., 1]

def normalize(self, w, h):
    """Normalize bounding boxes, segments, and keypoints to image dimensions."""
    if self.normalized:
        return
    self._bboxes.mul(scale=(1 / w, 1 / h, 1 / w, 1 / h))
    self.segments[..., 0] /= w
    self.segments[..., 1] /= h
    if self.keypoints is not None:
        self.keypoints[..., 0] /= w
        self.keypoints[..., 1] /= h
    self.normalized = True

def remove_zero_area_boxes(self):
    """Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height."""
    good = self.bbox_areas > 0
    if not all(good):
        self._bboxes = self._bboxes[good]
        if len(self.segments):
            self.segments = self.segments[good]
        if self.keypoints is not None:
            self.keypoints = self.keypoints[good]
    return good

def scale(self, scale_w, scale_h, bbox_only=False):
    """Similar to denormalize func but without normalized sign."""
    self._bboxes.mul(scale=(scale_w, scale_h, scale_w, scale_h))
    if bbox_only:
        return
    self.segments[..., 0] *= scale_w
    self.segments[..., 1] *= scale_h
    if self.keypoints is not None:
        self.keypoints[..., 0] *= scale_w
        self.keypoints[..., 1] *= scale_h

def update(self, bboxes, segments=None, keypoints=None):
    """Updates instance variables."""
    self._bboxes = Bboxes(bboxes, format=self._bboxes.format)
    if segments is not None:
        self.segments = segments
    if keypoints is not None:
        self.keypoints = keypoints