instance.py
ultralytics\utils\instance.py
目录
1.所需的库和模块
# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
from collections import abc
from itertools import repeat
from numbers import Number
from typing import List
import numpy as np
from .ops import ltwh2xywh, ltwh2xyxy, resample_segments, xywh2ltwh, xywh2xyxy, xyxy2ltwh, xyxy2xywh2.def _ntuple(n):
# 这段代码定义了一个函数 _ntuple ，它返回一个内部函数 parse ，用于将输入值转换为长度为 n 的元组。如果输入值已经是一个可迭代对象（如列表、元组等），则直接返回该对象；否则，将输入值重复 n 次生成元组。这种设计模式在 PyTorch 的内部实现中经常被用来处理参数的标准化。
# 定义了一个函数 _ntuple ，接收一个参数。
# 1.n ：目标元组的长度。
def _ntuple(n):
# 来自 PyTorch 内部。
"""From PyTorch internals."""
# 在 _ntuple 函数内部定义了一个嵌套函数 parse ，用于实际执行转换逻辑。
# parse 接收一个参数。
# 1.x ：需要被转换的输入值。
def parse(x):
# 解析 XYWH 和 LTWH 之间的边界框格式。
"""Parse bounding boxes format between XYWH and LTWH."""
# abc.Iterable
# abc.Iterable 是 Python 中 collections.abc 模块定义的一个抽象基类（Abstract Base Class, ABC），用于检查一个对象是否是可迭代的。可迭代对象是指可以被迭代器遍历的对象，例如列表、元组、字典、集合等。
# 定义 ：
# abc.Iterable 是一个抽象基类，它定义了可迭代对象的接口。一个对象如果实现了 __iter__() 方法或者 __getitem__() 方法（并且可以接受从零开始的整数索引），则被认为是可迭代的。
# 用途 ：
# 通过继承 abc.Iterable ，可以确保一个类的对象是可迭代的。此外，可以使用 isinstance() 函数来检查一个对象是否是可迭代的，例如 isinstance(obj, abc.Iterable) 。
# abc.Iterable 是一个非常有用的抽象基类，它提供了一种标准的方式来定义和检查可迭代对象。通过继承 abc.Iterable 或使用 isinstance() 函数，可以确保对象具有可迭代的特性，从而在需要迭代的场景中使用这些对象。
# 这是 parse 函数的核心逻辑。
# 如果输入 x 是一个可迭代对象（如列表、元组等），则直接返回 x 。
# 如果输入 x 不是可迭代对象（如整数、浮点数等），则使用 repeat(x, n) 生成一个长度为 n 的迭代器，并将其转换为元组。
# repeat(x, n) 是 itertools 模块中的一个函数，用于重复某个值 n 次。
return x if isinstance(x, abc.Iterable) else tuple(repeat(x, n))
# _ntuple 函数返回内部定义的 parse 函数。这意味着 _ntuple(n) 的返回值是一个函数，可以用来将输入值转换为长度为 n 的元组。
return parse
# 示例 ：
# 示例 1 ：将单个值转换为元组。
# # 创建一个将输入值转换为长度为 2 的元组的函数
# to_tuple = _ntuple(2)
# # 测试
# print(to_tuple(5)) # 输出：(5, 5)
# print(to_tuple([1, 2])) # 输出：[1, 2]
# print(to_tuple((3, 4))) # 输出：(3, 4)
# 示例 2 ：将单个值转换为长度为 4 的元组。
# to_tuple = _ntuple(4)
# print(to_tuple(10)) # 输出：(10, 10, 10, 10)
# print(to_tuple([1, 2, 3, 4])) # 输出：[1, 2, 3, 4]
# 这段代码实现了一个通用的工具函数 _ntuple ，用于将输入值转换为长度为 n 的元组。它通过返回一个内部函数 parse 来实现这一功能。 parse 函数会检查输入值是否为可迭代对象。如果是可迭代对象，则直接返回该对象。如果不是可迭代对象，则将输入值重复 n 次生成元组。这种设计模式在处理参数标准化时非常有用，例如在定义卷积层时， kernel_size 、 stride 和 padding 等参数可能需要被转换为元组形式。
# 这段代码定义了两个函数 to_2tuple 和 to_4tuple ，并声明了一些与边界框格式相关的变量和模块导出内容。
# 使用之前定义的 _ntuple 函数，创建了两个转换函数。这些函数通常用于将标量值（如整数或浮点数）转换为元组形式，以满足某些函数或类的参数要求。
# 将输入值转换为长度为 2 的元组。
to_2tuple = _ntuple(2)
# 将输入值转换为长度为 4 的元组。
to_4tuple = _ntuple(4)
# `xyxy` means left top and right bottom
# `xywh` means center x, center y and width, height(YOLO format)
# `ltwh` means left top and width, height(COCO format)
# 定义了一个列表 _formats ，包含三种常见的边界框表示格式。
# xyxy ：表示为左上角坐标和右下角坐标（ [x1, y1, x2, y2] ），通常用于一些目标检测框架中。
# xywh ：表示为中心点坐标和宽高（ [x_center, y_center, width, height] ），这是 YOLO 格式。
# ltwh ：表示为左上角坐标和宽高（ [left, top, width, height] ），这是 COCO 格式。
# 这些格式在目标检测任务中非常常见，不同的数据集和模型可能使用不同的格式。
_formats = ["xyxy", "xywh", "ltwh"]
# 定义了模块的导出内容，指定当使用 from module_name import * 时，哪些类或函数会被导出。
# 在这个例子中，模块会导出两个类或对象 ： Bboxes 和 Instances 。
# Bboxes 是一个用于处理边界框的类。
# Instances 是一个用于处理目标检测实例的类。
# __all__ 的值是一个元组 (Bboxes, Instances) ，也可以是一个列表 [Bboxes, Instances] ，两者的效果相同。
__all__ = ("Bboxes", "Instances") # tuple or list
# 这段代码的主要功能包括。创建转换函数： to_2tuple 和 to_4tuple 用于将标量值转换为长度为 2 或 4 的元组。这些函数通常用于标准化参数，例如在定义卷积层时将标量参数转换为元组形式。定义边界框格式： _formats 列表定义了三种常见的边界框表示格式： xyxy 、 xywh 和 ltwh 。这些格式在目标检测任务中非常常见，不同的数据集和模型可能使用不同的格式。模块导出内容： __all__ 指定了模块导出的内容，确保在使用 from module_name import * 时，只有 Bboxes 和 Instances 会被导入。这种设计模式在编写库或框架时非常常见，有助于提高代码的可读性和可维护性。3.class Bboxes:
# 这段代码定义了一个名为 Bboxes 的类，用于处理边界框数据。它支持多种边界框格式（ xyxy 、 xywh 和 ltwh ），并提供了格式转换、面积计算、缩放、偏移等功能。
# 定义了一个名为 Bboxes 的类，用于处理边界框数据。
class Bboxes:
# 用于处理边界框的类。
# 该类支持各种边界框格式，如“xyxy”、“xywh”和“ltwh”。
# 边界框数据应以 numpy 数组的形式提供。
# 注意：
# 此类不处理边界框的规范化或非规范化。
"""
A class for handling bounding boxes.
The class supports various bounding box formats like 'xyxy', 'xywh', and 'ltwh'.
Bounding box data should be provided in numpy arrays.
Attributes:
bboxes (numpy.ndarray): The bounding boxes stored in a 2D numpy array.
format (str): The format of the bounding boxes ('xyxy', 'xywh', or 'ltwh').
Note:
This class does not handle normalization or denormalization of bounding boxes.
"""
# 这段代码是 Bboxes 类的初始化方法 __init__ 的定义，用于创建一个 Bboxes 对象，并初始化边界框数据及其格式。
# 定义了 Bboxes 类的初始化方法 __init__ ，接收两个参数。
# 1.bboxes ：边界框数据，应为一个 NumPy 数组。
# 2.format ：边界框的格式，默认值为 "xyxy" 。 支持的格式包括 ： "xyxy" 左上角坐标和右下角坐标 [x1, y1, x2, y2] 。 "xywh" 中心点坐标和宽高 [x_center, y_center, width, height] 。 "ltwh" 左上角坐标和宽高 [left, top, width, height] 。
def __init__(self, bboxes, format="xyxy") -> None:
# 使用指定格式的边界框数据初始化 Bboxes 类。
"""Initializes the Bboxes class with bounding box data in a specified format."""
# 断言边界框的格式必须是 _formats 列表中的一个。 _formats 是一个全局变量，定义了支持的边界框格式 ：["xyxy", "xywh", "ltwh"] 。 如果 format 不在 _formats 中，抛出错误，提示无效的边界框格式。
assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}" # 边界框格式无效：{format}，格式必须是 {_formats} 之一。
# 如果输入的 bboxes 是一维数组（即只包含一个边界框），则将其扩展为二维数组。 bboxes[None, :] 在数组前面增加一个维度，将一维数组变为二维数组。
# 例如，如果 bboxes 是 [1, 2, 3, 4] ，则变为 [[1, 2, 3, 4]] 。
# 如果 bboxes 已经是二维数组，则直接使用。
bboxes = bboxes[None, :] if bboxes.ndim == 1 else bboxes
# 断言 bboxes 必须是二维数组。 二维数组的每一行表示一个边界框的 4 个坐标值。
assert bboxes.ndim == 2
# 断言 bboxes 的第二维大小必须为 4，即每个边界框必须有 4 个坐标值。 这确保了输入的边界框数据格式正确。
assert bboxes.shape[1] == 4
# 将 边界框数据 存储到类的属性 bboxes 中。
self.bboxes = bboxes
# 将 边界框的格式 存储到类的属性 format 中。
self.format = format
# 这行代码被注释掉了，可能是用于标记边界框是否已经归一化。 如果需要支持归一化功能，可以取消注释并实现相关逻辑。
# self.normalized = normalized
# 这段代码实现了 Bboxes 类的初始化方法 __init__ ，主要功能包括。验证边界框格式：确保输入的边界框格式是支持的格式之一（ xyxy 、 xywh 或 ltwh ）。处理输入数据：如果输入是一维数组（单个边界框），将其扩展为二维数组。确保输入数据是二维数组，并且每行有 4 个坐标值。存储边界框数据和格式：将边界框数据和格式分别存储到类的属性 bboxes 和 format 中。通过这种方式， Bboxes 类可以灵活地处理不同格式的边界框数据，并为后续的操作（如格式转换、面积计算等）提供基础。
# 这段代码定义了 Bboxes 类中的 convert 方法，用于将边界框的格式从当前格式转换为指定的目标格式。
# 定义了 convert 方法，接收一个参数。
# 1.format ：目标边界框格式。
def convert(self, format):
# 将边界框格式从一种类型转换为另一种类型。
"""Converts bounding box format from one type to another."""
# 断言目标格式必须是 _formats 列表中的一个（ xyxy 、 xywh 或 ltwh ）。 如果目标格式不在 _formats 中，抛出错误，提示无效的边界框格式。
assert format in _formats, f"Invalid bounding box format: {format}, format must be one of {_formats}" # 边界框格式无效：{format}，格式必须是 {_formats} 之一。
# 如果当前格式与目标格式相同，则直接返回，无需进行转换。
if self.format == format:
return
# 如果当前格式为 xyxy ，根据目标格式选择相应的转换函数。 如果目标格式为 xywh ，则使用 xyxy2xywh 函数。 如果目标格式为 ltwh ，则使用 xyxy2ltwh 函数。
elif self.format == "xyxy":
func = xyxy2xywh if format == "xywh" else xyxy2ltwh
# 如果当前格式为 xywh ，根据目标格式选择相应的转换函数。 如果目标格式为 xyxy ，则使用 xywh2xyxy 函数。 如果目标格式为 ltwh ，则使用 xywh2ltwh 函数。
elif self.format == "xywh":
func = xywh2xyxy if format == "xyxy" else xywh2ltwh
# 如果当前格式为 ltwh ，根据目标格式选择相应的转换函数。 如果目标格式为 xyxy ，则使用 ltwh2xyxy 函数。 如果目标格式为 xywh ，则使用 ltwh2xywh 函数。
else:
func = ltwh2xyxy if format == "xyxy" else ltwh2xywh
# 使用选定的转换函数对边界框数据进行转换。 将转换后的边界框数据存储回 self.bboxes 。
self.bboxes = func(self.bboxes)
# 更新边界框的格式属性为新的目标格式。
self.format = format
# 这段代码实现了 Bboxes 类中的 convert 方法，用于将边界框的格式从当前格式转换为指定的目标格式。具体步骤如下。验证目标格式：确保目标格式是支持的格式之一（ xyxy 、 xywh 或 ltwh ）。检查是否需要转换：如果当前格式与目标格式相同，则直接返回。选择转换函数：根据当前格式和目标格式，选择相应的转换函数。执行转换：使用选定的转换函数对边界框数据进行转换。更新格式属性：将边界框的格式属性更新为目标格式。这种方法使得 Bboxes 类能够灵活地处理不同格式的边界框数据，并在需要时进行格式转换。这对于目标检测任务中的数据预处理和后处理非常有用。
# 这段代码定义了 Bboxes 类中的 areas 方法，用于计算边界框的面积。根据边界框的格式不同，计算面积的方式也不同。
# 定义了 areas 方法，用于计算边界框的面积。该方法不接收额外参数，直接使用类的属性 bboxes 和 format 。
def areas(self):
# 返回边界框区域。
"""Return box areas."""
# 计算面积的逻辑。
return (
# 如果边界框的格式是 xyxy （左上角坐标和右下角坐标 [x1, y1, x2, y2] ）。
# 面积公式为 (x2 - x1) * (y2 - y1) 。
# self.bboxes[:, 2] - self.bboxes[:, 0] 计算宽度（ x2 - x1 ）。
# self.bboxes[:, 3] - self.bboxes[:, 1] 计算高度（ y2 - y1 ）。
# 两者相乘得到面积。
(self.bboxes[:, 2] - self.bboxes[:, 0]) * (self.bboxes[:, 3] - self.bboxes[:, 1]) # format xyxy
if self.format == "xyxy"
# 如果边界框的格式是 xywh 或 ltwh （中心点坐标和宽高 [x_center, y_center, width, height] 或左上角坐标和宽高 [left, top, width, height] ）。
# 面积公式为 width * height 。
# self.bboxes[:, 2] 表示宽度， self.bboxes[:, 3] 表示高度。
# 两者相乘得到面积。
else self.bboxes[:, 3] * self.bboxes[:, 2] # format xywh or ltwh
)
# 这段代码实现了 Bboxes 类中的 areas 方法，用于计算边界框的面积。具体步骤如下。判断边界框格式：如果格式为 xyxy ，使用 (x2 - x1) * (y2 - y1) 计算面积。如果格式为 xywh 或 ltwh ，使用 width * height 计算面积。返回面积：返回一个 NumPy 数组，包含每个边界框的面积。这种方法使得 Bboxes 类能够根据不同的边界框格式灵活地计算面积，适用于目标检测任务中的各种场景。
# def denormalize(self, w, h):
# if not self.normalized:
# return
# assert (self.bboxes <= 1.0).all()
# self.bboxes[:, 0::2] *= w
# self.bboxes[:, 1::2] *= h
# self.normalized = False
#
# def normalize(self, w, h):
# if self.normalized:
# return
# assert (self.bboxes > 1.0).any()
# self.bboxes[:, 0::2] /= w
# self.bboxes[:, 1::2] /= h
# self.normalized = True
# 这段代码定义了 Bboxes 类中的 mul 方法，用于将边界框的坐标乘以一个缩放因子。
# 定义了 mul 方法，接收一个参数。
# 1.scale ：缩放因子。
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.
"""
# 如果 scale 是一个标量（即 Number 类型，如整数或浮点数）。
if isinstance(scale, Number):
# 则将其转换为长度为 4 的元组。 to_4tuple 是一个函数，将标量重复 4 次生成元组。例如，如果 scale = 2 ，则 to_4tuple(2) 返回 (2, 2, 2, 2) 。 这样可以确保每个坐标（ x1, y1, x2, y2 或 x_center, y_center, width, height ）都能应用相同的缩放因子。
scale = to_4tuple(scale)
# 断言 scale 必须是一个元组或列表。 如果 scale 不是元组或列表，则抛出错误。
assert isinstance(scale, (tuple, list))
# 断言 scale 的长度必须为 4。 如果 scale 的长度不是 4，则抛出错误。 这确保了每个边界框的 4 个坐标都能分别应用一个缩放因子。
assert len(scale) == 4
# 将边界框的每个坐标分别乘以对应的缩放因子。
# 第一个坐标（如 x1 或 x_center ）乘以 scale[0] 。
self.bboxes[:, 0] *= scale[0]
# 第二个坐标（如 y1 或 y_center ）乘以 scale[1] 。
self.bboxes[:, 1] *= scale[1]
# 第三个坐标（如 x2 或 width ）乘以 scale[2] 。
self.bboxes[:, 2] *= scale[2]
# 第四个坐标（如 y2 或 height ）乘以 scale[3] 。
self.bboxes[:, 3] *= scale[3]
# 这段代码实现了 Bboxes 类中的 mul 方法，用于将边界框的坐标乘以一个缩放因子。具体步骤如下。处理缩放因子：如果 scale 是一个标量，则将其转换为长度为 4 的元组。确保 scale 是一个长度为 4 的元组或列表。应用缩放：将边界框的每个坐标分别乘以对应的缩放因子。这种方法使得 Bboxes 类能够灵活地对边界框的坐标进行缩放，适用于目标检测任务中的数据增强和预处理。例如，在图像缩放时，边界框的坐标也需要相应地进行缩放。
# 这段代码定义了 Bboxes 类中的 add 方法，用于将边界框的坐标加上一个偏移量。
# 定义了 add 方法，接收一个参数。
# 1.offset ：偏移量。
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.
"""
# 如果 offset 是一个标量（即 Number 类型，如整数或浮点数）。
if isinstance(offset, Number):
# 则将其转换为长度为 4 的元组。 to_4tuple 是一个函数，将标量重复 4 次生成元组。例如，如果 offset = 2 ，则 to_4tuple(2) 返回 (2, 2, 2, 2) 。 这样可以确保每个坐标（ x1, y1, x2, y2 或 x_center, y_center, width, height ）都能应用相同的偏移量。
offset = to_4tuple(offset)
# 断言 offset 必须是一个元组或列表。 如果 offset 不是元组或列表，则抛出错误。
assert isinstance(offset, (tuple, list))
# 断言 offset 的长度必须为 4。 如果 offset 的长度不是 4，则抛出错误。 这确保了每个边界框的 4 个坐标都能分别应用一个偏移量。
assert len(offset) == 4
# 将边界框的每个坐标分别加上对应的偏移量。
# 第一个坐标（如 x1 或 x_center ）加上 offset[0] 。
self.bboxes[:, 0] += offset[0]
# 第二个坐标（如 y1 或 y_center ）加上 offset[1] 。
self.bboxes[:, 1] += offset[1]
# 第三个坐标（如 x2 或 width ）加上 offset[2] 。
self.bboxes[:, 2] += offset[2]
# 第四个坐标（如 y2 或 height ）加上 offset[3] 。
self.bboxes[:, 3] += offset[3]
# 这段代码实现了 Bboxes 类中的 add 方法，用于将边界框的坐标加上一个偏移量。具体步骤如下。处理偏移量：如果 offset 是一个标量，则将其转换为长度为 4 的元组。确保 offset 是一个长度为 4 的元组或列表。应用偏移：将边界框的每个坐标分别加上对应的偏移量。这种方法使得 Bboxes 类能够灵活地对边界框的坐标进行平移，适用于目标检测任务中的数据增强和预处理。例如，在图像平移时，边界框的坐标也需要相应地进行平移。
# 这段代码定义了 Bboxes 类中的 __len__ 方法，用于返回边界框的数量。
# 定义了 __len__ 方法。这是一个特殊方法，用于实现 Python 的内置函数 len() 。 当调用 len(instance) 时，Python 会自动调用该实例的 __len__ 方法。
def __len__(self):
# 返回边界框的数量。
"""Return the number of boxes."""
# 返回 self.bboxes 的长度，即边界框数组的行数。 self.bboxes 是一个二维 NumPy 数组，其中每一行表示一个边界框的 4 个坐标值。 len(self.bboxes) 返回数组的行数，即边界框的数量。
return len(self.bboxes)
# 这段代码实现了 Bboxes 类中的 __len__ 方法，用于返回边界框的数量。具体步骤如下。调用 len() 函数：当使用 len(instance) 时，Python 会自动调用 instance.__len__() 。返回边界框数量：通过 len(self.bboxes) 返回边界框数组的行数，即边界框的数量。这种方法使得 Bboxes 类的实例可以像普通 Python 容器一样使用 len() 函数来获取边界框的数量，从而提高了类的易用性和一致性。
# 这段代码定义了 Bboxes 类中的一个类方法 concatenate ，用于将多个 Bboxes 对象拼接成一个新的 Bboxes 对象。
# @classmethod
# 在Python中， @classmethod 是一个装饰器，用于将一个普通的方法转换为类方法。类方法的第一个参数总是 cls ，它代表类本身，而不是类的实例。这意味着你可以在不创建类实例的情况下调用这个方法，并且可以在这个方法内部访问类的属性和方法。
# 类方法通常用于不需要类实例就可以执行的操作，例如 ：
# 创建类实例时不依赖于类的状态。
# 需要访问类属性而不是实例属性。
# 实现备选构造器（alternative constructors）。
# 类方法可以被子类继承，并且可以被子类的实例和子类本身调用。
@classmethod
# 使用 @classmethod 装饰器定义了一个类方法 concatenate 。 方法接收两个参数。
# 1.boxes_list ：一个包含多个 Bboxes 对象的列表或元组。
# 2.axis ：拼接的轴，默认值为 0 ，表示沿第一个轴（行）拼接。
# 方法返回一个新的 Bboxes 对象。
def concatenate(cls, boxes_list: List["Bboxes"], axis=0) -> "Bboxes":
# 将 Bboxes 对象列表连接成单个 Bboxes 对象。
# 注意：
# 输入应为 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.
"""
# 断言 boxes_list 必须是一个列表或元组。 如果 boxes_list 不是列表或元组，则抛出错误。
assert isinstance(boxes_list, (list, tuple))
# 如果 boxes_list 为空（即没有提供任何 Bboxes 对象），则返回一个空的 Bboxes 对象。 使用 np.empty(0) 创建一个空的 NumPy 数组，并通过 cls 构造函数创建一个空的 Bboxes 对象。
if not boxes_list:
return cls(np.empty(0))
# 断言 boxes_list 中的所有元素都必须是 Bboxes 类的实例。 使用 all() 和生成器表达式检查每个元素是否为 Bboxes 类型。 如果有任何元素不是 Bboxes 类型，则抛出错误。
assert all(isinstance(box, Bboxes) for box in boxes_list)
# 如果 boxes_list 中只有一个 Bboxes 对象。
if len(boxes_list) == 1:
# 则直接返回该对象，无需拼接。
return boxes_list[0]
# 如果 boxes_list 中有多个 Bboxes 对象，则将它们的边界框数据拼接成一个新的 NumPy 数组。
# 使用列表推导式 [b.bboxes for b in boxes_list] 提取每个 Bboxes 对象的 bboxes 属性。
# 使用 np.concatenate 沿指定轴拼接这些数组。
# 使用 cls 构造函数将拼接后的数组包装成一个新的 Bboxes 对象并返回。
return cls(np.concatenate([b.bboxes for b in boxes_list], axis=axis))
# 这段代码实现了 Bboxes 类中的 concatenate 类方法，用于将多个 Bboxes 对象拼接成一个新的 Bboxes 对象。具体步骤如下。验证输入：确保 boxes_list 是一个列表或元组。确保 boxes_list 中的所有元素都是 Bboxes 类的实例。处理特殊情况：如果 boxes_list 为空，返回一个空的 Bboxes 对象。如果 boxes_list 中只有一个 Bboxes 对象，直接返回该对象。拼接边界框数据：提取每个 Bboxes 对象的 bboxes 属性。使用 np.concatenate 沿指定轴拼接这些数组。返回新的 Bboxes 对象：使用 cls 构造函数将拼接后的数组包装成一个新的 Bboxes 对象并返回。这种方法使得 Bboxes 类能够灵活地处理多个边界框对象的拼接操作，适用于目标检测任务中的数据处理和合并。
# 这段代码定义了 Bboxes 类中的 __getitem__ 方法，用于通过索引访问边界框数据。 __getitem__ 是一个特殊方法，允许类的实例支持索引操作（如 instance[index] ）。
# 定义了 __getitem__ 方法，接收一个参数。
# 1.index ：索引。
# 方法返回一个新的 Bboxes 对象，包含索引指定的边界框数据。
def __getitem__(self, index) -> "Bboxes":
# 使用索引检索特定边界框或一组边界框。
# 引发：
# AssertionError：如果索引的边界框不形成二维矩阵。
# 注意：
# 使用布尔索引时，请确保提供长度与边界框数量相同的布尔数组。
"""
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.
"""
# 如果 index 是一个整数。
if isinstance(index, int):
# 使用 self.bboxes[index] 提取单个边界框。 由于单个边界框是一维数组，需要将其重新塑形为二维数组（ reshape(1, -1) ），以便保持与类的内部表示一致。 使用 Bboxes 构造函数创建一个新的 Bboxes 对象，包含单个边界框数据。
return Bboxes(self.bboxes[index].reshape(1, -1))
# 如果 index 不是整数（可能是切片、布尔数组或其他索引方式），使用 self.bboxes[index] 提取边界框数据。
b = self.bboxes[index]
# 断言提取的结果 b 必须是二维数组。 如果 b 不是二维数组，则抛出错误，提示索引操作失败。
assert b.ndim == 2, f"Indexing on Bboxes with {index} failed to return a matrix!" # 使用 {index} 对 Bboxes 进行索引无法返回矩阵！
# 使用 Bboxes 构造函数创建一个新的 Bboxes 对象，包含提取的边界框数据。
return Bboxes(b)
# 这段代码实现了 Bboxes 类中的 __getitem__ 方法，用于通过索引访问边界框数据。具体步骤如下。处理整数索引：如果 index 是整数，提取单个边界框并将其重新塑形为二维数组。返回一个新的 Bboxes 对象，包含单个边界框数据。处理其他索引方式：如果 index 不是整数，提取边界框数据。确保提取的结果是二维数组。返回一个新的 Bboxes 对象，包含提取的边界框数据。这种方法使得 Bboxes 类的实例可以像普通 Python 容器一样使用索引操作来访问边界框数据，从而提高了类的易用性和灵活性。
# Bboxes 类是一个用于处理边界框数据的工具类，支持多种常见的边界框格式（如 xyxy 、 xywh 和 ltwh ）。它提供了丰富的功能，包括边界框格式的转换、面积计算、坐标缩放与平移，以及多个边界框对象的拼接。此外，通过实现 __len__ 和 __getitem__ 等特殊方法， Bboxes 类能够像普通容器一样使用，方便用户进行边界框数据的操作和管理。该类的设计注重灵活性和易用性，适用于目标检测任务中的数据预处理、后处理以及数据增强等场景。4.class Instances:
# 这段代码定义了一个名为 Instances 的类，用于封装和处理目标检测中的边界框、分割掩码和关键点信息。
# 定义了一个名为 Instances 的类。
class Instances:
# 用于图像中检测到的对象的边界框、片段和关键点的容器。
# 注意：
# 边界框格式为“xywh”或“xyxy”，由“bbox_format”参数决定。
# 此类不执行输入验证，并假定输入格式正确。
"""
Container for bounding boxes, segments, and keypoints of detected objects in an image.
Attributes:
_bboxes (Bboxes): Internal object for handling bounding box operations.
keypoints (ndarray): keypoints(x, y, visible) with shape [N, 17, 3]. Default is None.
normalized (bool): Flag indicating whether the bounding box coordinates are normalized.
segments (ndarray): Segments array with shape [N, 1000, 2] after resampling.
Args:
bboxes (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.
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 类的初始化方法 __init__ ，用于创建一个 Instances 对象，并初始化边界框、分割掩码和关键点等属性。
# 定义了 Instances 类的初始化方法 __init__ ，接收以下参数 ：
# 1.bboxes ：边界框数组，形状为 [N, 4] ，表示 N 个边界框的坐标。
# 2.segments ：分割掩码，可以是列表或数组，形状为 [N, M, 2] ，其中 M 是分割掩码的点数，默认为 None 。
# 3.keypoints ：关键点数组，形状为 [N, 17, 3] ，表示 N 个对象的 17 个关键点的 (x, y, visible) 坐标，默认为 None 。
# 4.bbox_format ：边界框的格式，可以是 'xywh' （中心点坐标和宽高）或 'xyxy' （左上角和右下角坐标），默认为 'xywh' 。
# 5.normalized ：布尔值，表示边界框坐标是否已归一化，默认为 True 。
def __init__(self, bboxes, segments=None, keypoints=None, bbox_format="xywh", normalized=True) -> None:
# 使用边界框、线段和关键点初始化对象。
# 参数：
# bboxes (np.ndarray)：边界框，形状为 [N, 4]。
# keypoints (np.ndarray，可选)：关键点，形状为 [N, 17, 3] 且格式为 (x, y, visible)。默认为 None。
"""
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 类创建一个内部对象 _bboxes ，用于处理边界框操作。 将输入的 边界框数据 bboxes 和 格式 bbox_format 传递给 Bboxes 类的构造函数。
self._bboxes = Bboxes(bboxes=bboxes, format=bbox_format)
# 将关键点数组 keypoints 存储到类的属性 keypoints 中。 如果 keypoints 为 None ，则表示没有关键点数据。
self.keypoints = keypoints
# 将归一化标志 normalized 存储到类的属性 normalized 中。 该标志表示边界框坐标是否已经归一化到 [0, 1] 范围内。
self.normalized = normalized
# 将分割掩码 segments 存储到类的属性 segments 中。 如果 segments 为 None ，则表示没有分割掩码数据。
self.segments = segments
# 这段代码实现了 Instances 类的初始化方法 __init__ ，用于创建一个 Instances 对象，并初始化以下属性。边界框：使用 Bboxes 类封装边界框数据，支持多种格式（ xywh 或 xyxy ）。关键点：存储关键点数据，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标。分割掩码：存储分割掩码数据，形状为 [N, M, 2] ，表示每个对象的分割掩码的点坐标。归一化标志：存储一个布尔值，表示边界框坐标是否已经归一化。通过这种方式， Instances 类能够灵活地处理目标检测中的边界框、分割掩码和关键点数据，适用于多种目标检测任务和数据预处理场景。
# 这段代码定义了 Instances 类中的 convert_bbox 方法，用于将边界框的格式从当前格式转换为指定的目标格式。
# 定义了 convert_bbox 方法，接收一个参数。
# 1.format ：目标边界框格式。 format 的值可以是 'xyxy' 或 'xywh' ，表示边界框的表示方式 ： xyxy 左上角坐标和右下角坐标 [x1, y1, x2, y2] 。 xywh 中心点坐标和宽高 [x_center, y_center, width, height] 。
def convert_bbox(self, format):
# 转换边界框格式。
"""Convert bounding box format."""
# 调用 _bboxes 对象的 convert 方法，将边界框的格式从当前格式转换为指定的目标格式。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。
# convert 方法会根据当前格式和目标格式，选择合适的转换函数（如 xyxy2xywh 或 xywh2xyxy ）来完成转换。
# 转换后的边界框数据会存储在 _bboxes 对象中，并且 _bboxes 的 format 属性会被更新为目标格式。
self._bboxes.convert(format=format)
# 这段代码实现了 Instances 类中的 convert_bbox 方法，用于将边界框的格式从当前格式转换为指定的目标格式。具体步骤如下。接收目标格式：通过参数 format 指定目标边界框格式。调用 _bboxes 的 convert 方法：将边界框的格式从当前格式转换为指定的目标格式。更新 _bboxes 的格式属性：转换后的边界框数据存储在 _bboxes 中，并且格式属性被更新为目标格式。这种方法使得 Instances 类能够灵活地处理边界框格式的转换，适用于目标检测任务中的数据预处理和后处理阶段。
# 这段代码定义了 Instances 类中的一个属性 bbox_areas ，用于计算并返回边界框的面积。
@property
# 使用 @property 装饰器定义了一个只读属性 bbox_areas 。这使得 bbox_areas 可以像普通属性一样被访问，而无需显式调用方法。
def bbox_areas(self):
# 计算边界框的面积。
"""Calculate the area of bounding boxes."""
# 调用 _bboxes 对象的 areas 方法，计算并返回边界框的面积。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。
# areas 方法会根据边界框的格式（ xyxy 或 xywh ）计算每个边界框的面积。
return self._bboxes.areas()
# 这段代码实现了 Instances 类中的 bbox_areas 属性，用于计算并返回边界框的面积。具体步骤如下。定义只读属性：使用 @property 装饰器定义了一个只读属性 bbox_areas 。调用 _bboxes 的 areas 方法：通过 _bboxes 对象的 areas 方法计算边界框的面积。返回面积：返回计算得到的边界框面积。这种方法使得 Instances 类能够方便地访问边界框的面积，而无需显式调用方法。这在目标检测任务中非常有用，例如在计算损失函数或评估指标时需要使用边界框的面积。
# 这段代码定义了 Instances 类中的 scale 方法，用于对边界框、分割掩码和关键点进行缩放。
# 定义了 scale 方法，接收以下参数 ：
# 1.scale_w ：宽度方向的缩放因子。
# 2.scale_h ：高度方向的缩放因子。
# 3.bbox_only ：布尔值，表示是否只对边界框进行缩放，默认为 False 。
def scale(self, scale_w, scale_h, bbox_only=False):
# 类似于反规范化函数，但没有规范化符号。
"""Similar to denormalize func but without normalized sign."""
# 调用 _bboxes 对象的 mul 方法，对边界框的坐标进行缩放。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。 mul 方法会将边界框的每个坐标分别乘以对应的缩放因子。 x1 和 x2 （或 width ）乘以 scale_w 。 y1 和 y2 （或 height ）乘以 scale_h 。
self._bboxes.mul(scale=(scale_w, scale_h, scale_w, scale_h))
# 如果 bbox_only 为 True ，则只对边界框进行缩放，不处理分割掩码和关键点。 如果 bbox_only 为 False ，则继续对分割掩码和关键点进行缩放。
if bbox_only:
return
# 对分割掩码的 x 坐标乘以 scale_w ，对 y 坐标乘以 scale_h 。 self.segments 是一个数组，形状为 [N, M, 2] ，其中 M 是分割掩码的点数。 使用 ... 表示对所有边界框的分割掩码进行操作。
self.segments[..., 0] *= scale_w
self.segments[..., 1] *= scale_h
# 如果存在关键点数据。
if self.keypoints is not None:
# 在 Python 中，尤其是在处理多维数组（如 NumPy 数组）时， ... （ellipsis）是一个特殊的语法，用于表示“所有中间维度”。它可以帮助我们简化代码，尤其是在对多维数组的特定维度进行操作时。理解这一点后，就可以清楚地解释为什么使用 self.keypoints[..., 0] 而不是 self.keypoints[..., ..., 0] 。
# 关键点数组的结构 ：
# 假设 self.keypoints 是一个形状为 [N, 17, 3] 的数组 ：
# N ：表示边界框的数量。
# 17 ：表示每个边界框有 17 个关键点。
# 3 ：表示每个关键点有 3 个值，分别是 x 坐标、 y 坐标和可见性标志。
# 使用 ... 的原因 ：
# self.keypoints[..., 0]
# ... 表示“所有中间维度”。在这种情况下， ... 会自动展开为 [:, :] ，表示对所有边界框和所有关键点进行操作。
# 0 表示最后一个维度的第一个值，即 x 坐标。
# 因此， self.keypoints[..., 0] 表示选择所有边界框的所有关键点的 x 坐标。
# self.keypoints[..., ..., 0]
# 这种写法是多余的，因为 ... 已经表示了“所有中间维度”，再加一个 ... 是不必要的。
# 在 NumPy 中， ... 通常用于简化索引，避免显式地写出所有中间维度。如果写成 self.keypoints[..., ..., 0] ，虽然不会报错，但它是冗余的，没有实际意义。
# 总结 ：
# 使用 self.keypoints[..., 0] 而不是 self.keypoints[..., ..., 0] 的原因是 ：
# ... 已经表示了“所有中间维度”，再加一个 ... 是多余的。
# self.keypoints[..., 0] 是更简洁和标准的写法，能够清晰地表示对所有边界框的所有关键点的 x 坐标进行操作。
# 这种写法在处理多维数组时非常常见，能够提高代码的可读性和简洁性。
# 则对关键点的 x 坐标乘以 scale_w ，对 y 坐标乘以 scale_h 。 self.keypoints 是一个数组，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标。 使用 ... 表示对所有边界框的关键点进行操作。
self.keypoints[..., 0] *= scale_w
self.keypoints[..., 1] *= scale_h
# 这段代码实现了 Instances 类中的 scale 方法，用于对边界框、分割掩码和关键点进行缩放。具体步骤如下。缩放边界框：调用 _bboxes 的 mul 方法，对边界框的坐标进行缩放。检查是否只缩放边界框：如果 bbox_only 为 True ，则直接返回。缩放分割掩码：对分割掩码的 x 和 y 坐标分别乘以 scale_w 和 scale_h 。缩放关键点：如果存在关键点数据，则对关键点的 x 和 y 坐标分别乘以 scale_w 和 scale_h 。这种方法使得 Instances 类能够灵活地对边界框、分割掩码和关键点进行缩放，适用于目标检测任务中的数据预处理和增强。例如，在图像缩放时，需要对这些几何信息进行相应的缩放，以保持其与图像的比例关系。
# 这段代码定义了 Instances 类中的 denormalize 方法，用于将边界框、分割掩码和关键点从归一化坐标转换为绝对坐标。
# 定义了 denormalize 方法，接收两个参数。
# 1.w ：图像的宽度。
# 2.h ：图像的高度。
def denormalize(self, w, h):
# 从标准化坐标中对框、段和关键点进行非标准化处理。
"""Denormalizes boxes, segments, and keypoints from normalized coordinates."""
# 检查 self.normalized 标志。如果边界框坐标已经未归一化（即 self.normalized 为 False ）。
if not self.normalized:
# 则直接返回，不执行任何操作。
return
# 调用 _bboxes 对象的 mul 方法，将边界框的坐标乘以图像的宽度和高度。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。 mul 方法会将边界框的每个坐标分别乘以对应的缩放因子。 x1 和 x2 （或 width ）乘以 w 。 y1 和 y2 （或 height ）乘以 h 。
self._bboxes.mul(scale=(w, h, w, h))
# 对分割掩码的 x 坐标乘以图像宽度 w ，对 y 坐标乘以图像高度 h 。 self.segments 是一个数组，形状为 [N, M, 2] ，其中 M 是分割掩码的点数。 使用 ... 表示对所有边界框的分割掩码进行操作。
self.segments[..., 0] *= w
self.segments[..., 1] *= h
# 如果存在关键点数据。
if self.keypoints is not None:
# 则对关键点的 x 坐标乘以图像宽度 w ，对 y 坐标乘以图像高度 h 。 self.keypoints 是一个数组，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标。 使用 ... 表示对所有边界框的关键点进行操作。
self.keypoints[..., 0] *= w
self.keypoints[..., 1] *= h
# 将 self.normalized 标志设置为 False ，表示边界框坐标已经转换为绝对坐标。
self.normalized = False
# 这段代码实现了 Instances 类中的 denormalize 方法，用于将边界框、分割掩码和关键点从归一化坐标转换为绝对坐标。具体步骤如下。检查是否需要去归一化：如果 self.normalized 为 False ，则直接返回，不执行任何操作。缩放边界框：调用 _bboxes 的 mul 方法，将边界框的坐标乘以图像的宽度和高度。缩放分割掩码：对分割掩码的 x 和 y 坐标分别乘以图像的宽度和高度。缩放关键点：如果存在关键点数据，则对关键点的 x 和 y 坐标分别乘以图像的宽度和高度。更新归一化标志：将 self.normalized 设置为 False ，表示坐标已经转换为绝对坐标。这种方法使得 Instances 类能够灵活地处理归一化和绝对坐标之间的转换，适用于目标检测任务中的数据预处理和后处理阶段。
# 这段代码定义了 Instances 类中的 normalize 方法，用于将边界框、分割掩码和关键点从绝对坐标转换为归一化坐标。
# 定义了 normalize 方法，接收两个参数。
# 1.w ：图像的宽度。
# 2.h ：图像的高度。
def normalize(self, w, h):
# 将边界框、线段和关键点标准化为图像尺寸。
"""Normalize bounding boxes, segments, and keypoints to image dimensions."""
# 检查 self.normalized 标志。如果边界框坐标已经归一化（即 self.normalized 为 True ）。
if self.normalized:
# 则直接返回，不执行任何操作。
return
# 调用 _bboxes 对象的 mul 方法，将边界框的坐标除以图像的宽度和高度。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。 mul 方法会将边界框的每个坐标分别乘以对应的缩放因子。 x1 和 x2 （或 width ）除以 w 。 y1 和 y2 （或 height ）除以 h 。
self._bboxes.mul(scale=(1 / w, 1 / h, 1 / w, 1 / h))
# 对分割掩码的 x 坐标除以图像宽度 w ，对 y 坐标除以图像高度 h 。 self.segments 是一个数组，形状为 [N, M, 2] ，其中 M 是分割掩码的点数。 使用 ... 表示对所有边界框的分割掩码进行操作。
self.segments[..., 0] /= w
self.segments[..., 1] /= h
# 如果存在关键点数据。
if self.keypoints is not None:
# 则对关键点的 x 坐标除以图像宽度 w ，对 y 坐标除以图像高度 h 。 self.keypoints 是一个数组，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标。 使用 ... 表示对所有边界框的关键点进行操作。
self.keypoints[..., 0] /= w
self.keypoints[..., 1] /= h
# 将 self.normalized 标志设置为 True ，表示边界框坐标已经转换为归一化坐标。
self.normalized = True
# 这段代码实现了 Instances 类中的 normalize 方法，用于将边界框、分割掩码和关键点从绝对坐标转换为归一化坐标。具体步骤如下。检查是否需要归一化：如果 self.normalized 为 True ，则直接返回，不执行任何操作。缩放边界框：调用 _bboxes 的 mul 方法，将边界框的坐标除以图像的宽度和高度。缩放分割掩码：对分割掩码的 x 和 y 坐标分别除以图像的宽度和高度。缩放关键点：如果存在关键点数据，则对关键点的 x 和 y 坐标分别除以图像的宽度和高度。更新归一化标志：将 self.normalized 设置为 True ，表示坐标已经转换为归一化坐标。这种方法使得 Instances 类能够灵活地处理归一化和绝对坐标之间的转换，适用于目标检测任务中的数据预处理和后处理阶段。归一化坐标通常用于模型输入，而绝对坐标则用于可视化和评估。
# 这段代码定义了 Instances 类中的 add_padding 方法，用于在边界框、分割掩码和关键点的坐标上添加填充偏移量。
# 定义了 add_padding 方法，接收两个参数。
# 1.padw ：宽度方向的填充偏移量。
# 2.padh ：高度方向的填充偏移量。
def add_padding(self, padw, padh):
# 处理矩形和马赛克情况。
"""Handle rect and mosaic situation."""
# 断言 self.normalized 为 False ，即边界框坐标必须是绝对坐标，而不是归一化坐标。 如果 self.normalized 为 True ，则抛出错误，提示应该在绝对坐标上添加填充偏移量。
assert not self.normalized, "you should add padding with absolute coordinates." # 您应该添加具有绝对坐标的填充。
# 调用 _bboxes 对象的 add 方法，对边界框的坐标加上填充偏移量。
# _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。 add 方法会将边界框的每个坐标分别加上对应的偏移量。 x1 和 x2 （或 width ）加上 padw 。 y1 和 y2 （或 height ）加上 padh 。
self._bboxes.add(offset=(padw, padh, padw, padh))
# 对分割掩码的 x 坐标加上宽度方向的填充偏移量 padw ，对 y 坐标加上高度方向的填充偏移量 padh 。 self.segments 是一个数组，形状为 [N, M, 2] ，其中 M 是分割掩码的点数。 使用 ... 表示对所有边界框的分割掩码进行操作。
self.segments[..., 0] += padw
self.segments[..., 1] += padh
# 如果存在关键点数据。
if self.keypoints is not None:
# 则对关键点的 x 坐标加上宽度方向的填充偏移量 padw ，对 y 坐标加上高度方向的填充偏移量 padh 。 self.keypoints 是一个数组，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标。 使用 ... 表示对所有边界框的关键点进行操作。
self.keypoints[..., 0] += padw
self.keypoints[..., 1] += padh
# 这段代码实现了 Instances 类中的 add_padding 方法，用于在边界框、分割掩码和关键点的坐标上添加填充偏移量。具体步骤如下。检查是否为绝对坐标：断言 self.normalized 为 False ，确保边界框坐标是绝对坐标。2. 添加边界框的偏移量：调用 _bboxes 的 add 方法，对边界框的坐标加上填充偏移量。添加分割掩码的偏移量：对分割掩码的 x 和 y 坐标分别加上宽度和高度方向的填充偏移量。添加关键点的偏移量：如果存在关键点数据，则对关键点的 x 和 y 坐标分别加上宽度和高度方向的填充偏移量。这种方法使得 Instances 类能够灵活地处理边界框、分割掩码和关键点的填充操作，适用于目标检测任务中的数据预处理阶段，尤其是在处理图像填充（如在使用 Mosaic 数据增强时）时非常有用。
# 这段代码定义了 Instances 类中的 __getitem__ 方法，用于通过索引访问特定的实例或一组实例。
# 定义了 __getitem__ 方法，接收一个参数。
# 1.index ：索引。
# 方法返回一个新的 Instances 对象，包含索引指定的边界框、分割掩码和关键点数据。
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.
"""
# 如果 self.segments 不为空，则使用 index 对 self.segments 进行索引，提取对应的分割掩码。 如果 self.segments 为空，则直接使用 self.segments （即保持为空）。
segments = self.segments[index] if len(self.segments) else self.segments
# 如果 self.keypoints 不为 None ，则使用 index 对 self.keypoints 进行索引，提取对应的关键点。 如果 self.keypoints 为 None ，则保持 keypoints 为 None 。
keypoints = self.keypoints[index] if self.keypoints is not None else None
# 使用 index 对 self.bboxes 进行索引，提取对应的边界框。
bboxes = self.bboxes[index]
# 获取 当前边界框的格式 ，存储在 bbox_format 中。
bbox_format = self._bboxes.format
# 使用提取的 边界框 、 分割掩码 、 关键点 、 边界框格式 和 归一化标志 ，创建一个新的 Instances 对象并返回。
return Instances(
bboxes=bboxes,
segments=segments,
keypoints=keypoints,
bbox_format=bbox_format,
normalized=self.normalized,
)
# 这段代码实现了 Instances 类中的 __getitem__ 方法，用于通过索引访问特定的实例或一组实例。具体步骤如下。提取分割掩码：如果 self.segments 不为空，则使用 index 提取对应的分割掩码。如果 self.segments 为空，则保持为空。提取关键点：如果 self.keypoints 不为 None ，则使用 index 提取对应的关键点。如果 self.keypoints 为 None ，则保持 keypoints 为 None 。提取边界框：使用 index 提取对应的边界框。获取边界框格式：获取当前边界框的格式。创建新的 Instances 对象：使用提取的数据和属性，创建一个新的 Instances 对象并返回。这种方法使得 Instances 类的实例可以像普通容器一样使用索引操作来访问特定的实例或一组实例，从而提高了类的易用性和灵活性。
# 这段代码定义了 Instances 类中的 flipud 方法，用于将边界框、分割掩码和关键点沿着图像的垂直轴（上下翻转）进行翻转。
# 定义了 flipud 方法，接收一个参数。
# 1.h ：图像的高度。
def flipud(self, h):
# 垂直翻转边界框、线段和关键点的坐标。
"""Flips the coordinates of bounding boxes, segments, and keypoints vertically."""
# 检查边界框的格式是否为 xyxy （左上角坐标和右下角坐标 [x1, y1, x2, y2] ）。
if self._bboxes.format == "xyxy":
# 如果边界框格式为 xyxy ，则提取 y1 和 y2 坐标，并将其复制到临时变量中。
# self.bboxes[:, 1] ：左上角的 y 坐标。
# self.bboxes[:, 3] ：右下角的 y 坐标。
y1 = self.bboxes[:, 1].copy()
y2 = self.bboxes[:, 3].copy()
# 对边界框的 y1 和 y2 坐标进行上下翻转。 新的 y1 坐标为 h - y2 。 新的 y2 坐标为 h - y1 。 这样可以实现上下翻转的效果。
self.bboxes[:, 1] = h - y2
self.bboxes[:, 3] = h - y1
# 如果边界框格式不是 xyxy （例如 xywh ，中心点坐标和宽高 [x_center, y_center, width, height] ），则直接对 y_center 坐标进行翻转。
else:
# 对边界框的 y_center 坐标进行上下翻转。 新的 y_center 坐标为 h - y_center 。
self.bboxes[:, 1] = h - self.bboxes[:, 1]
# 对分割掩码的 y 坐标进行上下翻转。 self.segments[..., 1] 表示所有分割掩码的 y 坐标。 将每个 y 坐标翻转为 h - y 。
self.segments[..., 1] = h - self.segments[..., 1]
# 如果存在关键点数据，则对关键点的 y 坐标进行上下翻转。
if self.keypoints is not None:
# 对关键点的 y 坐标进行上下翻转。 self.keypoints[..., 1] 表示所有关键点的 y 坐标。 将每个 y 坐标翻转为 h - y 。
self.keypoints[..., 1] = h - self.keypoints[..., 1]
# 这段代码实现了 Instances 类中的 flipud 方法，用于将边界框、分割掩码和关键点沿着图像的垂直轴进行上下翻转。具体步骤如下。检查边界框格式：如果边界框格式为 xyxy ，则对 y1 和 y2 坐标进行翻转。如果边界框格式为 xywh ，则对 y_center 坐标进行翻转。翻转分割掩码的 y 坐标：对所有分割掩码的 y 坐标进行翻转。翻转关键点的 y 坐标：如果存在关键点数据，则对所有关键点的 y 坐标进行翻转。这种方法使得 Instances 类能够灵活地处理边界框、分割掩码和关键点的上下翻转操作，适用于目标检测任务中的数据增强阶段。
# 这段代码定义了 Instances 类中的 fliplr 方法，用于将边界框、分割掩码和关键点沿着图像的水平轴（左右翻转）进行翻转。
# 定义了 fliplr 方法，接收一个参数。
# 1.w ：图像的宽度。
def fliplr(self, w):
# 水平反转边界框和线段的顺序。
"""Reverses the order of the bounding boxes and segments horizontally."""
# 检查边界框的格式是否为 xyxy （左上角坐标和右下角坐标 [x1, y1, x2, y2] ）。
if self._bboxes.format == "xyxy":
# 如果边界框格式为 xyxy ，则提取 x1 和 x2 坐标，并将其复制到临时变量中。
# self.bboxes[:, 0] ：左上角的 x 坐标。
# self.bboxes[:, 2] ：右下角的 x 坐标。
x1 = self.bboxes[:, 0].copy()
x2 = self.bboxes[:, 2].copy()
# 对边界框的 x1 和 x2 坐标进行左右翻转。 新的 x1 坐标为 w - x2 。 新的 x2 坐标为 w - x1 。 这样可以实现左右翻转的效果。
self.bboxes[:, 0] = w - x2
self.bboxes[:, 2] = w - x1
# 如果边界框格式不是 xyxy （例如 xywh ，中心点坐标和宽高 [x_center, y_center, width, height] ），则直接对 x_center 坐标进行翻转。
else:
# 对边界框的 x_center 坐标进行左右翻转。 新的 x_center 坐标为 w - x_center 。
self.bboxes[:, 0] = w - self.bboxes[:, 0]
# 对分割掩码的 x 坐标进行左右翻转。 self.segments[..., 0] 表示所有分割掩码的 x 坐标。 将每个 x 坐标翻转为 w - x 。
self.segments[..., 0] = w - self.segments[..., 0]
# 如果存在关键点数据，则对关键点的 x 坐标进行左右翻转。
if self.keypoints is not None:
# 对关键点的 x 坐标进行左右翻转。 self.keypoints[..., 0] 表示所有关键点的 x 坐标。 将每个 x 坐标翻转为 w - x 。
self.keypoints[..., 0] = w - self.keypoints[..., 0]
# 这段代码实现了 Instances 类中的 fliplr 方法，用于将边界框、分割掩码和关键点沿着图像的水平轴进行左右翻转。具体步骤如下。检查边界框格式：如果边界框格式为 xyxy ，则对 x1 和 x2 坐标进行翻转。如果边界框格式为 xywh ，则对 x_center 坐标进行翻转。翻转分割掩码的 x 坐标：对所有分割掩码的 x 坐标进行翻转。翻转关键点的 x 坐标：如果存在关键点数据，则对所有关键点的 x 坐标进行翻转。这种方法使得 Instances 类能够灵活地处理边界框、分割掩码和关键点的左右翻转操作，适用于目标检测任务中的数据增强阶段。
# 这段代码定义了 Instances 类中的 clip 方法，用于将边界框、分割掩码和关键点的坐标值限制在图像边界内。
# 定义了 clip 方法，接收两个参数。
# 1.w ：图像的宽度。
# 2.h ：图像的高度。
def clip(self, w, h):
# 裁剪边界框、线段和关键点值以保持在图像边界内。
"""Clips bounding boxes, segments, and keypoints values to stay within image boundaries."""
# 保存当前边界框的格式到变量 ori_format 中，以便在操作完成后恢复原始格式。
ori_format = self._bboxes.format
# 将边界框的格式转换为 xyxy （左上角坐标和右下角坐标 [x1, y1, x2, y2] ），因为 clip 操作在 xyxy 格式下更容易实现。
self.convert_bbox(format="xyxy")
# 对边界框的 x1 和 x2 坐标进行裁剪，确保它们在 [0, w] 范围内。 self.bboxes[:, [0, 2]] 表示所有边界框的 x1 和 x2 坐标。 使用 NumPy 的 clip 方法将这些坐标限制在 [0, w] 范围内。
self.bboxes[:, [0, 2]] = self.bboxes[:, [0, 2]].clip(0, w)
# 对边界框的 y1 和 y2 坐标进行裁剪，确保它们在 [0, h] 范围内。 self.bboxes[:, [1, 3]] 表示所有边界框的 y1 和 y2 坐标。 使用 NumPy 的 clip 方法将这些坐标限制在 [0, h] 范围内。
self.bboxes[:, [1, 3]] = self.bboxes[:, [1, 3]].clip(0, h)
# 如果原始边界框格式不是 xyxy ，则将边界框格式恢复为原始格式。
if ori_format != "xyxy":
self.convert_bbox(format=ori_format)
# 对分割掩码的 x 和 y 坐标进行裁剪，确保它们在 [0, w] 和 [0, h] 范围内。 self.segments[..., 0] 表示所有分割掩码的 x 坐标。 self.segments[..., 1] 表示所有分割掩码的 y 坐标。 使用 NumPy 的 clip 方法将这些坐标限制在 [0, w] 和 [0, h] 范围内。
self.segments[..., 0] = self.segments[..., 0].clip(0, w)
self.segments[..., 1] = self.segments[..., 1].clip(0, h)
# 如果存在关键点数据。
if self.keypoints is not None:
# 则对关键点的 x 和 y 坐标进行裁剪，确保它们在 [0, w] 和 [0, h] 范围内。 self.keypoints[..., 0] 表示所有关键点的 x 坐标。 self.keypoints[..., 1] 表示所有关键点的 y 坐标。 使用 NumPy 的 clip 方法将这些坐标限制在 [0, w] 和 [0, h] 范围内。
self.keypoints[..., 0] = self.keypoints[..., 0].clip(0, w)
self.keypoints[..., 1] = self.keypoints[..., 1].clip(0, h)
# 这段代码实现了 Instances 类中的 clip 方法，用于将边界框、分割掩码和关键点的坐标值限制在图像边界内。具体步骤如下。保存原始边界框格式：保存当前边界框的格式到 ori_format 。转换边界框格式为 xyxy ：将边界框格式转换为 xyxy ，以便进行裁剪操作。裁剪边界框坐标：对边界框的 x1 、 x2 、 y1 和 y2 坐标进行裁剪，确保它们在 [0, w] 和 [0, h] 范围内。恢复原始边界框格式：如果原始格式不是 xyxy ，则将边界框格式恢复为原始格式。裁剪分割掩码坐标：对分割掩码的 x 和 y 坐标进行裁剪，确保它们在 [0, w] 和 [0, h] 范围内。裁剪关键点坐标：如果存在关键点数据，则对关键点的 x 和 y 坐标进行裁剪，确保它们在 [0, w] 和 [0, h] 范围内。这种方法使得 Instances 类能够灵活地处理边界框、分割掩码和关键点的裁剪操作，确保它们不会超出图像边界，适用于目标检测任务中的数据预处理阶段。
# 这段代码定义了 Instances 类中的 remove_zero_area_boxes 方法，用于移除面积为零的边界框，并相应地更新分割掩码和关键点。
# 定义了 remove_zero_area_boxes 方法，该方法不接收额外参数。
def remove_zero_area_boxes(self):
# 删除零面积框，即裁剪后某些框的宽度或高度可能为零。
"""Remove zero-area boxes, i.e. after clipping some boxes may have zero width or height."""
# 计算每个边界框的面积是否大于零。 self.bbox_areas 是一个属性，返回一个数组，包含每个边界框的面积。 good 是一个布尔数组，表示每个边界框的面积是否大于零。
good = self.bbox_areas > 0
# 检查是否所有边界框的面积都大于零。 如果存在面积为零的边界框，则执行后续的移除操作。
if not all(good):
# 使用布尔索引 good 过滤掉面积为零的边界框。 self._bboxes[good] 会返回一个新的 Bboxes 对象，只包含面积大于零的边界框。
self._bboxes = self._bboxes[good]
# 如果存在分割掩码，则使用布尔索引 good 过滤掉对应的分割掩码。 self.segments[good] 会返回一个新的数组，只包含面积大于零的分割掩码。
if len(self.segments):
self.segments = self.segments[good]
# 如果存在关键点数据，则使用布尔索引 good 过滤掉对应的关键点。 self.keypoints[good] 会返回一个新的数组，只包含面积大于零的关键点。
if self.keypoints is not None:
self.keypoints = self.keypoints[good]
# 返回布尔数组 good ，表示哪些边界框的面积大于零。
return good
# 这段代码实现了 Instances 类中的 remove_zero_area_boxes 方法，用于移除面积为零的边界框，并相应地更新分割掩码和关键点。具体步骤如下。计算边界框面积：计算每个边界框的面积，并生成布尔数组 good ，表示面积是否大于零。检查是否需要移除：如果存在面积为零的边界框，则执行后续的移除操作。移除面积为零的边界框：使用布尔索引 good 过滤掉面积为零的边界框。更新分割掩码：如果存在分割掩码，则使用布尔索引 good 过滤掉对应的分割掩码。更新关键点：如果存在关键点数据，则使用布尔索引 good 过滤掉对应的关键点。返回布尔数组：返回布尔数组 good ，表示哪些边界框的面积大于零。这种方法使得 Instances 类能够灵活地处理边界框的移除操作，确保所有相关数据（边界框、分割掩码和关键点）保持一致，适用于目标检测任务中的数据预处理阶段。
# 这段代码定义了 Instances 类中的 update 方法，用于更新边界框、分割掩码和关键点数据。
# 定义了 update 方法，接收以下参数 ：
# 1.bboxes ：新的边界框数据，形状为 [N, 4] 。
# 2.segments ：新的分割掩码数据，形状为 [N, M, 2] ，其中 M 是分割掩码的点数，默认为 None 。
# 3.keypoints ：新的关键点数据，形状为 [N, 17, 3] ，表示每个对象的 17 个关键点的 (x, y, visible) 坐标，默认为 None 。
def update(self, bboxes, segments=None, keypoints=None):
# 更新实例变量。
"""Updates instance variables."""
# 使用新的边界框数据 bboxes 创建一个新的 Bboxes 对象，并将其存储到 self._bboxes 中。 保持边界框的格式不变，使用当前 _bboxes 的格式作为新 Bboxes 对象的格式。
self._bboxes = Bboxes(bboxes, format=self._bboxes.format)
# 如果提供了新的分割掩码数据 segments ，则将其存储到 self.segments 中。 如果 segments 为 None ，则 self.segments 保持不变。
if segments is not None:
self.segments = segments
# 如果提供了新的关键点数据 keypoints ，则将其存储到 self.keypoints 中。 如果 keypoints 为 None ，则 self.keypoints 保持不变。
if keypoints is not None:
self.keypoints = keypoints
# 这段代码实现了 Instances 类中的 update 方法，用于更新边界框、分割掩码和关键点数据。具体步骤如下。更新边界框：使用新的边界框数据 bboxes 创建一个新的 Bboxes 对象，并保持边界框的格式不变。更新分割掩码：如果提供了新的分割掩码数据 segments ，则更新 self.segments 。更新关键点：如果提供了新的关键点数据 keypoints ，则更新 self.keypoints 。这种方法使得 Instances 类能够灵活地更新其内部数据，适用于目标检测任务中的数据处理和增强阶段。例如，在数据预处理或后处理时，可能需要更新边界框、分割掩码和关键点数据，以反映图像变换后的结果。
# 这段代码定义了 Instances 类中的 __len__ 方法，用于返回实例中的边界框数量。
# 定义了 __len__ 方法。这是一个特殊方法，用于实现 Python 的内置函数 len() 。 当调用 len(instance) 时，Python 会自动调用该实例的 __len__ 方法。
def __len__(self):
# 返回实例列表的长度。
"""Return the length of the instance list."""
# 返回 self.bboxes 的长度，即边界框数组的行数。 self.bboxes 是一个二维 NumPy 数组，其中每一行表示一个边界框的 4 个坐标值。 len(self.bboxes) 返回数组的行数，即边界框的数量。
return len(self.bboxes)
# 这段代码实现了 Instances 类中的 __len__ 方法，用于返回实例中的边界框数量。具体步骤如下。调用 len() 函数：当使用 len(instance) 时，Python 会自动调用 instance.__len__() 。返回边界框数量：通过 len(self.bboxes) 返回边界框数组的行数，即边界框的数量。这种方法使得 Instances 类的实例可以像普通 Python 容器一样使用 len() 函数来获取边界框的数量，从而提高了类的易用性和一致性。
# 这段代码定义了 Instances 类中的 concatenate 类方法，用于将多个 Instances 对象拼接成一个新的 Instances 对象。
# 使用 @classmethod 装饰器定义了一个类方法 concatenate 。
@classmethod
# 方法接收两个参数。
# 1.instances_list ：一个包含多个 Instances 对象的列表或元组。
# 2.axis ：拼接的轴，默认值为 0 ，表示沿第一个轴（行）拼接。
# 方法返回一个新的 Instances 对象。
def concatenate(cls, instances_list: List["Instances"], axis=0) -> "Instances":
# 将实例对象列表连接成单个实例对象。
# 注意：
# 列表中的 `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.
"""
# 断言 instances_list 必须是一个列表或元组。 如果 instances_list 不是列表或元组，则抛出错误。
assert isinstance(instances_list, (list, tuple))
# 如果 instances_list 为空（即没有提供任何 Instances 对象）。
if not instances_list:
# 则返回一个空的 Instances 对象。 使用 np.empty(0) 创建一个空的 NumPy 数组，并通过 cls 构造函数创建一个空的 Instances 对象。
return cls(np.empty(0))
# 断言 instances_list 中的所有元素都必须是 Instances 类的实例。 使用 all() 和生成器表达式检查每个元素是否为 Instances 类型。 如果有任何元素不是 Instances 类型，则抛出错误。
assert all(isinstance(instance, Instances) for instance in instances_list)
# 如果 instances_list 中只有一个 Instances 对象。
if len(instances_list) == 1:
# 则直接返回该对象，无需拼接。
return instances_list[0]
# 检查第一个 Instances 对象 是否包含关键点数据 。 如果包含关键点数据，则 use_keypoint 为 True ，否则为 False 。
use_keypoint = instances_list[0].keypoints is not None
# 获取第一个 Instances 对象的 边界框格式 。
bbox_format = instances_list[0]._bboxes.format
# 获取第一个 Instances 对象的 归一化标志 。
normalized = instances_list[0].normalized
# 使用 np.concatenate 沿指定轴拼接所有 Instances 对象的边界框数据。 ins.bboxes 是每个 Instances 对象的边界框数组。
cat_boxes = np.concatenate([ins.bboxes for ins in instances_list], axis=axis)
# 获取每个 Instances 对象的 分割掩码的点数 （第二个维度的大小）。
seg_len = [b.segments.shape[1] for b in instances_list]
# frozenset([iterable])
# frozenset() 是 Python 的内置函数，用于创建一个不可变的集合（即 冻结集合）。冻结集合与普通集合（ set ）类似，但有以下关键区别 ：
# 不可变性 ：冻结集合一旦创建，其内容不能被修改（例如，不能添加或删除元素）。这使得冻结集合可以作为字典的键或其他集合的元素，而普通集合则不能。
# 哈希性 ：由于冻结集合是不可变的，它是可哈希的，因此可以作为字典的键或存储在其他集合中。
# 性能 ：在某些情况下，冻结集合的不可变性可以带来性能上的优化，尤其是在需要频繁检查集合成员关系时。
# 参数 ：
# iterable ：可选参数，可以是任何可迭代对象（如列表、元组、字典的键等）。如果不提供参数，则创建一个空的冻结集合。
# 返回值 ：
# 返回一个 frozenset 对象。
# frozenset() 是一个非常有用的工具，尤其在需要不可变集合时。它提供了集合的基本功能（如成员检查、去重等），同时保证了不可变性和哈希性，使得它可以作为字典的键或其他集合的元素。
# 检查分割掩码的点数是否一致。 如果点数不一致，则需要对分割掩码进行重采样，使其长度一致。
if len(frozenset(seg_len)) > 1: # resample segments if there's different length
# 获取最大的分割掩码点数。
max_len = max(seg_len)
# 对每个 Instances 对象的分割掩码进行重采样，使其长度一致。
# 使用 np.concatenate 沿指定轴拼接所有重采样后的分割掩码。
cat_segments = np.concatenate(
[
# def resample_segments(segments, n=1000): -> 用于对输入的二维线段数据进行重采样，使其每个线段的点数统一为指定的数量 n 。返回处理后的线段数据列表。 -> return segments
resample_segments(list(b.segments), max_len)
if len(b.segments)
# 如果某个 Instances 对象没有分割掩码，则生成一个空的分割掩码数组。
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 为 None 。
cat_keypoints = np.concatenate([b.keypoints for b in instances_list], axis=axis) if use_keypoint else None
# 使用 拼接后的 边界框 、分割掩码 和 关键点数据 ，创建一个新的 Instances 对象并返回。
return cls(cat_boxes, cat_segments, cat_keypoints, bbox_format, normalized)
# 这段代码实现了 Instances 类中的 concatenate 类方法，用于将多个 Instances 对象拼接成一个新的 Instances 对象。具体步骤如下。验证输入：确保 instances_list 是一个列表或元组。确保 instances_list 中的所有元素都是 Instances 类的实例。处理特殊情况：如果 instances_list 为空，返回一个空的 Instances 对象。如果 instances_list 中只有一个 Instances 对象，直接返回该对象。拼接边界框：沿指定轴拼接所有 Instances 对象的边界框数据。处理分割掩码：如果分割掩码的点数不一致，则对分割掩码进行重采样，使其长度一致。沿指定轴拼接所有分割掩码。拼接关键点：如果存在关键点数据，则沿指定轴拼接所有关键点数据。创建新的 Instances 对象：使用拼接后的数据创建一个新的 Instances 对象并返回。这种方法使得 Instances 类能够灵活地处理多个实例的拼接操作，适用于目标检测任务中的数据处理和合并。
# 这段代码定义了 Instances 类中的一个属性 bboxes ，用于访问边界框数据。
@property
# 使用 @property 装饰器定义了一个只读属性 bboxes 。 这使得 bboxes 可以像普通属性一样被访问，而无需显式调用方法。
def bboxes(self):
# 返回边界框。
"""Return bounding boxes."""
# 返回 _bboxes 对象的 bboxes 属性。 _bboxes 是一个 Bboxes 类的实例，负责处理边界框的操作。 self._bboxes.bboxes 是一个二维 NumPy 数组，形状为 [N, 4] ，表示 N 个边界框的坐标。
return self._bboxes.bboxes
# 这段代码实现了 Instances 类中的 bboxes 属性，用于访问边界框数据。具体步骤如下。定义只读属性：使用 @property 装饰器定义了一个只读属性 bboxes 。返回边界框数据：通过 _bboxes 对象的 bboxes 属性返回边界框数据。这种方法使得 Instances 类的用户可以方便地访问边界框数据，而无需直接操作 _bboxes 对象。这不仅提高了代码的可读性，还保持了类的封装性。
# Instances 类是一个用于封装和处理目标检测任务中的边界框、分割掩码和关键点信息的容器类。它支持多种操作，包括边界框格式的转换、面积计算、坐标缩放、归一化与去归一化、填充偏移、水平和垂直翻转、裁剪以及移除面积为零的边界框等。此外， Instances 类还提供了灵活的数据拼接功能，能够将多个实例对象合并为一个新的实例对象。通过封装这些功能， Instances 类为处理目标检测数据提供了便利，适用于数据预处理、数据增强和后处理等阶段，能够有效提升代码的可维护性和可扩展性。