augment.py
ultralytics\data\augment.py
目录
5.class Mosaic(BaseMixTransform):
6.class MixUp(BaseMixTransform):
14.def v8_transforms(dataset, imgsz, hyp, stretch=False):
1.所需的库和模块
# Ultralytics YOLO 🚀, AGPL-3.0 license
# 变量 labels 是 Instances 实例。
import math
import random
from copy import deepcopy
import cv2
import numpy as np
import torch
import torchvision.transforms as T
from ultralytics.utils import LOGGER, colorstr
from ultralytics.utils.checks import check_version
from ultralytics.utils.instance import Instances
from ultralytics.utils.metrics import bbox_ioa
from ultralytics.utils.ops import segment2box, xyxyxyxy2xywhr
from ultralytics.utils.torch_utils import TORCHVISION_0_10, TORCHVISION_0_11, TORCHVISION_0_13
from .utils import polygons2masks, polygons2masks_overlap
# 这些常量定义了在图像预处理中常用的默认参数，通常用于数据标准化和裁剪。
# 一个元组，表示 图像每个通道的默认均值 。在图像预处理中，通常需要将图像的像素值减去均值，以进行标准化处理。这里 (0.0, 0.0, 0.0) 表示每个通道的均值都为 0.0。
DEFAULT_MEAN = (0.0, 0.0, 0.0)
# 一个元组，表示 图像每个通道的默认标准差 。在图像预处理中，通常需要将图像的像素值除以标准差，以进行标准化处理。这里 (1.0, 1.0, 1.0) 表示每个通道的标准差都为 1.0。
DEFAULT_STD = (1.0, 1.0, 1.0)
# 一个浮点数，表示 裁剪图像的比例 。这里 1.0 表示不进行裁剪，即使用完整的图像。
DEFAULT_CROP_FTACTION = 1.0
# 这些常量 DEFAULT_MEAN 、 DEFAULT_STD 和 DEFAULT_CROP_FTACTION 用于定义图像预处理中的默认参数。通过合理设置这些参数，可以确保图像数据在输入模型之前进行适当的标准化和裁剪，从而提高模型的性能和泛化能力。在实际应用中，这些参数可以根据具体的数据集和任务进行调整。2.class BaseTransform:
# TODO: we might need a BaseTransform to make all these augments be compatible with both classification and semantic # TODO：我们可能需要一个 BaseTransform 来使所有这些增强与分类和语义兼容。
# 这段代码定义了一个名为 BaseTransform 的类，用于对图像及其标签进行一系列变换操作。
# 声明了一个名为 BaseTransform 的类，这是后续定义变换操作的基础类。
class BaseTransform:
# 图像转换的基类。
# 这是一个通用的转换类，可以根据特定的图像处理需求进行扩展。
# 该类旨在兼容分类和语义分割任务。
# 方法：
# __init__：初始化 BaseTransform 对象。
# apply_image：将图像转换应用于标签。
# apply_instances：将转换应用于标签中的对象实例。
# apply_semantic：将语义分割应用于图像。
# __call__：将所有标签转换应用于图像、实例和语义掩码。
"""
Base class for image transformations.
This is a generic transformation class that can be extended for specific image processing needs.
The class is designed to be compatible with both classification and semantic segmentation tasks.
Methods:
__init__: Initializes the BaseTransform object.
apply_image: Applies image transformation to labels.
apply_instances: Applies transformations to object instances in labels.
apply_semantic: Applies semantic segmentation to an image.
__call__: Applies all label transformations to an image, instances, and semantic masks.
"""
# 定义了类的初始化方法 __init__ ，当创建 BaseTransform 类的实例时会被调用。 -> None 表示该方法没有返回值。
def __init__(self) -> None:
# 初始化 BaseTransform 对象。
"""Initializes the BaseTransform object."""
# 在 __init__ 方法中暂时不做任何操作，后续可根据需要添加具体的初始化代码。
pass
# 定义了一个名为 apply_image 的方法，用于对图像的标签进行变换操作， 1.labels 参数表示图像的标签。
def apply_image(self, labels):
# 将图像转换应用于标签。
"""Applies image transformations to labels."""
# 在 apply_image 方法中暂时不做任何操作，后续需根据具体变换需求实现该方法。
pass
# 定义了一个名为 apply_instances 的方法，用于对图像中对象实例的标签进行变换操作， 1.labels 参数表示对象实例的标签。
def apply_instances(self, labels):
# 将转换应用于标签中的对象实例。
"""Applies transformations to object instances in labels."""
# 在 apply_instances 方法中暂时不做任何操作，后续需根据具体变换需求实现该方法。
pass
# 定义了一个名为 apply_semantic 的方法，用于对图像进行语义分割操作， 1.labels 参数表示语义分割的标签。
def apply_semantic(self, labels):
# 将语义分割应用于图像。
"""Applies semantic segmentation to an image."""
# 在 apply_semantic 方法中暂时不做任何操作，后续需根据具体语义分割需求实现该方法。
pass
# 定义了一个名为 __call__ 的特殊方法，使得 BaseTransform 类的实例可以像函数一样被调用，1.labels 参数表示需要进行变换的标签。
def __call__(self, labels):
# 将所有标签转换应用于图像、实例和语义掩码。
"""Applies all label transformations to an image, instances, and semantic masks."""
# 在 __call__ 方法中调用 apply_image 方法，对图像标签进行变换。
self.apply_image(labels)
# 在 __call__ 方法中调用 apply_instances 方法，对图像中对象实例的标签进行变换。
self.apply_instances(labels)
# 在 __call__ 方法中调用 apply_semantic 方法，对图像进行语义分割操作。
self.apply_semantic(labels)
# 这段代码定义了一个基础的变换类 BaseTransform ，它提供了对图像及其标签进行变换的框架，包括图像变换、对象实例变换和语义分割变换。通过 __call__ 方法，可以一次性对图像的标签进行所有相关变换操作。这个类为后续实现具体的图像处理和变换功能提供了一个灵活的基础架构，后续可在各个方法中添加具体的变换逻辑来满足不同的图像处理需求。3.class Compose:
# 这段代码定义了一个名为 Compose 的类，用于组合多个图像变换操作。
# 声明了一个名为 Compose 的类，目的是将多个图像变换操作组合起来，以便一次性对图像数据进行一系列的处理。
class Compose:
# 用于组成多个图像转换的类。
"""Class for composing multiple image transformations."""
# 定义了类的初始化方法 __init__ ，接收一个参数 1.transforms ，该参数是一个包含多个变换操作的列表。
def __init__(self, transforms):
# 使用转换列表初始化 Compose 对象。
"""Initializes the Compose object with a list of transforms."""
# 在初始化方法中，将传入的 变换操作列表 赋值给实例变量 self.transforms ，以便后续使用。
self.transforms = transforms
# 定义了一个名为 __call__ 的特殊方法，使得 Compose 类的实例可以像函数一样被调用，接收一个参数 1.data ，表示需要进行变换的图像数据。
def __call__(self, data):
# 对输入数据应用一系列转换。
"""Applies a series of transformations to input data."""
# 在 __call__ 方法中，通过循环遍历 self.transforms 列表中的每一个变换操作 t 。
for t in self.transforms:
# 对每个变换操作 t ，将其应用于当前的图像数据 data ，并将变换后的结果重新赋值给 data ，以便进行下一个变换操作。
data = t(data)
# 在所有变换操作完成后，返回最终变换后的图像数据 data 。
return data
# 定义了一个名为 append 的方法，用于向现有的变换操作列表中添加一个新的变换操作。
def append(self, transform):
# 将新的转换附加到现有的转换列表中。
"""Appends a new transform to the existing list of transforms."""
# 在 append 方法中，使用列表的 append 方法将新的变换操作 transform 添加到 self.transforms 列表中。
self.transforms.append(transform)
# 定义了一个名为 tolist 的方法，用于将变换操作列表转换为标准的Python列表。
def tolist(self):
# 将变换列表转换为标准 Python 列表。
"""Converts the list of transforms to a standard Python list."""
# 在 tolist 方法中，直接返回 self.transforms 列表，因为该列表本身就是标准的Python列表。
return self.transforms
# 定义了一个名为 __repr__ 的特殊方法，用于返回对象的字符串表示形式，便于调试和打印对象信息。
def __repr__(self):
# 返回对象的字符串表示形式。
"""Returns a string representation of the object."""
# 在 __repr__ 方法中，使用字符串格式化的方式，返回一个包含 类名 和 变换操作列表字符串表示形式 的字符串。通过列表推导式 [f'{t}' for t in self.transforms] 生成每个变换操作的字符串表示形式，并使用 ', '.join(...) 将它们连接成一个字符串，最后与类名一起格式化为最终的字符串表示形式。
return f"{self.__class__.__name__}({', '.join([f'{t}' for t in self.transforms])})"
# 这段代码实现了一个 Compose 类，它能够将多个图像变换操作组合在一起，方便地对图像数据进行一系列的处理。通过 __call__ 方法，可以依次执行列表中的每个变换操作； append 方法允许动态添加新的变换操作； tolist 方法可以获取变换操作列表的标准Python表示； __repr__ 方法提供了对象的字符串表示形式，便于调试和查看对象状态。这个类为图像处理流程的组合和管理提供了一个灵活且易于使用的工具。4.class BaseMixTransform:
# 这段代码定义了一个名为 BaseMixTransform 的类，用于实现图像混合变换的基础框架，如Mosaic或MixUp等数据增强技术。
# 声明了一个名为 BaseMixTransform 的类，它是实现图像混合变换的基础类。
class BaseMixTransform:
# 基础混合（MixUp/Mosaic）转换类。
# 此实现来自 mmyolo。
"""
Class for base mix (MixUp/Mosaic) transformations.
This implementation is from mmyolo.
"""
# 定义了类的初始化方法 __init__ ，接收三个参数。
# 1.dataset ：数据集对象。
# 2.pre_transform ：预变换操作，可选，默认为 None 。
# 3.p ：执行混合变换的概率，默认为 0.0 。
def __init__(self, dataset, pre_transform=None, p=0.0) -> None:
# 使用数据集、pre_transform 和概率初始化 BaseMixTransform 对象。
"""Initializes the BaseMixTransform object with dataset, pre_transform, and probability."""
# 将传入的 数据集对象 赋值给实例变量 self.dataset ，用于后续获取图像及其标签。
self.dataset = dataset
# 将传入的 预变换操作 赋值给实例变量 self.pre_transform ，如果提供了预变换操作，则在混合变换前对图像进行处理。
self.pre_transform = pre_transform
# 将传入的 执行混合变换的概率 赋值给实例变量 self.p ，用于控制是否执行混合变换。
self.p = p
# 定义了一个名为 __call__ 的特殊方法，使得 BaseMixTransform 类的实例可以像函数一样被调用，接收一个参数。
# 1.labels ：表示图像的标签。
def __call__(self, labels):
# 将预处理转换和混合/马赛克转换应用于标签数据。
"""Applies pre-processing transforms and mixup/mosaic transforms to labels data."""
# 在 __call__ 方法中，使用 random.uniform(0, 1) 生成一个[0, 1)范围内的随机数，如果该随机数大于 self.p ，则不执行混合变换，直接返回原始标签。
if random.uniform(0, 1) > self.p:
return labels
# Get index of one or three other images
# 调用 get_indexes 方法获取一个或三个其他图像的索引，用于后续的混合变换。
indexes = self.get_indexes()
# 判断 indexes 是否为整数，如果是，则将其转换为包含该整数的列表。
if isinstance(indexes, int):
indexes = [indexes]
# Get images information will be used for Mosaic or MixUp
# 使用列表推导式，根据获取的索引从数据集中获取 图像 及 其标签 ，用于混合变换。
mix_labels = [self.dataset.get_image_and_label(i) for i in indexes]
# 如果提供了 预变换操作 ，则对获取的每个图像及其标签执行预变换操作。
if self.pre_transform is not None:
# 遍历 mix_labels 列表中的每个图像及其标签。
for i, data in enumerate(mix_labels):
# 对每个图像及其标签执行预变换操作，并更新 mix_labels 列表。
mix_labels[i] = self.pre_transform(data)
# 将处理后的图像及其标签列表赋值给 labels 字典的 "mix_labels" 键，以便后续的混合变换使用。
labels["mix_labels"] = mix_labels
# Mosaic or MixUp
# 调用 _mix_transform 方法执行具体的混合变换操作，该方法需要在子类中实现。
labels = self._mix_transform(labels)
# 从 labels 字典中移除 "mix_labels" 键及其对应的值，清理不再需要的数据。
labels.pop("mix_labels", None)
# 返回经过混合变换后的标签。
return labels
# 定义了一个名为 _mix_transform 的方法，用于执行具体的混合变换操作。该方法在 BaseMixTransform 类中被声明为抽象方法，需要在子类中实现具体的混合变换逻辑。
def _mix_transform(self, labels):
# 将 MixUp 或 Mosaic 增强应用于标签字典。
"""Applies MixUp or Mosaic augmentation to the label dictionary."""
# 抛出 NotImplementedError 异常，表示该方法在 BaseMixTransform 类中没有实现，需要在子类中进行具体实现。
raise NotImplementedError
# 定义了一个名为 get_indexes 的方法，用于获取用于混合变换的其他图像的索引。同样，该方法在 BaseMixTransform 类中被声明为抽象方法，需要在子类中实现具体的索引获取逻辑。
def get_indexes(self):
# 获取用于马赛克增强的混洗索引列表。
"""Gets a list of shuffled indexes for mosaic augmentation."""
# 抛出 NotImplementedError 异常，表示该方法在 BaseMixTransform 类中没有实现，需要在子类中进行具体实现。
raise NotImplementedError
# 这段代码实现了一个 BaseMixTransform 类，它提供了一个基础框架用于实现图像混合变换，如Mosaic或MixUp等数据增强技术。通过 __call__ 方法，根据给定的概率决定是否执行混合变换； _mix_transform 和 get_indexes 方法被声明为抽象方法，需要在子类中实现具体的混合变换逻辑和索引获取逻辑。这个类为实现各种图像混合变换提供了一个灵活且可扩展的基础。5.class Mosaic(BaseMixTransform):
# 这段代码定义了一个名为 Mosaic 的类，继承自 BaseMixTransform 类，用于实现Mosaic数据增强技术，这是一种常用于目标检测任务的数据增强方法，通过将多张图像拼接在一起形成一张新的图像，增加模型对不同图像组合的学习能力。
# 声明了一个名为 Mosaic 的类，继承自 BaseMixTransform 类。
class Mosaic(BaseMixTransform):
# 马赛克增强。
# 此类通过将多张（4 张或 9 张）图像组合成一张马赛克图像来执行马赛克增强。
# 增强以给定的概率应用于数据集。
"""
Mosaic augmentation.
This class performs mosaic augmentation by combining multiple (4 or 9) images into a single mosaic image.
The augmentation is applied to a dataset with a given probability.
Attributes:
dataset: The dataset on which the mosaic augmentation is applied.
imgsz (int, optional): Image size (height and width) after mosaic pipeline of a single image. Default to 640.
p (float, optional): Probability of applying the mosaic augmentation. Must be in the range 0-1. Default to 1.0.
n (int, optional): The grid size, either 4 (for 2x2) or 9 (for 3x3).
"""
# 这段代码是 Mosaic 类的初始化方法 __init__ 的定义，用于创建 Mosaic 类的实例并初始化其属性。
# 定义了 Mosaic 类的初始化方法 __init__ ，它接收四个参数。
# 1.self ：指向类实例本身的引用，用于访问类的属性和方法。
# 2.dataset ：数据集对象，提供图像及其标签的数据源。
# 3.imgsz ：图像的大小，默认值为640。这通常是指图像的宽度和高度，用于后续的图像处理和拼接操作。
# 4.p ：执行Mosaic变换的概率，默认值为1.0，意味着默认情况下每次都会执行Mosaic变换。
# 5.n ：拼接的图像数量，默认值为4，表示通常使用2x2的网格进行图像拼接。根据Mosaic变换的实现， n 的值也可以是9，对应3x3的网格。
def __init__(self, dataset, imgsz=640, p=1.0, n=4):
# 使用数据集、图像大小、概率和边框初始化对象。
"""Initializes the object with a dataset, image size, probability, and border."""
# 使用 assert 语句断言概率 p 的值在0到1的范围内（包括0和1）。如果 p 的值不在这个范围内，会抛出一个异常，并附带一条错误信息，指出概率值应该在[0, 1]范围内，但实际得到的是 p 的值。
assert 0 <= p <= 1.0, f"The probability should be in range [0, 1], but got {p}." # 概率应该在 [0, 1] 范围内，但得到的是 {p}。
# 使用 assert 语句断言图像数量 n 的值只能是4或9。如果 n 的值不是4或9，会抛出一个异常，并附带一条错误信息，指出网格大小必须等于4或9。
assert n in (4, 9), "grid must be equal to 4 or 9." # 网格必须等于 4 或 9。
# 调用父类 BaseMixTransform 的初始化方法 __init__ ，并将 dataset 和 p 参数传递给它。这是Python中继承机制的一部分，用于确保父类的初始化逻辑也被执行。
super().__init__(dataset=dataset, p=p)
# 将传入的 dataset 参数赋值给类实例的 dataset 属性，这样类的其他方法就可以通过 self.dataset 访问数据集对象。
self.dataset = dataset
# 将传入的 imgsz 参数赋值给类实例的 imgsz 属性，用于后续的图像处理操作。
self.imgsz = imgsz
# 计算并设置Mosaic图像的边界。这里将边界设置为图像大小的一半的负值，即 (-imgsz // 2, -imgsz // 2) ，这通常用于后续的图像裁剪操作，以确保拼接后的图像大小符合预期。
self.border = (-imgsz // 2, -imgsz // 2) # width, height
# 将传入的 n 参数赋值给类实例的 n 属性，用于确定Mosaic变换中使用的图像数量，即拼接网格的大小。
self.n = n
# 这段初始化方法 __init__ 的作用是设置 Mosaic 类实例的基本属性，包括数据集对象、图像大小、执行变换的概率以及拼接的图像数量。同时，它还通过断言确保传入的概率值和图像数量符合预期的范围和条件，以保证Mosaic变换能够正确执行。通过调用父类的初始化方法，它还确保了从 BaseMixTransform 类继承的属性和方法被正确初始化。
# 这段代码是 Mosaic 类中的 get_indexes 方法的定义，其作用是根据指定的条件获取用于Mosaic数据增强的其他图像的索引。
# 定义了 get_indexes 方法，它接收一个参数。
# 1.buffer ：默认值为 True 。这个参数决定了是从数据集的缓冲区中选择图像，还是从整个数据集中随机选择图像。
def get_indexes(self, buffer=True):
# 从数据集返回随机索引列表。
"""Return a list of random indexes from the dataset."""
# 判断 buffer 参数的值。如果 buffer 为 True ，则表示从数据集的缓冲区中选择图像。
if buffer: # select images from buffer
# 如果 buffer 为 True ，则使用 random.choices 函数从数据集的缓冲区 self.dataset.buffer 中随机选择 self.n - 1 个图像的索引。这里使用 list(self.dataset.buffer) 将缓冲区转换为列表，以便 random.choices 可以从中选择元素。 k=self.n - 1 指定了需要选择的索引数量，因为Mosaic变换通常需要 n 张图像，其中一张是当前图像，其余 n-1 张是从缓冲区或数据集中选择的。
return random.choices(list(self.dataset.buffer), k=self.n - 1)
# 如果 buffer 为 False ，则表示从整个数据集中随机选择图像。
else: # select any images
# 如果 buffer 为 False ，则使用列表推导式生成一个包含 self.n - 1 个随机索引的列表。每个索引是通过 random.randint(0, len(self.dataset) - 1) 生成的，范围是从0到数据集长度减1，确保索引有效。
return [random.randint(0, len(self.dataset) - 1) for _ in range(self.n - 1)]
# get_indexes 方法根据 buffer 参数的值，从数据集的缓冲区或整个数据集中随机选择 n-1 个图像的索引，用于Mosaic数据增强。这种方法为Mosaic变换提供了灵活性，可以根据需要选择不同的图像组合来进行数据增强，从而提高模型的泛化能力。
# 这段代码是 Mosaic 类中的 _mix_transform 方法的定义，其作用是根据配置的图像数量 n 执行相应的Mosaic数据增强变换。
# 定义了 _mix_transform 方法，它接收一个参数。
# 1.labels ：这个参数是一个字典，包含了当前图像的标签信息以及可能的其他图像的标签信息（用于Mosaic变换）。
def _mix_transform(self, labels):
# 对输入图像和标签应用混合变换。
"""Apply mixup transformation to the input image and labels."""
# 使用 assert 语句检查 labels 字典中是否包含 "rect_shape" 键。如果存在这个键，说明可能已经应用了Rect训练方法，而Rect训练和Mosaic变换是互斥的，因此抛出一个异常。
assert labels.get("rect_shape", None) is None, "rect and mosaic are mutually exclusive." # rect 和 mosaic 是互斥的。
# 使用 assert 语句检查 labels 字典中的 "mix_labels" 键对应的值（一个列表）的长度是否大于0。这确保了有其他图像用于Mosaic数据增强，如果没有，则抛出一个异常。
# 在 Mosaic 类中， labels 字典中的 "mix_labels" 键用于存储用于Mosaic数据增强的其他图像的标签信息。具体来说， "mix_labels" 键对应的值是一个列表，每个元素是一个字典，包含了一张图像的标签信息。这些标签信息用于在Mosaic变换过程中，将多张图像的标签合并到一张拼接后的图像中。
assert len(labels.get("mix_labels", [])), "There are no other images for mosaic augment." # 没有其他可用于马赛克增强的图像。
# 根据 self.n 的值决定调用哪个具体的Mosaic变换方法。
# 如果 self.n == 3 ，则调用 self._mosaic3(labels) 方法，执行3张图像的Mosaic变换。 如果 self.n == 4 ，则调用 self._mosaic4(labels) 方法，执行4张图像的Mosaic变换。 如果 self.n 既不是3也不是4，那么默认调用 self._mosaic9(labels) 方法，执行9张图像的Mosaic变换。
# 注释 # This code is modified for mosaic3 method. 说明这段代码为了支持3张图像的Mosaic方法进行了修改。
return (
self._mosaic3(labels) if self.n == 3 else self._mosaic4(labels) if self.n == 4 else self._mosaic9(labels)
) # This code is modified for mosaic3 method. 此代码针对mosaic3方法进行了修改。
# _mix_transform 方法是 Mosaic 类中用于执行Mosaic数据增强的核心方法。它首先进行一些必要的检查，确保当前的配置适合执行Mosaic变换，然后根据配置的图像数量调用相应的Mosaic变换实现方法。这种方法的设计使得 Mosaic 类能够灵活地支持不同数量的图像拼接，从而适应不同的数据增强需求。
# 什么是Rect训练？
# Rect训练（矩形训练）是一种在目标检测任务中常用的数据预处理方法，旨在优化图像的尺寸调整和填充策略，以减少冗余信息，提高训练和推理的效率。具体来说，Rect训练的核心思想是将输入图像调整为矩形尺寸，而不是传统的正方形尺寸，这样可以减少填充的像素数量，从而减少计算量和显存开销。
# 工作原理 ：
# 等比例缩放 ：将图像等比例缩放，使得图像的长边或短边达到指定的尺寸，通常是模型输入尺寸的倍数（如32的倍数）。
# 填充 ：对缩放后的图像进行必要的填充，使得图像的尺寸符合模型输入的要求。填充的像素通常使用灰色（114, 114, 114）或黑色（0, 0, 0）。
# 批量处理 ：在批量处理时，选择一个批次中所有图像的最大长和宽作为该批次的统一尺寸，这样可以减少填充的像素数量，提高训练效率。
# 为什么Rect训练和Mosaic变换是互斥的？
# Rect训练和Mosaic变换在数据预处理和增强策略上有本质的不同，这导致它们在实际应用中通常是互斥的。具体原因如下 ：
# 图像尺寸调整策略不同 ：
# Rect训练 ：将图像调整为矩形尺寸，减少填充的像素数量，提高训练和推理效率。
# Mosaic变换 ：将多张图像拼接成一个更大的图像，通常需要将每张图像调整为相同的正方形尺寸，以便拼接后的图像尺寸一致。
# 数据增强目标不同 ：
# Rect训练 ：主要目的是减少冗余信息，提高训练和推理的效率。它通过减少填充的像素数量来实现这一点。
# Mosaic变换 ：主要目的是通过拼接多张图像来增加数据的多样性，提高模型的泛化能力。它通过将多张图像拼接在一起，使得模型能够学习到更多样的图像组合。
# 实现细节不同 ：
# Rect训练 ：在数据加载阶段，对每张图像进行等比例缩放和必要的填充，确保图像尺寸一致。
# Mosaic变换 ：在数据加载阶段，随机选择多张图像，将它们拼接成一个更大的图像，并更新相应的标签信息。
# 示例 ：
# 假设我们有一张原始图像，尺寸为1280x720，模型输入尺寸为640x640。
# Rect训练 ：
# 等比例缩放 ：将图像等比例缩放，使得长边达到640像素，短边为360像素（1280/720 * 640 = 360）。
# 填充 ：对缩放后的图像进行填充，使得图像尺寸为640x640。填充的像素值为114。
# 批量处理 ：在批量处理时，选择一个批次中所有图像的最大长和宽作为该批次的统一尺寸，减少填充的像素数量。
# Mosaic变换 ：
# 随机选择图像 ：随机选择4张图像，每张图像的尺寸为640x640。
# 拼接图像 ：将4张图像拼接成一个2x2的网格，形成一个1280x1280的图像。
# 更新标签 ：更新每张图像的标签信息，确保标签在拼接后的图像中的位置正确。
# 总结 ：
# Rect训练和Mosaic变换在目标检测任务中各有其优势和适用场景。Rect训练通过减少冗余信息提高训练和推理效率，而Mosaic变换通过增加数据多样性提高模型的泛化能力。由于它们在图像尺寸调整和数据增强策略上有本质的不同，因此在实际应用中通常是互斥的。在选择使用哪种方法时，需要根据具体任务的需求和资源情况进行权衡。
# 这段代码是 Mosaic 类中的 _mosaic3 方法的定义，用于创建一个1x3的图像拼接（Mosaic）。
# 定义了 _mosaic3 方法，接收一个参数。
# 1.labels ：这是一个字典，包含了当前图像的标签信息以及可能的其他图像的标签信息。
def _mosaic3(self, labels):
# 创建 1x3 图像马赛克。
"""Create a 1x3 image mosaic."""
# 初始化一个空列表，用于存储每个图像块的标签信息。
mosaic_labels = []
# 获取图像大小，用于后续的图像拼接和坐标计算。
s = self.imgsz
# 循环3次，处理3个图像块。
for i in range(3):
# 如果当前是第一个图像块（中心图像），则使用传入的 labels ；否则，从 mix_labels 中获取其他图像的标签信息。
labels_patch = labels if i == 0 else labels["mix_labels"][i - 1]
# Load image
# 从 labels_patch 中获取图像数据。
img = labels_patch["img"]
# 从 labels_patch 中获取图像的调整后的尺寸，并从字典中移除该键值对。
h, w = labels_patch.pop("resized_shape")
# Place img in img3
# 如果是中心图像块。
if i == 0: # center
# 创建一个3倍图像大小的基底图像，填充值为114（通常用于表示背景）。
img3 = np.full((s * 3, s * 3, img.shape[2]), 114, dtype=np.uint8) # base image with 3 tiles
# 保存中心图像的尺寸。
h0, w0 = h, w
# 计算中心图像块的坐标范围。
c = s, s, s + w, s + h # xmin, ymin, xmax, ymax (base) coordinates
# 如果是右侧图像块。
elif i == 1: # right
# 计算右侧图像块的坐标范围。
c = s + w0, s, s + w0 + w, s + h
# 如果是左侧图像块。
elif i == 2: # left
# 计算左侧图像块的坐标范围。
c = s - w, s + h0 - h, s, s + h0
# 获取填充宽度和高度。
padw, padh = c[:2]
# 确保坐标值不为负数。
x1, y1, x2, y2 = (max(x, 0) for x in c) # allocate coords
# 将当前图像块填充到基底图像的相应位置。
img3[y1:y2, x1:x2] = img[y1 - padh :, x1 - padw :] # img3[ymin:ymax, xmin:xmax]
# hp, wp = h, w # height, width previous for next iteration
# Labels assuming imgsz*2 mosaic size
# 调用 _update_labels 方法更新标签信息，考虑图像的填充和边界。
labels_patch = self._update_labels(labels_patch, padw + self.border[0], padh + self.border[1])
# 将更新后的标签信息添加到 mosaic_labels 列表中。
mosaic_labels.append(labels_patch)
# 调用 _cat_labels 方法合并所有图像块的标签信息。
final_labels = self._cat_labels(mosaic_labels)
# 裁剪基底图像，去除边界部分，得到最终的Mosaic图像。
final_labels["img"] = img3[-self.border[0] : self.border[0], -self.border[1] : self.border[1]]
# 返回包含最终图像和标签信息的字典。
return final_labels
# _mosaic3 方法实现了1x3图像拼接的Mosaic数据增强技术。它通过创建一个3倍图像大小的基底图像，将3个图像块分别放置在中心、右侧和左侧位置，然后更新和合并标签信息，最后裁剪基底图像以去除边界部分，得到最终的Mosaic图像。这个方法为Mosaic数据增强提供了一种灵活的实现方式，适用于目标检测任务中的数据增强。
# 这段代码定义了 Mosaic 类中的 _mosaic4 方法，用于创建一个2x2的图像拼接（Mosaic）。
# 定义了 _mosaic4 方法，接收一个参数.
# 1.labels ：这是一个字典，包含了当前图像的标签信息以及可能的其他图像的标签信息。
def _mosaic4(self, labels):
# 创建 2x2 的图像马赛克。
"""Create a 2x2 image mosaic."""
# 初始化一个空列表，用于存储每个图像块的标签信息。
mosaic_labels = []
# 获取图像大小，用于后续的图像拼接和坐标计算。
s = self.imgsz
# 生成 Mosaic图像的中心坐标 yc （y坐标）和 xc （x坐标）。 random.uniform(-x, 2 * s + x) 生成一个在 [-x, 2 * s + x] 范围内的随机浮点数， int 将其转换为整数。 self.border 是一个包含两个元素的元组，分别表示水平和垂直方向的边界。
yc, xc = (int(random.uniform(-x, 2 * s + x)) for x in self.border) # mosaic center x, y
# 循环处理每个图像块。
# 循环4次，处理4个图像块。
for i in range(4):
# 如果当前是第一个图像块（中心图像），则使用传入的 labels ；否则，从 mix_labels 中获取其他图像的标签信息。
labels_patch = labels if i == 0 else labels["mix_labels"][i - 1]
# Load image
# 加载图像。
# 从 labels_patch 中获取图像数据。
img = labels_patch["img"]
# 从 labels_patch 中获取图像的调整后的尺寸，并从字典中移除该键值对。
h, w = labels_patch.pop("resized_shape")
# 图像拼接。
# Place img in img4
# 如果是左上角图像块。
if i == 0: # top left
# 创建一个2倍图像大小的基底图像，填充值为114（通常用于表示背景）。
img4 = np.full((s * 2, s * 2, img.shape[2]), 114, dtype=np.uint8) # base image with 4 tiles
# 计算左上角图像块的坐标范围。
x1a, y1a, x2a, y2a = max(xc - w, 0), max(yc - h, 0), xc, yc # xmin, ymin, xmax, ymax (large image)
# 计算左上角图像块在原图中的坐标范围。
x1b, y1b, x2b, y2b = w - (x2a - x1a), h - (y2a - y1a), w, h # xmin, ymin, xmax, ymax (small image)
# 如果是右上角图像块。
elif i == 1: # top right
# 计算右上角图像块的坐标范围。
x1a, y1a, x2a, y2a = xc, max(yc - h, 0), min(xc + w, s * 2), yc
# 计算右上角图像块在原图中的坐标范围。
x1b, y1b, x2b, y2b = 0, h - (y2a - y1a), min(w, x2a - x1a), h
# 如果是左下角图像块。
elif i == 2: # bottom left
# 计算左下角图像块的坐标范围。
x1a, y1a, x2a, y2a = max(xc - w, 0), yc, xc, min(s * 2, yc + h)
# 计算左下角图像块在原图中的坐标范围。
x1b, y1b, x2b, y2b = w - (x2a - x1a), 0, w, min(y2a - y1a, h)
# 如果是右下角图像块。
elif i == 3: # bottom right
# 计算右下角图像块的坐标范围。
x1a, y1a, x2a, y2a = xc, yc, min(xc + w, s * 2), min(s * 2, yc + h)
# 计算右下角图像块在原图中的坐标范围。
x1b, y1b, x2b, y2b = 0, 0, min(w, x2a - x1a), min(y2a - y1a, h)
# 图像填充。
# 将当前图像块填充到基底图像的相应位置。
img4[y1a:y2a, x1a:x2a] = img[y1b:y2b, x1b:x2b] # img4[ymin:ymax, xmin:xmax]
# 计算水平方向的填充像素数。
padw = x1a - x1b
# 计算垂直方向的填充像素数。
padh = y1a - y1b
# 标签更新。
# 调用 _update_labels 方法更新标签信息，考虑图像的填充。
labels_patch = self._update_labels(labels_patch, padw, padh)
# 将更新后的标签信息添加到 mosaic_labels 列表中。
mosaic_labels.append(labels_patch)
# 合并标签。调用 _cat_labels 方法合并所有图像块的标签信息。
final_labels = self._cat_labels(mosaic_labels)
# 裁剪最终图像。将拼接后的图像赋值给 final_labels 字典的 "img" 键。
final_labels["img"] = img4
# 返回结果。返回包含最终图像和标签信息的字典。
return final_labels
# _mosaic4 方法实现了2x2图像拼接的Mosaic数据增强技术。它通过创建一个2倍图像大小的基底图像，将4个图像块分别放置在左上角、右上角、左下角和右下角位置，然后更新和合并标签信息，得到最终的Mosaic图像。这个方法为Mosaic数据增强提供了一种灵活的实现方式，适用于目标检测任务中的数据增强。
# 通过一个具体的例子来详细说明 _mosaic4 方法中各个坐标值和填充值的计算过程。假设我们有4张图像用于2x2的Mosaic拼接，每张图像的尺寸都是640x640，模型输入尺寸也是640x640。
# 假设条件 ：
# self.imgsz = 640 ：每张图像的尺寸为640x640。
# self.border = (-320, -320) ：边界值为图像尺寸的一半的负值，即-320。
# yc, xc ：Mosaic中心坐标，假设随机生成的值为 yc = 640 和 xc = 640 。
# 图像和标签数据 ：
# 假设 labels 字典如下 ：
# labels = {
# "img": current_image_data, # 当前图像的数据
# "resized_shape": (640, 640), # 当前图像调整后的尺寸
# "cls": [1, 2, 3], # 当前图像的类别标签
# "instances": current_instances, # 当前图像的边界框信息
# "mix_labels": [
# {
# "img": image_data_1, # 第一张图像的数据
# "resized_shape": (640, 640), # 第一张图像调整后的尺寸
# "cls": [1, 2], # 第一张图像的类别标签
# "instances": instances_1 # 第一张图像的边界框信息
# },
# {
# "img": image_data_2, # 第二张图像的数据
# "resized_shape": (640, 640), # 第二张图像调整后的尺寸
# "cls": [3, 4], # 第二张图像的类别标签
# "instances": instances_2 # 第二张图像的边界框信息
# },
# {
# "img": image_data_3, # 第三张图像的数据
# "resized_shape": (640, 640), # 第三张图像调整后的尺寸
# "cls": [5, 6], # 第三张图像的类别标签
# "instances": instances_3 # 第三张图像的边界框信息
# }
# ]
# }
# 计算过程 ：
# 创建基底图像 ：
# img4 = np.full((1280, 1280, 3), 114, dtype=np.uint8) ：创建一个1280x1280x3的基底图像，填充值为114。
# 处理每个图像块 ：
# 左上角图像块 (i == 0) ：
# x1a, y1a, x2a, y2a = max(640 - 640, 0), max(640 - 640, 0), 640, 640 => 0, 0, 640, 640
# x1b, y1b, x2b, y2b = 640 - (640 - 0), 640 - (640 - 0), 640, 640 => 0, 0, 640, 640
# padw = 0 - 0 = 0
# padh = 0 - 0 = 0
# 右上角图像块 (i == 1) ：
# x1a, y1a, x2a, y2a = 640, max(640 - 640, 0), min(640 + 640, 1280), 640 => 640, 0, 1280, 640
# x1b, y1b, x2b, y2b = 0, 640 - (640 - 0), min(640, 1280 - 640), 640 => 0, 0, 640, 640
# padw = 640 - 0 = 640
# padh = 0 - 0 = 0
# 左下角图像块 (i == 2) ：
# x1a, y1a, x2a, y2a = max(640 - 640, 0), 640, 640, min(1280, 640 + 640) => 0, 640, 640, 1280
# x1b, y1b, x2b, y2b = 640 - (640 - 0), 0, 640, min(640, 1280 - 640) => 0, 0, 640, 640
# padw = 0 - 0 = 0
# padh = 640 - 0 = 640
# 右下角图像块 (i == 3) ：
# x1a, y1a, x2a, y2a = 640, 640, min(640 + 640, 1280), min(1280, 640 + 640) => 640, 640, 1280, 1280
# x1b, y1b, x2b, y2b = 0, 0, min(640, 1280 - 640), min(640, 1280 - 640) => 0, 0, 640, 640
# padw = 640 - 0 = 640
# padh = 640 - 0 = 640
# 图像填充 ：
# 左上角图像块 ： img4[0:640, 0:640] = img[0:640, 0:640]
# 右上角图像块 ： img4[0:640, 640:1280] = img[0:640, 0:640]
# 左下角图像块 ： img4[640:1280, 0:640] = img[0:640, 0:640]
# 右下角图像块 ： img4[640:1280, 640:1280] = img[0:640, 0:640]
# 标签更新 :
# 左上角图像块 : labels_patch = self._update_labels(labels_patch, 0, 0)
# 右上角图像块 : labels_patch = self._update_labels(labels_patch, 640, 0)
# 左下角图像块 : labels_patch = self._update_labels(labels_patch, 0, 640)
# 右下角图像块 : labels_patch = self._update_labels(labels_patch, 640, 640)
# 合并标签 : final_labels = self._cat_labels(mosaic_labels)
# 裁剪最终图像 : final_labels["img"] = img4
# 返回结果 : return final_labels
# 总结 :
# 通过这个例子，可以看到每个图像块的坐标范围和填充值的计算过程。这些计算确保了每个图像块正确地放置在基底图像的相应位置，并且标签信息也相应地进行了更新。最终，得到了一个1280x1280的Mosaic图像，其中包含了4个640x640的图像块。
# 这段代码定义了 Mosaic 类中的 _mosaic9 方法，用于创建一个3x3的图像拼接（Mosaic）。
# 定义了 _mosaic9 方法，接收一个参数。
# 1.labels ：这是一个字典，包含了当前图像的标签信息以及可能的其他图像的标签信息。
def _mosaic9(self, labels):
"""Create a 3x3 image mosaic."""
# 初始化一个空列表，用于存储每个图像块的标签信息。
mosaic_labels = []
# 获取 图像大小 ，用于后续的图像拼接和坐标计算。
s = self.imgsz
# 初始化 前一个图像的高度和宽度 ，初始值为-1，用于后续的坐标计算。
hp, wp = -1, -1 # height, width previous
# 循环处理每个图像块。
# 循环9次，处理9个图像块。
for i in range(9):
# 如果当前是第一个图像块（中心图像），则使用传入的 labels ；否则，从 mix_labels 中获取其他图像的标签信息。
labels_patch = labels if i == 0 else labels["mix_labels"][i - 1]
# Load image
# 从 labels_patch 中获取 图像数据 。
img = labels_patch["img"]
# 从 labels_patch 中获取 图像的调整后的尺寸 ，并从字典中移除该键值对。
h, w = labels_patch.pop("resized_shape")
# Place img in img9
# 如果是中心图像块。
if i == 0: # center
# 创建一个3倍图像大小的基底图像，填充值为114（通常用于表示背景）。
img9 = np.full((s * 3, s * 3, img.shape[2]), 114, dtype=np.uint8) # base image with 4 tiles
# 保存中心图像的尺寸。
h0, w0 = h, w
# 计算中心图像块的坐标范围。
c = s, s, s + w, s + h # xmin, ymin, xmax, ymax (base) coordinates
# 如果是顶部中间图像块。
elif i == 1: # top
# 计算顶部中间图像块的坐标范围。
c = s, s - h, s + w, s
# 如果是右上角图像块。
elif i == 2: # top right
# 计算右上角图像块的坐标范围。
c = s + wp, s - h, s + wp + w, s
# 如果是右侧中间图像块。
elif i == 3: # right
# 计算右侧中间图像块的坐标范围。
c = s + w0, s, s + w0 + w, s + h
# 如果是右下角图像块。
elif i == 4: # bottom right
# 计算右下角图像块的坐标范围。
c = s + w0, s + hp, s + w0 + w, s + hp + h
# 如果是底部中间图像块。
elif i == 5: # bottom
# 计算底部中间图像块的坐标范围。
c = s + w0 - w, s + h0, s + w0, s + h0 + h
# 如果是左下角图像块。
elif i == 6: # bottom left
# 计算左下角图像块的坐标范围。
c = s + w0 - wp - w, s + h0, s + w0 - wp, s + h0 + h
# 如果是左侧中间图像块。
elif i == 7: # left
# 计算左侧中间图像块的坐标范围。
c = s - w, s + h0 - h, s, s + h0
# 如果是左上角图像块。
elif i == 8: # top left
# 计算左上角图像块的坐标范围。
c = s - w, s + h0 - hp - h, s, s + h0 - hp
# 坐标调整。
# 获取填充宽度和高度。
padw, padh = c[:2]
# 确保坐标值不为负数。
x1, y1, x2, y2 = (max(x, 0) for x in c) # allocate coords
# Image
# 将当前图像块填充到基底图像的相应位置。
img9[y1:y2, x1:x2] = img[y1 - padh :, x1 - padw :] # img9[ymin:ymax, xmin:xmax]
# 更新前一个图像的高度和宽度，用于下一个图像块的坐标计算。
hp, wp = h, w # height, width previous for next iteration
# 标签更新。
# Labels assuming imgsz*2 mosaic size
# 调用 _update_labels 方法更新标签信息，考虑图像的填充和边界。
labels_patch = self._update_labels(labels_patch, padw + self.border[0], padh + self.border[1])
# 将更新后的标签信息添加到 mosaic_labels 列表中。
mosaic_labels.append(labels_patch)
# 合并标签。调用 _cat_labels 方法合并所有图像块的标签信息。
final_labels = self._cat_labels(mosaic_labels)
# 裁剪最终图像。裁剪基底图像，去除边界部分，得到最终的Mosaic图像。
final_labels["img"] = img9[-self.border[0] : self.border[0], -self.border[1] : self.border[1]]
# 返回结果。返回包含最终图像和标签信息的字典。
return final_labels
# _mosaic9 方法实现了3x3图像拼接的Mosaic数据增强技术。它通过创建一个3倍图像大小的基底图像，将9个图像块分别放置在相应的位置，然后更新和合并标签信息，得到最终的Mosaic图像。这个方法为Mosaic数据增强提供了一种灵活的实现方式，适用于目标检测任务中的数据增强。
# 这段代码定义了一个静态方法 _update_labels ，用于更新图像标签信息，特别是在进行图像拼接（如Mosaic数据增强）时，考虑图像的填充（padding）。
# 装饰器，表示下面的方法是一个静态方法，不需要实例化类就可以调用。
@staticmethod
# 定义了 _update_labels 方法，接收三个参数。
# 1.labels ：一个字典，包含图像的标签信息。
# 2.padw ：水平方向的填充像素数。
# 3.padh ：垂直方向的填充像素数。
def _update_labels(labels, padw, padh):
# 更新标签。
"""Update labels."""
# 获取图像尺寸。从 labels 字典中获取图像数据 labels["img"] ，并提取其 高度 nh 和 宽度 nw 。 shape[:2] 表示取图像数据的前两个维度，即高度和宽度。
nh, nw = labels["img"].shape[:2]
# 更新边界框格式。调用 labels["instances"] 对象的 convert_bbox 方法，将边界框格式转换为 xyxy 格式。 xyxy 格式表示边界框的左上角和右下角坐标，即 [x1, y1, x2, y2] 。
labels["instances"].convert_bbox(format="xyxy")
# 反归一化。调用 labels["instances"] 对象的 denormalize 方法，将边界框坐标从归一化坐标转换为实际像素坐标。 denormalize 方法需要传入图像的宽度 nw 和高度 nh ，以便进行反归一化。
labels["instances"].denormalize(nw, nh)
# 添加填充。调用 labels["instances"] 对象的 add_padding 方法，将边界框坐标调整为考虑填充后的坐标。 add_padding 方法需要传入 水平方向的填充像素数 padw 和 垂直方向的填充像素数 padh ，以便更新边界框坐标。
# def add_padding(self, padw, padh): -> 用于在实例中的边界框、分割掩码和关键点的坐标上添加填充偏移。
labels["instances"].add_padding(padw, padh)
# 返回更新后的标签。返回更新后的 labels 字典，其中包含更新后的边界框坐标。
return labels
# _update_labels 方法用于在图像拼接（如Mosaic数据增强）时更新图像的标签信息。获取图像的尺寸。将边界框格式转换为 xyxy 格式。将边界框坐标从归一化坐标转换为实际像素坐标。考虑图像的填充，更新边界框坐标。这个方法确保在图像拼接后，边界框坐标仍然准确地表示目标对象的位置，从而保证数据增强的有效性和准确性。
# 这段代码定义了 Mosaic 类中的 _cat_labels 方法，用于合并多个图像块的标签信息，并裁剪超出Mosaic边界的部分。
# 定义了 _cat_labels 方法，接收一个参数。
# 1.mosaic_labels ：这是一个列表，包含每个图像块的标签信息。
def _cat_labels(self, mosaic_labels):
# 返回带有裁剪的马赛克边框实例的标签。
"""Return labels with mosaic border instances clipped."""
# 检查 mosaic_labels 列表是否为空。
if len(mosaic_labels) == 0:
# 如果列表为空，返回一个空字典。
return {}
# 初始化一个空列表，用于存储所有图像块的 类别标签 。
cls = []
# 初始化一个空列表，用于存储所有图像块的 边界框信息 。
instances = []
# 计算Mosaic图像的尺寸，通常是 单个图像尺寸的两倍 。
imgsz = self.imgsz * 2 # mosaic imgsz
# 循环处理每个图像块。
# 遍历 mosaic_labels 列表中的每个图像块的标签信息。
for labels in mosaic_labels:
# 将当前图像块的 类别标签 添加到 cls 列表中。
cls.append(labels["cls"])
# 将当前图像块的 边界框信息 添加到 instances 列表中。
instances.append(labels["instances"])
# Final labels
# 合并标签。初始化一个字典，用于存储最终的标签信息。
final_labels = {
# 设置最终图像的文件路径，通常取第一个图像块的文件路径。
"im_file": mosaic_labels[0]["im_file"],
# 设置最终图像的原始尺寸，通常取第一个图像块的原始尺寸。
"ori_shape": mosaic_labels[0]["ori_shape"],
# 设置最终图像的调整后尺寸，通常是单个图像尺寸的两倍。
"resized_shape": (imgsz, imgsz),
# 将所有图像块的类别标签合并为一个数组。
"cls": np.concatenate(cls, 0),
# 将所有图像块的边界框信息合并为一个 Instances 对象。
# def concatenate(cls, instances_list: List["Instances"], axis=0) -> "Instances":
# -> 将多个 Instances 实例合并为一个新的 Instances 实例。使用合并后的边界框、分割掩码、关键点、边界框格式和归一化状态创建一个新的 Instances 实例。返回这个新的 Instances 实例，它包含了合并后的所有数据。
# -> return cls(cat_boxes, cat_segments, cat_keypoints, bbox_format, normalized)
"instances": Instances.concatenate(instances, axis=0),
# 设置Mosaic图像的边界。
"mosaic_border": self.border,
}
# 裁剪边界框。
# 调用 Instances 对象的 clip 方法，裁剪超出Mosaic边界的部分。
# def clip(self, w, h): -> 用于将实例中的边界框、分割掩码和关键点的坐标裁剪到指定的范围内，以确保它们不会超出图像的边界。
final_labels["instances"].clip(imgsz, imgsz)
# 调用 Instances 对象的 remove_zero_area_boxes 方法，移除面积为零的边界框，并返回有效的边界框索引。
# def remove_zero_area_boxes(self): -> 用于移除面积为零的边界框及其对应的分割掩码和关键点。返回布尔数组 good ，表示哪些边界框的面积大于零。这可以用于进一步的处理或检查。 -> return good
good = final_labels["instances"].remove_zero_area_boxes()
# 根据有效的边界框索引，更新类别标签数组。
final_labels["cls"] = final_labels["cls"][good]
# 返回包含最终图像和标签信息的字典。
return final_labels
# _cat_labels 方法用于合并多个图像块的标签信息，并裁剪超出Mosaic边界的部分。检查输入列表是否为空。初始化类别标签和边界框信息的列表。循环处理每个图像块，将类别标签和边界框信息添加到列表中。合并所有图像块的标签信息，创建最终的标签字典。裁剪超出Mosaic边界的部分，移除面积为零的边界框。返回包含最终图像和标签信息的字典。这个方法确保在Mosaic数据增强后，标签信息仍然准确地表示目标对象的位置，从而保证数据增强的有效性和准确性。
# Mosaic 类实现了Mosaic数据增强技术，通过拼接多张图像来创建新的训练样本。这个类继承自 BaseMixTransform ，并实现了具体的Mosaic变换逻辑，包括图像的拼接和标签的更新。通过不同的方法，支持2x2和3x3的Mosaic网格，以及从数据集缓冲区或整个数据集中选择图像进行拼接。6.class MixUp(BaseMixTransform):
# 这段代码定义了一个名为 MixUp 的类，继承自 BaseMixTransform 类，用于实现MixUp数据增强技术。MixUp通过混合两张图像及其标签来创建新的训练样本，从而增加数据的多样性，提高模型的泛化能力。
# 定义了 MixUp 类，继承自 BaseMixTransform 类。
class MixUp(BaseMixTransform):
# 用于将 MixUp 增强应用于数据集的类。
"""Class for applying MixUp augmentation to the dataset."""
# 初始化方法。
# 定义了 MixUp 类的初始化方法，接收三个参数。
# 1.dataset ：数据集对象，提供图像及其标签的数据源。
# 2.pre_transform ：预变换操作，可选，默认为 None 。
# 3.p ：执行MixUp变换的概率，默认为0.0。
def __init__(self, dataset, pre_transform=None, p=0.0) -> None:
# 使用 dataset 、pre_transform 和 pre_transform MixUp 的概率初始化 MixUp 对象。
"""Initializes MixUp object with dataset, pre_transform, and probability of applying MixUp."""
# 调用父类 BaseMixTransform 的初始化方法，传入 dataset 、 pre_transform 和 p 参数。
super().__init__(dataset=dataset, pre_transform=pre_transform, p=p)
# 获取随机索引。
# 定义了 get_indexes 方法，用于从数据集中获取一个随机索引。
def get_indexes(self):
# 从数据集中获取一个随机索引。
"""Get a random index from the dataset."""
# 返回一个在 [0, len(self.dataset) - 1] 范围内的随机整数，表示数据集中的一个随机索引。
return random.randint(0, len(self.dataset) - 1)
# 这段代码定义了 MixUp 类中的 _mix_transform 方法，用于应用MixUp数据增强技术。MixUp通过混合两张图像及其标签来创建新的训练样本，从而增加数据的多样性，提高模型的泛化能力。
# 定义了 _mix_transform 方法，接收一个参数。
# 1.labels ：这是一个字典，包含了当前图像的标签信息以及可能的其他图像的标签信息。
def _mix_transform(self, labels):
# 按照 https://arxiv.org/pdf/1710.09412.pdf 应用 MixUp 增强。
"""Applies MixUp augmentation as per https://arxiv.org/pdf/1710.09412.pdf."""
# np.random.beta(a, b, size=None)
# np.random.beta 是 NumPy 库中的一个函数，用于从贝塔分布（Beta distribution）中生成随机样本。贝塔分布是一种定义在区间 [0, 1] 上的连续概率分布，常用于表示概率或比例等值。
# 参数 :
# a 和 b ：贝塔分布的两个形状参数（shape parameters），它们是正实数。这两个参数定义了贝塔分布的形状，其中 a 和 b 越大，分布越接近正态分布。
# size ：输出数组的形状。如果未指定， np.random.beta 将返回一个单一的随机样本。如果指定，它将返回一个给定形状的数组，数组中的每个元素都是从贝塔分布中抽取的随机样本。
# 返回值 :
# 返回一个或一组从贝塔分布中抽取的随机样本。如果 size 参数未指定，返回一个浮点数；如果指定了 size 参数，返回一个 NumPy 数组。
# 生成混合比例。生成一个Beta分布的随机数 r ，用于表示混合比例。这里使用 alpha=beta=32.0 ，根据论文中的建议，这个值可以调整。Beta分布生成的随机数 r 在[0, 1]范围内，表示第一个图像在混合图像中的权重。
r = np.random.beta(32.0, 32.0) # mixup ratio, alpha=beta=32.0
# 获取第二个图像的标签信息。从 labels 字典中获取第二个图像的标签信息。 labels["mix_labels"] 是一个列表，包含其他图像的标签信息，这里取第一个元素。
labels2 = labels["mix_labels"][0]
# 混合图像。将两个图像按比例混合，生成新的图像数据。
# labels["img"] * r ：将当前图像乘以混合比例 r 。
# labels2["img"] * (1 - r) ：将第二个图像乘以 1 - r 。
# (labels["img"] * r + labels2["img"] * (1 - r)) ：将两个图像按比例相加。
# .astype(np.uint8) ：将结果转换为 np.uint8 类型，确保图像数据的类型一致。
labels["img"] = (labels["img"] * r + labels2["img"] * (1 - r)).astype(np.uint8)
# 合并边界框信息。将两个图像的边界框信息合并。 Instances.concatenate 方法用于合并多个 Instances 对象， axis=0 表示在第一个维度（即样本维度）上进行合并。
labels["instances"] = Instances.concatenate([labels["instances"], labels2["instances"]], axis=0)
# 合并类别标签。将两个图像的类别标签合并。 np.concatenate 方法用于合并多个数组， 0 表示在第一个维度（即样本维度）上进行合并。
labels["cls"] = np.concatenate([labels["cls"], labels2["cls"]], 0)
# 返回更新后的标签。返回更新后的 labels 字典，包含混合后的图像和标签信息。
return labels
# _mix_transform 方法实现了MixUp数据增强技术，通过混合两张图像及其标签来创建新的训练样本。生成一个Beta分布的随机数，表示混合比例。获取第二个图像的标签信息。按比例混合两个图像的数据，生成新的图像。合并两个图像的边界框信息和类别标签。返回包含混合后图像和标签信息的字典。这个方法为MixUp数据增强提供了一种灵活的实现方式，适用于图像分类和目标检测任务中的数据增强。通过增加数据的多样性，MixUp有助于提高模型的泛化能力和鲁棒性。
# MixUp 类实现了MixUp数据增强技术，通过混合两张图像及其标签来创建新的训练样本。初始化类实例，设置数据集、预变换操作和执行概率。从数据集中获取一个随机索引，用于选择第二个图像。生成一个Beta分布的随机数，表示混合比例。按比例混合两个图像的数据，生成新的图像。合并两个图像的边界框信息和类别标签。返回包含混合后图像和标签信息的字典。这个类为MixUp数据增强提供了一种灵活的实现方式，适用于图像分类和目标检测任务中的数据增强。通过增加数据的多样性，MixUp有助于提高模型的泛化能力和鲁棒性。7.class RandomPerspective:
# 这段代码定义了一个名为 RandomPerspective 的类，用于对图像进行随机透视变换，包括旋转、缩放、剪切、平移和透视效果。这种变换常用于数据增强，特别是在目标检测和图像分类任务中。
# 定义了 RandomPerspective 类。
class RandomPerspective:
# 在图像和相应的边界框、片段和关键点上实现随机透视和仿射变换。这些变换包括旋转、平移、缩放和剪切。该类还提供以指定概率有条件地应用这些变换的选项。
# 方法：
# affine_transform(img, border)：对图像应用一系列仿射变换。
# apply_bboxes(bboxes, M)：使用计算仿射矩阵。
# apply_segments(segments, M)：转换段并生成新的边界框。
# apply_keypoints(keypoints, M)：转换关键点。
# __call__(labels)：将转换应用于图像及其相应注释的主要方法。
# box_candidates(box1, box2)：过滤掉转换后不符合特定标准的边界框。
"""
Implements random perspective and affine transformations on images and corresponding bounding boxes, segments, and
keypoints. These transformations include rotation, translation, scaling, and shearing. The class also offers the
option to apply these transformations conditionally with a specified probability.
Attributes:
degrees (float): Degree range for random rotations.
translate (float): Fraction of total width and height for random translation.
scale (float): Scaling factor interval, e.g., a scale factor of 0.1 allows a resize between 90%-110%.
shear (float): Shear intensity (angle in degrees).
perspective (float): Perspective distortion factor.
border (tuple): Tuple specifying mosaic border.
pre_transform (callable): A function/transform to apply to the image before starting the random transformation.
Methods:
affine_transform(img, border): Applies a series of affine transformations to the image.
apply_bboxes(bboxes, M): Transforms bounding boxes using the calculated affine matrix.
apply_segments(segments, M): Transforms segments and generates new bounding boxes.
apply_keypoints(keypoints, M): Transforms keypoints.
__call__(labels): Main method to apply transformations to both images and their corresponding annotations.
box_candidates(box1, box2): Filters out bounding boxes that don't meet certain criteria post-transformation.
"""
# 这段代码是 RandomPerspective 类的初始化方法 __init__ 的定义，用于创建 RandomPerspective 类的实例并初始化其属性。 RandomPerspective 类用于对图像进行随机透视变换，包括旋转、缩放、剪切、平移和透视效果。这些变换常用于数据增强，特别是在目标检测和图像分类任务中。
# 定义了 RandomPerspective 类的初始化方法 __init__ ，它接收多个参数。
# 1.degrees ：旋转角度范围，默认为0.0度。表示图像可以随机旋转的最大角度。
# 2.translate ：平移比例范围，默认为0.1。表示图像可以随机平移的最大比例。
# 3.scale ：缩放比例范围，默认为0.5。表示图像可以随机缩放的最大比例。
# 4.shear ：剪切角度范围，默认为0.0度。表示图像可以随机剪切的最大角度。
# 5.perspective ：透视变换比例范围，默认为0.0。表示图像可以随机透视变换的最大比例。
# 6.border ：Mosaic边界的尺寸，默认为(0, 0)。表示在图像周围添加的边界像素数。
# 7.pre_transform ：预变换操作，可选，默认为 None 。表示在应用随机透视变换之前可以应用的预变换操作。
def __init__(
self, degrees=0.0, translate=0.1, scale=0.5, shear=0.0, perspective=0.0, border=(0, 0), pre_transform=None
):
# 使用转换参数初始化 RandomPerspective 对象。
"""Initializes RandomPerspective object with transformation parameters."""
# 初始化属性。
# 将传入的 degrees 参数赋值给实例变量 self.degrees ，用于控制 图像的旋转角度范围 。
self.degrees = degrees
# 将传入的 translate 参数赋值给实例变量 self.translate ，用于控制 图像的平移比例范围 。
self.translate = translate
# 将传入的 scale 参数赋值给实例变量 self.scale ，用于控制 图像的缩放比例范围 。
self.scale = scale
# 将传入的 shear 参数赋值给实例变量 self.shear ，用于控制 图像的剪切角度范围 。
self.shear = shear
# 将传入的 perspective 参数赋值给实例变量 self.perspective ，用于控制 图像的透视变换比例范围 。
self.perspective = perspective
# 将传入的 border 参数赋值给实例变量 self.border ，用于控制 图像周围的边界像素数 。
self.border = border # mosaic border
# 将传入的 pre_transform 参数赋值给实例变量 self.pre_transform ，用于 存储预变换操作 。
self.pre_transform = pre_transform
# RandomPerspective 类的初始化方法 __init__ 用于设置各种变换参数，这些参数控制图像的旋转、平移、缩放、剪切和透视变换。通过这些参数，可以灵活地生成多种数据增强效果，提高模型的泛化能力。预变换操作 pre_transform 允许在应用随机透视变换之前对图像进行其他处理，增加了数据增强的灵活性。
# 这段代码定义了 RandomPerspective 类中的 affine_transform 方法，用于对图像进行仿射变换，包括旋转、缩放、剪切、平移和透视效果。这个方法通过一系列的矩阵操作来实现这些变换，并最终应用到图像上。
# 定义了 affine_transform 方法，接收两个参数。
# 1.img ：输入图像，一个三维的NumPy数组。
# 2.border ：边界尺寸，一个包含两个元素的元组，表示图像周围的边界像素数。
def affine_transform(self, img, border):
# 应用以图像中心为中心的一系列仿射变换。
"""
Applies a sequence of affine transformations centered around the image center.
Args:
img (ndarray): Input image.
border (tuple): Border dimensions.
Returns:
img (ndarray): Transformed image.
M (ndarray): Transformation matrix.
s (float): Scale factor.
"""
# Center
# 中心化变换。
# 创建一个3x3的单位矩阵，用于中心化变换。
C = np.eye(3, dtype=np.float32)
# 设置x方向的平移量，将图像中心移到原点。
C[0, 2] = -img.shape[1] / 2 # x translation (pixels)
# 设置y方向的平移量，将图像中心移到原点。
C[1, 2] = -img.shape[0] / 2 # y translation (pixels)
# Perspective
# 透视变换。
# 创建一个3x3的单位矩阵，用于透视变换。
P = np.eye(3, dtype=np.float32)
# 设置x方向的透视变换参数，范围在 [-self.perspective, self.perspective] 之间。
P[2, 0] = random.uniform(-self.perspective, self.perspective) # x perspective (about y)
# 设置y方向的透视变换参数，范围在 [-self.perspective, self.perspective] 之间。
P[2, 1] = random.uniform(-self.perspective, self.perspective) # y perspective (about x)
# Rotation and Scale
# 旋转和缩放变换。
# 创建一个3x3的单位矩阵，用于旋转和缩放变换。
R = np.eye(3, dtype=np.float32)
# 生成一个随机旋转角度，范围在 [-self.degrees, self.degrees] 之间。
a = random.uniform(-self.degrees, self.degrees)
# a += random.choice([-180, -90, 0, 90]) # add 90deg rotations to small rotations
# 生成一个随机缩放比例，范围在 [1 - self.scale, 1 + self.scale] 之间。
s = random.uniform(1 - self.scale, 1 + self.scale)
# s = 2 ** random.uniform(-scale, scale)
# cv2.getRotationMatrix2D(center, angle, scale)
# cv2.getRotationMatrix2D() 是 OpenCV 库中的一个函数，用于生成二维旋转矩阵。这个函数在图像处理和计算机视觉任务中非常有用，尤其是在需要旋转图像时。
# 参数 ：
# center ：旋转中心点，通常是一个 (x, y) 的二元组，表示图像中旋转轴的中心点。
# angle ：旋转角度，单位是度。正数表示逆时针旋转，负数表示顺时针旋转。
# scale ：缩放因子。当 scale 等于 1 时，表示没有缩放，图像大小不变；大于 1 表示放大；小于 1 表示缩小。
# 返回值 ：
# 函数返回一个 2x3 的仿射变换矩阵，该矩阵可以用于 cv2.warpAffine() 或 cv2.warpPerspective() 函数来对图像进行旋转。
# 矩阵形式 ：
# 返回的旋转矩阵 M 的形式如下 ：
# [ cos(θ) -sin(θ) tx ]
# [ sin(θ) cos(θ) ty ]
# 其中， θ 是旋转角度， tx 和 ty 是平移量。
# 由于 cv2.getRotationMatrix2D() 生成的 tx 和 ty 实际上是为了确保图像围绕指定的中心点旋转而不超出边界，它们并不是固定的，而是根据旋转中心和图像尺寸动态计算的。
# 生成旋转和缩放矩阵。
R[:2] = cv2.getRotationMatrix2D(angle=a, center=(0, 0), scale=s)
# Shear
# 剪切变换。
# 创建一个3x3的单位矩阵，用于剪切变换。
S = np.eye(3, dtype=np.float32)
# 设置x方向的剪切参数，范围在 [-self.shear, self.shear] 之间，转换为弧度。
S[0, 1] = math.tan(random.uniform(-self.shear, self.shear) * math.pi / 180) # x shear (deg)
# 设置y方向的剪切参数，范围在 [-self.shear, self.shear] 之间，转换为弧度。
S[1, 0] = math.tan(random.uniform(-self.shear, self.shear) * math.pi / 180) # y shear (deg)
# Translation
# 平移变换。
# 创建一个3x3的单位矩阵，用于平移变换。
T = np.eye(3, dtype=np.float32)
# 设置x方向的平移量，范围在 [0.5 - self.translate, 0.5 + self.translate] 之间，乘以图像的宽度。
T[0, 2] = random.uniform(0.5 - self.translate, 0.5 + self.translate) * self.size[0] # x translation (pixels)
# 设置y方向的平移量，范围在 [0.5 - self.translate, 0.5 + self.translate] 之间，乘以图像的高度。
T[1, 2] = random.uniform(0.5 - self.translate, 0.5 + self.translate) * self.size[1] # y translation (pixels)
# Combined rotation matrix
# 综合变换矩阵。计算综合变换矩阵，注意操作顺序从右到左是重要的。这个矩阵包含了中心化、透视、旋转、剪切和平移变换。
M = T @ S @ R @ P @ C # order of operations (right to left) is IMPORTANT
# Affine image
# 应用仿射变换。
# 检查图像是否需要变换。
if (border[0] != 0) or (border[1] != 0) or (M != np.eye(3)).any(): # image changed
# 如果启用透视变换，使用 cv2.warpPerspective 进行透视变换。
if self.perspective:
img = cv2.warpPerspective(img, M, dsize=self.size, borderValue=(114, 114, 114))
# 否则，使用 cv2.warpAffine 进行仿射变换。
else: # affine
img = cv2.warpAffine(img, M[:2], dsize=self.size, borderValue=(114, 114, 114))
# 返回 变换后的图像 、 变换矩阵 和 缩放比例 。
return img, M, s
# affine_transform 方法通过一系列的矩阵操作实现了图像的仿射变换，包括旋转、缩放、剪切、平移和透视效果。这些变换常用于数据增强，特别是在目标检测和图像分类任务中。通过这些变换，可以生成多样化的训练样本，提高模型的泛化能力。
# 透视变换（Perspective Transformation）和仿射变换（Affine Transformation）是图像处理中常用的两种几何变换，它们用于对图像进行各种几何操作，如旋转、缩放、平移和剪切。下面分别介绍这两种变换的定义、特点以及它们之间的区别。
# 透视变换（Perspective Transformation） ：
# 定义 ：透视变换是一种二维到三维的投影变换，它可以模拟相机拍摄图像时的透视效果。透视变换可以将一个平面内的点映射到另一个平面内的点，同时考虑了深度信息。这种变换通常用于处理图像中的透视畸变，例如将一张拍摄的桌面图像校正为正视图。
# 数学表示 ：透视变换通常用一个3x3的矩阵表示，可以处理更复杂的变换，包括旋转、缩放、平移和透视效果。
# 特点 ：可以处理透视畸变，模拟相机的视角效果。 可以将一个四边形映射到另一个四边形。 保留直线，但不保留平行线（平行线在透视变换后可能不再平行）。
# 仿射变换（Affine Transformation） ：
# 定义 ：仿射变换是一种二维到二维的线性变换，它保持了图像中的直线和平行线。仿射变换可以用于旋转、缩放、平移和剪切操作。仿射变换不考虑深度信息，因此它是一种更简单的变换。
# 数学表示 ：仿射变换通常用一个2x3的矩阵表示，可以处理旋转、缩放、平移和剪切操作。
# 特点 ：保持直线和平行线，即变换后的图像中，平行线仍然是平行的。 可以处理旋转、缩放、平移和剪切操作。 不能处理透视畸变。
# 透视变换与仿射变换的区别 ：
# 处理的维度 ：
# 透视变换 ：是一种三维变换，可以处理更复杂的几何变换，包括透视效果。
# 仿射变换 ：是一种二维变换，只能处理平面内的几何变换。
# 矩阵形式 ：
# 透视变换 ：使用3x3的矩阵。
# 仿射变换 ：使用2x3的矩阵。
# 保留的几何特性 ：
# 透视变换 ：保留直线，但不保留平行线。
# 仿射变换 ：保留直线和平行线。
# 应用场景 ：
# 透视变换 ：适用于处理透视畸变，例如将拍摄的桌面图像校正为正视图。
# 仿射变换 ：适用于处理旋转、缩放、平移和剪切操作，常用于图像的常规几何变换。
# 示例 ：
# 假设我们有一张拍摄的桌面图像，桌面在图像中呈现透视畸变。使用透视变换可以将这张图像校正为正视图，而仿射变换则可以用于将图像旋转、缩放或平移。
# 总结 ：
# 透视变换和仿射变换都是图像处理中重要的几何变换技术。透视变换可以处理更复杂的透视效果，而仿射变换则适用于简单的平面几何变换。根据具体的应用场景选择合适的变换方法，可以有效地处理图像中的各种几何问题。
# 这段代码定义了 RandomPerspective 类中的 apply_bboxes 方法，用于对边界框（bounding boxes）进行透视变换或仿射变换。
# 定义了 apply_bboxes 方法，接收两个参数。
# 1.bboxes ：一个二维数组，每一行表示一个边界框，格式为 [x1, y1, x2, y2] 。
# 2.M ：一个3x3的变换矩阵，用于对边界框进行变换。
def apply_bboxes(self, bboxes, M):
# 仅将仿射应用于 bboxes。
# 参数：
# bboxes (ndarray)：bboxes 列表，xyxy 格式，形状为 (num_bboxes, 4)。
# M (ndarray)：仿射矩阵。
# 返回：
# new_bboxes (ndarray)：仿射后的 bboxes，[num_bboxes, 4]。
"""
Apply affine to bboxes only.
Args:
bboxes (ndarray): list of bboxes, xyxy format, with shape (num_bboxes, 4).
M (ndarray): affine matrix.
Returns:
new_bboxes (ndarray): bboxes after affine, [num_bboxes, 4].
"""
# 检查边界框数量。
# 获取边界框的数量。
n = len(bboxes)
# 如果边界框数量为0，直接返回空数组。
if n == 0:
# 返回空的边界框数组。
return bboxes
# 创建坐标矩阵。
# 创建一个形状为 (n * 4, 3) 的矩阵，用于存储边界框的四个角的坐标。每个边界框有四个角，因此总共有 n * 4 个点。矩阵的第三列初始化为1，用于透视变换。
xy = np.ones((n * 4, 3), dtype=bboxes.dtype)
# 将边界框的四个角的坐标展开为 (n * 4, 2) 的矩阵。具体顺序为 [x1, y1, x2, y2, x1, y2, x2, y1] ，即左上角、右下角、左下角、右上角。
xy[:, :2] = bboxes[:, [0, 1, 2, 3, 0, 3, 2, 1]].reshape(n * 4, 2) # x1y1, x2y2, x1y2, x2y1
# 应用变换矩阵。将坐标矩阵 xy 与变换矩阵 M 的转置相乘，应用变换。
xy = xy @ M.T # transform
# 如果启用透视变换，进行透视归一化；否则，直接取前两列。最后将结果重塑为 (n, 8) 的矩阵，每行表示一个边界框的四个角的坐标。
xy = (xy[:, :2] / xy[:, 2:3] if self.perspective else xy[:, :2]).reshape(n, 8) # perspective rescale or affine
# Create new boxes
# 创建新的边界框。
# 提取变换后的x坐标。
x = xy[:, [0, 2, 4, 6]]
# 提取变换后的y坐标。
y = xy[:, [1, 3, 5, 7]]
# 计算 新的边界框坐标 ，格式为 [x_min, y_min, x_max, y_max] ，并返回。
# np.concatenate((x.min(1), y.min(1), x.max(1), y.max(1)), dtype=bboxes.dtype) ：将这些最小和最大值合并为一个数组。 dtype=bboxes.dtype 确保结果数组的数据类型与输入的 bboxes 数组相同。
# reshape(4, n) ：将合并后的数组重塑为一个形状为 (4, n) 的矩阵，其中每列代表一个边界框的四个坐标（ x_min, y_min, x_max, y_max ）。
# .T ：对矩阵进行转置，使其形状变为 (n, 4) ，每行代表一个边界框的四个坐标。
# 详细解释假 ：
# 设我们有以下边界框坐标数组 bboxes 和变换后的坐标矩阵 xy ：
# bboxes = np.array([
# [10, 10, 50, 50], # 边界框1
# [100, 100, 150, 150] # 边界框2
# ])
# xy = np.array([
# [10, 10, 50, 50, 10, 50, 50, 10], # 边界框1的四个角
# [100, 100, 150, 150, 100, 150, 150, 100] # 边界框2的四个角
# ])
# 计算最小和最大值 ：
# x.min(1) ：计算每个边界框的最小x坐标。 x_min = np.array([10, 100])
# y.min(1) ：计算每个边界框的最小y坐标。 y_min = np.array([10, 100])
# x.max(1) ：计算每个边界框的最大x坐标。 x_max = np.array([50, 150])
# y.max(1) ：计算每个边界框的最大y坐标。 y_max = np.array([50, 150])
# 合并这些值 ：
# np.concatenate((x_min, y_min, x_max, y_max), dtype=bboxes.dtype) ： new_bboxes = np.array([10, 10, 50, 50, 100, 100, 150, 150])
# 重塑数组 ：
# .reshape(4, 2) ：
# new_bboxes = np.array([
# [10, 100],
# [10, 100],
# [50, 150],
# [50, 150]
# ])
# .T ：
# new_bboxes = np.array([
# [10, 10, 50, 50],
# [100, 100, 150, 150]
# ])
# 最终结果 ：最终结果 new_bboxes 是一个形状为 (n, 4) 的数组，每行代表一个边界框的四个坐标（ x_min, y_min, x_max, y_max ）。
# 这行代码通过计算每个边界框的最小和最大x、y坐标，合并这些值，并重塑数组，最终生成新的边界框坐标。这些新的边界框坐标可以用于后续的图像处理和目标检测任务，确保边界框在变换后的图像中仍然准确地表示目标对象的位置。
return np.concatenate((x.min(1), y.min(1), x.max(1), y.max(1)), dtype=bboxes.dtype).reshape(4, n).T
# apply_bboxes 方法通过以下步骤对边界框进行透视变换或仿射变换，检查边界框数量，如果为0，直接返回。创建一个坐标矩阵，存储边界框的四个角的坐标。应用变换矩阵，对坐标进行变换。如果启用透视变换，进行透视归一化。计算新的边界框坐标，格式为 [x_min, y_min, x_max, y_max] ，并返回。这个方法确保在对图像进行透视变换或仿射变换后，边界框仍然准确地表示目标对象的位置，从而保证数据增强的有效性和准确性。
# 这段代码定义了 RandomPerspective 类中的 apply_segments 方法，用于对分割掩码（segments）进行透视变换或仿射变换。
# 定义了 apply_segments 方法，接收两个参数。
# 1.segments ：一个三维数组，每一行表示一个分割掩码，格式为 [x1, y1, x2, y2, ...] 。
# 2.M ：一个3x3的变换矩阵，用于对分割掩码进行变换。
def apply_segments(self, segments, M):
# 将仿射应用于片段并从片段生成新的 bbox。
# 参数：
# 片段 (ndarray)：片段列表，[num_samples, 500, 2]。
# M (ndarray)：仿射矩阵。
# 返回：
# new_segments (ndarray)：仿射后的片段列表，[num_samples, 500, 2]。
# new_bboxes (ndarray)：仿射后的 bbox，[N, 4]。
"""
Apply affine to segments and generate new bboxes from segments.
Args:
segments (ndarray): list of segments, [num_samples, 500, 2].
M (ndarray): affine matrix.
Returns:
new_segments (ndarray): list of segments after affine, [num_samples, 500, 2].
new_bboxes (ndarray): bboxes after affine, [N, 4].
"""
# 检查分割掩码数量。
# 获取 分割掩码的数量 n 和 每个分割掩码的点数 num 。
n, num = segments.shape[:2]
# 如果分割掩码数量为0，直接返回空数组和原始分割掩码。
if n == 0:
# 返回空的边界框数组和原始分割掩码。
return [], segments
# 创建坐标矩阵。
# 创建一个形状为 (n * num, 3) 的矩阵，用于存储分割掩码的坐标。每个分割掩码有 num 个点，因此总共有 n * num 个点。矩阵的第三列初始化为1，用于透视变换。
xy = np.ones((n * num, 3), dtype=segments.dtype)
# 将 分割掩码的坐标 展开为 (n * num, 2) 的矩阵。
segments = segments.reshape(-1, 2)
# 将分割掩码的坐标存储到矩阵中。
xy[:, :2] = segments
# 应用变换矩阵。将坐标矩阵 xy 与变换矩阵 M 的转置相乘，应用变换。
xy = xy @ M.T # transform
# 进行透视归一化，将结果重塑为 (n * num, 2) 的矩阵。
# 这行代码是 apply_segments 方法中的一个关键步骤，用于对变换后的坐标进行透视归一化。具体来说，它将每个点的x和y坐标除以该点的透视因子（即z坐标），以确保透视变换后的坐标仍然在图像平面内。
# xy[:, :2] ：提取变换后的x和y坐标，形状为 (n * num, 2) 。
# xy[:, 2:3] ：提取变换后的z坐标，形状为 (n * num, 1) 。
# xy[:, :2] / xy[:, 2:3] ：将每个点的x和y坐标除以z坐标，进行透视归一化。这一步确保透视变换后的坐标仍然在图像平面内。
# 这行代码通过透视归一化，将齐次坐标转换为笛卡尔坐标，确保透视变换后的坐标仍然在图像平面内。这一步是透视变换中非常重要的一步，因为它确保变换后的坐标在图像平面内是有效的。通过这种方式，可以正确地处理透视变换后的分割掩码和边界框，确保它们在变换后的图像中仍然准确地表示目标对象的位置和形状。
xy = xy[:, :2] / xy[:, 2:3]
# 重塑分割掩码。将变换后的坐标重塑为原始形状 (n, num, 2) 。
segments = xy.reshape(n, -1, 2)
# 计算新的边界框。对每个分割掩码计算新的边界框坐标。 segment2box 函数将分割掩码的坐标转换为边界框坐标。
bboxes = np.stack([segment2box(xy, self.size[0], self.size[1]) for xy in segments], 0)
# 裁剪分割掩码。
# 裁剪x坐标，确保分割掩码的x坐标在边界框的范围内。
segments[..., 0] = segments[..., 0].clip(bboxes[:, 0:1], bboxes[:, 2:3])
# 裁剪y坐标，确保分割掩码的y坐标在边界框的范围内。
segments[..., 1] = segments[..., 1].clip(bboxes[:, 1:2], bboxes[:, 3:4])
# 返回结果。返回 新的边界框 和 裁剪后的分割掩码 。
return bboxes, segments
# apply_segments 方法通过以下步骤对分割掩码进行透视变换或仿射变换，检查分割掩码数量，如果为0，直接返回。创建一个坐标矩阵，存储分割掩码的坐标。应用变换矩阵，对坐标进行变换。进行透视归一化。重塑分割掩码，恢复原始形状。计算新的边界框坐标。裁剪分割掩码，确保坐标在边界框的范围内。返回新的边界框和裁剪后的分割掩码。这个方法确保在对图像进行透视变换或仿射变换后，分割掩码仍然准确地表示目标对象的形状，从而保证数据增强的有效性和准确性。
# 这段代码定义了 RandomPerspective 类中的 apply_keypoints 方法，用于对关键点（keypoints）进行透视变换或仿射变换。
# 定义了 apply_keypoints 方法，接收两个参数。
# 1.keypoints ：一个三维数组，每一行表示一个关键点，格式为 [x, y, visibility] 。
# 2.M ：一个3x3的变换矩阵，用于对关键点进行变换。
def apply_keypoints(self, keypoints, M):
# 将仿射应用于关键点。
# 参数：
# keypoints (ndarray)：关键点，[N, 17, 3]。
# M (ndarray)：仿射矩阵。
# 返回：
# new_keypoints (ndarray)：仿射后的关键点，[N, 17, 3]。
"""
Apply affine to keypoints.
Args:
keypoints (ndarray): keypoints, [N, 17, 3].
M (ndarray): affine matrix.
Returns:
new_keypoints (ndarray): keypoints after affine, [N, 17, 3].
"""
# 检查关键点数量。
# 获取 关键点的数量 n 和 每个关键点的维度 nkpt 。
n, nkpt = keypoints.shape[:2]
# 如果关键点数量为0，直接返回。
if n == 0:
# 返回空的关键点数组。
return keypoints
# 创建坐标矩阵。
# 创建一个形状为 (n * nkpt, 3) 的矩阵，用于存储关键点的坐标。每个关键点有 nkpt 个点，因此总共有 n * nkpt 个点。矩阵的第三列初始化为1，用于透视变换。
xy = np.ones((n * nkpt, 3), dtype=keypoints.dtype)
# 提取关键点的可见性信息，并重塑为 (n * nkpt, 1) 的矩阵。
visible = keypoints[..., 2].reshape(n * nkpt, 1)
# 将关键点的x和y坐标存储到矩阵中。
xy[:, :2] = keypoints[..., :2].reshape(n * nkpt, 2)
# 应用变换矩阵。
# 将坐标矩阵 xy 与变换矩阵 M 的转置相乘，应用变换。
xy = xy @ M.T # transform
# 进行透视归一化，将结果重塑为 (n * nkpt, 2) 的矩阵。
xy = xy[:, :2] / xy[:, 2:3] # perspective rescale or affine
# 检查关键点是否在图像范围内。创建一个掩码，标记那些变换后不在图像范围内的关键点。
out_mask = (xy[:, 0] < 0) | (xy[:, 1] < 0) | (xy[:, 0] > self.size[0]) | (xy[:, 1] > self.size[1])
# 将不在图像范围内的关键点的可见性设置为0。
visible[out_mask] = 0
# 合并坐标和可见性。将变换后的坐标和可见性信息合并，并重塑为原始形状 (n, nkpt, 3) 。
return np.concatenate([xy, visible], axis=-1).reshape(n, nkpt, 3)
# apply_keypoints 方法通过以下步骤对关键点进行透视变换或仿射变换，检查关键点数量，如果为0，直接返回。创建一个坐标矩阵，存储关键点的坐标。应用变换矩阵，对坐标进行变换。进行透视归一化。检查关键点是否在图像范围内，将不在范围内的关键点的可见性设置为0。合并坐标和可见性信息，重塑为原始形状。这个方法确保在对图像进行透视变换或仿射变换后，关键点仍然准确地表示目标对象的关键部位，同时处理了关键点可能移出图像范围的情况。这在目标检测和关键点检测任务中非常有用，确保数据增强的有效性和准确性。
# 这段代码定义了 RandomPerspective 类中的 __call__ 方法，用于对图像及其标签进行随机透视变换。
# 定义了 __call__ 方法，接收一个参数。
# 1.labels ：这是一个字典，包含了图像、类别标签和实例信息。
def __call__(self, labels):
# 仿射图像和目标。
"""
Affine images and targets.
Args:
labels (dict): a dict of `bboxes`, `segments`, `keypoints`.
"""
# 预变换。
# 如果定义了预变换操作且 labels 中没有 "mosaic_border" 键，则应用预变换。
if self.pre_transform and "mosaic_border" not in labels:
# 应用预变换操作。
labels = self.pre_transform(labels)
# 移除 "ratio_pad" 键，因为不需要这个信息。
labels.pop("ratio_pad", None) # do not need ratio pad
# 提取图像和标签。
# 提取图像数据。
img = labels["img"]
# 提取类别标签。
cls = labels["cls"]
# 提取 实例信息 ，并从 labels 中移除 "instances" 键。
instances = labels.pop("instances")
# Make sure the coord formats are right
# 确保边界框格式为 xyxy 。
instances.convert_bbox(format="xyxy")
# 对边界框进行反归一化，确保坐标在图像尺寸范围内。
instances.denormalize(*img.shape[:2][::-1])
# 计算边界和图像尺寸。
# 提取 "mosaic_border" 键的值，如果不存在则使用 self.border 。
border = labels.pop("mosaic_border", self.border)
# 计算变换后的图像尺寸，考虑边界。
self.size = img.shape[1] + border[1] * 2, img.shape[0] + border[0] * 2 # w, h
# M is affine matrix
# Scale for func:`box_candidates`
# 应用仿射变换。对图像应用仿射变换，返回 变换后的图像 、 变换矩阵 M 和 缩放比例 scale 。
img, M, scale = self.affine_transform(img, border)
# 应用边界框变换。对边界框应用变换矩阵 M 。
bboxes = self.apply_bboxes(instances.bboxes, M)
# 应用分割掩码变换。
# 提取分割掩码。
segments = instances.segments
# 提取关键点。
keypoints = instances.keypoints
# Update bboxes if there are segments.
# 如果存在 分割掩码 ，对分割掩码应用变换矩阵 M 。
if len(segments):
# 对分割掩码应用变换，并更新边界框。
bboxes, segments = self.apply_segments(segments, M)
# 应用关键点变换。
# 如果存在关键点，对关键点应用变换矩阵 M 。
if keypoints is not None:
# 对关键点应用变换。
keypoints = self.apply_keypoints(keypoints, M)
# 创建新的实例信息。创建新的实例信息对象，包含变换后的边界框、分割掩码和关键点。
# class Instances:
# -> 用于表示和操作图像实例，包括边界框、分割掩码和关键点等信息。
# -> def __init__(self, bboxes, segments=None, keypoints=None, bbox_format="xywh", normalized=True) -> None:
new_instances = Instances(bboxes, segments, keypoints, bbox_format="xyxy", normalized=False)
# Clip
# 裁剪实例信息。对新的实例信息进行裁剪，确保坐标在图像尺寸范围内。
new_instances.clip(*self.size)
# Filter instances
# 筛选实例。
# 对原始实例信息进行缩放，确保边界框与新的边界框具有相同的尺度。
instances.scale(scale_w=scale, scale_h=scale, bbox_only=True)
# Make the bboxes have the same scale with new_bboxes
# 筛选满足条件的边界框。
i = self.box_candidates(
box1=instances.bboxes.T, box2=new_instances.bboxes.T, area_thr=0.01 if len(segments) else 0.10
)
# 更新 labels 中的 实例信息 ，只保留满足条件的实例。
labels["instances"] = new_instances[i]
# 更新 labels 中的 类别标签 ，只保留满足条件的类别标签。
labels["cls"] = cls[i]
# 更新 labels 中的 图像数据 。
labels["img"] = img
# 更新 labels 中的 图像尺寸 。
labels["resized_shape"] = img.shape[:2]
# 返回结果。返回更新后的 labels 字典。
return labels
# __call__ 方法通过以下步骤对图像及其标签进行随机透视变换，应用预变换操作（如果定义）。提取图像、类别标签和实例信息。确保边界框格式为 xyxy ，并对边界框进行反归一化。计算变换后的图像尺寸，考虑边界。对图像应用仿射变换，返回变换后的图像、变换矩阵和缩放比例。对边界框、分割掩码和关键点应用变换矩阵。创建新的实例信息对象，包含变换后的边界框、分割掩码和关键点。对新的实例信息进行裁剪，确保坐标在图像尺寸范围内。筛选满足条件的边界框，更新 labels 中的实例信息和类别标签。返回更新后的 labels 字典。这个方法确保在对图像进行随机透视变换后，边界框、分割掩码和关键点仍然准确地表示目标对象的位置和形状，从而保证数据增强的有效性和准确性。
# 这段代码定义了 RandomPerspective 类中的 box_candidates 方法，用于筛选变换后的边界框（bounding boxes），确保它们满足一定的条件。这个方法接收多个参数，用于控制筛选的阈值。
# 定义了 box_candidates 方法，接收以下参数 ：
# 1.box1 ：原始边界框的坐标，格式为 [x1, y1, x2, y2] 。
# 2.box2 ：变换后的边界框的坐标，格式为 [x1, y1, x2, y2] 。
# 3.wh_thr ：宽度和高度的最小阈值，边界框的宽度和高度必须大于这个值。
# 4.ar_thr ：长宽比的最大阈值，边界框的长宽比必须小于这个值。
# 5.area_thr ：面积比的最小阈值，变换后的边界框面积与原始边界框面积的比值必须大于这个值。
# 6.eps=1e-16 ：一个小的常数，用于避免除以零的错误。
def box_candidates(self, box1, box2, wh_thr=2, ar_thr=100, area_thr=0.1, eps=1e-16):
# 根据一组阈值计算候选框。此方法比较增强前后框的特征，以决定框是否是进一步处理的候选框。
"""
Compute box candidates based on a set of thresholds. This method compares the characteristics of the boxes
before and after augmentation to decide whether a box is a candidate for further processing.
Args:
box1 (numpy.ndarray): The 4,n bounding box before augmentation, represented as [x1, y1, x2, y2].
box2 (numpy.ndarray): The 4,n bounding box after augmentation, represented as [x1, y1, x2, y2].
wh_thr (float, optional): The width and height threshold in pixels. Default is 2.
ar_thr (float, optional): The aspect ratio threshold. Default is 100.
area_thr (float, optional): The area ratio threshold. Default is 0.1.
eps (float, optional): A small epsilon value to prevent division by zero. Default is 1e-16.
Returns:
(numpy.ndarray): A boolean array indicating which boxes are candidates based on the given thresholds.
"""
# 计算宽度和高度。
# 计算原始边界框的 宽度 和 高度 。
w1, h1 = box1[2] - box1[0], box1[3] - box1[1]
# 计算变换后的边界框的 宽度 和 高度 。
w2, h2 = box2[2] - box2[0], box2[3] - box2[1]
# 计算长宽比。计算变换后的边界框的长宽比。 eps 用于避免除以零的错误。 np.maximum 确保长宽比是宽度和高度的较大值。
ar = np.maximum(w2 / (h2 + eps), h2 / (w2 + eps)) # aspect ratio
# 筛选条件。
# 返回一个布尔数组，表示每个边界框是否满足以下条件 ：
# w2 > wh_thr ：宽度大于 wh_thr 。
# h2 > wh_thr ：高度大于 wh_thr 。
# w2 * h2 / (w1 * h1 + eps) > area_thr ：变换后的边界框面积与原始边界框面积的比值大于 area_thr 。
# ar < ar_thr ：长宽比小于 ar_thr 。
return (w2 > wh_thr) & (h2 > wh_thr) & (w2 * h2 / (w1 * h1 + eps) > area_thr) & (ar < ar_thr) # candidates
# box_candidates 方法通过以下步骤筛选变换后的边界框，计算原始边界框和变换后边界框的宽度和高度。计算变换后边界框的长宽比。根据宽度、高度、面积比和长宽比的阈值筛选边界框。返回一个布尔数组，表示每个边界框是否满足筛选条件。这个方法确保在对图像进行透视变换或仿射变换后，边界框仍然有效且合理，从而保证数据增强的有效性和准确性。这在目标检测任务中非常有用，确保变换后的边界框仍然准确地表示目标对象的位置和形状。8.class RandomHSV:
# 这段代码定义了一个名为 RandomHSV 的类，用于对图像进行随机HSV（色调、饱和度、亮度）变换。这种变换常用于数据增强，特别是在图像分类和目标检测任务中。
# 定义了 RandomHSV 类。
class RandomHSV:
# 此类负责对图像的色调、饱和度和值 (HSV) 通道进行随机调整。
# 调整是随机的，但在 hgain、sgain 和 vgain 设定的范围内。
"""
This class is responsible for performing random adjustments to the Hue, Saturation, and Value (HSV) channels of an
image.
The adjustments are random but within limits set by hgain, sgain, and vgain.
"""
# 初始化方法。
# 定义了类的初始化方法 __init__ ，接收三个参数。
# 1.hgain ：色调变化的增益，默认为0.5。
# 2.sgain ：饱和度变化的增益，默认为0.5。
# 3.vgain ：亮度变化的增益，默认为0.5。
def __init__(self, hgain=0.5, sgain=0.5, vgain=0.5) -> None:
# 使用每个 HSV 通道的增益初始化 RandomHSV 类。
"""
Initialize RandomHSV class with gains for each HSV channel.
Args:
hgain (float, optional): Maximum variation for hue. Default is 0.5.
sgain (float, optional): Maximum variation for saturation. Default is 0.5.
vgain (float, optional): Maximum variation for value. Default is 0.5.
"""
# 将传入的 hgain 参数赋值给实例变量 self.hgain 。
self.hgain = hgain
# 将传入的 sgain 参数赋值给实例变量 self.sgain 。
self.sgain = sgain
# 将传入的 vgain 参数赋值给实例变量 self.vgain 。
self.vgain = vgain
# 调用方法。
# 定义了类的调用方法 __call__ ，接收一个参数。
# 1.labels ：这是一个字典，包含了图像数据和其他标签信息。
def __call__(self, labels):
# 在预定义限制内对图像应用随机 HSV 增强。
# 修改后的图像将替换输入“标签”字典中的原始图像。
"""
Applies random HSV augmentation to an image within the predefined limits.
The modified image replaces the original image in the input 'labels' dict.
"""
# 从 labels 字典中提取图像数据。
img = labels["img"]
# 应用HSV变换。
# 如果任何一个增益不为0，则进行HSV变换。
if self.hgain or self.sgain or self.vgain:
# np.random.uniform(low=0.0, high=1.0, size=None)
# np.random.uniform() 是 NumPy 库中的一个函数，用于生成在指定范围内均匀分布的随机数。
# 参数说明 ：
# low ：随机数生成的下限，默认为0.0。
# high ：随机数生成的上限，默认为1.0。
# size ：输出数组的形状。如果为 None ，则返回一个单一的随机数。如果指定了 size ，则返回一个随机数数组。
# 返回值 ：
# 返回一个或一组随机数，取决于 size 参数的设置。
# 功能说明 ：
# np.random.uniform() 函数从指定的区间 [low, high) 中生成均匀分布的随机数。这意味着随机数可以取到 low 的值，但是取不到 high 的值。
# 生成一个随机增益向量 r ，每个元素在 [-1, 1] 范围内，乘以相应的增益并加1。
r = np.random.uniform(-1, 1, 3) * [self.hgain, self.sgain, self.vgain] + 1 # random gains
# 将图像从BGR颜色空间转换为HSV颜色空间，并分离出H、S、V三个通道。
hue, sat, val = cv2.split(cv2.cvtColor(img, cv2.COLOR_BGR2HSV))
# 获取图像的数据类型，通常是 uint8 。
dtype = img.dtype # uint8
# 生成一个从0到255的数组，用于创建查找表。
x = np.arange(0, 256, dtype=r.dtype)
# 创建 色调的查找表 ，确保值在0到179之间。
lut_hue = ((x * r[0]) % 180).astype(dtype)
# 创建 饱和度的查找表 ，确保值在0到255之间。
lut_sat = np.clip(x * r[1], 0, 255).astype(dtype)
# 创建 亮度的查找表 ，确保值在0到255之间。
lut_val = np.clip(x * r[2], 0, 255).astype(dtype)
# 使用查找表对H、S、V通道进行变换，并合并为一个新的HSV图像。
im_hsv = cv2.merge((cv2.LUT(hue, lut_hue), cv2.LUT(sat, lut_sat), cv2.LUT(val, lut_val)))
# 将变换后的HSV图像转换回BGR颜色空间，并直接在原图像上进行修改。
cv2.cvtColor(im_hsv, cv2.COLOR_HSV2BGR, dst=img) # no return needed
# 返回更新后的 labels 字典。
return labels
# RandomHSV 类通过以下步骤对图像进行随机HSV变换，初始化类实例，设置色调、饱和度和亮度的增益。提取图像数据。生成随机增益向量，用于调整色调、饱和度和亮度。将图像从BGR颜色空间转换为HSV颜色空间，并分离出H、S、V三个通道。创建查找表，对H、S、V通道进行变换。合并变换后的H、S、V通道，生成新的HSV图像。将变换后的HSV图像转换回BGR颜色空间，并直接在原图像上进行修改。返回更新后的 labels 字典。这个类确保在对图像进行HSV变换后，图像的颜色和亮度发生变化，从而增加数据的多样性，提高模型的泛化能力。9.class RandomFlip:
# 这段代码定义了一个名为 RandomFlip 的类，用于对图像及其标签进行随机翻转变换。这种变换常用于数据增强，特别是在图像分类和目标检测任务中。
# 定义了 RandomFlip 类。
class RandomFlip:
# 以给定概率对图像应用随机水平或垂直翻转。
# 还会相应地更新任何实例（边界框、关键点等）。
"""
Applies a random horizontal or vertical flip to an image with a given probability.
Also updates any instances (bounding boxes, keypoints, etc.) accordingly.
"""
# 初始化方法。
# 定义了类的初始化方法 __init__ ，接收三个参数。
# 1.p ：执行翻转操作的概率，默认为0.5。
# 2.direction ：翻转方向，可以是 "horizontal" （水平翻转）或 "vertical" （垂直翻转）。
# 3.flip_idx ：关键点翻转索引，用于处理关键点的翻转。
def __init__(self, p=0.5, direction="horizontal", flip_idx=None) -> None:
# 使用概率和方向初始化 RandomFlip 类。
"""
Initializes the RandomFlip class with probability and direction.
Args:
p (float, optional): The probability of applying the flip. Must be between 0 and 1. Default is 0.5.
direction (str, optional): The direction to apply the flip. Must be 'horizontal' or 'vertical'.
Default is 'horizontal'.
flip_idx (array-like, optional): Index mapping for flipping keypoints, if any.
"""
# 确保 direction 参数的值为 "horizontal" 或 "vertical" 。
assert direction in ["horizontal", "vertical"], f"Support direction `horizontal` or `vertical`, got {direction}" # 支持方向 `水平` 或 `垂直`，得到{direction} 。
# 确保 p 参数的值在0到1之间。
assert 0 <= p <= 1.0
# 将传入的 p 参数赋值给实例变量 self.p 。
self.p = p
# 将传入的 direction 参数赋值给实例变量 self.direction 。
self.direction = direction
# 将传入的 flip_idx 参数赋值给实例变量 self.flip_idx 。
self.flip_idx = flip_idx
# 调用方法。
# 定义了类的调用方法 __call__ ，接收一个参数。
# 1.labels ：这是一个字典，包含了图像数据和其他标签信息。
def __call__(self, labels):
# 对图像应用随机翻转，并相应地更新任何实例，如边界框或关键点。
"""
Applies random flip to an image and updates any instances like bounding boxes or keypoints accordingly.
Args:
labels (dict): A dictionary containing the keys 'img' and 'instances'. 'img' is the image to be flipped.
'instances' is an object containing bounding boxes and optionally keypoints.
Returns:
(dict): The same dict with the flipped image and updated instances under the 'img' and 'instances' keys.
"""
# 从 labels 字典中提取图像数据。
img = labels["img"]
# 提取实例信息，并从 labels 中移除 "instances" 键。
instances = labels.pop("instances")
# 确保边界框格式为 xywh 。
instances.convert_bbox(format="xywh")
# 获取图像的高度和宽度。
h, w = img.shape[:2]
# 如果边界框是归一化的，高度设为1；否则使用实际高度。
h = 1 if instances.normalized else h
# 如果边界框是归一化的，宽度设为1；否则使用实际宽度。
w = 1 if instances.normalized else w
# Flip up-down
# 应用翻转变换。
# 如果方向为垂直且随机数小于 self.p ，则进行垂直翻转。
if self.direction == "vertical" and random.random() < self.p:
# 对图像进行垂直翻转。
img = np.flipud(img)
# 对实例信息进行垂直翻转。
# def flipud(self, h): -> 用于对实例中的边界框、分割掩码和关键点进行上下翻转（垂直翻转）。
instances.flipud(h)
# 如果方向为水平且随机数小于 self.p ，则进行水平翻转。
if self.direction == "horizontal" and random.random() < self.p:
# 对图像进行水平翻转。
img = np.fliplr(img)
# 对实例信息进行水平翻转。
instances.fliplr(w)
# For keypoints
# 如果定义了关键点翻转索引且存在关键点，则对关键点进行翻转。
if self.flip_idx is not None and instances.keypoints is not None:
# np.ascontiguousarray(a, dtype=None)
# np.ascontiguousarray 是 NumPy 库中的一个函数，它用于返回一个连续的内存块数组。如果输入数组已经是连续的，它将返回原数组；如果不是连续的，它将返回一个新数组，该数组是原数组的连续副本。
# 参数 ：
# a ：输入数组。
# dtype ：数据类型，可选参数。如果指定，将输入数组转换为指定的数据类型。
# 返回值 ：
# 返回一个连续的数组。用途 np.ascontiguousarray 通常用于确保数组在内存中是连续存储的，这在某些情况下是非常重要的，例如 ：
# 当数组需要被传递给某些期望连续数据的库或函数时。
# 在进行内存操作或数组切片时，连续的数组可以提高性能。
# 使用翻转索引对关键点进行翻转。
instances.keypoints = np.ascontiguousarray(instances.keypoints[:, self.flip_idx, :])
# 更新 labels 字典。
# 将翻转后的 图像数据 更新到 labels 字典中。
labels["img"] = np.ascontiguousarray(img)
# 将更新后的 实例信息 更新到 labels 字典中。
labels["instances"] = instances
# 返回更新后的 labels 字典。
return labels
# RandomFlip 类通过以下步骤对图像及其标签进行随机翻转变换，初始化类实例，设置翻转概率、方向和关键点翻转索引。提取图像数据和实例信息。确保边界框格式为 xywh ，并获取图像的高度和宽度。根据方向和概率进行垂直或水平翻转。对图像和实例信息进行翻转操作。如果存在关键点且定义了翻转索引，则对关键点进行翻转。更新 labels 字典中的图像数据和实例信息。返回更新后的 labels 字典。这个类确保在对图像进行随机翻转变换后，图像和标签仍然准确地表示目标对象的位置和形状，从而保证数据增强的有效性和准确性。10.class LetterBox:
# 这段代码定义了一个名为 LetterBox 的类，用于将图像调整为指定的尺寸，同时保持图像的纵横比。这种变换常用于数据预处理，特别是在图像分类和目标检测任务中。
# 定义了 LetterBox 类。
class LetterBox:
# 调整图像和填充的大小以进行检测、实例分割和姿势调整。
"""Resize image and padding for detection, instance segmentation, pose."""
# 初始化方法。
# 定义了类的初始化方法 __init__ ，接收多个参数 ：
# 1.new_shape ：目标图像尺寸，默认为 (640, 640) 。
# 2.auto ：是否自动调整填充，确保图像尺寸是 stride 的倍数。
# 3.scaleFill ：是否拉伸图像以填充整个目标尺寸。
# 4.scaleup ：是否允许图像放大。
# 5.center ：是否将图像放在中心位置，否则放在左上角。
# 6.stride ：步长，用于自动调整填充。
def __init__(self, new_shape=(640, 640), auto=False, scaleFill=False, scaleup=True, center=True, stride=32):
# 使用特定参数初始化 LetterBox 对象。
"""Initialize LetterBox object with specific parameters."""
# 将传入的 new_shape 参数赋值给实例变量 self.new_shape 。
self.new_shape = new_shape
# 将传入的 auto 参数赋值给实例变量 self.auto 。
self.auto = auto
# 将传入的 scaleFill 参数赋值给实例变量 self.scaleFill 。
self.scaleFill = scaleFill
# 将传入的 scaleup 参数赋值给实例变量 self.scaleup 。
self.scaleup = scaleup
# 将传入的 stride 参数赋值给实例变量 self.stride 。
self.stride = stride
# 将传入的 center 参数赋值给实例变量 self.center 。
self.center = center # Put the image in the middle or top-left
# 这段代码定义了 LetterBox 类中的 __call__ 方法和 _update_labels 方法，用于将图像调整为指定的尺寸，同时保持图像的纵横比，并更新相应的标签信息。
# 定义了类的调用方法 __call__ ，接收两个参数。
# 1.labels ：一个字典，包含了图像数据和其他标签信息。
# 2.image ：图像数据，如果 labels 中没有 "img" 键，则使用这个参数。
def __call__(self, labels=None, image=None):
# 返回已更新的标签和已添加边框的图像。
"""Return updated labels and image with added border."""
# 初始化。
# 如果 labels 为 None ，初始化为空字典。
if labels is None:
labels = {}
# 从 labels 中提取图像数据，如果 image 不为 None ，则使用 image 。
img = labels.get("img") if image is None else image
# 获取图像的高度和宽度。
shape = img.shape[:2] # current shape [height, width]
# 从 labels 中提取 "rect_shape" 键的值，如果不存在则使用 self.new_shape 。
new_shape = labels.pop("rect_shape", self.new_shape)
# 如果 new_shape 是整数，将其转换为 (new_shape, new_shape) 。
if isinstance(new_shape, int):
new_shape = (new_shape, new_shape)
# Scale ratio (new / old)
# 计算缩放比例。
# 计算缩放比例，确保图像在目标尺寸内。
r = min(new_shape[0] / shape[0], new_shape[1] / shape[1])
# 如果 scaleup 为 False ，则只允许图像缩小，不允许放大。
if not self.scaleup: # only scale down, do not scale up (for better val mAP) 只缩小，不扩大（为了获得更好的 val mAP）。
# 将缩放比例限制在1.0以内。
r = min(r, 1.0)
# Compute padding
# 计算填充。
# 计算宽度和高度的缩放比例。
ratio = r, r # width, height ratios
# 计算缩放后的图像尺寸。
new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r))
# 计算填充的宽度和高度。
dw, dh = new_shape[1] - new_unpad[0], new_shape[0] - new_unpad[1] # wh padding
# 如果 auto 为 True ，则调整填充，确保图像尺寸是 stride 的倍数。
if self.auto: # minimum rectangle
# np.mod(x, y, out=None, where=None, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])
# 在 NumPy 中， np.mod 函数用于计算模运算，即对于给定的两个数组，它返回第一个数组中每个元素除以第二个数组中对应元素的余数。
# 参数说明 ：
# x ：被除数数组。
# y ：除数数组。 y 的形状必须与 x 相同，或者能够广播到 x 的形状。
# out ：（可选）用于存放结果的数组。
# where ：（可选）布尔数组，指定在哪些位置执行操作。
# casting ：（可选）控制如何处理不同数据类型之间的转换。
# order ：（可选）指定多维数组中元素的遍历顺序。
# dtype ：（可选）指定输出数组的数据类型。
# subok ：（可选）如果为 True，则返回的数组是 x 和 y 的子类。
# signature ：（可选）指定函数签名。
# extobj ：（可选）用于非常量参数的额外对象。
# 返回值 ：
# 返回一个数组，包含 x 中每个元素除以 y 中对应元素的余数。
# 需要注意的是， np.mod 的行为与 Python 内置的 % 运算符略有不同，特别是在处理负数时。 np.mod 总是返回一个非负余数，而 % 运算符则返回的余数的符号与被除数相同。
# 计算填充的宽度和高度，确保图像尺寸是 stride 的倍数。
dw, dh = np.mod(dw, self.stride), np.mod(dh, self.stride) # wh padding
# 如果 scaleFill 为 True ，则拉伸图像以填充整个目标尺寸。
elif self.scaleFill: # stretch
# 将填充设置为0。
dw, dh = 0.0, 0.0
# 将缩放后的图像尺寸设置为目标尺寸。
new_unpad = (new_shape[1], new_shape[0])
# 计算宽度和高度的缩放比例。
ratio = new_shape[1] / shape[1], new_shape[0] / shape[0] # width, height ratios
# 调整填充。
# 如果 center 为 True ，则将图像放在中心位置。
if self.center:
# 将填充宽度分成两部分。
dw /= 2 # divide padding into 2 sides
# 将填充高度分成两部分。
dh /= 2
# 调整图像尺寸。
# 如果图像尺寸需要调整。
if shape[::-1] != new_unpad: # resize
# 对图像进行缩放。
img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR)
# 添加边界。
# 计算顶部和底部的填充。
top, bottom = int(round(dh - 0.1)) if self.center else 0, int(round(dh + 0.1))
# 计算左侧和右侧的填充。
left, right = int(round(dw - 0.1)) if self.center else 0, int(round(dw + 0.1))
# dst = cv2.copyMakeBorder(src, top, bottom, left, right, borderType[, dst[, value[, mask]]])
# cv2.copyMakeBorder() 函数是 OpenCV 库中的一个函数，用于在图像周围添加边框（填充）。这个函数非常灵活，可以指定边框的厚度、类型以及边框的颜色。
# 参数说明 ：
# src ：输入图像，可以是灰度图或彩色图。
# top ：图像顶部的边框厚度。
# bottom ：图像底部的边框厚度。
# left ：图像左侧的边框厚度。
# right ：图像右侧的边框厚度。
# borderType ：边框的类型，有以下几种 ：
# cv2.BORDER_CONSTANT ：添加一个常数颜色的边框。 value 参数指定了这个颜色。
# cv2.BORDER_REFLECT ：反射图像来填充边框。
# cv2.BORDER_REFLECT_101 ：类似于 BORDER_REFLECT ，但有两个反射。
# cv2.BORDER_DEFAULT ：等同于 BORDER_REFLECT 。
# cv2.BORDER_REFLECT101 ：等同于 BORDER_REFLECT_101 。
# cv2.BORDER_WRAP ：重复图像来填充边框。
# cv2.BORDER_TRANSPARENT ：假设图像是透明的，并进行适当的填充。
# cv2.BORDER_REPLICATE ：复制边缘像素来填充边框。
# cv2.BORDER_CONSTANT ：添加一个常数颜色的边框，与 cv2.BORDER_CONSTANT 相同。
# dst ：（可选）输出图像，如果提供，函数将直接修改这个图像而不是创建一个新的。
# value ：（可选）一个标量或一个三元组或四元组，指定 BORDER_CONSTANT 时边框的颜色。对于彩色图像，它应该是一个三元组或四元组（BGR顺序）。
# mask ：（可选）一个8位单通道图像，与 src 大小相同，用于确定哪些像素需要被复制。在 BORDER_TRANSPARENT 模式下使用。
# 返回值 ：
# dst ：包含原始图像和添加的边框的新图像。
# 在图像周围添加边界。
img = cv2.copyMakeBorder(
img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(114, 114, 114)
) # add border
# 更新标签。
# 如果 labels 中有 "ratio_pad" 键。
if labels.get("ratio_pad"):
# 更新 "ratio_pad" 键的值。
# 这行代码在 LetterBox 类的 __call__ 方法中，用于更新 labels 字典中的 "ratio_pad" 键。这个键用于存储图像缩放比例和填充信息，这些信息在评估阶段非常有用。
# (labels["ratio_pad"], (left, top)) ：将当前的 "ratio_pad" 值和新的填充信息组合成一个新的元组，并赋值给 "ratio_pad" 键。
# 作用 ：
# 存储缩放比例和填充信息 ：在图像预处理过程中，图像可能会被缩放和填充。 "ratio_pad" 键用于存储这些信息，以便在后续的评估阶段可以正确地还原图像的原始尺寸和位置。
# 评估阶段的还原 ：在评估阶段，需要将预测的边界框和关键点从调整后的图像尺寸还原到原始图像尺寸。 "ratio_pad" 键中的信息可以帮助完成这一还原过程。
# 示例 ：
# 假设 labels 字典中已经存在 "ratio_pad" 键，其值为 (0.5, 0.5) ，表示图像在宽度和高度方向上的缩放比例均为0.5。现在，计算出左侧和顶部的填充像素数分别为100和50。那么，这行代码将更新 "ratio_pad" 键的值为 ((0.5, 0.5), (100, 50)) 。
# 总结 ：这行代码通过更新 labels 字典中的 "ratio_pad" 键，存储了图像的缩放比例和填充信息。这些信息在评估阶段非常有用，可以用于将预测的边界框和关键点从调整后的图像尺寸还原到原始图像尺寸，从而确保评估结果的准确性。
labels["ratio_pad"] = (labels["ratio_pad"], (left, top)) # for evaluation
# 如果 labels 不为空。
if len(labels):
# 更新标签信息。
labels = self._update_labels(labels, ratio, dw, dh)
# 更新图像数据。
labels["img"] = img
# 更新调整后的图像尺寸。
labels["resized_shape"] = new_shape
# 返回更新后的 labels 字典。
return labels
# 如果 labels 为空。
else:
# 返回调整后的图像。
return img
# LetterBox 类通过以下步骤将图像调整为指定的尺寸，同时保持图像的纵横比，并更新相应的标签信息。初始化类实例，设置目标尺寸、自动调整填充、拉伸填充、放大限制、中心位置和步长。提取图像数据和实例信息。计算缩放比例，确保图像在目标尺寸内。计算填充的宽度和高度，确保图像尺寸是步长的倍数。调整图像尺寸，对图像进行缩放。在图像周围添加边界，确保图像在目标尺寸内。更新标签信息，确保边界框和关键点在调整后的图像中仍然准确。返回更新后的 labels 字典或调整后的图像。这个类确保在对图像进行预处理时，图像和标签仍然准确地表示目标对象的位置和形状，从而保证数据预处理的有效性和准确性。
# 这段代码定义了 LetterBox 类中的 _update_labels 方法，用于更新图像调整后的标签信息。
# 定义了 _update_labels 方法，接收四个参数。
# 1.labels ：一个字典，包含图像数据和标签信息。
# 2.ratio ：一个元组，包含宽度和高度的缩放比例。
# 3.padw ：填充宽度。
# 4.padh ：填充高度。
def _update_labels(self, labels, ratio, padw, padh):
"""Update labels."""
# 将边界框格式转换为 xyxy 格式。 xyxy 格式表示边界框的左上角和右下角坐标，即 [x1, y1, x2, y2] 。
labels["instances"].convert_bbox(format="xyxy")
# 对边界框进行反归一化。如果边界框是归一化的（即坐标在0到1之间），则将其转换为实际像素坐标。 labels["img"].shape[:2][::-1] 获取图像的宽度和高度。
labels["instances"].denormalize(*labels["img"].shape[:2][::-1])
# 根据缩放比例调整边界框的坐标。 ratio 是一个元组，包含宽度和高度的缩放比例。
labels["instances"].scale(*ratio)
# 根据填充宽度和高度调整边界框的坐标。 padw 和 padh 分别表示水平和垂直方向的填充像素数。
labels["instances"].add_padding(padw, padh)
# 返回更新后的 labels 字典。
return labels
# _update_labels 方法通过以下步骤更新图像调整后的标签信息。将边界框格式转换为 xyxy 格式。对边界框进行反归一化，将归一化坐标转换为实际像素坐标。根据缩放比例调整边界框的坐标。根据填充宽度和高度调整边界框的坐标。返回更新后的 labels 字典。这个方法确保在对图像进行预处理（如缩放和填充）后，标签信息仍然准确地表示目标对象的位置和形状，从而保证数据预处理的有效性和准确性。这对于后续的训练和评估非常重要。
# LetterBox 类用于将图像调整为指定的尺寸，同时保持图像的纵横比。这个类通过计算适当的缩放比例和填充，确保图像在目标尺寸内，并且不会失真。它还提供了选项来自动调整填充，拉伸图像以填充整个目标尺寸，以及将图像放在中心或左上角位置。此外， LetterBox 类还更新了相应的标签信息，确保边界框和关键点在调整后的图像中仍然准确。这个类在图像预处理阶段非常有用，特别是在图像分类和目标检测任务中，可以确保图像和标签在预处理后仍然保持一致性和准确性。11.class CopyPaste:
# 这段代码定义了一个名为 CopyPaste 的类，用于实现Copy-Paste数据增强技术。Copy-Paste通过将一个图像中的对象复制并粘贴到另一个图像中，增加数据的多样性，提高模型对不同组合的泛化能力。
# 定义了 CopyPaste 类。
class CopyPaste:
# 实现论文 https://arxiv.org/abs/2012.07177 中描述的复制粘贴增强功能。此类负责对图像及其相应实例应用复制粘贴增强功能。
"""
Implements the Copy-Paste augmentation as described in the paper https://arxiv.org/abs/2012.07177. This class is
responsible for applying the Copy-Paste augmentation on images and their corresponding instances.
"""
# 初始化方法。
# 定义了类的初始化方法 __init__ ，接收一个参数。
# 1.p ：执行Copy-Paste操作的概率，默认为0.5。
def __init__(self, p=0.5) -> None:
# 使用给定的概率初始化 CopyPaste 类。
"""
Initializes the CopyPaste class with a given probability.
Args:
p (float, optional): The probability of applying the Copy-Paste augmentation. Must be between 0 and 1.
Default is 0.5.
"""
# 将传入的 p 参数赋值给实例变量 self.p 。
self.p = p
# 调用方法。
# 定义了类的调用方法 __call__ ，接收一个参数。
# 1.labels ：这是一个字典，包含了图像数据和其他标签信息。
def __call__(self, labels):
# 将复制粘贴增强功能应用于给定的图像和实例。
# 注意事项：
# 1. 实例需要将 'segments' 作为其属性之一，才能使此增强功能发挥作用。
# 2. 此方法会就地修改输入字典 'labels'。
"""
Applies the Copy-Paste augmentation to the given image and instances.
Args:
labels (dict): A dictionary containing:
- 'img': The image to augment.
- 'cls': Class labels associated with the instances.
- 'instances': Object containing bounding boxes, and optionally, keypoints and segments.
Returns:
(dict): Dict with augmented image and updated instances under the 'img', 'cls', and 'instances' keys.
Notes:
1. Instances are expected to have 'segments' as one of their attributes for this augmentation to work.
2. This method modifies the input dictionary 'labels' in place.
"""
# 从 labels 字典中提取 图像数据 。
im = labels["img"]
# 从 labels 字典中提取 类别标签 。
cls = labels["cls"]
# 获取图像的 高度 和 宽度 。
h, w = im.shape[:2]
# 提取 实例信息 ，并从 labels 中移除 "instances" 键。
instances = labels.pop("instances")
# 确保边界框格式为 xyxy 。
instances.convert_bbox(format="xyxy")
# 对 边界框进行反归一化 ，将归一化坐标转换为实际像素坐标。
instances.denormalize(w, h)
# 应用Copy-Paste增强。
# 如果执行Copy-Paste操作的概率不为0且存在分割掩码，则进行Copy-Paste增强。
if self.p and len(instances.segments):
# 获取 实例的数量 。
n = len(instances)
# 获取图像的宽度。
_, w, _ = im.shape # height, width, channels
# 创建一个与原图像相同尺寸的空白图像，用于绘制复制的实例。
im_new = np.zeros(im.shape, np.uint8)
# Calculate ioa first then select indexes randomly
# 深拷贝实例信息，用于水平翻转。
ins_flip = deepcopy(instances)
# 对复制的实例进行水平翻转。
# def fliplr(self, w): -> 用于对实例中的边界框、分割掩码和关键点进行左右翻转（水平翻转）。
ins_flip.fliplr(w)
# 计算翻转后的实例与原始实例的交并比（Intersection over Area, IOA）。
# def bbox_ioa(box1, box2, iou=False, eps=1e-7): -> 用于计算两个边界框集合之间的交并比（Intersection over Area, IOA）。返回交并比（IOA或IoU）。为了避免除以零的错误，加上一个小的常数 eps 。 -> return inter_area / (area + eps)
ioa = bbox_ioa(ins_flip.bboxes, instances.bboxes) # intersection over area, (N, M)
# np.nonzero(a, size=None)
# np.nonzero() 是 NumPy 库中的一个函数，它返回输入数组中非零元素的索引。这个函数对于找出数组中满足特定条件的元素位置非常有用，尤其是在处理条件过滤和索引操作时。
# 参数 ：
# a ：输入的数组。
# size ：一个整数或整数元组。如果提供，输出数组的大小将被修改以匹配这个参数。这个参数主要用于兼容旧版本的 NumPy。
# 返回值 ：
# np.nonzero() 返回一个元组，其中包含输入数组中非零元素的索引数组。每个索引数组对应输入数组的一个维度。
# 如果输入数组是一维的，返回的是一个包含索引的单个数组。
# 如果输入数组是多维的，返回的是与输入数组维度相同数量的数组，每个数组包含对应维度上的索引。
# 小于0.30的实例索引，确保复制的实例不会与原始实例重叠太多。
# 这行代码在 CopyPaste 类的 __call__ 方法中，用于选择符合条件的实例索引。具体来说，它选择那些翻转后的实例与原始实例的交并比（Intersection over Area, IOA）小于0.30的实例。
# indexes = np.nonzero((ioa < 0.30).all(1))[0] ：选择IOA小于0.30的实例索引。
# ioa < 0.30 ：创建一个布尔数组，表示每个翻转后的实例与所有原始实例的IOA是否小于0.30。
# (ioa < 0.30).all(1) ：对每一行（即每个翻转后的实例）进行逻辑与操作，确保该实例与所有原始实例的IOA都小于0.30。
# np.nonzero(...)[0] ：获取满足条件的行索引，即符合条件的翻转后实例的索引。
# 作用 ：这行代码的作用是选择那些翻转后的实例，这些实例与所有原始实例的交并比都小于0.30。这样可以确保复制的实例不会与原始实例重叠太多，从而避免生成过于复杂的图像，影响模型的训练效果。
# 示例 ：
# 假设 ioa 数组如下 ：
# ioa = np.array([
# [0.25, 0.20, 0.15], # 翻转后实例1与原始实例的IOA
# [0.35, 0.25, 0.10], # 翻转后实例2与原始实例的IOA
# [0.10, 0.15, 0.20] # 翻转后实例3与原始实例的IOA
# ])
# 执行 ioa < 0.30 后得到 ：
# np.array([
# [True, True, True], # 翻转后实例1与所有原始实例的IOA都小于0.30
# [False, True, True], # 翻转后实例2与原始实例1的IOA大于0.30
# [True, True, True] # 翻转后实例3与所有原始实例的IOA都小于0.30
# ])
# 执行 (ioa < 0.30).all(1) 后得到 ：
# np.array([True, False, True]) # 翻转后实例1和3满足条件
# 最后， np.nonzero(...)[0] 得到 ：
# np.array([0, 2]) # 翻转后实例1和3的索引
# 总结 ：这行代码通过计算翻转后实例与原始实例的交并比，选择那些与所有原始实例的交并比都小于0.30的实例索引，确保复制的实例不会与原始实例重叠太多，从而生成更合理的增强图像。
indexes = np.nonzero((ioa < 0.30).all(1))[0] # (N, )
# 获取符合条件的实例数量。
n = len(indexes)
# random.sample(population, k)
# random.sample 是 Python 标准库 random 模块中的一个函数，它用于从一个序列中随机选择指定数量的不重复元素，并返回一个新列表。
# population ：一个序列，表示可供选择的元素集合。
# k ：一个整数，表示需要随机选择的元素数量。
# 返回值 ：
# 返回一个新列表，包含从 population 中随机选择的 k 个不重复元素。
# 功能 ：
# random.sample 函数可以确保从 population 中选择的 k 个元素是唯一的，不会有重复。如果 population 中的元素数量小于 k ，则抛出 ValueError 。
# 注意事项 ：
# population 必须是一个序列，例如列表、元组或字符串。
# k 的值不能大于 population 中元素的数量，否则会抛出 ValueError 。
# 每次调用 random.sample 都会生成一个新的随机选择的列表，因为随机数生成器的状态在每次调用时都会改变。
# 随机选择一定比例的实例进行复制。
# 这行代码在 CopyPaste 类的 __call__ 方法中，用于从符合条件的实例索引中随机选择一定数量的实例进行复制。具体来说，它根据指定的概率 self.p 选择实例索引。
# for j in random.sample(list(indexes), k=round(self.p * n)): ：从符合条件的实例索引中随机选择一定数量的实例进行复制。
# indexes ：符合条件的实例索引列表。
# n ：符合条件的实例数量。
# self.p ：执行Copy-Paste操作的概率。
# k=round(self.p * n) ：计算需要选择的实例数量，即 self.p * n 的四舍五入值。
# random.sample(list(indexes), k=round(self.p * n)) ：从 indexes 列表中随机选择 k 个不重复的元素。
# 作用 ：这行代码的作用是从符合条件的实例索引中随机选择一定数量的实例进行复制。通过这种方式，可以确保每次增强操作中选择的实例数量是随机的，增加了数据的多样性，提高了模型的泛化能力。
# 示例 ：
# 假设 indexes 列表为 [0, 2, 4, 6, 8] ，表示有5个符合条件的实例。 n 为5， self.p 为0.5。那么 ：
# k=round(self.p * n) 计算为 round(0.5 * 5) = 2 。
# random.sample(list(indexes), k=2) 可能返回 [0, 4] ，表示从 indexes 中随机选择索引0和4的实例进行复制。
# 总结 ：这行代码通过随机选择符合条件的实例索引，确保每次增强操作中选择的实例数量是随机的，增加了数据的多样性，提高了模型的泛化能力。这对于Copy-Paste数据增强技术非常有用，可以生成更多样的训练样本。
for j in random.sample(list(indexes), k=round(self.p * n)):
# 将选择的实例的类别标签添加到类别标签列表中。
cls = np.concatenate((cls, cls[[j]]), axis=0)
# 将选择的实例添加到实例信息中。
instances = Instances.concatenate((instances, ins_flip[[j]]), axis=0)
# cv2.drawContours(image, contours, contourIdx, color, thickness=None, lineType=8, hierarchy=None)
# cv2.drawContours 是 OpenCV 库中的一个函数，它用于在图像上绘制轮廓。这个函数可以绘制简单的轮廓或复杂的轮廓，并且可以对轮廓进行填充。
# image ：要绘制轮廓的图像。
# contours ：轮廓的列表，其中每个轮廓都是一个点集的数组。
# contourIdx ：要绘制的轮廓的索引。如果为 -1 ，则绘制所有轮廓。
# color ：轮廓的颜色，以 BGR 格式指定。
# thickness ：轮廓的线条粗细。如果为负值，则轮廓将被填充。
# lineType ：轮廓的线条类型，例如 8 表示 cv2.LINE_8 ， cv2.CV_AA 表示抗锯齿线条。
# hierarchy ：轮廓的层次结构，用于指定轮廓之间的关系。
# 返回值 :
# 该函数不返回任何值，它直接在输入图像 image 上进行绘制。
# 注意事项 :
# 当 thickness 为负值时，例如 -1 ，轮廓将被填充。
# hierarchy 参数可以用来指定轮廓之间的父子关系，这对于处理具有嵌套结构的轮廓非常有用。
# cv2.drawContours 函数可以一次绘制多个轮廓，只需将它们作为列表传递给 contours 参数。
# 在空白图像上绘制选择的实例的分割掩码。
cv2.drawContours(im_new, instances.segments[[j]].astype(np.int32), -1, (1, 1, 1), cv2.FILLED)
# 对原图像进行水平翻转。
result = cv2.flip(im, 1) # augment segments (flip left-right)
# 对空白图像进行水平翻转，并转换为布尔数组。
i = cv2.flip(im_new, 1).astype(bool)
# 将翻转后的图像中对应的位置替换为原图像中的内容。
im[i] = result[i]
# 更新 labels 字典。
# 更新图像数据。
labels["img"] = im
# 更新类别标签。
labels["cls"] = cls
# 更新实例信息。
labels["instances"] = instances
# 返回更新后的 labels 字典。
return labels
# CopyPaste 类通过以下步骤实现Copy-Paste数据增强。初始化类实例，设置执行Copy-Paste操作的概率。提取图像数据、类别标签和实例信息。确保边界框格式为 xyxy ，并对边界框进行反归一化。计算翻转后的实例与原始实例的交并比，选择IOA小于0.30的实例进行复制。随机选择一定比例的实例进行复制，并将它们添加到实例信息中。在空白图像上绘制选择的实例的分割掩码。对原图像进行水平翻转，并将翻转后的图像中对应的位置替换为原图像中的内容。更新 labels 字典中的图像数据、类别标签和实例信息。返回更新后的 labels 字典。这个类确保在对图像进行Copy-Paste增强后，图像和标签仍然准确地表示目标对象的位置和形状，从而增加数据的多样性，提高模型的泛化能力。12.class Albumentations:
# 这段代码定义了一个名为 Albumentations 的类，用于将Albumentations库中的图像增强操作应用于图像及其标签。Albumentations是一个流行的图像增强库，提供了丰富的图像变换功能。
# 定义了 Albumentations 类。
class Albumentations:
# Albumentations 转换。
# 可选，卸载包以禁用。应用模糊、中值模糊、转换为灰度、对比度限制自适应直方图均衡、亮度和对比度的随机变化、RandomGamma 和通过压缩降低图像质量。
"""
Albumentations transformations.
Optional, uninstall package to disable. Applies Blur, Median Blur, convert to grayscale, Contrast Limited Adaptive
Histogram Equalization, random change of brightness and contrast, RandomGamma and lowering of image quality by
compression.
"""
# 这段代码定义了 Albumentations 类的初始化方法 __init__ ，用于设置图像增强操作的概率并初始化Albumentations库的变换。
# 定义了类的初始化方法 __init__ ，接收一个参数。
# 1.p ：执行图像增强操作的概率，默认为1.0。
def __init__(self, p=1.0):
# 为 YOLO bbox 格式的参数初始化转换对象。
"""Initialize the transform object for YOLO bbox formatted params."""
# 初始化变量。
# 将传入的 p 参数赋值给实例变量 self.p 。
self.p = p
# 初始化 变换对象 为 None 。
self.transform = None
# 定义日志前缀，用于记录信息。
# def colorstr(*input):
# -> 用于生成带有颜色和其他格式化选项的字符串，通常用于在终端或命令行界面中输出彩色文本。构建并返回最终的字符串。它通过遍历 args 中的每个元素，查找 colors 字典中对应的 ANSI 转义序列，并将它们与 string 连接起来。最后，它添加一个结束转义序列 colors["end"] 来重置终端的颜色和样式设置。
# -> return "".join(colors[x] for x in args) + f"{string}" + colors["end"]
prefix = colorstr("albumentations: ")
# 尝试导入和初始化。
# 尝试导入Albumentations库并进行版本检查。
try:
# 导入Albumentations库。
import albumentations as A
# 检查Albumentations库的版本是否满足要求，确保版本不低于1.0.3。
# def check_version(current: str = "0.0.0", required: str = "0.0.0", name: str = "version", hard: bool = False, verbose: bool = False, msg: str = "",) -> bool:
# -> 用于检查当前安装的软件包版本是否满足特定的要求。返回 result ，表示版本检查是否通过。
# -> return result
check_version(A.__version__, "1.0.3", hard=True) # version requirement
# Transforms
# 定义一系列图像增强操作，每个操作都有一个指定的概率 p 。
T = [
# 模糊操作，概率为0.01。
A.Blur(p=0.01),
# 中值模糊操作，概率为0.01。
A.MedianBlur(p=0.01),
# 转换为灰度图像，概率为0.01。
A.ToGray(p=0.01),
# 对比度限制的自适应直方图均衡化，概率为0.01。
A.CLAHE(p=0.01),
# 随机亮度和对比度调整，概率为0.0。
A.RandomBrightnessContrast(p=0.0),
# 随机伽马校正，概率为0.0。
A.RandomGamma(p=0.0),
# 图像压缩，质量下限为75，概率为0.0。
A.ImageCompression(quality_lower=75, p=0.0),
]
# A.Compose(transforms, bbox_params=None, keypoint_params=None, mask_params=None, p=1.0)
# albumentations.Compose 是 Albumentations 库中的一个函数，它用于组合多个图像变换（transforms）成一个复合变换（composition）。这个复合变换可以同时应用于图像和与之相关的标注（如边界框、关键点、掩码等）。
# 参数说明 ：
# transforms : 一个包含多个变换的列表。每个变换可以是一个单独的变换类实例，也可以是一个变换序列。
# bbox_params : 一个 BboxParams 对象，用于定义如何应用变换到边界框。如果为 None ，则不会对边界框应用任何变换。
# keypoint_params : 一个 KeypointParams 对象，用于定义如何应用变换到关键点。如果为 None ，则不会对关键点应用任何变换。
# mask_params : 一个 MaskParams 对象，用于定义如何应用变换到掩码。如果为 None ，则不会对掩码应用任何变换。
# p : 一个浮点数，表示应用整个复合变换的概率。值范围从 0 到 1，其中 1 表示总是应用变换。
# 返回值 ：
# 返回一个复合变换对象，可以被用于图像增强流程中。
# A.BboxParams(format=None, label_fields=None, min_area=0.0, min_visibility=0.0, check_each_transform=True)
# A.BboxParams() 是 Albumentations 库中用于定义边界框参数的类，一般用在 A.Compose() 实例的初始化参数中。
# 参数说明 ：
# format : 边界框的格式。可以是 "coco" 、 "pascal_voc" 、 "albumentations" 或 "yolo" 。
# "coco" 格式 ： [x_min, y_min, width, height] 。
# "pascal_voc" 格式 ： [x_min, y_min, x_max, y_max] 。
# "albumentations" 格式 ： 与 "pascal_voc" 相同，但归一化到 [0, 1] 范围内。
# "yolo" 格式 ： [x, y, width, height] ，其中 x, y 指归一化的边界框中心， width, height 指归一化的边界框宽高。
# label_fields : 与边界框相关联的标签字段列表。如果边界框和类别标签写在一起，则不需要此参数。
# min_area : 边界框的最小面积（以像素为单位）。所有可见面积小于这个值的边界框将被移除。默认为 0.0 。
# min_visibility : 边界框保持在列表中的最小可见面积比。默认为 0.0 。
# check_each_transform : 如果为 True ，在每个双重变换后都会检查边界框是否满足限制。默认为 True 。
# 使用 BboxParams 时，你需要根据你的数据集和边界框的格式来设置这些参数。这确保了在应用图像增强变换时，边界框能够被正确地处理和转换。
# 组合这些操作，并设置边界框参数。 bbox_params 用于指定边界框的格式和标签字段。
self.transform = A.Compose(T, bbox_params=A.BboxParams(format="yolo", label_fields=["class_labels"]))
# 记录应用的增强操作，去除不必要的日志信息。
LOGGER.info(prefix + ", ".join(f"{x}".replace("always_apply=False, ", "") for x in T if x.p))
# 异常处理。
# 如果Albumentations库未安装，跳过初始化，记录信息。
except ImportError: # package not installed, skip
pass
# 捕获其他异常，并记录错误信息。
except Exception as e:
LOGGER.info(f"{prefix}{e}")
# Albumentations 类的初始化方法 __init__ 通过以下步骤设置图像增强操作。初始化类实例，设置执行图像增强操作的概率。尝试导入Albumentations库并进行版本检查。定义一系列图像增强操作，每个操作都有一个指定的概率。组合这些操作，并设置边界框参数。记录应用的增强操作，确保在日志中显示相关信息。如果Albumentations库未安装或出现其他异常，记录相应的信息。这个类确保在对图像进行预处理时，可以灵活地应用多种图像增强操作，增加数据的多样性，提高模型的泛化能力。
# 这段代码定义了 Albumentations 类中的 __call__ 方法，用于对图像及其标签进行Albumentations库中的图像增强操作。
# 定义了类的调用方法 __call__ ，接收一个参数。
# 1.labels ：这是一个字典，包含了图像数据和其他标签信息。
def __call__(self, labels):
# 生成对象检测并返回包含检测结果的字典。
"""Generates object detections and returns a dictionary with detection results."""
# 提取图像和类别标签。
# 从 labels 字典中提取图像数据。
im = labels["img"]
# 从 labels 字典中提取类别标签。
cls = labels["cls"]
# 检查是否存在类别标签。
# 如果存在类别标签，进行图像增强。
if len(cls):
# 将边界框格式转换为 xywh 。
labels["instances"].convert_bbox("xywh")
# 对边界框进行归一化，将坐标转换为相对坐标。
# def normalize(self, w, h): -> 用于将实例中的边界框、分割掩码和关键点的坐标从绝对坐标状态转换为归一化状态。
# 这行代码在 Albumentations 类的 __call__ 方法中，用于对边界框进行归一化处理。归一化处理是将边界框的坐标从绝对像素值转换为相对图像尺寸的比例值。这样可以确保边界框在不同尺寸的图像中保持一致的比例关系。
# labels["instances"].normalize(*im.shape[:2][::-1]) ：对边界框进行归一化处理。
# im.shape[:2] ：获取图像的 高度 和 宽度 ，返回一个元组 (height, width) 。
# im.shape[:2][::-1] ：将 高度 和 宽度 的 顺序颠倒 ，返回一个元组 (width, height) 。
# *im.shape[:2][::-1] ：将元组 (width, height) 解包为两个参数，分别传递给 normalize 方法。
# labels["instances"].normalize(width, height) ：调用 normalize 方法，将边界框的坐标从绝对像素值转换为相对图像尺寸的比例值。
# 作用 ：这行代码的作用是将边界框的坐标从绝对像素值转换为相对图像尺寸的比例值。这样可以确保边界框在不同尺寸的图像中保持一致的比例关系，便于后续的图像增强和模型训练。
# 总结 ：这行代码通过将边界框的坐标从绝对像素值转换为相对图像尺寸的比例值，确保边界框在不同尺寸的图像中保持一致的比例关系。这对于后续的图像增强和模型训练非常有用，可以提高模型的泛化能力。
# 在图像处理和计算机视觉任务中，图像的形状通常表示为 (高度, 宽度, 通道数) 。然而，在处理边界框和分割掩码时，我们通常需要使用宽度和高度的顺序，因为这些坐标系的定义通常是基于 (x, y) ，其中 x 表示水平方向（宽度）， y 表示垂直方向（高度）。
# 为什么使用 [::-1] 将高度和宽度的顺序颠倒？
# 图像形状的表示 ：图像的形状通常表示为 (高度, 宽度, 通道数) 。例如，一个640x480的RGB图像，其形状为 (480, 640, 3) 。 im.shape[:2] 提取前两个维度，即 (高度, 宽度) ，在这个例子中为 (480, 640) 。
# 边界框和坐标系的定义 ：边界框的坐标通常表示为 (x1, y1, x2, y2) 或 (cx, cy, w, h) ，其中 x 表示水平方向（宽度）， y 表示垂直方向（高度）。 为了将边界框的坐标从绝对像素值转换为相对图像尺寸的比例值，我们需要使用图像的宽度和高度。
# 颠倒顺序 ： im.shape[:2][::-1] 将 (高度, 宽度) 颠倒为 (宽度, 高度) 。在这个例子中， (480, 640) 颠倒为 (640, 480) 。 这样可以确保在归一化边界框坐标时，使用正确的宽度和高度顺序。
# 代码示例 ：
# 假设我们有一个图像，其形状为 (480, 640, 3) ，即高度为480，宽度为640。边界框的坐标为 (100, 150, 300, 450) ，即左上角坐标为 (100, 150) ，右下角坐标为 (300, 450) 。那么 ：
# im = np.zeros((480, 640, 3), dtype=np.uint8) # 创建一个480x640的图像
# bboxes = np.array([[100, 150, 300, 450]], dtype=np.float32) # 创建一个边界框
# 归一化边界框 ：
# width, height = im.shape[:2][::-1] # (640, 480)
# normalized_bboxes = bboxes / np.array([width, height, width, height])
# 计算结果 ：
# normalized_bboxes = np.array([[100 / 640, 150 / 480, 300 / 640, 450 / 480]])
# 输出 ：
# [[0.15625, 0.3125, 0.46875, 0.9375]]
# 总结 ：使用 [::-1] 将高度和宽度的顺序颠倒，是为了确保在归一化边界框坐标时，使用正确的宽度和高度顺序。这样可以确保边界框的坐标在不同尺寸的图像中保持一致的比例关系，便于后续的图像增强和模型训练。
labels["instances"].normalize(*im.shape[:2][::-1])
# 提取边界框。
bboxes = labels["instances"].bboxes
# TODO: add supports of segments and keypoints TODO：添加段和关键点的支持。
# 应用图像增强操作。
# 如果定义了变换对象且随机数小于 self.p ，应用图像增强。
if self.transform and random.random() < self.p:
# 应用Albumentations库中的图像增强操作，返回一个新的字典 new ，包含 变换后的图像 、 边界框 和 类别标签 。
new = self.transform(image=im, bboxes=bboxes, class_labels=cls) # transformed
# 如果变换后的图像中存在边界框，更新 labels 字典。
if len(new["class_labels"]) > 0: # skip update if no bbox in new im
# 更新图像数据。
labels["img"] = new["image"]
# 更新类别标签。
labels["cls"] = np.array(new["class_labels"])
# 更新边界框。
bboxes = np.array(new["bboxes"], dtype=np.float32)
# 更新实例信息。更新实例信息中的边界框。
labels["instances"].update(bboxes=bboxes)
# 返回更新后的标签。返回更新后的 labels 字典。
return labels
# Albumentations 类的 __call__ 方法通过以下步骤对图像及其标签进行Albumentations库中的图像增强操作。提取图像数据和类别标签。如果存在类别标签，将边界框格式转换为 xywh ，并对边界框进行归一化。应用Albumentations库中的图像增强操作，更新图像数据、类别标签和边界框。返回更新后的 labels 字典。这个方法确保在对图像进行预处理时，图像和标签仍然准确地表示目标对象的位置和形状，从而增加数据的多样性，提高模型的泛化能力。
# Albumentations 类通过以下步骤将Albumentations库中的图像增强操作应用于图像及其标签。初始化类实例，设置执行图像增强操作的概率。导入Albumentations库并进行版本检查，定义一系列图像增强操作。提取图像数据和类别标签。如果存在类别标签，将边界框格式转换为 xywh ，并对边界框进行归一化。应用图像增强操作，更新图像数据、类别标签和边界框。返回更新后的 labels 字典。这个类确保在对图像进行预处理时，图像和标签仍然准确地表示目标对象的位置和形状，从而增加数据的多样性，提高模型的泛化能力。
# 在计算机视觉和目标检测任务中，"实例信息"（Instance Information）通常指的是与图像中每个独立对象（实例）相关联的详细信息。这些信息可以帮助模型更好地理解和处理图像中的各个对象。实例信息通常包括以下几个方面 ：
# 边界框（Bounding Boxes） ：
# 边界框是定义对象在图像中位置的矩形区域，通常用四个坐标值表示：左上角的x坐标、左上角的y坐标、右下角的x坐标和右下角的y坐标（格式为 [x1, y1, x2, y2] ），或者中心点的x坐标、中心点的y坐标、宽度和高度（格式为 [cx, cy, w, h] ）。
# 类别标签（Class Labels） ：
# 每个实例都属于一个特定的类别，类别标签是一个整数或字符串，表示该实例的类别。例如，在目标检测任务中，类别标签可以是“人”、“车”、“猫”等。
# 分割掩码（Segmentation Masks） ：
# 分割掩码是一个与图像尺寸相同的二值图像，用于表示对象的精确轮廓。每个像素值为1表示该像素属于该对象，为0表示不属于。分割掩码可以提供比边界框更精确的对象形状信息。
# 关键点（Keypoints） ：
# 关键点是对象上的特定位置，例如人的关节（如头部、肩膀、肘部等）。关键点通常用一组坐标值表示，每个关键点有一个或多个坐标值（通常是 [x, y] 或 [x, y, visibility] ，其中 visibility 表示关键点的可见性）。
# 其他属性 ：
# 实例信息还可以包括其他属性，如对象的置信度（confidence score）、跟踪ID（用于视频中的对象跟踪）等。
# 总结 ：实例信息是目标检测和分割任务中非常重要的数据结构，它包含了每个对象的详细信息，如边界框、类别标签、分割掩码和关键点。这些信息可以帮助模型更准确地识别和处理图像中的各个对象，提高模型的性能和泛化能力。13.class Format:
# TODO：从技术上来说这不是一个增强，也许我们应该把它放到另一个文件中。
# TODO: technically this is not an augmentation, maybe we should put this to another files
# 这段代码定义了一个名为 Format 的类，用于对图像及其标签进行格式化处理，以便于后续的训练和推理。这个类提供了多种选项，可以处理边界框、分割掩码、关键点和定向边界框（OBB）。
# 定义了 Format 类。
class Format:
# 为目标检测、实例分割和姿势估计任务格式化图像注释。该类标准化了 PyTorch DataLoader 中的 `collate_fn` 将使用的图像和实例注释。
"""
Formats image annotations for object detection, instance segmentation, and pose estimation tasks. The class
standardizes the image and instance annotations to be used by the `collate_fn` in PyTorch DataLoader.
Attributes:
bbox_format (str): Format for bounding boxes. Default is 'xywh'.
normalize (bool): Whether to normalize bounding boxes. Default is True.
return_mask (bool): Return instance masks for segmentation. Default is False.
return_keypoint (bool): Return keypoints for pose estimation. Default is False.
mask_ratio (int): Downsample ratio for masks. Default is 4.
mask_overlap (bool): Whether to overlap masks. Default is True.
batch_idx (bool): Keep batch indexes. Default is True.
bgr (float): The probability to return BGR images. Default is 0.0.
"""
# 初始化方法。
# 定义了类的初始化方法 __init__ ，接收多个参数。
# 1.bbox_format ：边界框的格式，默认为 "xywh" 。
# 2.normalize ：是否对边界框进行归一化，默认为 True 。
# 3.return_mask ：是否返回分割掩码，默认为 False 。
# 4.return_keypoint ：是否返回关键点，默认为 False 。
# 5.return_obb ：是否返回定向边界框（OBB），默认为 False 。
# 6.mask_ratio ：分割掩码的下采样比例，默认为4。
# 7.mask_overlap ：是否处理重叠的分割掩码，默认为 True 。
# 8.batch_idx ：是否保留批次索引，默认为 True 。
# 9.bgr ：是否将图像从BGR格式转换为RGB格式，默认为 0.0 。
def __init__(
self,
bbox_format="xywh",
normalize=True,
return_mask=False,
return_keypoint=False,
return_obb=False,
mask_ratio=4,
mask_overlap=True,
batch_idx=True,
bgr=0.0,
):
# 使用给定的参数初始化 Format 类。
"""Initializes the Format class with given parameters."""
self.bbox_format = bbox_format
self.normalize = normalize
self.return_mask = return_mask # set False when training detection only 仅在训练检测时设置 False 。
self.return_keypoint = return_keypoint
self.return_obb = return_obb
self.mask_ratio = mask_ratio
self.mask_overlap = mask_overlap
self.batch_idx = batch_idx # keep the batch indexes 保留批次索引。
self.bgr = bgr
# 这段代码定义了 Format 类中的 __call__ 方法，用于对图像及其标签进行格式化处理，以便于后续的训练和推理。
# 定义了类的调用方法 __call__ ，接收一个参数。
# 1.labels ：这是一个字典，包含了图像数据和其他标签信息。
def __call__(self, labels):
# 返回格式化的图像、类别、边界框和关键点以供‘collate_fn’使用。
"""Return formatted image, classes, bounding boxes & keypoints to be used by 'collate_fn'."""
# 提取图像和标签信息。
# 从 labels 字典中提取 图像数据 。
img = labels.pop("img")
# 获取图像的 高度 和 宽度 。
h, w = img.shape[:2]
# 从 labels 字典中提取 类别标签 。
cls = labels.pop("cls")
# 从 labels 字典中提取 实例信息 。
instances = labels.pop("instances")
# 将边界框格式转换为指定的格式。
instances.convert_bbox(format=self.bbox_format)
# 对边界框进行反归一化，将坐标转换为绝对像素值。
instances.denormalize(w, h)
# 获取实例的数量。
nl = len(instances)
# 处理分割掩码。
# 如果需要返回分割掩码。
if self.return_mask:
# 如果存在实例。
if nl:
# 格式化分割掩码。
masks, instances, cls = self._format_segments(instances, cls, w, h)
# 将分割掩码转换为PyTorch张量。
masks = torch.from_numpy(masks)
# 如果不存在实例。
else:
# 创建一个空的分割掩码张量。
# 这行代码在 Format 类的 __call__ 方法中，用于创建一个空的分割掩码张量。这个张量的形状取决于 是否处理重叠的分割掩码 （ mask_overlap ）以及 下采样比例 （ mask_ratio ）。
# masks = torch.zeros(1 if self.mask_overlap else nl, img.shape[0] // self.mask_ratio, img.shape[1] // self.mask_ratio) ：创建一个空的分割掩码张量。
# 1 if self.mask_overlap else nl ：如果 self.mask_overlap 为 True ，则创建一个形状为 (1, height // mask_ratio, width // mask_ratio) 的张量，表示所有实例的分割掩码合并为一个张量。如果 self.mask_overlap 为 False ，则创建一个形状为 (nl, height // mask_ratio, width // mask_ratio) 的张量，表示每个实例一个分割掩码。
# img.shape[0] // self.mask_ratio ：计算下采样后的高度， img.shape[0] 是图像的高度， self.mask_ratio 是下采样比例。
# img.shape[1] // self.mask_ratio ：计算下采样后的宽度， img.shape[1] 是图像的宽度， self.mask_ratio 是下采样比例。
# torch.zeros(...) ：创建一个全零张量，形状为 (1 or nl, height // mask_ratio, width // mask_ratio) 。
# 作用 ：这行代码的作用是创建一个空的分割掩码张量，用于存储格式化后的分割掩码。这个张量的形状取决于是否处理重叠的分割掩码以及下采样比例。下采样可以减少分割掩码的分辨率，从而减少内存使用和计算量。
# 示例 ：
# 假设图像的尺寸为 (480, 640, 3) ，即高度为480，宽度为640。下采样比例为4，实例数量为3。那么 ：
# img.shape[0] // self.mask_ratio 计算为 480 // 4 = 120 。
# img.shape[1] // self.mask_ratio 计算为 640 // 4 = 160 。
# 如果 self.mask_overlap 为 True ：创建一个形状为 (1, 120, 160) 的全零张量。
# 如果 self.mask_overlap 为 False ： 创建一个形状为 (3, 120, 160) 的全零张量。
# 总结 ：这行代码通过创建一个空的分割掩码张量，确保在处理分割掩码时，张量的形状和尺寸符合要求。下采样可以减少分割掩码的分辨率，从而减少内存使用和计算量。这在处理大规模数据集时非常有用，可以提高处理效率。
masks = torch.zeros(
1 if self.mask_overlap else nl, img.shape[0] // self.mask_ratio, img.shape[1] // self.mask_ratio
)
# 将 分割掩码 添加到 labels 字典中。
labels["masks"] = masks
# 归一化边界框。
# 如果需要对边界框进行归一化。
if self.normalize:
# 对边界框进行归一化，将坐标转换为相对图像尺寸的比例值。
instances.normalize(w, h)
# 格式化图像。格式化图像数据。
labels["img"] = self._format_img(img)
# 格式化类别标签和边界框。
# 将类别标签转换为PyTorch张量。
labels["cls"] = torch.from_numpy(cls) if nl else torch.zeros(nl)
# 将边界框转换为PyTorch张量。
labels["bboxes"] = torch.from_numpy(instances.bboxes) if nl else torch.zeros((nl, 4))
# 处理关键点。
# 如果需要返回关键点。
if self.return_keypoint:
# 将关键点转换为PyTorch张量。
labels["keypoints"] = torch.from_numpy(instances.keypoints)
# 处理定向边界框（OBB）。
# 如果需要返回定向边界框（OBB）。
if self.return_obb:
# 将多边形转换为OBB格式。
labels["bboxes"] = (
# def xyxyxyxy2xywhr(corners):
# -> 用于将八个顶点坐标（xyxyxyxy）格式转换为旋转矩形的中心点坐标、宽高和旋转角度（xywhr）格式。根据 corners 的数据类型，将 rboxes 转换为相应的张量或数组并返回。如果 corners 是PyTorch张量，将 rboxes 转换为PyTorch张量，并将其移动到与 corners 相同的设备上，数据类型也与 corners 相同；否则，将 rboxes 转换为NumPy数组。
# -> return (torch.tensor(rboxes, device=corners.device, dtype=corners.dtype) if is_torch else np.asarray(rboxes, dtype=points.dtype)) # rboxes
xyxyxyxy2xywhr(torch.from_numpy(instances.segments)) if len(instances.segments) else torch.zeros((0, 5))
)
# Then we can use collate_fn
# 添加批次索引。
# 如果需要保留批次索引。
if self.batch_idx:
# 创建一个批次索引张量。
labels["batch_idx"] = torch.zeros(nl)
# 返回格式化后的 labels 字典。
return labels
# Format 类的 __call__ 方法通过以下步骤对图像及其标签进行格式化处理。提取图像数据、类别标签和实例信息。将边界框格式转换为指定的格式，并进行反归一化。如果需要，处理分割掩码，生成分割掩码张量。如果需要，对边界框进行归一化。格式化图像数据，将图像从HWC格式转换为CHW格式，并处理颜色通道。格式化类别标签和边界框，将它们转换为PyTorch张量。如果需要，处理关键点和定向边界框（OBB）。如果需要，添加批次索引。返回格式化后的 labels 字典。这个类确保在对图像进行预处理时，图像和标签的格式化处理一致，便于后续的训练和推理。
# 这段代码定义了 Format 类中的 _format_img 方法，用于对图像数据进行格式化处理，以便于后续的训练和推理。
# 定义了 _format_img 方法，接收一个参数.
# 1.img ：图像数据。
def _format_img(self, img):
# 将 YOLO 的图像从 Numpy 数组格式化为 PyTorch 张量。
"""Format the image for YOLO from Numpy array to PyTorch tensor."""
# 处理单通道图像。
# 检查图像数据的维度。如果图像数据是单通道的（即维度小于3），则增加一个通道维度。
if len(img.shape) < 3:
# numpy.expand_dims(a, axis)
# np.expand_dims 函数是NumPy库中的一个非常有用的函数，用于在数组的指定位置插入一个新的轴（维度）。这在处理多维数组时非常有用，尤其是在需要调整数组形状以匹配特定函数或模型输入要求时。
# 参数 ：
# a ：输入数组。
# axis ：插入新轴的位置。可以是整数或整数元组。
# 返回值 ：
# 返回一个新的数组，其形状在指定的 axis 位置增加了一个维度。
# np.expand_dims 函数通过在指定位置插入新轴，可以方便地调整数组的形状。这在处理多维数组时非常有用，尤其是在需要将一维数组转换为二维或更高维度数组时。这个函数返回的新数组与输入数组共享数据，因此不会增加额外的内存开销。
# 使用 np.expand_dims 在最后一个维度上增加一个通道维度，将图像数据从 (height, width) 转换为 (height, width, 1) 。
img = np.expand_dims(img, -1)
# 转换图像格式。
# 将图像数据从HWC（高度、宽度、通道）格式转换为CHW（通道、高度、宽度）格式。这是PyTorch模型输入所需的格式。
img = img.transpose(2, 0, 1)
# 如果 self.bgr 为 True 且随机数大于 self.bgr ，则将图像从BGR格式转换为RGB格式。 img[::-1] 表示将图像的通道顺序颠倒。 np.ascontiguousarray 确保数组在内存中是连续的，这可以提高后续操作的效率。
img = np.ascontiguousarray(img[::-1] if random.uniform(0, 1) > self.bgr else img)
# 将图像数据从NumPy数组转换为PyTorch张量。
img = torch.from_numpy(img)
# 返回格式化后的图像数据。
return img
# _format_img 方法通过以下步骤对图像数据进行格式化处理。如果图像是单通道的，增加一个通道维度。将图像数据从HWC格式转换为CHW格式。如果需要，将图像从BGR格式转换为RGB格式。将图像数据从NumPy数组转换为PyTorch张量。这个方法确保在对图像进行预处理时，图像数据的格式化处理一致，便于后续的训练和推理。这对于确保模型输入的一致性和提高处理效率非常有用。
# 这段代码定义了 Format 类中的 _format_segments 方法，用于对实例的分割掩码进行格式化处理。
# 定义了 _format_segments 方法，接收四个参数。
# 1.instances ：实例信息，包含边界框和分割掩码。
# 2.cls ：类别标签。
# 3.w ：图像宽度。
# 4.h ：图像高度。
def _format_segments(self, instances, cls, w, h):
# 将多边形点转换为位图。
"""Convert polygon points to bitmap."""
# 提取分割掩码。从 instances 中提取分割掩码。
segments = instances.segments
# 处理重叠的分割掩码。
# 如果需要处理重叠的分割掩码。
if self.mask_overlap:
# 调用 polygons2masks_overlap 函数，处理重叠的分割掩码。这个函数返回一个 分割掩码张量 masks 和一个 排序索引 sorted_idx 。
# def polygons2masks_overlap(imgsz, segments, downsample_ratio=1): -> 用于处理多个可能存在重叠的多边形，并生成一个掩码图像，同时返回多边形的排序索引。返回最终的 掩码图像 masks 和 多边形的排序索引 index 。 -> return masks, index
masks, sorted_idx = polygons2masks_overlap((h, w), segments, downsample_ratio=self.mask_ratio)
# 增加一个批次维度，将形状从 (h, w) 转换为 (1, h, w) 。
masks = masks[None] # (640, 640) -> (1, 640, 640)
# 根据 排序索引 重新排序 实例信息 。
instances = instances[sorted_idx]
# 根据 排序索引 重新排序 类别标签 。
cls = cls[sorted_idx]
# 处理非重叠的分割掩码。
# 如果不需要处理重叠的分割掩码。
else:
# 调用 polygons2masks 函数，生成分割掩码。这个函数返回一个 分割掩码张量 masks 。
# def polygons2masks(imgsz, polygons, color, downsample_ratio=1): -> 用于将多个多边形批量转换为掩码图像数组。返回这个数组，数组中的每个元素是一个掩码图像，对应输入的每个多边形。 -> return np.array([polygon2mask(imgsz, [x.reshape(-1)], color, downsample_ratio) for x in polygons])
masks = polygons2masks((h, w), segments, color=1, downsample_ratio=self.mask_ratio)
# 返回 格式化后的分割掩码 、 实例信息 和 类别标签 。
return masks, instances, cls
# _format_segments 方法通过以下步骤对实例的分割掩码进行格式化处理。提取实例的分割掩码。如果需要处理重叠的分割掩码，调用 polygons2masks_overlap 函数，处理重叠的分割掩码，并根据排序索引重新排序实例信息和类别标签。如果不需要处理重叠的分割掩码，调用 polygons2masks 函数，生成分割掩码。返回格式化后的分割掩码、实例信息和类别标签。这个方法确保在对图像进行预处理时，分割掩码的格式化处理一致，便于后续的训练和推理。这对于处理复杂的分割任务，特别是涉及重叠对象的分割任务时非常有用。
# Format 类通过以下步骤对图像及其标签进行格式化处理。初始化类实例，设置各种格式化选项。提取图像数据、类别标签和实例信息。将边界框格式转换为指定的格式，并进行反归一化。如果需要，处理分割掩码，生成分割掩码张量。如果需要，对边界框进行归一化。格式化图像数据，将图像从HWC格式转换为CHW格式，并处理颜色通道。格式化类别标签和边界框，将它们转换为PyTorch张量。如果需要，处理关键点和定向边界框（OBB）。如果需要，添加批次索引。返回格式化后的 labels 字典。这个类确保在对图像进行预处理时，图像和标签的格式化处理一致，便于后续的训练和推理。14.def v8_transforms(dataset, imgsz, hyp, stretch=False):
# 这段代码定义了一个名为 v8_transforms 的函数，用于为YOLOv8训练准备图像数据增强流程。
# 定义函数 v8_transforms ，它有四个参数.
# 1.dataset ：数据集对象，包含数据集的相关信息和方法。
# 2.imgsz ：目标图像尺寸，用于调整图像大小。
# 3.hyp ：超参数对象，包含各种数据增强相关的超参数。
# 4.stretch ：布尔值，表示是否进行拉伸变换，默认为 False 。
def v8_transforms(dataset, imgsz, hyp, stretch=False):
# 将图像转换为适合 YOLOv8 训练的大小。
"""Convert images to a size suitable for YOLOv8 training."""
# 定义一个预处理变换 pre_transform ，使用 Compose 将多个变换组合在一起。
# class Compose:
# -> 用于组合多个图像变换操作。
# -> def __init__(self, transforms):
pre_transform = Compose(
[
# 进行马赛克增强，将多张图像拼接在一起， p 参数控制马赛克增强的概率。
Mosaic(dataset, imgsz=imgsz, p=hyp.mosaic),
# 进行复制粘贴增强，将一个图像中的对象复制到另一个图像中， p 参数控制复制粘贴增强的概率。
CopyPaste(p=hyp.copy_paste),
# 进行随机透视变换，包括旋转、平移、缩放、剪切和透视变换。 pre_transform 参数根据 stretch 的值决定是否使用 LetterBox 进行填充和调整图像尺寸。
RandomPerspective(
degrees=hyp.degrees,
translate=hyp.translate,
scale=hyp.scale,
shear=hyp.shear,
perspective=hyp.perspective,
pre_transform=None if stretch else LetterBox(new_shape=(imgsz, imgsz)),
),
]
)
# 从数据集对象中获取 flip_idx ，这是一个 用于关键点增强的索引数组 ，表示在水平翻转时关键点的对应关系。如果没有定义，则默认为空列表。
flip_idx = dataset.data.get("flip_idx", []) # for keypoints augmentation
# 如果数据集使用关键点。
if dataset.use_keypoints:
# 获取关键点的形状信息。
kpt_shape = dataset.data.get("kpt_shape", None)
# 如果 flip_idx 为空且水平翻转概率 hyp.fliplr 大于0。
if len(flip_idx) == 0 and hyp.fliplr > 0.0:
# 则将 hyp.fliplr 设置为0。
hyp.fliplr = 0.0
# 并发出警告，因为没有定义关键点的翻转索引。
LOGGER.warning("WARNING ⚠️ No 'flip_idx' array defined in data.yaml, setting augmentation 'fliplr=0.0'") # 警告⚠️ data.yaml 中未定义“flip_idx”数组，设置增强“fliplr=0.0”。
# 如果 flip_idx 不为空且其长度与关键点形状的第一个维度不匹配。
elif flip_idx and (len(flip_idx) != kpt_shape[0]):
# 则抛出值错误，因为翻转索引的长度必须与关键点的数量一致。
raise ValueError(f"data.yaml flip_idx={flip_idx} length must be equal to kpt_shape[0]={kpt_shape[0]}") # data.yaml flip_idx={flip_idx} 长度必须等于 kpt_shape[0]={kpt_shape[0]}。
# 返回最终的数据增强流程，使用 Compose 将多个变换组合在一起。
return Compose(
[
# 前面定义的预处理变换。
pre_transform,
# 进行混合增强，将两张图像及其标签混合在一起， p 参数控制混合增强的概率。
MixUp(dataset, pre_transform=pre_transform, p=hyp.mixup),
# 使用Albumentations库进行其他数据增强，概率为1.0。
Albumentations(p=1.0),
# 进行随机HSV色彩空间变换， hgain 、 sgain 、 vgain 分别控制色调、饱和度、亮度的增益。
RandomHSV(hgain=hyp.hsv_h, sgain=hyp.hsv_s, vgain=hyp.hsv_v),
# 进行随机翻转，包括垂直翻转和水平翻转， p 参数控制翻转的概率，水平翻转时使用 flip_idx 进行关键点的翻转。
RandomFlip(direction="vertical", p=hyp.flipud),
RandomFlip(direction="horizontal", p=hyp.fliplr, flip_idx=flip_idx),
]
) # transforms
# 这段代码定义了一个用于YOLOv8训练的图像数据增强流程。它首先定义了一个预处理变换，包括马赛克、复制粘贴和随机透视变换。然后根据数据集是否使用关键点进行一些检查和设置。最后，将预处理变换与其他增强方法（如混合增强、Albumentations、随机HSV变换和随机翻转）组合在一起，形成一个完整的数据增强流程。这个流程可以根据超参数 hyp 中的设置进行灵活调整，以适应不同的训练需求。15.def classify_transforms(size=224, mean=DEFAULT_MEAN, std=DEFAULT_STD, interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR, crop_fraction: float = DEFAULT_CROP_FTACTION,):
# Classification augmentations 分类增强-----------------------------------------------------------------------------------------
# 这段代码定义了一个名为 classify_transforms 的函数，用于生成图像分类任务的数据预处理流程。
# 定义函数 classify_transforms ，它有五个参数。
# 1.size ：目标图像尺寸，可以是整数或元组，表示最终图像的大小。
# 2.mean ：图像归一化的均值，默认为 DEFAULT_MEAN 。
# 3.std ：图像归一化的标准差，默认为 DEFAULT_STD 。
# 4.interpolation ：插值模式，默认为 T.InterpolationMode.BILINEAR ，即双线性插值。
# 5.crop_fraction ：裁剪比例，默认为 DEFAULT_CROP_FRACTION ，用于计算缩放尺寸。
def classify_transforms(
size=224,
mean=DEFAULT_MEAN,
std=DEFAULT_STD,
interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR,
crop_fraction: float = DEFAULT_CROP_FTACTION,
):
# 用于评估/推理的分类转换。灵感来自 timm/data/transforms_factory.py。
"""
Classification transforms for evaluation/inference. Inspired by timm/data/transforms_factory.py.
Args:
size (int): image size
mean (tuple): mean values of RGB channels
std (tuple): std values of RGB channels
interpolation (T.InterpolationMode): interpolation mode. default is T.InterpolationMode.BILINEAR.
crop_fraction (float): fraction of image to crop. default is 1.0.
Returns:
(T.Compose): torchvision transforms
"""
# import torchvision.transforms as T
# 根据 size 的类型（整数或元组）计算 缩放尺寸 scale_size 。
# 如果 size 是元组或列表，确保其长度为2，并计算每个维度的缩放尺寸。
if isinstance(size, (tuple, list)):
assert len(size) == 2
scale_size = tuple(math.floor(x / crop_fraction) for x in size)
# 如果 size 是整数，计算缩放尺寸并将其转换为元组。
else:
scale_size = math.floor(size / crop_fraction)
scale_size = (scale_size, scale_size)
# aspect ratio is preserved, crops center within image, no borders are added, image is lost
# 根据 缩放尺寸 scale_size 选择合适的 缩放方法 。
# 如果 scale_size 是正方形（即两个维度相等），使用 T.Resize 进行缩放，传入单个尺寸值。
if scale_size[0] == scale_size[1]:
# T.Resize(size, interpolation=InterpolationMode.BILINEAR)
# T.Resize() 是 PyTorch 的 torchvision.transforms 模块中的一个函数，它用于调整图像的大小。这个函数可以接收一个整数或一个元组作为参数，以指定输出图像的大小。
# 参数说明 ：
# size ：目标图像的大小，可以是一个整数或一个元组 (width, height) 。
# 如果是整数，表示将图像的最短边缩放到指定长度，同时保持长宽比。
# 如果是元组，表示将图像的宽度和高度分别调整为指定的尺寸。
# interpolation ：插值方法，用于指定图像缩放时采用的插值算法。默认值为 InterpolationMode.BILINEAR ，即双线性插值。其他可选的插值方法包括 ：
# InterpolationMode.NEAREST ：最近邻插值。
# InterpolationMode.BILINEAR ：双线性插值。
# InterpolationMode.BICUBIC ：双三次插值。
# InterpolationMode.BOX ：盒式插值。
# InterpolationMode.HAMMING ：汉明窗插值。
# 返回值 ：
# 该函数返回一个 Resize 变换对象，可以被用于 T.Compose() 之中，或者直接应用于图像。
# T.Resize() 是图像预处理中常用的操作之一，它可以帮助标准化图像输入到深度学习模型中，或者在数据增强过程中改变图像的尺寸。
# simple case, use torchvision built-in Resize w/ shortest edge mode (scalar size arg)
tfl = [T.Resize(scale_size[0], interpolation=interpolation)]
# 如果 scale_size 不是正方形，使用 T.Resize 进行缩放，传入元组尺寸值。
else:
# resize shortest edge to matching target dim for non-square target
tfl = [T.Resize(scale_size)]
# T.CenterCrop(size)
# T.CenterCrop 是 PyTorch 中 torchvision.transforms 模块的一个类，用于对图像进行中心裁剪。这个类在图像处理和数据预处理中非常常用，特别是在图像分类任务中。
# 参数 ：
# size (int or sequence) ：裁剪的尺寸。如果是一个整数，裁剪的尺寸将是一个正方形，即 (size, size) 。如果是一个序列（如元组或列表），则应包含两个元素，分别表示高度和宽度，即 (height, width) 。
# 功能 ：
# T.CenterCrop 的主要功能是从输入图像的中心区域裁剪出指定尺寸的图像。这个操作不会改变图像的像素值，只是从图像的中心区域提取出一个子图像。
# 适用场景 ：
# T.CenterCrop 常用于图像分类任务中的数据预处理，特别是在需要将图像裁剪到固定尺寸以适应模型输入时。它也可以用于其他图像处理任务，如目标检测和语义分割，但在这些任务中，通常需要保留图像的完整信息，因此使用中心裁剪的情况较少。
# 在缩放后，使用 T.CenterCrop 进行中心裁剪，裁剪尺寸为 size 。
tfl += [T.CenterCrop(size)]
# 将图像转换为张量，并进行归一化处理。
tfl += [
# T.ToTensor()
# T.ToTensor 是 PyTorch 中 torchvision.transforms 模块的一个类，用于将 PIL 图像或 NumPy 数组转换为 PyTorch 张量。这个类在图像处理和数据预处理中非常常用，特别是在深度学习任务中。
# 功能 ：
# T.ToTensor 的主要功能是将输入的 PIL 图像或 NumPy 数组转换为 PyTorch 张量，并将像素值从 [0, 255] 缩放到 [0.0, 1.0]。具体来说，它执行以下操作 ：
# 类型转换 ：将输入的 PIL 图像或 NumPy 数组转换为 PyTorch 张量。
# 像素值缩放 ：将像素值从 [0, 255] 缩放到 [0.0, 1.0]。
# 输入类型 ：
# PIL 图像 ：输入可以是一个 PIL 图像对象，例如 Image.open('path/to/your/image.jpg') 。
# NumPy 数组 ：输入也可以是一个 NumPy 数组，例如 np.array(img) 。
# 输出类型 ：
# 输出是一个 PyTorch 张量，数据类型为 torch.float32 。
# 对于 RGB 图像，输出张量的形状为 (C, H, W) ，其中 C 是通道数（3）， H 是高度， W 是宽度。
# 对于灰度图像，输出张量的形状为 (1, H, W) 。
# T.ToTensor() 将图像从PIL图像或NumPy数组转换为浮点张量，并将像素值从[0, 255]缩放到[0.0, 1.0]。
T.ToTensor(),
# T.Normalize 使用指定的均值 mean 和标准差 std 对图像进行归一化。
T.Normalize(
mean=torch.tensor(mean),
std=torch.tensor(std),
),
]
# T.Compose(transforms)
# T.Compose() 是 PyTorch 的 torchvision.transforms 模块中的一个函数，它用于将多个图像变换组合成一个流程。这个函数允许你按顺序应用一系列变换，从而创建复杂的数据预处理或数据增强管道。
# 参数说明 ：
# transforms ：一个包含多个变换对象的列表或元组。这些变换对象可以是 torchvision.transforms 模块中定义的任何变换，如 Resize 、 CenterCrop 、 ToTensor 、 Normalize 等。
# 返回值 ：
# 该函数返回一个组合变换对象，这个对象可以被用于图像数据的预处理或增强。
# T.Compose() 是构建深度学习模型训练和测试管道中不可或缺的工具，它使得数据预处理和增强步骤变得简洁和高效。通过组合不同的变换，你可以轻松地创建复杂的图像处理流程。
# 使用 T.Compose 将所有预处理步骤组合成一个完整的预处理流程，并返回该流程。
return T.Compose(tfl)
# 这段代码定义了一个用于图像分类任务的数据预处理流程。它首先根据目标尺寸和裁剪比例计算缩放尺寸，然后选择合适的缩放方法进行缩放，接着进行中心裁剪，最后将图像转换为张量并进行归一化处理。这个预处理流程可以灵活调整参数，以适应不同的图像分类任务需求。
# def classify_transforms(size=224, mean=DEFAULT_MEAN, std=DEFAULT_STD, interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR, crop_fraction: float = DEFAULT_CROP_FTACTION,):16.def classify_augmentations(size=224, mean=DEFAULT_MEAN, std=DEFAULT_STD, scale=None, ratio=None, hflip=0.5, vflip=0.0, auto_augment=None, hsv_h=0.015, hsv_s=0.4, hsv_v=0.4, force_color_jitter=False, erasing=0.0, interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR,):
# Classification augmentations train 分类增强训练---------------------------------------------------------------------------------------
# 这段代码定义了一个名为 classify_augmentations 的函数，用于生成图像分类任务的数据增强流程。这个函数结合了多种数据增强技术，以提高模型的泛化能力和鲁棒性。
# 这行代码定义了一个名为 classify_augmentations 的函数，它接受以下参数 ：
# 1.size (int) ：目标图像尺寸。
# 2.mean (tuple) ：图像归一化的均值。
# 3.std (tuple) ：图像归一化的标准差。
# 4.scale (tuple, optional) ： RandomResizedCrop 的缩放范围，默认为 (0.08, 1.0) 。
# 5.ratio (tuple, optional) ： RandomResizedCrop 的宽高比范围，默认为 (3.0 / 4.0, 4.0 / 3.0) 。
# 6.hflip (float) ：水平翻转的概率，默认为 0.5 。
# 7.vflip (float) ：垂直翻转的概率，默认为 0.0 。
# 8.auto_augment (str, optional) ：自动数据增强策略，可以是 "randaugment" , "augmix" , "autoaugment" 或 None 。
# 9.hsv_h (float) ：HSV色彩空间中色调的增强比例，默认为 0.015 。
# 10.hsv_s (float) ：HSV色彩空间中饱和度的增强比例，默认为 0.4 。
# 11.hsv_v (float) ：HSV色彩空间中亮度的增强比例，默认为 0.4 。
# 12.force_color_jitter (bool) ：是否强制使用色彩抖动，即使启用了自动数据增强策略，默认为 False 。
# 13.erasing (float) ：随机擦除的概率，默认为 0.0 。
# 14.interpolation (T.InterpolationMode) ：插值模式，默认为 T.InterpolationMode.BILINEAR 。
def classify_augmentations(
size=224,
mean=DEFAULT_MEAN,
std=DEFAULT_STD,
scale=None,
ratio=None,
hflip=0.5,
vflip=0.0,
auto_augment=None,
hsv_h=0.015, # image HSV-Hue augmentation (fraction)
hsv_s=0.4, # image HSV-Saturation augmentation (fraction)
hsv_v=0.4, # image HSV-Value augmentation (fraction)
force_color_jitter=False,
erasing=0.0,
interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR,
):
# 分类转换，使用增强进行训练。灵感来自 timm/data/transforms_factory.py。
"""
Classification transforms with augmentation for training. Inspired by timm/data/transforms_factory.py.
Args:
size (int): image size
scale (tuple): scale range of the image. default is (0.08, 1.0)
ratio (tuple): aspect ratio range of the image. default is (3./4., 4./3.)
mean (tuple): mean values of RGB channels
std (tuple): std values of RGB channels
hflip (float): probability of horizontal flip
vflip (float): probability of vertical flip
auto_augment (str): auto augmentation policy. can be 'randaugment', 'augmix', 'autoaugment' or None.
hsv_h (float): image HSV-Hue augmentation (fraction)
hsv_s (float): image HSV-Saturation augmentation (fraction)
hsv_v (float): image HSV-Value augmentation (fraction)
force_color_jitter (bool): force to apply color jitter even if auto augment is enabled
erasing (float): probability of random erasing
interpolation (T.InterpolationMode): interpolation mode. default is T.InterpolationMode.BILINEAR.
Returns:
(T.Compose): torchvision transforms
"""
# 这段代码是 classify_augmentations 函数的一部分，用于定义图像分类任务中的主要数据增强步骤。这些步骤在 albumentations 库未安装的情况下使用 torchvision.transforms 模块来实现。
# Transforms to apply if albumentations not installed 明了以下代码块是在 albumentations 库未安装时使用的数据增强步骤。
# 检查 size 参数是否为整数。如果不是整数，抛出 TypeError 异常，提示 size 必须是整数，而不是列表或元组。
if not isinstance(size, int):
raise TypeError(f"classify_transforms() size {size} must be integer, not (list, tuple)") # classify_transforms() 大小 {size} 必须是整数，而不是 (列表，元组)。
# 设置 RandomResizedCrop 的缩放范围。如果 scale 参数未提供，则使用默认值 (0.08, 1.0) ，这是ImageNet数据集常用的缩放范围。
scale = tuple(scale or (0.08, 1.0)) # default imagenet scale range
# 设置 RandomResizedCrop 的宽高比范围。如果 ratio 参数未提供，则使用默认值 (3.0 / 4.0, 4.0 / 3.0) ，这也是ImageNet数据集常用的宽高比范围。
ratio = tuple(ratio or (3.0 / 4.0, 4.0 / 3.0)) # default imagenet ratio range
# 创建一个列表 primary_tfl ，包含一个 RandomResizedCrop 变换，用于随机裁剪和缩放图像。 size 参数指定了裁剪后的目标尺寸， scale 和 ratio 参数控制裁剪区域的缩放范围和宽高比， interpolation 参数指定了插值方法。
primary_tfl = [T.RandomResizedCrop(size, scale=scale, ratio=ratio, interpolation=interpolation)]
# 如果水平翻转的概率 hflip 大于0，则在 primary_tfl 列表中添加一个 RandomHorizontalFlip 变换，用于随机水平翻转图像。 p 参数指定了水平翻转的概率。
if hflip > 0.0:
primary_tfl += [T.RandomHorizontalFlip(p=hflip)]
# 如果垂直翻转的概率 vflip 大于0，则在 primary_tfl 列表中添加一个 RandomVerticalFlip 变换，用于随机垂直翻转图像。 p 参数指定了垂直翻转的概率。
if vflip > 0.0:
primary_tfl += [T.RandomVerticalFlip(p=vflip)]
# 这段代码定义了图像分类任务中的主要数据增强步骤，包括随机裁剪、缩放、水平翻转和垂直翻转。这些步骤通过 torchvision.transforms 模块实现，适用于在 albumentations 库未安装的情况下使用。这些数据增强技术可以提高模型的泛化能力和鲁棒性，特别是在图像分类任务中。
# 这段代码是 classify_augmentations 函数的一部分，用于定义图像分类任务中的次要数据增强步骤，特别是自动数据增强策略。这些步骤在 albumentations 库未安装的情况下使用 torchvision.transforms 模块来实现。
# 初始化一个空列表 secondary_tfl ，用于存储 次要的数据增强步骤 。
secondary_tfl = []
# 初始化一个布尔变量 disable_color_jitter ，默认值为 False ，用于控制 是否禁用色彩抖动 。
disable_color_jitter = False
# 如果 auto_augment 参数不为空，确保它是一个字符串。这一步确保传入的自动数据增强策略是有效的。
if auto_augment:
assert isinstance(auto_augment, str)
# color jitter is typically disabled if AA/RA on,
# this allows override without breaking old hparm cfgs
# 如果启用了自动数据增强策略（如 autoaugment 、 randaugment 、 augmix ），通常会禁用色彩抖动，除非 force_color_jitter 参数为 True 。这一步允许在不破坏旧配置的情况下强制使用色彩抖动。
disable_color_jitter = not force_color_jitter
# 如果自动数据增强策略是 randaugment ，并且 torchvision 版本大于或等于0.11.0，则在 secondary_tfl 列表中添加 T.RandAugment 变换。如果 torchvision 版本低于0.11.0，则发出警告并禁用该策略。
if auto_augment == "randaugment":
if TORCHVISION_0_11:
secondary_tfl += [T.RandAugment(interpolation=interpolation)]
else:
LOGGER.warning('"auto_augment=randaugment" requires torchvision >= 0.11.0. Disabling it.') # “auto_augment=randaugment” 需要 torchvision >= 0.11.0。禁用它。
# 如果自动数据增强策略是 augmix ，并且 torchvision 版本大于或等于0.13.0，则在 secondary_tfl 列表中添加 T.AugMix 变换。如果 torchvision 版本低于0.13.0，则发出警告并禁用该策略。
elif auto_augment == "augmix":
if TORCHVISION_0_13:
secondary_tfl += [T.AugMix(interpolation=interpolation)]
else:
LOGGER.warning('"auto_augment=augmix" requires torchvision >= 0.13.0. Disabling it.') # “auto_augment=augmix” 需要 torchvision >= 0.13.0。禁用它。
# 如果自动数据增强策略是 autoaugment ，并且 torchvision 版本大于或等于0.10.0，则在 secondary_tfl 列表中添加 T.AutoAugment 变换。如果 torchvision 版本低于0.10.0，则发出警告并禁用该策略。
elif auto_augment == "autoaugment":
if TORCHVISION_0_10:
secondary_tfl += [T.AutoAugment(interpolation=interpolation)]
else:
LOGGER.warning('"auto_augment=autoaugment" requires torchvision >= 0.10.0. Disabling it.') # “auto_augment=autoaugment” 需要 torchvision >= 0.10.0。禁用它。
# 如果 auto_augment 参数不是 "randaugment" 、 "augmix" 、 "autoaugment" 或 None ，则抛出 ValueError 异常，提示无效的自动数据增强策略。
else:
raise ValueError(
f'Invalid auto_augment policy: {auto_augment}. Should be one of "randaugment", '
f'"augmix", "autoaugment" or None' # 无效的自动增强策略：{auto_augment}。应为“randaugment”、“augmix”、“autoaugment”或 None 之一。
)
# 这段代码定义了图像分类任务中的次要数据增强步骤，特别是自动数据增强策略。这些步骤通过 torchvision.transforms 模块实现，适用于在 albumentations 库未安装的情况下使用。自动数据增强策略（如 RandAugment 、 AugMix 、 AutoAugment ）可以进一步提高模型的泛化能力和鲁棒性。通过这些策略，可以自动生成多样化的数据增强组合，从而提高模型在不同条件下的表现。
# 这段代码是 classify_augmentations 函数的一部分，用于定义图像分类任务中的数据增强流程的最后几个步骤。这些步骤包括色彩抖动、转换为张量、归一化和随机擦除。
# 如果 disable_color_jitter 为 False ，则在 secondary_tfl 列表中添加 T.ColorJitter 变换。
if not disable_color_jitter:
# T.ColorJitter(brightness: Union[float, Tuple[float, float]] = 0, contrast: Union[float, Tuple[float, float]] = 0, saturation: Union[float, Tuple[float, float]] = 0, hue: Union[float, Tuple[float, float]] = 0)
# T.ColorJitter 是 PyTorch 中 torchvision.transforms 模块的一个类，用于随机改变图像的亮度、对比度、饱和度和色调。这个类在图像处理和数据预处理中非常常用，特别是在深度学习任务中。
# 参数 ：
# brightness (float or tuple of float (min, max)) ：亮度的变化范围。如果是一个浮点数，亮度因子会从 [max(0, 1 - brightness), 1 + brightness] 中均匀选择。如果是一个元组 (min, max) ，亮度因子会从 [min, max] 中均匀选择。应为非负数。
# contrast (float or tuple of float (min, max)) ：对比度的变化范围。如果是一个浮点数，对比度因子会从 [max(0, 1 - contrast), 1 + contrast] 中均匀选择。如果是一个元组 (min, max) ，对比度因子会从 [min, max] 中均匀选择。应为非负数。
# saturation (float or tuple of float (min, max)) ：饱和度的变化范围。如果是一个浮点数，饱和度因子会从 [max(0, 1 - saturation), 1 + saturation] 中均匀选择。如果是一个元组 (min, max) ，饱和度因子会从 [min, max] 中均匀选择。应为非负数。
# hue (float or tuple of float (min, max)) ：色调的变化范围。如果是一个浮点数，色调因子会从 [-hue, hue] 中均匀选择。如果是一个元组 (min, max) ，色调因子会从 [min, max] 中均匀选择。应满足 0 <= hue <= 0.5 或 -0.5 <= min <= max <= 0.5 。为了改变色调，输入图像的像素值必须是非负的，以便转换到 HSV 空间。
# 功能 ：
# T.ColorJitter 的主要功能是随机改变图像的亮度、对比度、饱和度和色调。这些变化可以增加数据的多样性，提高模型的泛化能力。
# T.ColorJitter 是一个非常有用的图像数据增强工具，可以随机改变图像的亮度、对比度、饱和度和色调。这些变化可以增加数据的多样性，提高模型的泛化能力。通过灵活调整参数，可以生成多样化的数据增强组合，从而提高模型在不同条件下的表现。
# T.ColorJitter 用于随机调整图像的亮度、对比度、饱和度和色调。
# brightness=hsv_v ：亮度调整的范围， hsv_v 是亮度的增强比例。
# contrast=hsv_v ：对比度调整的范围， hsv_v 是对比度的增强比例。
# saturation=hsv_s ：饱和度调整的范围， hsv_s 是饱和度的增强比例。
# hue=hsv_h ：色调调整的范围， hsv_h 是色调的增强比例。
secondary_tfl += [T.ColorJitter(brightness=hsv_v, contrast=hsv_v, saturation=hsv_s, hue=hsv_h)]
# final_tfl 列表包含最终的数据增强步骤。
final_tfl = [
# 将图像从PIL图像或NumPy数组转换为PyTorch张量，并将像素值从[0, 255]缩放到[0.0, 1.0]。
T.ToTensor(),
# 对张量进行归一化处理，使用指定的均值 mean 和标准差 std 。
T.Normalize(mean=torch.tensor(mean), std=torch.tensor(std)),
# T.RandomErasing(p: float = 0.5, scale: Tuple[float, float] = (0.02, 0.33), ratio: Tuple[float, float] = (0.3, 3.3), value: Union[int, float, str, Tuple[int, int, int]] = 0, inplace: bool = False)
# T.RandomErasing 是 PyTorch 中 torchvision.transforms 模块的一个类，用于随机选择图像中的一个矩形区域并擦除其像素。这个类在图像处理和数据预处理中非常常用，特别是在深度学习任务中。
# 参数 ：
# p (float) ：执行随机擦除操作的概率，默认为0.5。
# scale (tuple of float) ：擦除区域与输入图像的比例范围，默认为 (0.02, 0.33) 。这个范围内的值表示擦除区域的面积占图像总面积的比例。
# ratio (tuple of float) ：擦除区域的纵横比范围，默认为 (0.3, 3.3) 。这个范围内的值表示擦除区域的长宽比。
# value (int, float, str, or tuple of int) ：擦除值。默认值为0。可以是 ：单个整数或浮点数，用于擦除所有像素。 长度为3的元组，分别用于擦除R、G、B通道。 字符串 'random' ，表示使用随机值擦除每个像素。
# inplace (bool) ：是否在原张量上进行操作，默认为 False 。
# 功能 ：
# T.RandomErasing 的主要功能是随机选择图像中的一个矩形区域并擦除其像素。这种数据增强方法可以增加模型对遮挡的鲁棒性，提高模型的泛化能力。
# T.RandomErasing 是一个非常有用的数据增强工具，可以随机选择图像中的一个矩形区域并擦除其像素。这种数据增强方法可以增加模型对遮挡的鲁棒性，提高模型的泛化能力。通过灵活调整参数，可以生成多样化的数据增强组合，从而提高模型在不同条件下的表现。
# 以概率 erasing 随机擦除图像的一部分区域， inplace=True 表示在原张量上进行操作，节省内存。
T.RandomErasing(p=erasing, inplace=True),
]
# 使用 T.Compose 将所有数据增强步骤（ primary_tfl 、 secondary_tfl 和 final_tfl ）组合成一个完整的数据增强流程。
# 返回这个组合后的数据增强流程，可以作为一个整体应用于图像数据。
return T.Compose(primary_tfl + secondary_tfl + final_tfl)
# 这段代码定义了图像分类任务中的数据增强流程的最后几个步骤，包括色彩抖动、转换为张量、归一化和随机擦除。这些步骤通过 torchvision.transforms 模块实现，适用于在 albumentations 库未安装的情况下使用。通过这些数据增强技术，可以进一步提高模型的泛化能力和鲁棒性，特别是在图像分类任务中。
# 这个函数 classify_augmentations 生成了一个综合的数据增强流程，包括随机裁剪、水平和垂直翻转、自动数据增强策略（如 RandAugment 、 AugMix 、 AutoAugment ）、色彩抖动、转换为张量、归一化和随机擦除。这些步骤可以灵活调整，以适应不同的图像分类任务需求。通过这些数据增强技术，可以提高模型的泛化能力和鲁棒性。
# def classify_augmentations(size=224, mean=DEFAULT_MEAN, std=DEFAULT_STD, scale=None, ratio=None, hflip=0.5, vflip=0.0, auto_augment=None, hsv_h=0.015, hsv_s=0.4, hsv_v=0.4, force_color_jitter=False, erasing=0.0, interpolation: T.InterpolationMode = T.InterpolationMode.BILINEAR,):17.class ClassifyLetterBox:
# NOTE: keep this class for backward compatibility 注意：保留此类是为了向后兼容。
# 这段代码定义了一个名为 ClassifyLetterBox 的类，用于将图像调整到指定尺寸，并在必要时进行填充，以确保图像的宽高比不变。这种处理方式常用于图像分类任务中，特别是在需要将图像输入到固定尺寸的模型时。
class ClassifyLetterBox:
# YOLOv8 LetterBox 类用于图像预处理，旨在成为转换步骤的一部分，例如 T.Compose([LetterBox(size), ToTensor()])。
"""
YOLOv8 LetterBox class for image preprocessing, designed to be part of a transformation pipeline, e.g.,
T.Compose([LetterBox(size), ToTensor()]).
Attributes:
h (int): Target height of the image.
w (int): Target width of the image.
auto (bool): If True, automatically solves for short side using stride.
stride (int): The stride value, used when 'auto' is True.
"""
# 这段代码是 ClassifyLetterBox 类的构造函数 __init__ ，用于初始化类的实例。
# 1.size (tuple or int) ：目标图像尺寸。如果是一个整数，表示目标图像的宽度和高度相同。默认值为 (640, 640) 。
# 2.auto (bool) ：是否自动计算短边尺寸，以确保图像的宽高比不变。默认值为 False 。
# 3.stride (int) ：用于自动计算短边尺寸时的步长。默认值为 32 。
def __init__(self, size=(640, 640), auto=False, stride=32):
# 使用目标大小、自动标记和步幅初始化 ClassifyLetterBox 类。
"""
Initializes the ClassifyLetterBox class with a target size, auto-flag, and stride.
Args:
size (Union[int, Tuple[int, int]]): The target dimensions (height, width) for the letterbox.
auto (bool): If True, automatically calculates the short side based on stride.
stride (int): The stride value, used when 'auto' is True.
"""
# 调用父类的构造函数。虽然在这个类中没有明确的父类，但这是一个好的编程习惯，可以确保父类的初始化方法被正确调用。
super().__init__()
# 如果 size 是一个整数，将 self.h 和 self.w 都设置为 size 。 如果 size 是一个元组，将 self.h 和 self.w 分别设置为元组的两个元素。
self.h, self.w = (size, size) if isinstance(size, int) else size
# 一个布尔值，表示 是否自动计算短边尺寸 。如果为 True ，则会根据步长 stride 自动计算短边尺寸，以确保图像的宽高比不变。
self.auto = auto # pass max size integer, automatically solve for short side using stride
# 一个整数，用于 自动计算短边尺寸时的步长 。这个参数在 auto 为 True 时生效。
self.stride = stride # used with auto
# 这个构造函数 __init__ 用于初始化 ClassifyLetterBox 类的实例，设置目标图像尺寸、是否自动计算短边尺寸以及步长。这些参数在后续的图像处理方法中会被使用，以确保图像在调整尺寸时保持宽高比不变，并在必要时进行填充。这种处理方式常用于图像分类任务中，特别是在需要将图像输入到固定尺寸的模型时。通过灵活调整参数，可以生成多样化的数据预处理组合，从而提高模型在不同条件下的表现。
# 这段代码是 ClassifyLetterBox 类的 __call__ 方法，用于将图像调整到指定尺寸，并在必要时进行填充，以确保图像的宽高比不变。这个方法在调用类实例时会被自动调用。
# 1.im ：输入的图像，可以是任何支持 shape 属性的图像数组（例如，NumPy数组）。
def __call__(self, im):
# 调整图像大小并使用 letterbox 方法填充。
"""
Resizes the image and pads it with a letterbox method.
Args:
im (numpy.ndarray): The input image as a numpy array of shape HWC.
Returns:
(numpy.ndarray): The letterboxed and resized image as a numpy array.
"""
# 获取输入图像的 高度 imh 和 宽度 imw 。
imh, imw = im.shape[:2]
# 计算 缩放比例 r ，确保图像在缩放后不会超出目标尺寸。 r 是目标高度与输入高度的比值和目标宽度与输入宽度的比值中的较小值。
r = min(self.h / imh, self.w / imw) # ratio of new/old dimensions
# 计算 缩放后的图像 高度 h 和 宽度 w ，并四舍五入到最近的整数。
h, w = round(imh * r), round(imw * r) # resized image dimensions
# Calculate padding dimensions
# 如果 self.auto 为 True ，则自动计算填充后的高度 hs 和宽度 ws ，确保它们是 self.stride 的倍数。 否则，直接使用目标尺寸 self.h 和 self.w 。
hs, ws = (math.ceil(x / self.stride) * self.stride for x in (h, w)) if self.auto else (self.h, self.w)
# 计算填充区域的顶部 top 和左侧 left 偏移量，确保填充后的图像居中。 -0.1 是为了确保偏移量是整数，避免浮点数精度问题。
top, left = round((hs - h) / 2 - 0.1), round((ws - w) / 2 - 0.1)
# Create padded image
# 创建一个填充后的图像 im_out ，尺寸为 (hs, ws, 3) ，填充值为 114 ，数据类型与输入图像相同。
im_out = np.full((hs, ws, 3), 114, dtype=im.dtype)
# 使用 cv2.resize 将输入图像 im 缩放到 (w, h) ，并将其放置在填充后的图像 im_out 的中心位置。
im_out[top : top + h, left : left + w] = cv2.resize(im, (w, h), interpolation=cv2.INTER_LINEAR)
# 返回填充后的图像 im_out 。
return im_out
# ClassifyLetterBox 类的 __call__ 方法用于将图像调整到指定尺寸，并在必要时进行填充，以确保图像的宽高比不变。这种处理方式常用于图像分类任务中，特别是在需要将图像输入到固定尺寸的模型时。通过灵活调整参数，可以生成多样化的数据预处理组合，从而提高模型在不同条件下的表现。
# ClassifyLetterBox 类用于将图像调整到指定尺寸，并在必要时进行填充，以确保图像的宽高比不变。这种处理方式常用于图像分类任务中，特别是在需要将图像输入到固定尺寸的模型时。通过灵活调整参数，可以生成多样化的数据预处理组合，从而提高模型在不同条件下的表现。18.class CenterCrop:
# NOTE: keep this class for backward compatibility 注意：保留此类是为了向后兼容。
# 这段代码定义了一个名为 CenterCrop 的类，用于从图像中裁剪出中心区域，并将其调整到指定尺寸。
# 定义了一个名为 CenterCrop 的类，用于实现图像的中心裁剪功能。
class CenterCrop:
# YOLOv8 CenterCrop 类用于图像预处理，旨在成为转换步骤的一部分，例如 T.Compose([CenterCrop(size), ToTensor()])。
"""YOLOv8 CenterCrop class for image preprocessing, designed to be part of a transformation pipeline, e.g.,
T.Compose([CenterCrop(size), ToTensor()]).
"""
# 定义了类的构造函数，接受一个参数。
# 1.size ：默认值为 640。 size 可以是一个整数或一个元组，表示裁剪后的图像尺寸。
def __init__(self, size=640):
# 将图像从 numpy 数组转换为 PyTorch 张量。
"""Converts an image from numpy array to PyTorch tensor."""
# 调用父类的构造函数。虽然在这个类中没有明确的父类，但这是一个好的编程习惯，可以确保父类的初始化方法被正确调用。
super().__init__()
# 根据 size 的类型，设置裁剪后的图像高度 self.h 和宽度 self.w 。如果 size 是一个整数，则 self.h 和 self.w 都设置为 size 。如果 size 是一个元组，则分别设置 self.h 和 self.w 为元组的两个元素。
self.h, self.w = (size, size) if isinstance(size, int) else size
# 定义了类的 __call__ 方法，使得类的实例可以像函数一样被调用。
# 1.im ：输入的图像，可以是任何支持 shape 属性的图像数组（例如，NumPy数组）。
def __call__(self, im):
# 使用 letterbox 方法调整图像大小并裁剪图像中心。
"""
Resizes and crops the center of the image using a letterbox method.
Args:
im (numpy.ndarray): The input image as a numpy array of shape HWC.
Returns:
(numpy.ndarray): The center-cropped and resized image as a numpy array.
"""
# 获取输入图像的 高度 imh 和 宽度 imw 。
imh, imw = im.shape[:2]
# 计算输入图像的最小维度 m ，即高度和宽度中的较小值。
m = min(imh, imw) # min dimension
# 计算裁剪区域的顶部 top 和左侧 left 偏移量，确保裁剪区域居中。 // 表示整数除法，确保偏移量是整数。
top, left = (imh - m) // 2, (imw - m) // 2
# 从输入图像 im 中裁剪出中心区域 im[top : top + m, left : left + m] ，并使用 cv2.resize 将其调整到目标尺寸 (self.w, self.h) ，插值方法为 cv2.INTER_LINEAR 。返回调整后的图像。
return cv2.resize(im[top : top + m, left : left + m], (self.w, self.h), interpolation=cv2.INTER_LINEAR)
# CenterCrop 类用于从图像中裁剪出中心区域，并将其调整到指定尺寸。这种处理方式常用于图像预处理，特别是在需要将图像输入到固定尺寸的模型时。通过灵活调整 size 参数，可以生成不同尺寸的裁剪图像，从而提高模型在不同条件下的表现。这个类的实现简单高效，适用于各种图像处理任务。19.class ToTensor:
# NOTE: keep this class for backward compatibility 注意：保留此类是为了向后兼容。
# 这段代码定义了一个名为 ToTensor 的类，用于将图像从 NumPy 数组转换为 PyTorch 张量，并进行一些预处理操作。
# 定义了一个名为 ToTensor 的类，用于实现图像的转换和预处理功能。
class ToTensor:
# YOLOv8 ToTensor 类用于图像预处理，即 T.Compose([LetterBox(size), ToTensor()])
"""YOLOv8 ToTensor class for image preprocessing, i.e., T.Compose([LetterBox(size), ToTensor()])."""
# 定义了类的构造函数，接受一个参数。
# 1.half ：默认值为 False 。 half 参数用于控制是否将图像数据类型转换为半精度浮点数（ float16 ）。
def __init__(self, half=False):
# 使用可选的半精度支持初始化 YOLOv8 ToTensor 对象。
"""Initialize YOLOv8 ToTensor object with optional half-precision support."""
# 调用父类的构造函数。虽然在这个类中没有明确的父类，但这是一个好的编程习惯，可以确保父类的初始化方法被正确调用。
super().__init__()
# 将 half 参数的值赋给类的实例变量 self.half ，用于在 __call__ 方法中使用。
self.half = half
# 定义了类的 __call__ 方法，使得类的实例可以像函数一样被调用。
# 1.im ：输入的图像，可以是任何支持 shape 属性的图像数组（例如，NumPy数组）。
def __call__(self, im):
# 将图像从 numpy 数组转换为 PyTorch 张量，应用可选的半精度和规范化。
"""
Transforms an image from a numpy array to a PyTorch tensor, applying optional half-precision and normalization.
Args:
im (numpy.ndarray): Input image as a numpy array with shape (H, W, C) in BGR order.
Returns:
(torch.Tensor): The transformed image as a PyTorch tensor in float32 or float16, normalized to [0, 1].
"""
# im.transpose((2, 0, 1)) ：将图像从 HWC（高度、宽度、通道）格式转换为 CHW（通道、高度、宽度）格式。
# [::-1] ：将通道顺序从 BGR 转换为 RGB。
# np.ascontiguousarray ：确保数组在内存中是连续的，这有助于提高后续操作的效率。
im = np.ascontiguousarray(im.transpose((2, 0, 1))[::-1]) # HWC to CHW -> BGR to RGB -> contiguous
# 将 NumPy 数组转换为 PyTorch 张量。
im = torch.from_numpy(im) # to torch
# 根据 self.half 的值，将张量的数据类型转换为半精度浮点数（ float16 ）或单精度浮点数（ float32 ）。
im = im.half() if self.half else im.float() # uint8 to fp16/32
# 将像素值从 [0, 255] 缩放到 [0.0, 1.0]。
im /= 255.0 # 0-255 to 0.0-1.0
# 返回转换后的张量。
return im
# ToTensor 类用于将图像从 NumPy 数组转换为 PyTorch 张量，并进行一些预处理操作，包括：将图像从 HWC 格式转换为 CHW 格式。将通道顺序从 BGR 转换为 RGB。将数据类型转换为半精度或单精度浮点数。将像素值从 [0, 255] 缩放到 [0.0, 1.0]。这种预处理方式常用于图像分类、目标检测等深度学习任务中，特别是在需要将图像输入到 PyTorch 模型时。通过灵活调整 half 参数，可以控制数据类型，从而在训练和推理时提高效率。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
