datasets.py
utils\datasets.py
目录
5.class InfiniteDataLoader(torch.utils.data.dataloader.DataLoader):
6.class _RepeatSampler(object):
10.class LoadImagesAndLabels(Dataset):
11.def load_image(self, index):
12.def augment_hsv(img, hgain=0.5, sgain=0.5, vgain=0.5):
13.def hist_equalize(img, clahe=True, bgr=False):
14.def load_mosaic(self, index):
15.def load_mosaic9(self, index):
16.def load_samples(self, index):
17.def copy_paste(img, labels, segments, probability=0.5):
18.def remove_background(img, labels, segments):
19.def sample_segments(img, labels, segments, probability=0.5):
20.def replicate(img, labels):
23.def box_candidates(box1, box2, wh_thr=2, ar_thr=20, area_thr=0.1, eps=1e-16):
26.def pastein(image, labels, sample_labels, sample_images, sample_masks):
28.def create_folder(path='./new'):
29.def flatten_recursive(path='../coco'):
30.def extract_boxes(path='../coco/'):
31.def autosplit(path='../coco', weights=(0.9, 0.1, 0.0), annotated_only=False):
32.def load_segmentations(self, index):
1.所需的库和模块
# Dataset utils and dataloaders
import glob
import logging
import math
import os
import random
import shutil
import time
from itertools import repeat
from multiprocessing.pool import ThreadPool
from pathlib import Path
from threading import Thread
import cv2
import numpy as np
import torch
import torch.nn.functional as F
from PIL import Image, ExifTags
from torch.utils.data import Dataset
from tqdm import tqdm
import pickle
from copy import deepcopy
#from pycocotools import mask as maskUtils
from torchvision.utils import save_image
from torchvision.ops import roi_pool, roi_align, ps_roi_pool, ps_roi_align
from utils.general import check_requirements, xyxy2xywh, xywh2xyxy, xywhn2xyxy, xyn2xy, segment2box, segments2boxes, \
resample_segments, clean_str
from utils.torch_utils import torch_distributed_zero_first
# Parameters 参数。
# 这些参数用于指定处理图像和视频文件时的可接受格式，以及用于日志记录的设置。
# 这是一个字符串，包含了一个 URL 链接，指向 YOLOv5 的官方 GitHub 维基页面，提供了如何使用 YOLOv5 训练自定义数据集的指南。这个 URL 可以用于获取更多关于如何配置和使用 YOLO 模型的信息。
help_url = 'https://github.com/ultralytics/yolov5/wiki/Train-Custom-Data'
# 这是一个列表，包含了 YOLOv7 可以处理的图像文件的格式。这些格式包括常见的图像文件扩展名，如 BMP、JPG、PNG 等。这意味着 YOLOv7 能够识别和处理这些格式的图像文件。
img_formats = ['bmp', 'jpg', 'jpeg', 'png', 'tif', 'tiff', 'dng', 'webp', 'mpo'] # acceptable image suffixes
# 这是一个列表，包含了 YOLOv7 可以处理的视频文件的格式。这些格式包括常见的视频文件扩展名，如 MP4、AVI、MOV 等。这意味着 YOLOv7 能够识别和处理这些格式的视频文件。
vid_formats = ['mov', 'avi', 'mp4', 'mpg', 'mpeg', 'm4v', 'wmv', 'mkv'] # acceptable video suffixes
# 这是一个日志记录器对象，用于在 YOLOv7 的运行过程中记录日志信息。这个对象是通过调用 logging.getLogger(__name__) 创建的，其中 __name__ 是当前模块的名称。这个日志记录器可以用来记录错误、警告、信息和调试消息，帮助开发者了解程序的运行状态和调试程序。
logger = logging.getLogger(__name__)
# 这段代码是用于从图像的 EXIF（Exchangeable Image File Format，可交换图像文件格式）数据中获取“Orientation”（方向）标签的键值。EXIF 数据包含了图像的元数据，比如拍摄时间、相机设置、图像的方向等。
# 获取方向 exif 标签。
# Get orientation exif tag
# ExifTags.TAGS ：这是一个字典，包含了所有 EXIF 标签的编号和描述的映射关系。
# 这个循环遍历 ExifTags.TAGS 字典的所有键（即所有的 EXIF 标签编号）。
for orientation in ExifTags.TAGS.keys():
# 这个条件检查当前循环中的键对应的值（描述）是否等于字符串 'Orientation' 。
if ExifTags.TAGS[orientation] == 'Orientation':
# 如果找到了匹配的键，即找到了描述为 'Orientation' 的键，就跳出循环。
break
# 这段代码的目的是找到表示“Orientation”标签的键，以便后续可以获取该标签的值，从而知道图像的正确方向。一旦找到对应的键，就可以使用它来从图像的 EXIF 数据中提取方向信息。这个方向信息通常用于图像查看器正确地显示图像，而不是将其旋转到不正确的方向。2.def get_hash(files):
# 这个 get_hash 函数的目的是计算一个包含文件路径的列表的单个哈希值。
# 不过，当前的实现方式并不是一个真正的哈希函数，因为它只是简单地计算了列表中所有文件的大小之和。这并不是一个安全的哈希值，因为它不涉及任何加密或散列算法，也不能保证不同文件内容的哈希值是唯一的。
def get_hash(files):
# os.path.getsize(path)
# os.path.getsize() 函数是 Python 标准库 os.path 模块中的一个函数，它用于获取文件的大小，单位是字节。
# path ：要获取大小的文件的路径。
# 功能 ：
# os.path.getsize() 函数返回指定文件的大小，单位是字节。如果文件不存在或者路径指向的不是一个文件，将抛出一个 FileNotFoundError 或 OSError 。
# 请注意， os.path.getsize() 只返回文件的大小，不包括文件的元数据或其他属性。如果你需要获取文件的更多信息，可能需要使用其他函数，如 os.stat() 。
# 返回文件列表的单个哈希值。
# Returns a single hash value of a list of files
# os.path.getsize(f) : 这是一个函数调用，用于获取单个文件 f 的大小（以字节为单位）。 os.path 是 Python 标准库中的一个模块，提供了许多与文件路径相关的函数。
# for f in files : 这是一个 for 循环，用于迭代 files 列表中的每个元素。每个元素都是一个文件路径。
# if os.path.isfile(f) : 这是一个条件语句，用于检查 f 是否是一个文件。 os.path.isfile() 函数返回 True 如果路径 f 是一个存在的文件，否则返回 False 。这个条件确保了只有文件（而不是目录或其他类型的路径）被包含在大小计算中。
# sum(...) : 这是一个函数调用，用于计算生成器表达式中所有项的总和。在这个上下文中，它计算了所有有效文件的大小总和。
return sum(os.path.getsize(f) for f in files if os.path.isfile(f))3.def exif_size(img):
# 这段代码定义了一个名为 exif_size 的函数，其目的是返回一个图像的 EXIF 校正后的 PIL（Python Imaging Library，现在更多的是使用它的分支 Pillow）尺寸。
# EXIF 数据包含了图像的元数据，其中包括图像的方向信息。这个函数会检查图像是否需要根据 EXIF 数据中的旋转信息来调整其尺寸。
def exif_size(img):
# 返回经过 exif 校正的 PIL 大小。
# Returns exif-corrected PIL size
# 获取图像的原始尺寸， img.size 返回一个元组 (width, height) 。
s = img.size # (width, height)
# 尝试获取图像的 EXIF 数据，并从中提取旋转信息。
try:
# dict(img._getexif().items()) ：将 EXIF 数据转换为字典，以便可以通过键值访问。
# [orientation] ：这里假设 orientation 是之前定义的变量，它应该包含 EXIF 标签中表示图像方向的键。 orientation 是 'Orientation' 的键值。
# 从 EXIF 数据中获取图像的方向（旋转）信息。
rotation = dict(img._getexif().items())[orientation]
# 检查旋转信息，如果图像需要顺时针旋转 270 度（旋转 270）或 90 度（旋转 90），则交换宽度和高度的值，因为旋转后图像的宽度和高度会互换。
if rotation == 6: # rotation 270 旋转270。
s = (s[1], s[0])
elif rotation == 8: # rotation 90 旋转90。
s = (s[1], s[0])
# 如果获取 EXIF 数据或处理旋转信息时出现任何异常，将忽略这些异常并继续执行。
except:
pass
# 返回图像的尺寸，如果图像没有旋转信息或者旋转信息不是 6 或 8，则返回原始尺寸。
return s
# 请注意，这段代码假设 img 对象有一个 _getexif() 方法，这个方法在 Pillow 库的 Image 对象中是存在的。
# 如果 img 对象没有这个方法，或者图像没有 EXIF 数据，那么 _getexif() 将返回 None ，这将导致 dict(img._getexif().items()) 抛出 AttributeError 。4.def create_dataloader(path, imgsz, batch_size, stride, opt, hyp=None, augment=False, cache=False, pad=0.0, rect=False, rank=-1, world_size=1, workers=8, image_weights=False, quad=False, prefix=''):
# 这段代码定义了一个名为 create_dataloader 的函数，它用于创建并返回一个 PyTorch 数据加载器（dataloader），这个加载器可以用于深度学习模型的训练过程中加载数据。函数接受多个参数，用于配置数据加载器的行为。
# 1.path : 数据集的路径。
# 2.imgsz : 图像的尺寸。
# 3.batch_size : 批处理大小。
# 4.stride : 模型的步长。
# 5.opt : 一个包含多个选项的对象或命名空间。
# 6.hyp : 用于数据增强的超参数。
# 7.augment : 是否对图像进行增强。
# 8.cache : 是否缓存图像。
# 9.pad : 填充比例。
# 10.rect : 是否使用矩形训练。
# 11.rank : 在分布式训练中的排名。
# 12.world_size : 分布式训练中的总进程数。
# 13.workers : 加载数据的工作线程数。
# 14.image_weights : 是否使用图像权重。
# 15.quad : 是否使用四倍数据增强。
# 16.prefix : 日志前缀。
def create_dataloader(path, imgsz, batch_size, stride, opt, hyp=None, augment=False, cache=False, pad=0.0, rect=False,
rank=-1, world_size=1, workers=8, image_weights=False, quad=False, prefix=''):
# 确保只有 DDP 中的第一个进程首先处理数据集，之后的其他进程才能使用缓存。
# Make sure only the first process in DDP process the dataset first, and the following others can use the cache
# 分布式处理。使用 torch_distributed_zero_first 确保在分布式数据并行（DDP）中只有第一个进程首先处理数据集，其他进程可以利用缓存。
# def torch_distributed_zero_first(local_rank: int):
# -> 名为 torch_distributed_zero_first 的上下文管理器（context manager），它用于在分布式训练中协调多个进程，确保所有进程等待某个特定的进程（通常是本地的主进程，即 local_rank 为 0 的进程）首先执行某些操作，然后其他进程再继续执行。
with torch_distributed_zero_first(rank):
# 创建数据集。实例化 LoadImagesAndLabels 类，它负责加载图像和标签，并根据提供的参数进行配置。
# 1. path ：指定了图像数据集的路径。这通常是包含图像文件的目录路径或是一个包含图像路径的文本文件。
# 2. imgsz ：指定了图像的尺寸。这可以是图像的宽度和高度，用于调整图像大小以适应模型输入。
# 3. batch_size ：指定了每个批次中的图像数量。这是训练过程中每次迭代提供给模型的图像数量。
# 4. augment ：一个布尔值，指示是否对图像进行数据增强。数据增强是一种通过创建图像变体来增加数据集多样性的技术，有助于模型泛化。
# 5. hyp ：数据增强的超参数。这可能是一个字典或对象，包含了控制数据增强效果的参数，如旋转角度、缩放比例等。
# 6. rect ：一个布尔值，指示是否使用矩形训练。在目标检测中，这可能指的是是否使用矩形（而不是图像的宽高比）来确定训练图像的尺寸。
# 7. cache_images ：一个布尔值，指示是否缓存图像数据。如果设置为 True ，图像数据可能会在内存或磁盘上缓存，以加快数据加载速度。
# 8. single_cls ：一个布尔值，指示是否为单类别检测。在单类别检测中，模型只被训练来识别一种类型的物体。
# 9. stride ：模型的步长或下采样率。在目标检测模型中，这通常与模型的输入尺寸和特征图的尺寸有关。
# 10. pad ：填充比例或填充策略。这用于确定如何处理图像尺寸与模型输入尺寸不匹配的情况。
# 11. image_weights ：一个布尔值，指示是否使用图像权重。图像权重可以用于处理不平衡数据集，给予稀有类别的图像更高的权重。
# 12. prefix ：一个字符串，可能用于日志记录或输出，提供额外的上下文信息。
# class LoadImagesAndLabels(Dataset):
# -> def __init__(self, path, img_size=640, batch_size=16, augment=False, hyp=None, rect=False, image_weights=False, cache_images=False, single_cls=False, stride=32, pad=0.0, prefix=''):
# -> 这段代码定义了一个名为 LoadImagesAndLabels 的类，它继承自 PyTorch 的 Dataset 类。这个类用于在训练或测试期间加载图像及其对应的标签。
dataset = LoadImagesAndLabels(path, imgsz, batch_size,
augment=augment, # augment images
hyp=hyp, # augmentation hyperparameters
rect=rect, # rectangular training
cache_images=cache,
single_cls=opt.single_cls,
stride=int(stride),
pad=pad,
image_weights=image_weights,
prefix=prefix)
# 调整批处理大小。确保批处理大小不超过数据集的大小。
batch_size = min(batch_size, len(dataset))
# 计算工作线程数。计算可用于数据加载的工作线程数，考虑到 CPU 核心数、批处理大小和用户指定的工作线程数。
nw = min([os.cpu_count() // world_size, batch_size if batch_size > 1 else 0, workers]) # number of workers
# 选择采样器。在分布式训练中使用 DistributedSampler ，在非分布式训练中不使用采样器。
sampler = torch.utils.data.distributed.DistributedSampler(dataset) if rank != -1 else None
# 选择数据加载器。根据是否使用图像权重选择使用 torch.utils.data.DataLoader 或 InfiniteDataLoader 。
# class InfiniteDataLoader(torch.utils.data.dataloader.DataLoader):
# -> def __init__(self, *args, **kwargs):
# -> InfiniteDataLoader 类的构造函数 __init__ 的定义，它是一个自定义的数据加载器，继承自 PyTorch 的 DataLoader 类。这个构造函数的作用是初始化 InfiniteDataLoader 实例，并将其设置为一个可以无限重复提供数据的加载器。
loader = torch.utils.data.DataLoader if image_weights else InfiniteDataLoader
# Use torch.utils.data.DataLoader() if dataset.properties will update during training else InfiniteDataLoader()
# 创建数据加载器。使用选定的数据加载器类创建数据加载器实例，配置批处理大小、工作线程数、采样器、内存固定和合并函数。
dataloader = loader(dataset,
batch_size=batch_size,
num_workers=nw,
sampler=sampler,
pin_memory=True,
collate_fn=LoadImagesAndLabels.collate_fn4 if quad else LoadImagesAndLabels.collate_fn)
# 返回数据加载器和数据集。函数返回创建的数据加载器和数据集对象。
return dataloader, dataset5.class InfiniteDataLoader(torch.utils.data.dataloader.DataLoader):
# 这段代码定义了一个名为 InfiniteDataLoader 的类，它继承自 PyTorch 的 torch.utils.data.dataloader.DataLoader 类。
# InfiniteDataLoader 的目的是创建一个可以无限重复的数据加载器，这在某些训练场景中很有用，比如当你想要模型无限次地在同一个数据集上进行训练时。
class InfiniteDataLoader(torch.utils.data.dataloader.DataLoader):
# 重用 worker 的数据加载器。
# 使用与 vanilla DataLoader 相同的语法。
""" Dataloader that reuses workers
Uses same syntax as vanilla DataLoader
"""
# InfiniteDataLoader 类的构造函数 __init__ 的定义，它是一个自定义的数据加载器，继承自 PyTorch 的 DataLoader 类。这个构造函数的作用是初始化 InfiniteDataLoader 实例，并将其设置为一个可以无限重复提供数据的加载器。
def __init__(self, *args, **kwargs):
# 这行代码调用了父类 DataLoader 的构造函数，使用任意数量的位置参数 *args 和关键字参数 **kwargs 来初始化 DataLoader 。这些参数通常包括数据集对象、批处理大小、是否打乱数据等配置。
super().__init__(*args, **kwargs)
# 这行代码使用 object.__setattr__ 方法来设置 InfiniteDataLoader 实例的 batch_sampler 属性。通常， DataLoader 使用 batch_sampler 来确定如何从数据集中采样批次。
# 在这里，原始的 batch_sampler 被一个 _RepeatSampler 对象替换，这个对象会包装原始的 batch_sampler 并使其能够无限重复。
# object.__setattr__ ：这是一个直接设置对象属性的方法，绕过了任何可能的属性设置钩子或属性描述符。
# _RepeatSampler ：这是一个自定义的采样器类，它需要实现无限重复采样的逻辑。
# _RepeatSampler 类的作用 ：
# _RepeatSampler 类的目的是创建一个无限的采样器，它不断地重复调用原始 batch_sampler 来生成批次索引。这样，当 InfiniteDataLoader 被迭代时，它将不断地提供新的批次，直到程序显式地停止迭代。
object.__setattr__(self, 'batch_sampler', _RepeatSampler(self.batch_sampler))
# 这行代码初始化 InfiniteDataLoader 的迭代器。通过调用父类的 __iter__ 方法，它创建了一个迭代器，该迭代器可以用来遍历数据加载器生成的批次。
# 这个迭代器被存储在 self.iterator 属性中，以便在 InfiniteDataLoader 的 __iter__ 方法中使用。
self.iterator = super().__iter__()
# 这个构造函数通过替换 DataLoader 的 batch_sampler 为一个无限重复的采样器，并初始化一个迭代器，使得 InfiniteDataLoader 能够无限地提供数据批次。这对于需要长时间训练或持续处理数据流的应用非常有用。
# 在 Python 中， __len__ 方法是一个特殊方法（也称为魔术方法或内置方法），它被用来返回对象的长度。当在对象上使用内置的 len() 函数时，会触发这个方法的调用。
# 这个方法的作用是返回 self.batch_sampler.sampler 的长度。
# self ：指的是类实例本身。
def __len__(self):
# self.batch_sampler ：是类的一个属性，它可能是一个与数据加载相关的采样器对象。
# self.batch_sampler.sampler ：是 batch_sampler 属性中的 sampler 属性，它可能是一个 Python 序列（如列表、元组）或者任何其他支持 len() 函数的数据结构。
# len(self.batch_sampler.sampler) ：调用 len() 函数来获取 self.batch_sampler.sampler 的长度。
return len(self.batch_sampler.sampler)
# 使用场景 ：在数据加载器的上下文中， __len__ 方法通常用来确定数据集中有多少个批次。例如，如果你的数据加载器需要知道可以产生多少个批次的数据，它可以通过调用 __len__ 方法来获取这个信息。
# 这段代码定义了一个 __iter__ 方法，它是一个特殊方法，用于返回对象的迭代器。在 Python 中，当一个对象被用在 for 循环中或者需要迭代时， __iter__ 方法会被自动调用。
# 这是定义 __iter__ 方法的声明， self 代表类的实例本身。
def __iter__(self):
# 这个 for 循环会根据 __len__ 方法返回的长度来迭代。 range(len(self)) 生成一个序列，从 0 到 __len__ 返回值减 1。
for i in range(len(self)):
# 在每次迭代中， yield 语句产生（返回） self.iterator 的下一个元素。 self.iterator 是一个迭代器，它在 __iter__ 方法中被创建，并指向了数据加载器中的批次数据。
# next(self.iterator) 调用迭代器的 __next__ 方法来获取下一个元素，而 yield 使得这个元素可以在每次迭代中被逐个返回。
yield next(self.iterator)
# 作用 ：
# 这个方法使得包含它的类的实例可以被迭代，每次迭代都会产生数据加载器中的下一个批次数据。这在数据加载器中非常有用，因为它允许你使用 for 循环来遍历所有的数据批次。
# 注意 ：
# 如果 self.iterator 在迭代完所有批次后没有更多的数据， next(self.iterator) 将会抛出 StopIteration 异常。这个异常通常被 for 循环捕获，并用来结束循环。
# 这个方法假设 __len__ 方法返回的是数据加载器中批次的总数，但实际上，如果数据加载器是无限的或者其长度是动态变化的，那么 __len__ 方法可能不会返回准确的批次数。
# yield
# yield 是 Python 中的一个关键字，它用于在函数中创建一个生成器（generator）。当一个函数中包含 yield 语句时，这个函数就变成了一个生成器函数，它允许你逐个产生函数的值，而不是一次性返回所有值。
# 与 return 的区别 ：
# return 语句用于从函数返回一个值，并结束函数的执行。
# yield 语句用于从生成器函数返回一个值，但不结束函数的执行。函数的状态被保存，以便下一次从生成器请求值时继续执行。
# yield 的这些特性使得它在需要迭代处理数据时非常有用，特别是在数据量大或数据生成成本高的情况下。
# InfiniteDataLoader 类的使用方式与标准的 DataLoader 类似，但它会无限重复提供数据，直到程序显式地停止它。
# 这在某些情况下非常有用，比如在持续的训练循环中，或者当你想要确保模型在固定的数据集上进行训练，直到达到某个性能指标。
6.class _RepeatSampler(object):
# 这个 _RepeatSampler 类是一个自定义的采样器，它的作用是无限重复地提供另一个采样器（ sampler ）的样本。这种采样器在创建一个无限循环的数据加载器时非常有用，例如在某些训练场景中，你可能希望模型无限次地遍历数据集。
class _RepeatSampler(object):
# 永远重复的采样器。
""" Sampler that repeats forever
Args:
sampler (Sampler)
"""
# 这是 _RepeatSampler 类的构造函数，它接受一个参数 sampler ，这个参数是一个采样器对象，它定义了如何从数据集中采样。
def __init__(self, sampler):
# 在构造函数中，传入的采样器对象被保存在实例变量 self.sampler 中，以便后续使用。
self.sampler = sampler
# 这个方法使得 _RepeatSampler 可以被迭代，这是创建迭代器的关键。
def __iter__(self):
# 这个无限循环确保了 _RepeatSampler 会永远重复提供样本。
while True:
# 在循环中， yield from 语句用于迭代 self.sampler ，并一次提供一个样本。
# yield from 是 Python 3.3 引入的语法，它允许一个生成器从另一个生成器返回值。
# 这意味着，每次调用 _RepeatSampler 的 __iter__ 方法时，它都会开始一个新的迭代，从 self.sampler 的第一个样本开始，直到 self.sampler 的所有样本都被遍历完毕，然后循环重新开始。
yield from iter(self.sampler)
# 使用场景 ：_RepeatSampler 通常与 DataLoader 一起使用，以创建一个无限循环的数据加载器。
# 例如，如果你有一个数据集，并且希望模型无限次地遍历这个数据集，你可以将 _RepeatSampler 作为 DataLoader 的 sampler 参数传入，这样就可以实现无限循环的数据加载。7.class LoadImages:
# 这段代码定义了一个名为 LoadImages 的类，它用于在推理（inference）阶段加载图像或视频文件。
class LoadImages: # for inference
# 类的构造函数，接受三个参数。
# 1.path ：要加载的图像或视频文件的路径。
# 2.img_size ：加载图像的目标大小，默认为 640。
# 3.stride ：图像处理时的步长，默认为 32。
def __init__(self, path, img_size=640, stride=32):
# Path.absolute()
# .absolute() 方法是 Python pathlib 模块中 Path 类的一个方法，它用于返回路径的绝对版本。这个方法会解析路径中的符号链接（如果有的话），并返回一个指向实际文件或目录的路径。
# 参数 ：无参数。
# 返回值 ：
# 返回一个 Path 对象，表示原始路径的绝对路径。
# 将输入的 path 转换为绝对路径，并转换为字符串类型。
p = str(Path(path).absolute()) # os-agnostic absolute path 与操作系统无关的绝对路径。
# 检查路径中是否包含通配符 * 。
if '*' in p:
# sorted(iterable, key=None, reverse=False)
# Python 中的 sorted 函数用于对可迭代对象（如列表、元组、字符串等）中的元素进行排序，并返回一个新的排好序的列表。
# 参数说明 ：
# iterable ：需要排序的可迭代对象。
# key ：一个函数，它会被用来在进行比较之前从每个列表元素中提取一个比较键（比如通过一个函数指定排序的依据）。
# reverse ：布尔值。如果设置为 True ，则列表元素将被逆序排列，默认为 False 。
# 返回值 ：
# 返回一个新的排好序的列表，原可迭代对象不会被改变。
# 如果包含，则使用 glob.glob 递归地获取所有匹配的文件。
files = sorted(glob.glob(p, recursive=True)) # glob
elif os.path.isdir(p):
# 如果路径是一个目录，则获取该目录下所有文件。
files = sorted(glob.glob(os.path.join(p, '*.*'))) # dir
# os.path.isfile(path)
# isfile() 是 Python os.path 模块中的一个函数，用于检查给定的路径是否为一个存在的文件（不是目录）。如果路径指向一个存在的文件，则返回 True ；否则返回 False 。
# 参数说明 ：
# path ：需要检查的文件路径。
# 返回值 ：
# 返回一个布尔值， True 表示路径指向一个存在的文件， False 表示路径不存在或者路径指向的是一个目录。
# 请注意， isfile() 函数只检查路径是否存在且是否为文件，它不会检查文件是否为空或者是否可读。如果需要检查路径是否存在并且可读，你可能需要结合使用 os.path.exists() 和 os.access() 函数。
elif os.path.isfile(p):
# 如果路径是一个文件，则将其作为一个列表元素。
files = [p] # files
else:
# 如果路径不存在，则抛出异常。
raise Exception(f'ERROR: {p} does not exist') # 错误：{p} 不存在。
# 从文件列表中筛选出图像文件， img_formats 是支持的图像格式列表。
images = [x for x in files if x.split('.')[-1].lower() in img_formats]
# 从文件列表中筛选出视频文件， vid_formats 是支持的视频格式列表。
videos = [x for x in files if x.split('.')[-1].lower() in vid_formats]
# 计算图像文件和视频文件的数量。
ni, nv = len(images), len(videos)
# 设置图像的目标大小。
self.img_size = img_size
# 设置图像处理的步长。
self.stride = stride
# 将图像文件和视频文件合并到一个列表中。
self.files = images + videos
# 计算总的文件数量。
self.nf = ni + nv # number of files 文件数量。
# 创建一个标志列表，用于区分图像文件和视频文件。
self.video_flag = [False] * ni + [True] * nv
# 设置模式为 'image'。
self.mode = 'image'
if any(videos):
# 如果存在视频文件，则调用 self.new_video(videos[0]) 处理第一个视频文件。
# def new_video(self, path): -> 用于处理视频文件的类的一个部分。这个方法在处理新视频文件时被调用，负责初始化视频捕获和帧计数。
self.new_video(videos[0]) # new video
else:
# 如果没有视频文件，则设置 self.cap = None 。
self.cap = None
# 确保至少存在一个文件，否则抛出异常。
assert self.nf > 0, f'No images or videos found in {p}. ' \
f'Supported formats are:\nimages: {img_formats}\nvideos: {vid_formats}' # 在 {p} 中未找到图像或视频。支持的格式为：\n图像：{img_formats}\n视频：{vid_formats}。
# 这段代码定义了一个 Python 类的 __iter__ 方法。在 Python 中， __iter__ 方法是一个特殊方法，它使得一个对象成为可迭代的。当你在一个对象上调用 iter() 函数或者在对象后面使用 for 循环时，Python 会自动调用这个方法。
# 定义了类的 __iter__ 方法，它不接受除了 self 之外的任何参数。
def __iter__(self):
# 在每次迭代开始时，将 self.count 设置为 0。这通常用于跟踪迭代过程中的当前位置或状态。
self.count = 0
# 返回对象本身。为了让对象成为可迭代的， __iter__ 方法需要返回一个迭代器，这个迭代器实现了 __next__ 方法。在这种情况下，对象自己就是迭代器，所以方法返回 self 。
return self
# 这个 __iter__ 方法通常与 __next__ 方法一起使用， __next__ 方法定义了迭代器的逻辑，即如何产生下一个元素。每次调用迭代器时， __next__ 方法会被调用，直到它返回 StopIteration 异常，表示迭代结束。
# 这段代码定义了一个名为 __next__ 的特殊方法，它是 Python 迭代器协议的一部分。 __next__ 方法用于返回迭代器的下一个元素。当没有更多的元素可以返回时，这个方法应该抛出一个 StopIteration 异常。
# 定义了类的 __next__ 方法，它不接受除了 self 之外的任何参数。
def __next__(self):
# 检查是否已经到达了文件列表的末尾。
if self.count == self.nf:
# 如果已经到达列表末尾，则抛出 StopIteration 异常，表示迭代结束。
raise StopIteration
# 获取当前索引对应的文件路径。
path = self.files[self.count]
# 检查当前路径是否指向一个视频文件。
if self.video_flag[self.count]:
# Read video
# 设置模式为 'video'。
self.mode = 'video'
# 读取视频帧。
# 这行代码是在使用 OpenCV 的 VideoCapture 对象从视频文件中读取帧。 self.cap 是一个 VideoCapture 对象，它已经被初始化为指向一个视频文件或视频流。 read() 方法用于从视频捕获对象中读取一帧图像。
# ret_val ：这是一个布尔值，表示是否成功读取了帧。如果成功读取帧， ret_val 为 True ；如果没有更多的帧可以读取（即已经到达视频的末尾）， ret_val 为 False 。
# img0 ：这是读取的帧图像本身，如果成功读取，它将是一个 NumPy 数组，表示图像的像素数据；如果没有更多的帧可以读取， img0 将是一个空对象。
ret_val, img0 = self.cap.read()
# 检查是否成功读取了视频帧。
if not ret_val:
# 如果读取失败，增加计数器。
self.count += 1
# 释放视频捕获对象。
self.cap.release()
# 检查当前计数器 self.count 是否等于文件总数 self.nf 。如果是，意味着已经处理了所有文件（这里是视频文件），因此需要结束迭代。
if self.count == self.nf: # last video
# 如果处理了所有视频，则抛出 StopIteration 异常。
raise StopIteration
# 如果还有文件需要处理，即 self.count 不等于 self.nf ，则执行以下操作。
else:
# 获取下一个文件（视频）的路径。
path = self.files[self.count]
# 调用 new_video 方法来初始化一个新的视频捕获对象 self.cap ，并准备读取这个新视频的帧。这个方法通常会设置视频捕获对象，并获取视频的帧数等信息。
# def new_video(self, path): -> 用于处理视频文件的类的一个部分。这个方法在处理新视频文件时被调用，负责初始化视频捕获和帧计数。
self.new_video(path)
# 使用新初始化的视频捕获对象 self.cap 读取新视频的第一帧。 ret_val 是一个布尔值，表示是否成功读取帧； img0 是读取到的帧图像，如果成功读取，它将是一个 NumPy 数组。
ret_val, img0 = self.cap.read()
# 增加视频帧计数器。
self.frame += 1
# 打印视频帧信息。
print(f'video {self.count + 1}/{self.nf} ({self.frame}/{self.nframes}) {path}: ', end='')
# 如果当前路径指向的是图像文件。
else:
# Read image
self.count += 1
# cv2.imread(path, flags=cv2.IMREAD_COLOR)
# cv2.imread 函数是 OpenCV 库中用于读取图像文件的函数。它从一个指定的文件路径加载图像，并将其作为 NumPy 数组返回。
# 参数说明 ：
# path ：图像文件的路径。
# flags ：读取图像时使用的模式，它是一个可选参数，默认值为 cv2.IMREAD_COLOR 。其他可选模式包括 ：
# cv2.IMREAD_GRAYSCALE ：以灰度模式读取图像。
# cv2.IMREAD_UNCHANGED ：包括图像的alpha通道在内的原始图像。
# 返回值 ：
# 如果成功，返回一个 NumPy 数组，该数组表示图像的像素数据。
# 如果文件路径不正确或文件类型不支持，返回 None 。
# 使用 OpenCV 读取图像。
img0 = cv2.imread(path) # BGR
# 确保图像被成功加载。
assert img0 is not None, 'Image Not Found ' + path
#print(f'image {self.count}/{self.nf} {path}: ', end='')
# Padded resize
# 对图像进行缩放和填充，以适应模型输入尺寸。
# def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# -> 用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
# -> return img, ratio, (dw, dh)
img = letterbox(img0, self.img_size, stride=self.stride)[0]
# Convert
# 这行代码执行了两个操作，用于将图像数据从 BGR（Blue, Green, Red）格式转换为 RGB（Red, Green, Blue）格式，并调整维度以匹配深度学习模型的输入要求。
# img[:, :, ::-1] ：这个操作将图像数据从 BGR 格式转换为 RGB 格式。
# img 是一个三维的 NumPy 数组，其中第一个维度是高度（H），第二个维度是宽度（W），第三个维度是颜色通道（C）。
# ::-1 是一个切片操作，它反转了颜色通道的顺序。在 OpenCV 中，默认的图像格式是 BGR，所以 img[:, :, ::-1] 将蓝色通道、绿色通道和红色通道的顺序反转，从而得到 RGB 格式。
# .transpose(2, 0, 1) ：这个操作重新排列图像数组的维度，以匹配深度学习模型的输入格式。
# transpose 是 NumPy 数组的一个方法，它返回一个新的数组，其中轴的顺序被交换。
# 参数 2, 0, 1 指定了新的轴顺序 ：颜色通道（C）移动到第一个维度，高度（H）移动到第二个维度，宽度（W）移动到第三个维度。
# 这种格式（C, H, W）是许多深度学习框架（如 PyTorch 和 TensorFlow）所期望的输入格式。
# 综上所述，这行代码将图像从 OpenCV 的 BGR 格式转换为深度学习模型所需的 RGB 格式，并调整维度顺序为（C, H, W）。这种转换对于确保模型正确处理图像数据至关重要。
img = img[:, :, ::-1].transpose(2, 0, 1) # BGR to RGB, to 3x416x416
# 确保图像数据在内存中是连续的。
img = np.ascontiguousarray(img)
# 返回 文件路径 、 处理后的图像 、 原始图像 和 视频捕获对象 。
return path, img, img0, self.cap
# 这个方法通常与 __iter__ 方法一起使用， __iter__ 方法返回迭代器对象本身，而 __next__ 方法提供迭代的逻辑。在这个例子中，迭代器可以处理图像和视频文件，对它们进行预处理，并返回处理后的图像数据。
# 这段代码定义了一个名为 new_video 的方法，它是用于处理视频文件的类的一个部分。这个方法在处理新视频文件时被调用，负责初始化视频捕获和帧计数。
# 定义了 new_video 方法，它接受两个参数。
# 1.self ：类的实例。
# 2.path ：视频文件的路径。
def new_video(self, path):
# 将 self.frame 设置为 0，这个属性用于跟踪当前处理的视频帧编号。
self.frame = 0
# 使用 OpenCV 的 VideoCapture 类创建一个视频捕获对象，并用视频文件的路径初始化它。这个对象将用于从视频中读取帧。
self.cap = cv2.VideoCapture(path)
# 获取视频文件的总帧数。 cv2.CAP_PROP_FRAME_COUNT 是 OpenCV 中的一个属性，它表示视频的帧数。 self.cap.get() 方法用于获取这个属性的值，并将结果转换为整数，然后存储在 self.nframes 中。
self.nframes = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT))
# 这个方法通常在迭代器的上下文中使用，当迭代器遇到一个视频文件时，会调用 new_video 方法来准备视频处理。这样，迭代器就可以逐帧读取视频内容，并对其进行进一步的处理或分析。
# 这个方法是Python中特殊方法的一部分，用于定义对象的长度，即当你使用 len() 函数时返回的值。在这种情况下， __len__ 方法被用来告诉外界这个 LoadImages 对象包含了多少个文件。
# 定义了类的 __len__ 方法，这个方法不需要任何参数，除了 self 。
def __len__(self):
# 返回一个整数，即 self.nf ，这个属性在类的初始化方法 __init__ 中被设置，代表加载的图片文件的数量。
return self.nf # number of files8.class LoadWebcam:
# LoadWebcam 类是用来加载网络摄像头或者本地摄像头的类，以便在 YOLOv7 模型中进行推理。
class LoadWebcam: # for inference
# 这个类接受三个参数 ：
# 1. pipe ：摄像头的路径或者设备索引，可以是本地摄像头的索引（如 '0'），网络摄像头的 RTSP 流地址，或者是 IP 摄像头的 URL。
# 2. img_size ：输入图像的大小，用于调整摄像头捕获的图像大小以适应模型。
# 3. stride ：模型的步长，通常与模型的设计有关。
def __init__(self, pipe='0', img_size=640, stride=32):
# 这行代码将传入的 img_size 参数赋值给类实例的 img_size 属性。这个属性通常用于存储模型输入图像的期望尺寸。
self.img_size = img_size
# 这行代码将传入的 stride 参数赋值给类实例的 stride 属性。 stride 是模型结构中的一个参数，它与模型的下采样率有关。
self.stride = stride
# str.isnumeric()
# 在 Python 中， isnumeric() 是字符串（ str ）类的一个方法，用于判断字符串是否只包含数字字符。
# 如果字符串至少包含一个字符，并且所有字符都是数字，则返回 True 。
# 如果字符串为空或者包含非数字字符，则返回 False 。
# 这个方法是基于 Unicode 编码的数字属性来判断的，这意味着它可能认为某些非 ASCII 字符也是数字。例如，罗马数字或其他文化中的数字字符可能会被识别为数字。
# 请注意， isnumeric() 方法与 isdigit() 方法不同， isdigit() 方法只检查字符串是否只包含十进制数字字符（0-9）。而 isnumeric() 方法则更广泛，它检查字符串是否包含任何 Unicode 数字字符。
# 这是一个条件判断语句，用于检查传入的 pipe 参数是否只包含数字。 isnumeric() 方法会检查字符串中的所有字符是否都是数字。
if pipe.isnumeric():
# eval(expression, globals=None, locals=None)
# eval 是 Python 中的一个内置函数，它用于将字符串作为 Python 表达式动态地计算并返回结果。使用 eval 时需要小心，因为它会执行字符串中的代码，这可能导致安全问题，特别是如果执行的代码来自不可信的源。
# expression ：一个字符串，包含要评估的 Python 表达式。
# globals ：一个字典，用于定义表达式评估时使用的全局变量。如果为 None ，则使用当前环境的全局变量。
# locals ：一个字典，用于定义表达式评估时使用的局部变量。如果为 None ，则使用当前环境的局部变量。
# 安全性考虑 ：
# 由于 eval 可以执行任意代码，因此只应该在完全信任代码来源的情况下使用。在处理用户输入或其他不可预测的数据时，使用 eval 可能会导致代码注入攻击。
# 替代方案 ：
# 如果只需要计算数学表达式，可以使用 ast.literal_eval ，它只能评估字面量表达式，因此更安全。
# ast.literal_eval 只能处理简单的数据结构，如数字、字符串、元组、列表、字典、布尔值和 None 。如果尝试评估更复杂的表达式，它会抛出 ValueError 或 SyntaxError 。
# 如果 pipe 参数只包含数字，那么这行代码会执行。 eval() 函数会将字符串作为 Python 表达式来计算，并返回结果。在这里，它将字符串转换为整数，因为摄像头索引通常是整数。
pipe = eval(pipe) # local camera
# pipe = 'rtsp://192.168.1.64/1' # IP camera
# pipe = 'rtsp://username:[email protected]/1' # IP camera with login
# pipe = 'http://wmccpinetop.axiscam.net/mjpg/video.mjpg' # IP golf camera
# 这行代码将 pipe 参数的值赋给类的实例变量 self.pipe 。这个变量存储了摄像头的索引（如果是本地摄像头）或者摄像头的 URL/路径（如果是网络摄像头）。
self.pipe = pipe
# 这行代码使用 OpenCV 库创建一个视频捕获对象 self.cap 。 cv2.VideoCapture() 函数接受一个参数，该参数指定了视频源。如果是本地摄像头，这个参数通常是摄像头的索引（例如 '0' 或 '1'）；如果是网络摄像头，这个参数则是摄像头的 RTSP 流地址或 MJPEG 流地址。
self.cap = cv2.VideoCapture(pipe) # video capture object
# 这行代码设置了视频捕获对象的缓冲区大小。 cv2.CAP_PROP_BUFFERSIZE 是 OpenCV 中的一个属性，用于控制视频流的缓冲区大小。
# 增加缓冲区大小可以提高视频流的稳定性，尤其是在处理网络摄像头时，因为网络延迟和丢包可能会导致视频流不稳定。这里将缓冲区大小设置为 3，意味着 OpenCV 会尝试使用更大的缓冲区来处理视频流，以减少帧丢失和提高流畅度。
self.cap.set(cv2.CAP_PROP_BUFFERSIZE, 3) # set buffer size
# 这段代码定义了一个 Python 类的 __iter__ 方法。 __iter__ 方法是 Python 中的一个特殊方法（也称为魔术方法），用于定义一个对象的迭代器行为。当你想要让一个类的对象可以被用于迭代（例如在 for 循环中）时，你需要实现这个方法。
# __iter__ 方法在每次迭代开始时被调用。
# 它应该返回一个迭代器对象，这个对象必须有一个 __next__ 方法。
# 在每次迭代中， __next__ 方法会被调用，直到它返回 StopIteration 异常，这表示迭代结束。
def __iter__(self):
# 这个方法首先将实例变量 self.count 设置为 -1 。这通常是为了在 __next__ 方法中跟踪当前的迭代位置。然后， __iter__ 方法返回 self ，这意味着类的实例本身被用作迭代器。
# 为了使这个类完全可迭代，还需要定义 __next__ 方法。
self.count = -1
return self
# 请注意，如果你的类需要实现迭代器协议，那么 __iter__ 和 __next__ 方法都是必需的。
# __iter__ 方法返回迭代器对象（通常是类实例本身），而 __next__ 方法定义了迭代的逻辑，并在迭代结束时抛出 StopIteration 异常。
# 这段代码定义了一个 Python 类的 __next__ 方法，这个方法是迭代器协议的一部分，用于生成序列中的下一个元素。在这种情况下，它被用来从摄像头捕获视频帧，并对其进行处理，然后返回处理后的图像数据。
def __next__(self):
# 这行代码递增计数器，用于跟踪迭代的次数。
self.count += 1
# 这行代码检查用户是否按下了 'q' 键，如果是，则释放摄像头资源并关闭所有 OpenCV 创建的窗口，然后抛出 StopIteration 异常来结束迭代。
# cv2.waitKey(1) ：这是一个 OpenCV 函数，它等待特定的毫秒数（在这个例子中是1毫秒）来检测键盘输入。如果在这个时间段内有按键被按下，它将返回按键的 ASCII 码；如果没有按键被按下，它将返回 -1 。
# ord('q') ：这是一个 Python 内置函数，它返回字符 'q' 的 ASCII 码值。对于大写字母 'Q' 和小写字母 'q'，它们的 ASCII 码分别是 81 和 113。
# 所以， if cv2.waitKey(1) == ord('q') 这个条件语句的作用是检查用户是否在上一帧显示后的1毫秒内按下了 'q' 键。如果检测到 'q' 键被按下，条件判断为真，程序可以执行相应的操作，通常是退出循环或释放资源。
if cv2.waitKey(1) == ord('q'): # q to quit
# .release()
# 在 OpenCV 中， .release() 函数是 cv2.VideoCapture 类的一个成员函数，用于释放与视频捕获对象相关联的资源。当你使用 cv2.VideoCapture 对象捕获视频帧时， .release() 方法用来正确关闭和释放视频文件或摄像头设备。
# cap.release() 被调用来释放视频文件或摄像头设备。这是非常重要的，因为它可以确保资源被正确释放，特别是在处理视频文件或摄像头时，不释放可能会导致资源泄露或其他问题。
# .release() 方法没有参数，也没有返回值。它只是简单地释放与 cv2.VideoCapture 对象相关联的资源。在实际应用中，通常在视频处理完成后，或者在捕获过程中发生错误需要提前退出时调用这个方法。
self.cap.release()
# cv2.destroyAllWindows()
# cv2.destroyAllWindows() 是 OpenCV 库中的一个函数，用于关闭所有由 OpenCV 创建的窗口。这个函数是 OpenCV 高级界面函数的一部分，通常在程序结束时被调用来清理打开的窗口。
# cv2.destroyAllWindows() 函数没有参数和返回值。它的作用是关闭所有由 OpenCV 打开的窗口，无论它们是否可见。这个函数通常在程序结束时被调用，以确保程序退出时不会留下任何悬挂的窗口。
cv2.destroyAllWindows()
raise StopIteration
# Read frame
# 如果 self.pipe 为 0（表示本地摄像头），则从摄像头读取一帧图像。
if self.pipe == 0: # local camera
ret_val, img0 = self.cap.read()
# 将捕获的图像左右翻转。
img0 = cv2.flip(img0, 1) # flip left-right
else: # IP camera
# 如果 self.pipe 不为 0（表示 IP 摄像头），则使用一个循环来抓取帧，并每 30 帧只检索一次，这是一种减少网络延迟和提高性能的方法。
n = 0
while True:
n += 1
# bool grab()
# .grab() 函数是 OpenCV 中 cv2.VideoCapture 类的一个成员函数，用于从视频文件或捕获设备中抓取（但不解码）下一帧。这个函数通常用于多相机同步环境中，尤其是当相机没有硬件同步时。
# 通过先调用 .grab() 指向下一帧，然后调用 .retrieve() 来解码和获取帧，可以减少Demosaicing或运动JPEG解压缩等操作的开销，从而使得从不同相机检索的帧在时间上更接近。
# 参数 ：无参数。
# 返回值 ：
# bool ：如果成功抓取下一帧，则返回 True ；否则返回 False 。
# cap.grab() 用于抓取视频的下一帧，而 cap.retrieve() 用于检索和返回抓取的帧。这种方法可以用于提高多相机环境中帧的检索效率。
self.cap.grab()
if n % 30 == 0: # skip frames
# bool retrieve(OutputArray image, int flag=0)
# cap.retrieve()
# retrieve() 函数是 OpenCV 中 cv2.VideoCapture 类的一个成员函数，用于在视频流或视频文件中检索（解码）已经通过 grab() 函数抓取的帧。
# 参数 ：
# image ：这是一个输出参数，检索到的帧将被存储在这个 OutputArray 对象中。如果检索失败，图像将是一个空的 cv::Mat 对象。
# flag ：这是一个可选参数，默认值为0。它可以是一个帧索引或者特定于驱动程序的标志。在大多数情况下，这个参数不被使用，因此默认值就足够了。
# 返回值 ：
# bool ：如果成功检索到帧，则返回 True ；如果失败（例如，因为没有帧被抓取或者设备已断开连接），则返回 False 。
# retrieve() 函数通常与 grab() 函数一起使用，特别是在多相机同步环境中，或者当需要减少Demosaicing或运动JPEG解压缩等操作的开销时。通过先调用 grab() 抓取帧，然后调用 retrieve() 检索帧，可以确保从不同相机检索的帧在时间上更接近。
ret_val, img0 = self.cap.retrieve()
if ret_val:
break
# Print
# 确保 ret_val 为 True ，如果不是，则断言失败并打印错误信息。
assert ret_val, f'Camera Error {self.pipe}'
# 定义图像的路径，尽管这里没有实际使用到路径。
img_path = 'webcam.jpg'
# 打印当前帧的计数。
print(f'webcam {self.count}: ', end='')
# Padded resize
# 调用 letterbox 函数对图像进行缩放和填充，使其适应模型的输入尺寸。
# def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# -> 用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
# -> return img, ratio, (dw, dh)
img = letterbox(img0, self.img_size, stride=self.stride)[0]
# Convert
# 将图像从 BGR 格式转换为 RGB 格式，并调整维度以适应模型输入。
img = img[:, :, ::-1].transpose(2, 0, 1) # BGR to RGB, to 3x416x416
# 确保图像数组是连续的，这对于某些模型是必要的。
img = np.ascontiguousarray(img)
# 返回 图像路径 、 处理后的图像 、 原始图像 和 None （可能用于其他目的，但在这里没有使用）。
return img_path, img, img0, None
# 这个方法的目的是捕获摄像头的帧，对其进行预处理，并返回准备好的图像数据，以便可以将其输入到模型中进行推理。这个方法可以与 __iter__ 方法一起使用，使得类的实例可以在 for 循环中迭代，每次迭代返回一帧处理后的图像。
# 在 Python 中， __len__ 方法是一个特殊方法，它允许对象被用于 len() 函数中。当你调用 len() 函数时，Python 会自动调用对象的 __len__ 方法来获取对象的长度。
def __len__(self):
# 这个方法总是返回 0 ，这意味着如果你有一个这个类的实例，并且你尝试使用 len() 函数来获取它的长度，你将总是得到 0 。这可能表明这个类的实例被认为是空的或者没有长度的。
return 0
# 在实际应用中，如果你的类代表一个集合或者序列，你应该在 __len__ 方法中返回集合或序列中元素的数量。如果类不包含任何元素，返回 0 是合适的。如果类不应该被用于 len() 函数，你也可以选择不实现这个方法，这样尝试使用 len() 函数时会引发 TypeError 。9.class LoadStreams:
# 这段代码定义了一个名为 LoadStreams 的 Python 类，它用于从多个 IP 摄像头或 RTSP 流加载视频流。
class LoadStreams: # multiple IP or RTSP cameras
# 方法是类的构造函数，它接收三个参数。
# 1.sources ：包含摄像头流地址的文件路径或单个流地址，默认为 'streams.txt' 。
# 2.img_size ：模型期望的输入图像尺寸，默认为 640 。
# 3.stride ：模型的步长，默认为 32 。
def __init__(self, sources='streams.txt', img_size=640, stride=32):
# 设置模式为 'stream' ，表示这是一个视频流。
self.mode = 'stream'
# self.img_size 和 self.stride ：将传入的 img_size 和 stride 参数赋值给类的实例变量。
self.img_size = img_size
self.stride = stride
# 检查 sources 参数是否指向一个存在的文件。
if os.path.isfile(sources):
# 如果是文件，则读取文件内容，并将每一行作为一个流地址存储在 sources 列表中。
with open(sources, 'r') as f:
# str.strip([chars])
# 在 Python 中， .strip() 方法是字符串（ str ）对象的一个内置方法，用于移除字符串两端的空白字符（包括空格、换行符 \n 、制表符 \t 等）。
# 参数 ：
# chars （可选）：一个字符串，指定需要从原始字符串两端移除的字符集合。如果未提供，则默认移除空白字符。
# 返回值 ：
# 返回一个新的字符串，其中原始字符串两端的指定字符或空白字符已被移除。
# .strip() 方法不会修改原始字符串，而是返回一个新的字符串。如果需要移除字符串中间的空白字符，可以使用 .strip() 方法结合切片操作来实现。
# str.splitlines()
# 在 Python 中， .splitlines() 是字符串（ str ）对象的一个方法，用于将字符串分割成多行，返回一个包含每一行作为元素的列表。这个方法在处理多行文本时非常有用，比如从文件中读取的内容或用户输入的多行数据。
# 参数 ：无参数。
# 返回值 ：
# 返回一个列表，其中每个元素都是原始字符串中的一行。
# .splitlines() 方法在处理文本文件时特别有用，因为它可以轻松地将文件内容分割成单独的行，便于进一步处理。
sources = [x.strip() for x in f.read().strip().splitlines() if len(x.strip())]
else:
# 如果不是文件，则将 sources 视为单个流地址，并创建一个只包含该地址的列表。
sources = [sources]
n = len(sources)
# 创建一个列表 self.imgs 来存储每个流的当前帧，初始值为 None 。
self.imgs = [None] * n
# 对流地址进行清理，以便后续使用。
# def clean_str(s): -> 返回一个新的字符串，其中所有指定的特殊字符都被替换为了下划线 _ 。 -> return re.sub(pattern="[|@#!¡·$€%&()=?¿^*;:,¨´><+]", repl="_", string=s)
self.sources = [clean_str(x) for x in sources] # clean source names for later
# 循环遍历 sources 列表，对每个流地址执行以下操作。
for i, s in enumerate(sources):
# 启动线程从视频流中读取帧。
# Start the thread to read frames from the video stream
# 打印正在处理的流编号和地址。
print(f'{i + 1}/{n}: {s}... ', end='')
# 如果流地址是数字字符串，则使用 eval 将其转换为整数（这可能不安全，应避免使用 eval ）。
url = eval(s) if s.isnumeric() else s
# 检查流地址是否是 YouTube 视频，如果是，则使用 pafy 库获取最佳质量的视频 URL。
if 'youtube.com/' in url or 'youtu.be/' in url: # if source is YouTube video
# def check_requirements(requirements='requirements.txt', exclude=()):
# -> 检查当前环境中安装的依赖是否满足特定的要求，并在必要时自动更新这些依赖。这个函数可以接收一个包含依赖的文本文件或依赖列表，并排除一些不需要检查的包。 返回值 ：无返回值，函数直接打印结果或执行操作。
check_requirements(('pafy', 'youtube_dl'))
import pafy
url = pafy.new(url).getbest(preftype="mp4").url
# cv2.VideoCapture([index])
# cv2.VideoCapture 是 OpenCV 库中的一个类，用于从视频文件、图像序列或摄像头捕获视频流。这个类提供了一个接口来访问视频捕获设备，如摄像头，或者读取视频文件中的视频流。
# 参数 :
# index ：这是一个可选参数，指定视频捕获设备的索引或视频文件的路径。对于摄像头， index 通常是一个整数，用于指定要打开的摄像头（例如， 0 表示默认摄像头）。对于视频文件， index 是文件的路径。
# 返回值 :
# 返回一个 cv2.VideoCapture 对象，如果无法打开指定的视频捕获设备或文件，则返回 None 。
# 方法 cv2.VideoCapture 对象提供了多个方法来控制视频流和获取视频信息 :
# .read() ：从视频流中读取下一帧。
# .grab() ：从视频流中抓取（但不解码）下一帧。
# .retrieve() ：检索（解码）由 .grab() 抓取的帧。
# .release() ：释放视频捕获设备。
# .isOpened() ：检查视频捕获设备是否成功打开。
# .set(propId, value) ：设置视频捕获属性。
# .get(propId) ：获取视频捕获属性。
# 示例中， cv2.VideoCapture(0) 用于打开默认摄像头。然后，使用 .read() 方法从摄像头读取帧，并使用 cv2.imshow 显示帧。最后，使用 .release() 方法释放摄像头资源，并使用 cv2.destroyAllWindows() 关闭所有 OpenCV 创建的窗口。
# 使用 cv2.VideoCapture 创建视频捕获对象。
cap = cv2.VideoCapture(url)
# 断言视频捕获对象成功打开。
assert cap.isOpened(), f'Failed to open {s}'
# 获取视频流的宽度、高度和帧率，并存储在 self.fps 中。
w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
self.fps = cap.get(cv2.CAP_PROP_FPS) % 100
# 读取每个流的第一帧，确保视频流已启动。
_, self.imgs[i] = cap.read() # guarantee first frame
# 为每个流创建一个线程，用于在后台更新帧。线程的目标是 self.update 方法，传递流的索引和视频捕获对象作为参数。 daemon=True 表示这是一个守护线程，当主程序退出时，该线程也会自动退出。
thread = Thread(target=self.update, args=([i, cap]), daemon=True)
# 打印成功消息，包括视频流的分辨率和帧率。
print(f' success ({w}x{h} at {self.fps:.2f} FPS).')
thread.start()
# 在所有流处理完毕后打印一个新行。
print('') # newline
# check for common shapes 检查常见形状。
# 这行代码使用列表推导式对 self.imgs 列表中的每个图像帧 x 应用 letterbox 函数。 letterbox 函数的作用是将图像调整到指定的 img_size ，同时保持图像的纵横比，并对图像进行填充。
# 这里， letterbox 函数返回的是一个元组，其中第一个元素是调整后的图像， [0] 表示我们只取这个元组的第一个元素。然后， .shape 获取这个图像的形状（高度、宽度、通道数）。 np.stack 将这些形状堆叠成一个 NumPy 数组 s ，其中第一个维度（axis=0）是不同的图像帧。
# def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# -> 用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
# -> return img, ratio, (dw, dh)
s = np.stack([letterbox(x, self.img_size, stride=self.stride)[0].shape for x in self.imgs], 0) # shapes
# numpy.unique(ar, axis=None, out=None, return_index=False, return_inverse=False, return_counts=False, sorted=True)
# np.unique 是 NumPy 库中的一个函数，用于返回数组中的唯一元素，删除重复项，并可以对这些唯一元素进行排序。
# 参数 :
# ar ：输入数组。
# axis ：指定沿哪个轴删除重复项。如果为 None ，则将数组视为一维。
# out ：如果提供，则是输出数组的存储位置。
# return_index ：布尔值，如果为 True ，则返回元素在原始数组中的位置索引。
# return_inverse ：布尔值，如果为 True ，则返回一个索引数组，该数组将 ar 中的元素映射到输出数组中的元素。
# return_counts ：布尔值，如果为 True ，则返回每个唯一元素在原始数组中的计数。
# sorted ：布尔值，如果为 True ，则返回排序后的唯一元素。
# 返回值 :
# 如果没有指定额外的返回值，则返回一个包含输入数组中唯一元素的数组。
# 如果指定了 return_index 、 return_inverse 或 return_counts ，则返回一个元组，包含唯一元素和相应的索引、逆索引或计数。
# 这行代码使用 np.unique 函数来找出 s 数组中唯一的形状。 axis=0 表示沿着第一个维度（即不同的图像帧）查找唯一值。
# 如果所有图像帧的形状相同，那么 np.unique(s, axis=0) 将返回一个形状为 (1, 3) 的数组，其中 3 表示形状数组的每个元素有三个维度（高度、宽度、通道数）。
# .shape[0] 获取这个数组的第一个维度的大小，如果为 1 ，则表示所有图像帧的形状相同。 self.rect 存储这个布尔值，用于后续判断是否所有图像帧都是矩形推理（即所有图像帧形状相同）。
self.rect = np.unique(s, axis=0).shape[0] == 1 # rect inference if all shapes equal 如果所有形状都相等，则推理正确。
# 如果 self.rect 为 False ，即不是所有图像帧的形状都相同，那么执行以下代码：
if not self.rect:
# 打印一条警告信息，提示用户检测到不同的流形状。为了获得最佳性能，建议提供形状相似的流。
# 警告：检测到不同的流形状。为获得最佳性能，请提供形状相似的流。
print('WARNING: Different stream shapes detected. For optimal performance supply similarly-shaped streams.')
# 这段代码定义了一个名为 update 的函数，它是一个成员函数，通常属于某个类，用于在一个守护线程中更新视频流的帧。这个函数的目的是从视频捕获对象 cap 中定期读取帧，并将其存储在类的 self.imgs 列表中，该列表的特定索引由参数 index 指定。
# 1.self ：类的实例本身。
# 2.index ：一个整数，指定 self.imgs 列表中要更新的帧的索引。
# 3.cap ：一个 cv2.VideoCapture 对象，用于从视频流中捕获帧。
def update(self, index, cap):
# Read next stream frame in a daemon thread 在守护线程中读取下一个流帧。
# 初始化一个计数器 n ，用于跟踪读取帧的次数。
n = 0
# 循环检查 cap 对象是否打开，这是为了防止在释放资源后继续执行循环。
while cap.isOpened():
# 每次循环时增加计数器 n 。
n += 1
# _, self.imgs[index] = cap.read()
# 从视频流中抓取（但不解码）下一帧。
cap.grab()
# 检查计数器 n 是否等于 4，如果是，则执行以下操作。
if n == 4: # read every 4th frame 每 4 帧读取一次。
# 检索（解码）由 .grab() 抓取的帧，并检查操作是否成功。
success, im = cap.retrieve()
# 如果检索成功，则将解码的帧 im 赋值给 self.imgs 列表中指定索引的元素；如果失败，则将该元素设置为零（这可能是一个占位符，表示没有有效的帧）。
self.imgs[index] = im if success else self.imgs[index] * 0
# 重置计数器 n 为 0，以便重新开始计数。
n = 0
# 使线程休眠一段时间，这个时间是视频流的帧率 self.fps 的倒数，以确保按照视频流的帧率同步读取帧。
time.sleep(1 / self.fps) # wait time 等待时间。
# __iter__ 是一个特殊的方法，用于定义一个对象如何被迭代。当一个对象需要被用于迭代操作时（比如在 for 循环中），Python 会自动调用这个方法。
def __iter__(self):
# 将实例变量 self.count 设置为 -1 。这可能是为了在迭代过程中跟踪当前的迭代次数或者作为某种状态标记。
self.count = -1
# 返回 self 。这意味着这个类的实例本身就是迭代器。在 Python 中，一个对象要成为迭代器，它需要实现 __iter__ 方法返回迭代器本身，并且还需要实现 __next__ 方法来定义每次迭代返回什么值。
return self
# 这个 __iter__ 方法的实现表明 LoadStreams 类的实例可以直接用于迭代，但是为了完整实现迭代器协议， LoadStreams 类还需要一个 __next__ 方法来定义每次迭代时返回的值。
# 如果没有 __next__ 方法，尝试迭代 LoadStreams 的实例将会引发错误，因为 Python 会期望通过 __next__ 方法获取下一个元素。
# 这段代码是 LoadStreams 类的 __next__ 方法的实现，它是 Python 迭代器协议的一部分。 __next__ 方法定义了迭代器如何返回序列中的下一个元素。
def __next__(self):
# 计数器递增。这行代码将 self.count 递增，这个计数器可能用于跟踪当前迭代的次数。
self.count += 1
# 复制图像列表。这里创建了 self.imgs 列表的一个副本， self.imgs 包含了当前帧的图像数据。复制这个列表可能是为了避免在后续处理中修改原始图像数据。
img0 = self.imgs.copy()
# 退出条件。这里使用 cv2.waitKey(1) 检查是否有按键按下，如果用户按下了 'q' 键，则关闭所有 OpenCV 创建的窗口，并抛出 StopIteration 异常来结束迭代。
if cv2.waitKey(1) == ord('q'): # q to quit
cv2.destroyAllWindows()
raise StopIteration
# Letterbox
# 图像预处理。这行代码对每个图像进行预处理，使用 letterbox 函数将图像调整到 self.img_size 的大小，同时保持图像的纵横比。 auto 和 stride 参数用于控制调整的详细行为。
# def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# -> 用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
# -> return img, ratio, (dw, dh)
img = [letterbox(x, self.img_size, auto=self.rect, stride=self.stride)[0] for x in img0]
# Stack
# 堆叠图像。使用 np.stack 将列表中的图像堆叠成一个 NumPy 数组，其中 0 表示沿着第一个维度（批次维度）堆叠。
img = np.stack(img, 0)
# Convert
# 颜色转换和数组转换。
# 这里首先将图像的颜色从 BGR 转换为 RGB，然后调整数组的维度顺序以匹配模型的输入要求（批次大小、颜色通道、高度、宽度）。最后，使用 np.ascontiguousarray 确保数组在内存中是连续的，这对于某些深度学习框架的性能至关重要。
img = img[:, :, :, ::-1].transpose(0, 3, 1, 2) # BGR to RGB, to bsx3x416x416
img = np.ascontiguousarray(img)
# 返回值。方法返回四个值。
# self.sources ： 图像的来源信息，流地址。
# img ：预处理后的图像数组。
# img0 ：原始图像列表的副本。
# None ：可能表示没有额外的信息或者标签。
return self.sources, img, img0, None
# 在 LoadStreams 类中定义的 __len__ 方法返回 0 ，这通常表示这个类实例的迭代次数是无限的或者未定义的。在 Python 中， __len__ 方法用于返回一个对象的长度，即它包含的元素数量。当这个方法被定义在迭代器上时，它可以用来表示迭代器可以产生元素的总数。
def __len__(self):
# 注释说明如果按照 1E12 （即 1 万亿）帧来计算，假设有 32 个视频流，每个流以每秒 30 帧（FPS）的速度播放，那么这些视频流可以连续播放 30 年。
# 这显然是一个理论上的极大值，实际上不太可能达到，因此 __len__ 方法返回 0 表示这个迭代器理论上可以无限迭代，或者其迭代次数是未知的。
return 0 # 1E12 frames = 32 streams at 30 FPS for 30 years
# 在实际应用中，这样的设计可能用于处理实时视频流，其中视频流是连续不断的，你不知道确切的帧数，因此无法提供一个确切的长度。在这种情况下，迭代器会一直产生新的帧，直到外部条件（比如用户按下 'q' 键）终止迭代。10.class LoadImagesAndLabels(Dataset):
# 这段代码定义了一个名为 LoadImagesAndLabels 的类，它继承自 PyTorch 的 Dataset 类。这个类用于在训练或测试期间加载图像及其对应的标签。
class LoadImagesAndLabels(Dataset): # for training/testing
# 参数解释 :
# 1.path ：数据集的路径，可以是包含图像文件的文件夹路径或包含图像路径的文本文件。
# 2.img_size ：加载图像的目标尺寸，默认为640像素。
# 3.batch_size ：批处理大小，默认为16。
# 4.augment ：是否应用数据增强，默认为False。
# 5.hyp ：数据增强的超参数，如果没有提供则为None。
# 6.rect ：是否进行矩形训练，默认为False。
# 7.image_weights ：是否使用图像权重，默认为False。
# 8.cache_images ：是否缓存图像数据，默认为False。
# 9.single_cls ：是否为单类别检测，默认为False。
# 10.stride ：模型的步长，默认为32。
# 11.pad ：填充比例，默认为0.0。
# 12.prefix ：前缀字符串，用于日志记录或输出。
def __init__(self, path, img_size=640, batch_size=16, augment=False, hyp=None, rect=False, image_weights=False,
cache_images=False, single_cls=False, stride=32, pad=0.0, prefix=''):
# 初始化了类的一些属性，这些属性控制着数据加载和预处理的行为。
# 将传入的 img_size 参数赋值给实例变量 self.img_size ，表示图像的目标尺寸。
self.img_size = img_size
# 将传入的 augment 参数赋值给实例变量 self.augment ，表示是否应用数据增强。
self.augment = augment
# 将传入的 hyp 参数（数据增强的超参数）赋值给实例变量 self.hyp 。
self.hyp = hyp
# 将传入的 image_weights 参数赋值给实例变量 self.image_weights ，表示是否使用图像权重。
self.image_weights = image_weights
# 根据是否使用图像权重来决定是否进行矩形训练。如果 image_weights 为 True ，则 self.rect 设置为 False ；否则，使用传入的 rect 参数值。
self.rect = False if image_weights else rect
# 判断是否在训练时将4张图像加载成一个马赛克（mosaic）。这仅在进行数据增强且不是矩形训练时启用。
self.mosaic = self.augment and not self.rect # load 4 images at a time into a mosaic (only during training)
# 设置马赛克图像的边界值。这里使用 img_size 的一半作为边界值，表示马赛克的中心位置。
self.mosaic_border = [-img_size // 2, -img_size // 2]
# 将传入的 stride 参数赋值给实例变量 self.stride ，表示模型的步长。
self.stride = stride
# 将传入的 path 参数赋值给实例变量 self.path ，表示数据集的路径。
self.path = path
# 这行代码被注释掉了，但如果取消注释，它将根据是否进行数据增强来初始化 self.albumentations 属性。 Albumentations 是一个用于图像增强的库，可以提供多种增强操作。
#self.albumentations = Albumentations() if augment else None
# 作用是从一个或多个路径中加载图像文件的路径，并存储在 self.img_files 属性中。这个过程涉及到检查路径是目录还是文件，递归地搜索目录中的图像文件，或者从文本文件中读取图像路径。
# 开始一个 try 块，用于捕获并处理可能发生的异常。
try:
# 初始化一个空列表 f ，用于存储找到的图像文件路径。
f = [] # image files 图像文件。
# 这个循环遍历 path 参数，如果 path 是列表，则直接遍历；如果不是列表，则将 path 包装成列表。
for p in path if isinstance(path, list) else [path]:
# 将路径转换为 Path 对象，使其跨操作系统兼容。
p = Path(p) # os-agnostic
# 检查 p 是否是目录。
if p.is_dir(): # dir
# 如果是目录。这行代码的作用是将路径 p 下的所有文件（包括子目录中的文件）的路径添加到列表 f 中。这样， f 就包含了所有需要处理的图像文件的路径。
# 使用 Python 的 glob 模块来查找指定路径 p 下的所有文件，并且递归地搜索所有子目录。
# glob.glob ：这是 glob 模块的一个函数，用于从目录通配符指定中搜索匹配的文件路径。
# str(p / '**' / '*.*') ：这里使用了 Python 的路径操作。 p 是一个 Path 对象， / 是路径分隔符， ** 表示任意深度的子目录， *.* 是一个通配符，匹配任意文件。 str() 函数将路径对象转换为字符串，因为 glob.glob 需要字符串参数。
# recursive=True ：这个参数指定 glob.glob 应该递归地搜索所有子目录。
f += glob.glob(str(p / '**' / '*.*'), recursive=True)
# f = list(p.rglob('**/*.*')) # pathlib
# 如果 p 是文件，读取文件内容。
elif p.is_file(): # file
# 打开文件并读取内容。
with open(p, 'r') as t:
# 读取文件内容，去除空白字符，并按行分割。
t = t.read().strip().splitlines()
# 获取文件的父目录路径，并添加操作系统特定的分隔符。
# p.parent ：这是 pathlib 模块中的 Path 对象的一个属性，它返回一个新的 Path 对象，表示原始路径 p 的父目录。
# str(p.parent) ：将 Path 对象转换成字符串形式的路径。这是因为 parent 属性返回的是一个 Path 对象，而我们需要一个字符串来构建完整的路径。
# os.sep ：这是一个常量，代表操作系统的路径分隔符。在 Windows 上， os.sep 是 \ ，而在 Unix 和 Linux 系统上， os.sep 是 / 。
# str(p.parent) + os.sep ：将父目录的字符串路径与操作系统的路径分隔符连接起来，确保路径以正确的分隔符结束，这对于后续构建完整的文件路径是必要的。
parent = str(p.parent) + os.sep
# 将文件中的相对路径转换为绝对路径，并添加到 f 列表中。
# 这行代码是一个列表推导式，用于处理从文件中读取的图像路径列表 t ，并将相对路径转换为绝对路径。
# f += [...] ：这是列表的连接操作，用于将推导式生成的新列表追加到现有的列表 f 中。
# for x in t ：这是列表推导式的循环部分，它遍历列表 t 中的每个元素 x 。
# x.replace('./', parent) if x.startswith('./') else x ：这是一个条件表达式（三元运算符），用于检查每个路径 x 是否以 './' 开头。
# 如果 x 以 './' 开头（即它是一个从当前目录开始的相对路径），则使用 replace 方法将 './' 替换为 parent 变量指定的父目录路径。这样，相对路径就被转换为了绝对路径。
# 如果 x 不以 './' 开头，这意味着它已经是一个绝对路径或以其他方式指定的路径，因此直接使用 x 。
# [x.replace('./', parent) if x.startswith('./') else x for x in t] ：整个列表推导式生成一个新的列表，其中包含了转换后的路径。
f += [x.replace('./', parent) if x.startswith('./') else x for x in t] # local to global path 本地到全局路径。
# f += [p.parent / x.lstrip(os.sep) for x in t] # local to global path (pathlib)
else:
# 如果 p 既不是目录也不是文件，抛出异常。
raise Exception(f'{prefix}{p} does not exist')
# 筛选 f 列表中的图像文件，并存储到 self.img_files 。这个列表只包含那些文件扩展名符合指定图像格式的文件。
# self.img_files ：这是类的实例变量，用于存储最终的图像文件路径列表。
# sorted(...) ：这是一个函数调用，用于将列表中的元素按照字典序排序。在这种情况下，它将对图像文件路径列表进行排序。
# for x in f ：这是一个列表推导式的循环部分，它遍历列表 f 中的每个元素 x 。
# x.replace('/', os.sep) ：这个表达式将路径 x 中的所有正斜杠 / 替换为操作系统特定的路径分隔符 os.sep 。这确保了路径在不同操作系统中的兼容性。
# if x.split('.')[-1].lower() in img_formats ：这是一个条件表达式，用于检查路径 x 的文件扩展名是否在允许的图像格式列表 img_formats 中。 x.split('.')[-1] 会分割文件名并获取最后一个部分，即文件扩展名。 lower() 函数确保扩展名的比较不受大小写影响。
# in img_formats ：这个表达式检查文件扩展名是否在 img_formats 列表中。
# [x.replace('/', os.sep) for x in f if x.split('.')[-1].lower() in img_formats] ：整个列表推导式生成一个新的列表，其中包含了所有有效图像文件的路径，这些路径的文件扩展名符合指定的图像格式，并且路径中的正斜杠已被替换为操作系统特定的路径分隔符。
self.img_files = sorted([x.replace('/', os.sep) for x in f if x.split('.')[-1].lower() in img_formats])
# self.img_files = sorted([x for x in f if x.suffix[1:].lower() in img_formats]) # pathlib
# 确保至少找到一个图像文件。
assert self.img_files, f'{prefix}No images found'
# 捕获并处理任何异常。
except Exception as e:
# 如果发生异常，抛出一个新的异常，包含错误信息和帮助链接。
raise Exception(f'{prefix}Error loading data from {path}: {e}\nSee {help_url}')
# 这段代码负责从给定的路径中加载图像文件的路径，处理了目录和文件两种情况，并确保找到的图像文件是有效的。它还处理了异常情况，并提供了错误信息和帮助链接。这是数据加载过程中的一个重要步骤，确保模型训练或测试时有正确的数据输入。
# Check cache 检查缓存。
# 负责检查和处理与图像标签相关的缓存。
# 这行代码调用 img2label_paths 函数，它将图像文件路径列表 self.img_files 转换为对应的标签文件路径列表，并存储在 self.label_files 中。
# def img2label_paths(img_paths): -> 这个 img2label_paths 函数接受一个图像文件路径列表 img_paths ，并返回对应的标签文件路径列表。 -> return ['txt'.join(x.replace(sa, sb, 1).rsplit(x.split('.')[-1], 1)) for x in img_paths]
self.label_files = img2label_paths(self.img_files) # labels 标签。
# 这行代码确定缓存文件的路径。如果 p 是一个文件路径，则使用该路径；否则，使用第一个标签文件的父目录。
# .with_suffix('.cache') ：将路径的后缀名更改为 .cache ，这是缓存文件的约定后缀。
cache_path = (p if p.is_file() else Path(self.label_files[0]).parent).with_suffix('.cache') # cached labels 检查标签。
# 这行代码检查缓存文件是否存在。
if cache_path.is_file():
# 如果缓存文件存在，使用 torch.load 加载缓存文件的内容到变量 cache ，并设置 exists 为 True 。
cache, exists = torch.load(cache_path), True # load 加载。
# 这是一个被注释掉的条件判断，用于检查缓存是否有效。如果缓存中的哈希值与当前标签文件和图像文件的哈希值不匹配，或者缓存中没有版本信息，则需要重新缓存。
#if cache['hash'] != get_hash(self.label_files + self.img_files) or 'version' not in cache: # changed
# 如果缓存无效，调用 self.cache_labels 方法重新生成缓存，并设置 exists 为 False 。
# cache, exists = self.cache_labels(cache_path, prefix), False # re-cache
# 如果缓存文件不存在，执行 else 块中的代码。
else:
# 调用 self.cache_labels 方法生成缓存文件，并设置 exists 为 False 。
# def cache_labels(self, path=Path('./labels.cache'), prefix=''): -> 这个方法的目的是缓存数据集的标签信息，检查图像文件和读取它们的尺寸。返回缓存数据。 -> return x
cache, exists = self.cache_labels(cache_path, prefix), False # cache 缓存。
# 这段代码的目的是在加载图像和标签之前检查缓存的有效性。如果缓存文件存在且有效，它将被加载以提高数据加载的效率。如果缓存文件不存在或无效，将重新生成缓存文件。这种方法可以显著提高数据加载的速度，特别是在处理大量数据时。
# 代码中的注释部分提供了一个额外的检查机制，用于在缓存文件的内容发生变化时重新生成缓存。这部分代码目前被注释掉了，但可以根据需要取消注释并使用。
# Display cache 显示缓存。
# 从缓存中提取扫描图像和标签的结果，并根据这些结果进行相应的处理和断言。
# 从缓存字典 cache 中弹出键为 'results' 的值，这个值包含了扫描图像和标签的结果，包括找到的 标签数 ( nf ) 、 缺失的标签数 ( nm ) 、 空的标签数 ( ne ) 、 损坏的图像或标签数 ( nc ) 以及 总数 ( n )。
nf, nm, ne, nc, n = cache.pop('results') # found, missing, empty, corrupted, total
# 如果缓存存在（即 exists 为 True ），则执行以下操作。
if exists:
# 构造一个描述字符串 d ，包含扫描的文件路径、找到的标签数、缺失的标签数、空的标签数和损坏的图像或标签数。
d = f"Scanning '{cache_path}' images and labels... {nf} found, {nm} missing, {ne} empty, {nc} corrupted" # 扫描“{cache_path}”图像和标签...找到 {nf} 个，缺少 {nm} 个，{ne} 个为空，{nc} 个已损坏。
# 使用 tqdm 库创建一个进度条，显示缓存结果。
# None 表示没有迭代器，因为这里只是显示信息而不是迭代处理。
# desc 参数设置进度条的描述文本， prefix + d 是前缀和描述字符串的组合。
# total=n 设置进度条的总长度为 n ，即总数。
# initial=n 设置进度条的初始位置为 n ，因为所有的处理都已经完成。
tqdm(None, desc=prefix + d, total=n, initial=n) # display cache results 显示缓存结果。
# 这是一个断言语句，检查是否至少找到了一个标签 ( nf > 0 ) 或者没有进行数据增强 ( not augment )。 如果没有找到任何标签且正在进行数据增强，断言将失败，并抛出一个异常，提示没有标签无法进行训练，并给出帮助链接。
assert nf > 0 or not augment, f'{prefix}No labels in {cache_path}. Can not train without labels. See {help_url}' # {prefix}{cache_path} 中没有标签。没有标签就无法训练。请参阅 {help_url}。
# 这段代码的目的是处理和显示缓存的结果，确保在训练之前有足够的标签数据。如果没有找到任何标签，它会阻止训练过程，并给出相应的错误信息。这是数据预处理和训练准备阶段的一个重要步骤，确保数据的完整性和训练的可行性。
# Read cache
# 它从缓存中提取图像的标签、形状、以及对应的文件路径，并进行相应的处理和转换。
# 从缓存中移除 'hash' 和 'version' 键值对。 'hash' 是用于验证缓存文件完整性的哈希值， 'version' 是缓存的版本号。
cache.pop('hash') # remove hash
cache.pop('version') # remove version
# 使用 zip 函数和解包操作符 * 将缓存中的值按照对应的键（通常是图像文件路径）分组，然后分别赋值给 labels 、 shapes 和 self.segments 。 labels 包含标签数据， shapes 包含图像尺寸， self.segments 包含分割数据。
labels, shapes, self.segments = zip(*cache.values())
# 将 labels 转换为列表，并赋值给 self.labels 。
self.labels = list(labels)
# 将 shapes 转换为 NumPy 数组，并指定数据类型为 np.float64 ，然后赋值给 self.shapes 。
self.shapes = np.array(shapes, dtype=np.float64)
# 获取缓存中的所有键（图像文件路径），并转换为列表，然后赋值给 self.img_files 。
self.img_files = list(cache.keys()) # update
# 使用 img2label_paths 函数将图像文件路径转换为对应的标签文件路径，并赋值给 self.label_files 。
# def img2label_paths(img_paths): -> 这个 img2label_paths 函数接受一个图像文件路径列表 img_paths ，并返回对应的标签文件路径列表。 -> return ['txt'.join(x.replace(sa, sb, 1).rsplit(x.split('.')[-1], 1)) for x in img_paths]
self.label_files = img2label_paths(cache.keys()) # update
# 检查是否设置了 single_cls 参数为 True 。 single_cls 通常用于指示数据集中是否只有一个类别。
if single_cls:
# 如果数据集是单类别的，这个循环遍历 self.labels 中的每个标签数组 x 。 self.labels 是一个包含所有图像标签的列表。
for x in self.labels:
# 对于每个标签数组 x ，将所有行的第一列（即类别标签）设置为 0。这里假设类别标签是数组的第一列，且在单类别数据集中，所有类别标签都相同，因此可以统一设置为 0 或任何其他指定的类别索引。
x[:, 0] = 0
# 获取图像的数量。
n = len(shapes) # number of images
# 计算每个图像属于哪个批次。这是通过将图像索引除以批次大小并向下取整来实现的。
bi = np.floor(np.arange(n) / batch_size).astype(np.int) # batch index 批次索引。
# 获取总的批次数量。
nb = bi[-1] + 1 # number of batches
# 将批次索引赋值给 self.batch 。
self.batch = bi # batch index of image 图像批次索引。
# 将图像数量赋值给 self.n 。
self.n = n
# 创建一个从 0 到 n-1 的整数序列，并赋值给 self.indices 。
self.indices = range(n)
# 这段代码的目的是将缓存中的数据提取出来，并进行必要的转换和处理，以便在后续的数据加载和模型训练中使用。通过这种方式，可以有效地管理和使用缓存数据，提高数据加载的效率和训练的便捷性。
# Rectangular Training 矩形训练。
# 处理矩形训练（Rectangular Training）的部分。矩形训练是一种数据增强技术，它通过改变训练图像的宽高比来增加数据集的多样性。
# 这是一个条件判断，检查是否设置了 self.rect 属性为 True 。 self.rect 通常用于指示是否启用矩形训练。
if self.rect:
# Sort by aspect ratio 按宽高比排序。
# 获取图像的形状，这里假设 self.shapes 包含了图像的宽度和高度（ wh ）。
s = self.shapes # wh
# 计算每个图像的宽高比（ aspect ratio ，AR），即宽度除以高度。
ar = s[:, 1] / s[:, 0] # aspect ratio 宽高比。
# 获取宽高比的排序索引，用于后续对图像文件、标签和形状进行排序。
irect = ar.argsort()
# 对 self.img_files 、 self.label_files 、 self.labels 、 self.shapes 和 ar进行排序。
# 使用 irect 索引对图像文件路径、标签文件路径、标签和图像形状进行排序，以确保它们按照宽高比的顺序排列。
self.img_files = [self.img_files[i] for i in irect]
self.label_files = [self.label_files[i] for i in irect]
self.labels = [self.labels[i] for i in irect]
self.shapes = s[irect] # wh
ar = ar[irect]
# Set training image shapes 设置训练图像形状。
# 初始化一个形状列表 shapes ，每个元素都是 [1, 1] ，长度为批次数量 nb 。
shapes = [[1, 1]] * nb
# 遍历每个批次，计算每个批次的图像形状。
for i in range(nb):
# 获取当前批次的宽高比。
ari = ar[bi == i]
# 计算当前批次宽高比的最小值和最大值。
mini, maxi = ari.min(), ari.max()
# 根据宽高比的最小值和最大值，设置当前批次的图像形状。
if maxi < 1:
# 如果最大宽高比小于 1，则设置形状为 [maxi, 1]。
shapes[i] = [maxi, 1]
elif mini > 1:
# 如果最小宽高比大于 1，则设置形状为 [1, 1 / mini]。
shapes[i] = [1, 1 / mini]
# 计算每个批次的图像形状，并将其转换为整数。这里使用 np.ceil 向上取整， img_size 是图像尺寸， stride 是模型的步长， pad 是填充比例。
# self.batch_shapes ，它代表每个批次图像的形状，考虑到了图像尺寸、步长和填充。
# np.array(shapes) ：将 shapes 列表转换为 NumPy 数组，以便进行向量化计算。
# * img_size / stride ：将 shapes 数组中的每个元素乘以图像尺寸 img_size ，然后除以步长 stride 。这一步是为了调整每个批次图像的形状，使其符合模型输入的要求。
# + pad ：将填充 pad 加到上一步的结果中。这里的 pad 是一个比例值，用于增加图像的尺寸以便在训练时增加一些边界信息。
# np.ceil(...) ：对上一步的结果应用 np.ceil 函数，该函数对数组中的每个元素向上取整。这样做是为了确保图像尺寸是整数，因为像素数不能是小数。
# .astype(np.int) ：将 NumPy 数组的数据类型转换为整数类型，因为图像尺寸必须是整数。
# * stride ：最后，将上一步的结果乘以步长 stride ，以恢复到原始的尺寸单位。
# self.batch_shapes ：将计算得到的形状数组赋值给 self.batch_shapes ，这个属性将用于后续的数据处理和模型训练中，以确保每个批次的图像都具有正确的尺寸。
self.batch_shapes = np.ceil(np.array(shapes) * img_size / stride + pad).astype(np.int) * stride
# 这段代码的目的是在矩形训练中，根据图像的宽高比对数据进行排序，并设置每个批次的图像形状。这种方法可以增加模型训练时的多样性，提高模型对不同宽高比图像的适应能力。
# 通过调整每个批次的图像形状，可以确保模型在训练过程中看到不同比例的图像，从而提高模型的泛化能力。
# 将图像缓存到内存中以加快训练速度（警告：大型数据集可能会超出系统 RAM）。
# Cache images into memory for faster training (WARNING: large datasets may exceed system RAM)
# 用于将图像缓存到内存或磁盘以加速训练的部分。
# 初始化一个列表 self.imgs ，用于存储加载的图像数据，长度为 n （图像数量）。
self.imgs = [None] * n
# 这是一个条件判断，检查是否设置了 cache_images 参数为 True 或特定的字符串。
if cache_images:
# 如果 cache_images 设置为 'disk' ，则将图像缓存到磁盘上的 .npy 文件中。
if cache_images == 'disk':
# path.as_posix()
# 在 Python 的 pathlib 模块中， Path 类的 .as_posix() 方法用于将 Path 对象表示的路径转换为 POSIX 风格的字符串。POSIX 是一个操作系统标准，它规定了文件路径应该使用正斜杠（ / ）作为目录分隔符。
# path ： Path 类的实例。
# 返回值 ：
# 返回一个字符串，表示 Path 对象的路径，其中所有的路径分隔符都被替换为正斜杠（ / ）。
# 方法功能 ：
# .as_posix() 方法将 Path 对象中的路径转换为一个字符串，这个字符串使用正斜杠（ / ）作为所有目录的分隔符，无论在原始路径中使用的是哪种操作系统的路径分隔符（例如，在 Windows 中可能是反斜杠 \ ）。
# 此外，该方法还会处理路径中的一些特殊情况，例如，将相对路径（如 ./ 或 ../ ）转换为简化形式，但不改变它们的相对性。 去除路径中多余的分隔符。
# 注意事项 ：
# .as_posix() 方法不检查路径的实际存在性，它仅仅进行字符串层面的转换。
# 如果你需要在不同的操作系统之间移植代码，或者与期望 POSIX 路径风格的外部工具或库交互，使用 .as_posix() 方法可以帮助确保路径的兼容性。
# 设置缓存目录的路径，通常是一个在图像文件所在目录下名为 _npy 的子目录。
self.im_cache_dir = Path(Path(self.img_files[0]).parent.as_posix() + '_npy')
# 为每个图像文件创建一个对应的 .npy 文件路径，并存储在 self.img_npy 列表中。
# path.with_suffix(suffix)
# with_suffix 是 Python pathlib 模块中 Path 类的一个方法，它用于修改路径对象的后缀（扩展名）。
# path ： Path 类的实例。
# suffix ：要设置的新后缀。如果为空字符串，则移除路径的当前后缀。
# 返回值 ：
# 返回一个新的 Path 对象，其后缀被修改为指定的 suffix 。
# 方法功能 ：
# 如果原始路径没有后缀， with_suffix 方法会将指定的后缀追加到路径的末尾。
# 如果原始路径已经有后缀， with_suffix 方法会替换为指定的新后缀。
# 如果指定的 suffix 是空字符串， with_suffix 方法会移除路径的当前后缀。
# 注意事项 ：
# with_suffix 方法不会修改原始的 Path 对象，而是返回一个新的 Path 对象。
# 这个方法在处理文件扩展名时非常有用，尤其是在你需要动态更改文件类型或处理不同格式的文件时。
self.img_npy = [self.im_cache_dir / Path(f).with_suffix('.npy').name for f in self.img_files]
# 创建缓存目录，如果目录已存在则不抛出异常。
self.im_cache_dir.mkdir(parents=True, exist_ok=True)
# 初始化一个计数器，用于跟踪已缓存图像的总大小（以GB为单位）。
gb = 0 # Gigabytes of cached images 数 GB 的缓存图像。
# 初始化两个列表，用于存储原始图像和缩放后图像的尺寸。
self.img_hw0, self.img_hw = [None] * n, [None] * n
# 使用线程池来并行加载图像， load_image 函数将被调用 n 次，每次传入 self 和一个图像索引。
# 使用了 Python 的 concurrent.futures 模块中的 ThreadPool 类来创建一个线程池，用于并行加载图像。
# ThreadPool(8) ： 创建一个包含8个工作线程的线程池。这意味着可以同时执行8个任务。
# .imap(...) ： .imap() 方法是一个迭代器，它将输入的可迭代对象中的每个元素分配给线程池中的一个线程进行处理，并返回结果的迭代器。
# lambda x: load_image(*x) ： 这是一个 lambda 函数，它接受一个参数 x ，并调用 load_image 函数，将 x 中的元素作为参数传递给 load_image 。 *x 表示将 x 解包为多个参数。
# zip(repeat(self), range(n)) ： zip() 函数将两个可迭代对象打包成一个元组的列表。 repeat(self) 创建一个无限迭代器，每次调用都返回 self 对象。 range(n) 创建一个从0到 n-1 的整数序列。
# 结果是一个元组列表，每个元组包含 self 和一个索引，用于 load_image 函数。
# 这段代码将 load_image 函数应用于 self 和每个索引的组合，其中 self 是包含图像路径和其他加载参数的对象。
# load_image 函数被并行执行，每个线程处理一个图像的加载。
# 结果是一个迭代器 results ，它生成每个图像加载的结果。
# def load_image(self, index):
# -> 负责从数据集中加载单个图像，并返回图像本身以及它的原始尺寸和调整后的尺寸。返回 加载的图像 以及它的 原始尺寸 和 调整后的尺寸 。
# -> return img, (h0, w0), img.shape[:2]
# -> return self.imgs[index], self.img_hw0[index], self.img_hw[index]
results = ThreadPool(8).imap(lambda x: load_image(*x), zip(repeat(self), range(n)))
# 创建一个进度条，用于显示图像加载的进度。
pbar = tqdm(enumerate(results), total=n)
# 遍历加载的图像结果。
for i, x in pbar:
if cache_images == 'disk':
# 如果缓存到磁盘，检查对应的 .npy 文件是否存在，如果不存在则保存图像数据。
if not self.img_npy[i].exists():
np.save(self.img_npy[i].as_posix(), x[0])
# 更新已缓存图像的总大小。
gb += self.img_npy[i].stat().st_size
else:
# 如果不是缓存到磁盘，直接将加载的图像数据存储到 self.imgs 中。
self.imgs[i], self.img_hw0[i], self.img_hw[i] = x
# 更新已缓存图像的总大小。
gb += self.imgs[i].nbytes
# 更新进度条的描述，显示已缓存图像的总大小。
pbar.desc = f'{prefix}Caching images ({gb / 1E9:.1f}GB)' # {prefix}缓存图像 ({gb / 1E9:.1f}GB)。
# 关闭进度条。
pbar.close()
# 这段代码通过并行加载图像并将它们缓存到内存或磁盘，以减少训练时的I/O开销。如果 cache_images 设置为 'disk' ，则图像数据被保存为 .npy 文件；否则，图像数据被直接存储到内存中。
# 这种方法可以显著提高训练速度，特别是当处理大型数据集时。
# 然而，需要注意的是，如果数据集过大，缓存到内存可能会导致系统内存不足。
# 这段代码定义了一个名为 cache_labels 的方法，它属于 LoadImagesAndLabels 类。这个方法的目的是缓存数据集的标签信息，检查图像文件和读取它们的尺寸。
# 方法参数 ：
# 1.self ：类的实例本身。
# 2.path ：缓存文件的路径，默认为当前目录下的 ./labels.cache 。
# 3.prefix ：前缀字符串，用于日志记录或输出，提供额外的上下文信息。
def cache_labels(self, path=Path('./labels.cache'), prefix=''):
# 缓存数据集标签、检查图像并读取形状。
# Cache dataset labels, check images and read shapes
# 初始化一个空字典 x ，用于存储缓存数据。
x = {} # dict
# 初始化计数器，分别用于记录 缺失的标签文件 、 找到的标签文件 、 空的标签文件 和 损坏的图像或标签 。
nm, nf, ne, nc = 0, 0, 0, 0 # number missing, found, empty, duplicate 缺失数量、找到、为空、重复。
# pbar = tqdm(...) ：创建一个进度条，用于显示扫描图像和标签的进度。
pbar = tqdm(zip(self.img_files, self.label_files), desc='Scanning images', total=len(self.img_files))
# 遍历图像文件和对应的标签文件。
for i, (im_file, lb_file) in enumerate(pbar):
# 尝试执行以下操作，捕获任何异常。
try:
# verify images 验证图像。
# 使用 PIL 打开图像文件。
im = Image.open(im_file)
# im.verify()
# 在 Python 的 PIL（Python Imaging Library）库中， .verify() 方法用于验证图像文件的完整性。当处理图像文件时，这个方法尝试确认文件是否未损坏并且可以被正确解码。
# im ：一个 PIL Image 对象。
# 功能 ：
# .verify() 方法检查图像文件是否完整且未损坏。如果文件损坏或无法被识别，这个方法会抛出一个 IOError （输入/输出错误）异常。
# 注意事项 ：
# .verify() 方法只适用于某些图像格式，特别是那些 PIL 支持的格式。
# 这个方法不会检查图像的元数据或内容，只检查图像文件的完整性和可读性。
# 在处理大量图像文件时，使用 .verify() 方法可以帮助识别和排除损坏的文件，以避免在后续处理中出现问题。
# 验证图像文件。
im.verify() # PIL verify PIL 验证。
# 获取图像的尺寸，考虑 EXIF 旋转信息。
# def exif_size(img): -> 返回一个图像的 EXIF 校正后的 PIL（Python Imaging Library，现在更多的是使用它的分支 Pillow）尺寸。返回图像的尺寸，如果图像没有旋转信息或者旋转信息不是 6 或 8，则返回原始尺寸。 -> return s
shape = exif_size(im) # image size 图像大小。
segments = [] # instance segments 实例段。
# 确保图像尺寸大于 10 像素。
assert (shape[0] > 9) & (shape[1] > 9), f'image size {shape} <10 pixels' # 图像大小{形状} <10像素。
# 确保图像格式有效。
assert im.format.lower() in img_formats, f'invalid image format {im.format}' # 无效的图像格式 {im.format}。
# verify labels 验证标签。
# 检查标签文件是否存在。
if os.path.isfile(lb_file):
# 如果标签文件存在，增加找到的标签文件计数。
nf += 1 # label found 找到标签。
# 打开标签文件。
with open(lb_file, 'r') as f:
# 读取标签文件的每一行，并分割每个标签。
# f.read().strip().splitlines() ：
# f.read() ：从文件对象 f 中读取所有内容。
# .strip() ：移除读取内容首尾的空白字符（包括换行符）。
# .splitlines() ：将去除空白后的字符串分割成行，返回一个列表，其中每个元素是原始文本的一行。
# [x.split() for x in ...] ： 这是一个列表推导式，它遍历 f.read().strip().splitlines() 返回的每一行（ x ）。
# x.split() ：将每一行 x 使用默认分隔符（通常是空格或换行符）分割成单词或标记，返回一个列表。
# l = ... ： 将列表推导式的结果赋值给变量 l 。
l = [x.split() for x in f.read().strip().splitlines()]
# 检查是否有实例分割标签。使用 Python 的 any() 函数来检查列表 l 中是否至少有一个元素（子列表）的长度大于 8。
# any(...) ：这是一个内置函数，它接受一个可迭代对象（如列表、元组等），并返回 True 如果可迭代对象中至少有一个元素为 True ，否则返回 False 。
# 应用场景 ：
# 这种条件检查在处理标签数据时非常有用，特别是在需要根据不同的标签长度执行不同操作的情况下。
# 例如，在目标检测任务中，标签可能包含类别信息和边界框坐标，如果标签包含额外的信息（如分割掩码坐标），则可能需要执行额外的处理步骤。这个条件检查可以帮助确定是否需要执行这些额外的步骤。
if any([len(x) > 8 for x in l]): # is segment
# 提取类别标签。
# 从列表 l 中的每个子列表 x 提取第一个元素（通常是类别标签），并将这些类别标签收集到一个新的列表中。然后，使用 np.array() 将这个列表转换为一个 NumPy 数组，数据类型为 np.float32 。
# x[0] ：每个子列表 x 的第一个元素，表示类别标签。
# np.array(...) ：将列表转换为 NumPy 数组。
# dtype=np.float32 ：指定数组的数据类型为 32 位浮点数。
classes = np.array([x[0] for x in l], dtype=np.float32)
# 提取实例分割坐标。
# 处理每个子列表 x 中除类别标签外的其余部分（通常是实例分割坐标），并将这些坐标转换为 NumPy 数组。
# x[1:] ：每个子列表 x 从第二个元素开始的所有元素，表示实例分割坐标。
# np.array(...) ：将列表转换为 NumPy 数组。
# dtype=np.float32 ：指定数组的数据类型为 32 位浮点数。
# .reshape(-1, 2) ：将数组重塑为每行有两个元素的二维数组， -1 表示自动计算行数。
segments = [np.array(x[1:], dtype=np.float32).reshape(-1, 2) for x in l] # (cls, xy1...)
# 将类别标签和实例分割坐标转换为边界框坐标。
# 将类别标签数组和实例分割坐标数组合并为一个统一的数组，通常用于目标检测任务中表示边界框。
# classes.reshape(-1, 1) ：将类别标签数组重塑为每行有一个元素的二维数组。
# np.concatenate(..., 1) ：沿着第二个轴（列）连接两个数组。
# def segments2boxes(segments): -> 它将分割标签（通常是一系列点的坐标）转换为边界框标签。 -> return xyxy2xywh(np.array(boxes)) # cls, xywh
l = np.concatenate((classes.reshape(-1, 1), segments2boxes(segments)), 1) # (cls, xywh)
# 使用 np.array 将列表 l 转换成一个 NumPy 数组，并且指定数组的数据类型为 np.float32 。
# dtype=np.float32 ：这是一个关键字参数，指定了数组元素的数据类型。 np.float32 表示 32 位浮点数，这是一种常用的数值类型，适用于存储实数，特别是当这些数值不需要太高的精度时。
l = np.array(l, dtype=np.float32)
# 如果标签不为空。
if len(l):
# 确保每个标签有 5 列。
assert l.shape[1] == 5, 'labels require 5 columns each' # 每个标签需要 5 列。
# 确保标签值非负。
assert (l >= 0).all(), 'negative labels' # 负标签。
# 确保坐标值在 0 到 1 之间。
assert (l[:, 1:] <= 1).all(), 'non-normalized or out of bounds coordinate labels' # 非规范化或超出范围的坐标标签。
# 确保没有重复的标签。
assert np.unique(l, axis=0).shape[0] == l.shape[0], 'duplicate labels' # 重复标签。
# 如果标签文件为空。
else:
# 增加空标签文件计数。
ne += 1 # label empty 标签为空。
l = np.zeros((0, 5), dtype=np.float32)
# 如果标签文件不存在。
else:
# 增加缺失标签文件计数。
nm += 1 # label missing 标签缺失。
l = np.zeros((0, 5), dtype=np.float32)
# 将标签数据、图像尺寸和实例分割存储在字典 x 中。
x[im_file] = [l, shape, segments]
except Exception as e:
# 捕获任何异常，并增加损坏的图像或标签计数。
nc += 1
# 更新进度条描述。
print(f'{prefix}WARNING: Ignoring corrupted image and/or label {im_file}: {e}') # {prefix}警告：忽略损坏的图像和/或标签 {im_file}：{e}。
pbar.desc = f"{prefix}Scanning '{path.parent / path.stem}' images and labels... " \
f"{nf} found, {nm} missing, {ne} empty, {nc} corrupted" # {prefix}扫描'{path.parent / path.stem}' 图像和标签...已找到 {nf} 个，缺少 {nm} 个，{ne} 个，已损坏 {nc} 个。
# 关闭进度条。
pbar.close()
if nf == 0:
# 如果没有找到任何标签文件，打印警告信息。
print(f'{prefix}WARNING: No labels found in {path}. See {help_url}') # {prefix}警告：在 {path} 中未找到标签。请参阅 {help_url}。
# 计算图像文件和标签文件的哈希值，并存储在缓存中。
# def get_hash(files): -> 计算一个包含文件路径的列表的单个哈希值。返回文件列表的单个哈希值。 -> return sum(os.path.getsize(f) for f in files if os.path.isfile(f))
x['hash'] = get_hash(self.label_files + self.img_files)
# 存储扫描结果。
x['results'] = nf, nm, ne, nc, i + 1
# 存储缓存版本。
x['version'] = 0.1 # cache version 缓存版本。
# 将缓存数据保存到文件。
torch.save(x, path) # save for next time 保存以供下次使用。
# 记录新缓存创建的信息。
logging.info(f'{prefix}New cache created: {path}') # {prefix} 创建新缓存：{path}。
# 返回缓存数据。
return x
# 这个方法通过扫描图像文件和对应的标签文件，验证图像和标签的有效性，并将结果存储在缓存文件中。这可以加快后续的数据加载速度，并确保数据的一致性。
# 这段代码定义了一个名为 __len__ 的特殊方法，它是 Python 类中的一个魔术方法，用于返回对象的长度。在 LoadImagesAndLabels 类中，这个方法被用来返回数据集中图像文件的数量。
# 这是 __len__ 方法的声明，它不接受任何参数，除了 self ，即类的实例本身。
def __len__(self):
# 这行代码返回 self.img_files 列表的长度，即数据集中图像文件的数量。
return len(self.img_files)
# 当你需要知道数据集中有多少个样本时，可以调用 len(dataloader) ，其中 dataloader 是 LoadImagesAndLabels 类的实例。Python 会自动调用这个类的 __len__ 方法。
# def __iter__(self):
# self.count = -1
# print('ran dataset iter')
# #self.shuffled_vector = np.random.permutation(self.nF) if self.augment else np.arange(self.nF)
# return self
# 这段代码是 LoadImagesAndLabels 类中的 __getitem__ 方法，这个方法是 Python 数据加载器中的关键方法，用于按索引获取数据集中的单个样本。
# 这是 __getitem__ 方法的声明，它接受两个参数.
# 1.self ：类的实例本身。
# 2.index ：要获取的样本的索引。
def __getitem__(self, index):
# 这行代码根据 self.indices 列表中的索引来调整 index 。 self.indices 可以是线性索引、随机打乱的索引，或者是基于图像权重的索引。这一步是为了支持随机采样或加权采样。
index = self.indices[index] # linear, shuffled, or image_weights
# 获取数据增强的超参数。
hyp = self.hyp
# 检查是否启用马赛克数据增强。 self.mosaic 是一个布尔值，指示是否使用马赛克数据增强。
# random.random() < hyp['mosaic'] 是一个概率判断，根据 hyp 字典中 'mosaic' 键对应的值（概率）来决定是否应用马赛克数据增强。
mosaic = self.mosaic and random.random() < hyp['mosaic']
# 检查是否启用马赛克数据增强。
if mosaic:
# Load mosaic
# 以 80% 的概率选择使用 load_mosaic 函数加载马赛克图像。
if random.random() < 0.8:
# 使用 load_mosaic 函数和当前索引 index 加载马赛克图像和对应的标签。
# def load_mosaic(self, index): -> 用于以 4 幅马赛克格式加载图像。 -> return img4, labels4
img, labels = load_mosaic(self, index)
else:
# 以 20% 的概率使用 load_mosaic9 函数加载马赛克图像和对应的标签。
img, labels = load_mosaic9(self, index)
# 设置 shapes 为 None ，因为在马赛克数据增强中，原始图像的尺寸不再适用。
shapes = None
# MixUp https://arxiv.org/pdf/1710.09412.pdf
# 以 hyp 字典中 mixup 键对应的值作为概率，决定是否应用 MixUp 数据增强。
if random.random() < hyp['mixup']:
# 以 80% 的概率选择使用 load_mosaic 函数加载第二个马赛克图像。
if random.random() < 0.8:
# 使用 load_mosaic 函数和随机索引加载第二个马赛克图像和对应的标签。
img2, labels2 = load_mosaic(self, random.randint(0, len(self.labels) - 1))
else:
# 以 20% 的概率使用 load_mosaic9 函数加载第二个马赛克图像和对应的标签。
# def load_mosaic9(self, index): -> 它用于加载并组合9张图像以创建一个3x3的图像拼贴（mosaic），同时处理相应的标签和分割信息。返回处理后的图像拼贴 img9 和相应的标签 labels9 。 -> return img9, labels9
img2, labels2 = load_mosaic9(self, random.randint(0, len(self.labels) - 1))
# numpy.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 作为 MixUp 比例，这里 alpha 和 beta 参数都设置为 8.0。
r = np.random.beta(8.0, 8.0) # mixup ratio, alpha=beta=8.0
# 根据 MixUp 比例 r 将两个图像 img 和 img2 进行线性组合。
img = (img * r + img2 * (1 - r)).astype(np.uint8)
# 将两个图像的标签 labels 和 labels2 进行拼接。
labels = np.concatenate((labels, labels2), 0)
# 这段代码实现了两种数据增强技术：马赛克和 MixUp。马赛克技术通过将多个图像拼接成一个大图像来增加数据的多样性，而 MixUp 技术通过线性组合两个图像及其标签来进一步增强数据。这两种技术都有助于提高模型的泛化能力和鲁棒性。
# 未使用马赛克数据增强。
else:
# Load image 载入图片。
# 加载图像。这行代码调用 load_image 函数来加载索引 index 对应的图像，并返回图像数组 img 以及图像的原始尺寸 (h0, w0) 和加载后的尺寸 (h, w) 。
# def load_image(self, index):
# -> 负责从数据集中加载单个图像，并返回图像本身以及它的原始尺寸和调整后的尺寸。返回 加载的图像 以及它的 原始尺寸 和 调整后的尺寸 。
# -> return img, (h0, w0), img.shape[:2]
# -> return self.imgs[index], self.img_hw0[index], self.img_hw[index]
img, (h0, w0), (h, w) = load_image(self, index)
# Letterbox
# 根据是否为矩形 ( self.rect ) 来确定最终的信封调整尺寸 shape 。如果是矩形，使用 self.batch_shapes 中的尺寸；否则，使用 self.img_size 。
shape = self.batch_shapes[self.batch[index]] if self.rect else self.img_size # final letterboxed shape
# 调用 letterbox 函数对图像进行信封调整，使其适应新的尺寸 shape 。 ratio 是宽高比， pad 是添加到图像边缘的填充。
# def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# -> 用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
# -> return img, ratio, (dw, dh)
img, ratio, pad = letterbox(img, shape, auto=False, scaleup=self.augment)
# 保存原始尺寸和调整后的尺寸比例以及填充信息，这些信息可能用于后续的评估，比如 COCO mAP 重缩放。
shapes = (h0, w0), ((h / h0, w / w0), pad) # for COCO mAP rescaling
# 处理标签。
# 复制当前索引 index 对应的标签信息。
labels = self.labels[index].copy()
# 检查标签数组是否非空。
if labels.size: # normalized xywh to pixel xyxy format 将 xywh 标准化为像素 xyxy 格式。
# 如果标签数组非空，将标签中的归一化坐标 [x, y, w, h] 转换为像素坐标 [x1, y1, x2, y2] 。这里使用 ratio[0] * w 和 ratio[1] * h 来调整宽度和高度， padw 和 padh 来考虑填充的影响。
# def xywhn2xyxy(x, w=640, h=640, padw=0, padh=0):
# -> 用于将边界框的坐标从中心点和宽度/高度（即 xywh 格式）转换为左上角和右下角的坐标（即 xyxy 格式）。返回一个新的数组或张量 y ，其中包含了转换后的 xyxy 格式的边界框坐标。
# -> return y
labels[:, 1:] = xywhn2xyxy(labels[:, 1:], ratio[0] * w, ratio[1] * h, padw=pad[0], padh=pad[1])
# 这段代码处理了图像的加载和信封调整，并将标签中的归一化坐标转换为像素坐标，同时考虑了图像尺寸的变化和边缘填充的影响。这些步骤对于确保模型输入的一致性和标签的准确性至关重要。通过这种方式，可以提高模型训练的效率和效果。
# 这段代码是在一个图像增强的上下文中，用于对图像和对应的标签进行一系列的数据增强操作。这些操作旨在模拟训练数据中的变化，以提高模型的泛化能力。
# 检查是否进行增强。如果类的实例 self 有一个 augment 属性且为真，则执行数据增强操作。
if self.augment:
# Augment imagespace 增强图像空间。
# 图像空间增强。
# 如果当前不是在进行图像拼贴（mosaic）增强，则对图像进行随机透视变换。
if not mosaic:
# 调用 random_perspective 函数，传入 图像 img 和 标签 labels ，以及从 hyp 字典中获取的增强参数（如旋转角度、平移比例、缩放比例、剪切强度和透视强度）。
# def random_perspective(img, targets=(), segments=(), degrees=10, translate=.1, scale=.1, shear=10, perspective=0.0, border=(0, 0)):
# -> 它通过对图像和目标边界框应用随机的几何变换来增强数据。函数返回 变换后的图像 img 和 更新后的目标边界框 targets 。
# -> return img, targets
img, labels = random_perspective(img, labels,
degrees=hyp['degrees'],
translate=hyp['translate'],
scale=hyp['scale'],
shear=hyp['shear'],
perspective=hyp['perspective'])
#img, labels = self.albumentations(img, labels)
# Augment colorspace 增强色彩空间。
# 颜色空间增强。
# 对图像 img 应用 HSV（色调、饱和度、亮度）颜色空间增强，参数从 hyp 字典中获取。
# def augment_hsv(img, hgain=0.5, sgain=0.5, vgain=0.5): -> 它用于对图像进行HSV颜色空间的增强。
augment_hsv(img, hgain=hyp['hsv_h'], sgain=hyp['hsv_s'], vgain=hyp['hsv_v'])
# Apply cutouts 应用剪切。
# 应用 cutouts。
# 注释掉的代码，如果随机数小于0.9，则对图像和标签应用 cutout 增强。
# if random.random() < 0.9:
# 调用 cutout 函数，对图像 img 和标签 labels 应用 cutout 增强。
# def cutout(image, labels):
# -> 它实现了图像切割增强（cutout augmentation），这是一种数据增强技术，通过在训练过程中随机遮盖图像的一部分来提高模型的鲁棒性。返回处理后的标签 labels 。
# -> return labels
# labels = cutout(img, labels)
# 粘贴增强。
# 如果随机数小于 hyp 字典中定义的 paste_in 概率，则执行粘贴增强。
if random.random() < hyp['paste_in']:
# 初始化用于粘贴的 样本标签 、 图像 和 掩码列表 。
sample_labels, sample_images, sample_masks = [], [], []
# 循环直到收集到30个样本标签。
while len(sample_labels) < 30:
# 调用 load_samples 函数，随机加载样本。
# def load_samples(self, index): -> 用于创建 4-mosaic 数据增强的函数。返回处理后的 标签 、 图像 和 掩码 。 -> return sample_labels, sample_images, sample_masks
sample_labels_, sample_images_, sample_masks_ = load_samples(self, random.randint(0, len(self.labels) - 1))
sample_labels += sample_labels_
sample_images += sample_images_
sample_masks += sample_masks_
#print(len(sample_labels))
if len(sample_labels) == 0:
break
# 调用 pastein 函数，将加载的样本粘贴到当前图像 img 上，并更新标签 labels 。
# def pastein(image, labels, sample_labels, sample_images, sample_masks):
# -> 这个函数的目的是将从其他图像中采样的对象（由 sample_images 和 sample_masks 表示）粘贴到当前处理的图像上，从而模拟对象被遮挡的情况。返回更新后的标签。
# -> return labels
labels = pastein(img, labels, sample_labels, sample_images, sample_masks)
# 这段代码通过多种数据增强技术来增加训练数据的多样性，包括随机透视变换、HSV颜色空间增强和粘贴增强。这些技术有助于模型学习到在不同视角、光照和遮挡条件下的目标特征，从而提高模型的鲁棒性和泛化能力。
# 通过随机选择增强操作和参数，可以模拟真实世界中的复杂变化，使模型更加健壮。
# 获取标签的数量，即图像中对象的数量。
nL = len(labels) # number of labels
# 检查是否有标签存在。
if nL:
# 如果存在标签，将边界框的坐标从 xyxy 格式（左上角和右下角的坐标）转换为 xywh 格式（中心点坐标和宽高）。
# def xyxy2xywh(x): -> 它用于将边界框的坐标从 xyxy 格式（即左上角和右下角的坐标）转换为 xywh 格式（即中心点坐标加上宽度和高度）。返回结果。返回转换后的 xywh 格式的边界框坐标。 -> return y
labels[:, 1:5] = xyxy2xywh(labels[:, 1:5]) # convert xyxy to xywh
# 将边界框的高（y2）归一化到 0-1 范围内，这是通过将高度除以图像的高度来实现的。
labels[:, [2, 4]] /= img.shape[0] # normalized height 0-1
# 将边界框的宽（x2）归一化到 0-1 范围内，这是通过将宽度除以图像的宽度来实现的。
labels[:, [1, 3]] /= img.shape[1] # normalized width 0-1
# 检查是否需要进行数据增强。
if self.augment:
# flip up-down
# 以一定的概率进行上下翻转（up-down flip）。
if random.random() < hyp['flipud']:
# 执行上下翻转操作。
img = np.flipud(img)
if nL:
# 更新边界框的 y 坐标，以适应翻转后的图像。
labels[:, 2] = 1 - labels[:, 2]
# flip left-right
# 以一定的概率进行左右翻转（left-right flip）。
if random.random() < hyp['fliplr']:
# numpy.fliplr(m)
# np.fliplr 是 NumPy 库中的一个函数，用于将数组中的列（在二维数组中）或者最后一个维度（在多维数组中）进行左右翻转。这个函数主要应用于图像处理中，用于实现图像的水平翻转。
# 参数说明 ：
# m ：输入的数组，可以是二维数组（如图像）或者多维数组。
# 返回值 ：
# 返回一个新的数组，其中输入数组的列（或最后一个维度）被左右翻转。
# 执行左右翻转操作。
img = np.fliplr(img)
if nL:
# 更新边界框的 x 坐标，以适应翻转后的图像。
labels[:, 1] = 1 - labels[:, 1]
# 创建一个新的 PyTorch 张量，用于存储处理后的标签。
labels_out = torch.zeros((nL, 6))
if nL:
# 将 NumPy 数组格式的标签转换为 PyTorch 张量，并存储在 labels_out 中。
labels_out[:, 1:] = torch.from_numpy(labels)
# Convert
# 将图像从 BGR 格式转换为 RGB 格式，并调整维度为 3x416x416。
img = img[:, :, ::-1].transpose(2, 0, 1) # BGR to RGB, to 3x416x416
# 确保图像数据在内存中是连续的，这对于某些深度学习框架的性能至关重要。
img = np.ascontiguousarray(img)
# 返回处理后的图像（转换为 PyTorch 张量）、标签、图像文件名和原始图像的形状。
return torch.from_numpy(img), labels_out, self.img_files[index], shapes
# 这段代码定义了一个名为 collate_fn 的静态方法，它通常用在 PyTorch 的 DataLoader 中，用于将一个批次的数据（由多个样本组成）汇总和整理成适合模型训练的格式。这个方法在进行数据加载和批处理时非常有用，尤其是在处理图像数据和对应的标签时。
# 这是一个装饰器，表示 collate_fn 是一个静态方法，不需要访问类的属性或方法。
@staticmethod
# 1.batch ：是一个列表，包含了一个批次中的所有样本。
def collate_fn(batch):
# 这行代码将 batch 中的样本进行解包和转置。 zip(*batch) 将 batch 中的样本按照相同的位置的元素分组，即所有样本的 图像 、 标签 、 路径 和 形状 分别组成四个列表。 img 、 label 、 path 和 shapes 分别是这些列表。
img, label, path, shapes = zip(*batch) # transposed 转置。
# 遍历 label 列表， i 是索引， l 是当前的标签。
for i, l in enumerate(label):
# 在每个标签数组的第一列（索引为 0）上设置当前样本的索引。这样做是为了在训练时能够区分不同样本的目标。
# 在目标检测任务中，标签数组 l 通常包含了关于目标的信息，如类别标签和边界框坐标。对于边界框，常见的表示方式是 xyxy 格式，即 [x1, y1, x2, y2] ，其中 (x1, y1) 是边界框左上角的坐标， (x2, y2) 是右下角的坐标。
# 在这段代码中， l[:, 0] 指的是标签数组 l 的第一列。这行代码 l[:, 0] = i 将这一列的所有值设置为当前样本的索引 i 。这意味着在原始的标签数组 l 中，第一列原本并不包含样本索引，而是在执行这行代码后被赋予了这个值。
# 因此， l 原本第一列的值是未定义的，或者它可能包含其他信息，但在执行 l[:, 0] = i 这行代码后，它被替换为当前样本的索引。这种操作通常用于在训练过程中跟踪每个目标属于哪个样本，特别是在处理多个目标时。
l[:, 0] = i # add target image index for build_targets() 为 build_targets() 添加目标图像索引。
# 返回处理后的数据。
# torch.stack(img, 0) ：将 img 列表中的所有图像堆叠成一个新维度（批次维度），即从 [3, H, W] 变为 [B, 3, H, W] ，其中 B 是批次大小。
# torch.cat(label, 0) ：将 label 列表中的所有标签连接起来，形成一个新的标签张量，增加了批次维度。
# path 和 shapes ：这两个列表不需要改变形状，直接返回即可。
return torch.stack(img, 0), torch.cat(label, 0), path, shapes
# 这个方法的目的是将一个批次中的多个样本（图像和标签）整理成一个适合模型训练的格式，包括堆叠图像和连接标签，同时保持路径和形状信息不变。这样处理后的数据可以直接用于模型的训练过程。
# 这段代码定义了一个名为 collate_fn4 的静态方法，它是一个自定义的批处理函数，用于在 PyTorch 的 DataLoader 中处理数据。这个方法特别设计用于处理四倍的图像数据，可能是为了实现一种特定的数据增强技术，如马赛克（4-mosaic）增强。
# @staticmethod ：表示这是一个静态方法，不依赖于类的实例。
@staticmethod
# 定义了 collate_fn4 方法，它接受一个参数。
# batch ：是一个列表，包含了一个批次中的所有样本。
def collate_fn4(batch):
# 将 batch 中的样本进行解包和转置，分别得到 图像 、 标签 、 路径 和 形状 的列表。
img, label, path, shapes = zip(*batch) # transposed 转置。
# 计算批次中每组四张图像的数量。
n = len(shapes) // 4
# 初始化空列表来存储处理后的图像和标签，以及原始路径和形状的切片。
img4, label4, path4, shapes4 = [], [], path[:n], shapes[:n]
# ho 和 wo ：定义了两个张量，分别代表 水平 和 垂直 偏移量。
ho = torch.tensor([[0., 0, 0, 1, 0, 0]])
wo = torch.tensor([[0., 0, 1, 0, 0, 0]])
# 定义了一个缩放因子张量。
s = torch.tensor([[1, 1, .5, .5, .5, .5]]) # scale
# 遍历每组四张图像。
for i in range(n): # zidane torch.zeros(16,3,720,1280) # BCHW
# 计算当前组的起始索引。
i *= 4
# 以 50% 的概率决定是进行双线性插值放大单张图像，还是将四张图像拼接在一起。
if random.random() < 0.5:
# 对单张图像进行双线性插值放大。
im = F.interpolate(img[i].unsqueeze(0).float(), scale_factor=2., mode='bilinear', align_corners=False)[
0].type(img[i].type())
# 获取对应的标签。
l = label[i]
else:
# 将四张图像水平和垂直拼接在一起。
im = torch.cat((torch.cat((img[i], img[i + 1]), 1), torch.cat((img[i + 2], img[i + 3]), 1)), 2)
# 将四张图像的标签合并，并应用偏移和缩放。
l = torch.cat((label[i], label[i + 1] + ho, label[i + 2] + wo, label[i + 3] + ho + wo), 0) * s
# 将处理后的图像和标签添加到列表中。
img4.append(im)
label4.append(l)
# 遍历 label4 列表，为每个标签添加目标图像索引。
for i, l in enumerate(label4):
# 将每个标签的第一列设置为当前样本的索引。
l[:, 0] = i # add target image index for build_targets()
# 返回处理后的 图像张量 、 标签张量 、 路径 和 形状 。
return torch.stack(img4, 0), torch.cat(label4, 0), path4, shapes4
# 这个方法通过随机选择是放大单张图像还是拼接四张图像，以及应用偏移和缩放，来增加数据的多样性和复杂性。这种技术可以帮助模型更好地泛化，尤其是在目标检测任务中。
# 在上述代码中， l 表示的是一组标签，它们对应于一个或多个图像中的目标对象。在 l[:, 0] = i 这行代码执行之前， l 中的第一列（即索引为 0 的列）的值通常是以下两种情况之一 :
# 1. 对于单张图像的标签：如果代码选择了单张图像进行双线性插值放大（当 random.random() < 0.5 ），那么 l 就是直接从原始标签 label[i] 获取的，这意味着在设置前 l 中的第一列可能包含的是类别标签或者是未初始化的值（如果原始标签没有这一列）。
# 2. 对于拼接图像的标签：如果代码选择了将四张图像拼接在一起（当 random.random() >= 0.5 ），那么 l 是通过合并四张图像的标签并应用偏移和缩放得到的。
# 具体来说， label[i] 是原始标签， label[i + 1] + ho 和 label[i + 2] + wo 分别是向右和向下偏移的标签， label[i + 3] + ho + wo 是同时向右和向下偏移的标签。在这个过程中， l 的第一列在合并前可能是类别标签或者是其他用于区分不同目标的标识。
# 在这两种情况下， l[:, 0] = i 这行代码的作用是为每个目标对象的标签添加一个额外的维度，即它们所属的样本（图像）的索引。
# 这样做的目的是为了在训练过程中能够区分不同样本中的目标对象，特别是在一个批次中有多个样本时。这个索引通常用于在损失函数中正确地将目标分配给它们对应的预测结果。11.def load_image(self, index):
# Ancillary functions 辅助功能 --------------------------------------------------------------------------------------------------
# 这段代码定义了一个名为 load_image 的函数，它是 LoadImagesAndLabels 类的一个方法。该函数负责从数据集中加载单个图像，并返回图像本身以及它的原始尺寸和调整后的尺寸。
# 函数参数 ：
# 1.self ：类的实例本身。
# 2.index ：要加载的图像在数据集中的索引。
def load_image(self, index):
# 从数据集加载 1 幅图像，返回 img 、 原始 hw 、 调整大小的 hw 。
# loads 1 image from dataset, returns img, original hw, resized hw
# 尝试从 self.imgs 列表中获取索引为 index 的图像数据。如果图像已经被缓存，则直接使用缓存的图像。
img = self.imgs[index]
# 如果图像数据为 None ，则表示图像尚未被缓存，需要从文件中加载。
if img is None: # not cached 未缓存。
# 获取图像文件的路径。
path = self.img_files[index]
# 使用 OpenCV 的 imread 函数读取图像文件。图像以 BGR 格式加载。
img = cv2.imread(path) # BGR
# 确保图像文件被成功加载，如果图像为 None ，则抛出异常。
assert img is not None, 'Image Not Found ' + path
# 获取原始图像的高度和宽度。
h0, w0 = img.shape[:2] # orig hw # 原始宽高。
# 计算缩放比例 r ，使得图像的最大维度等于 self.img_size 。
r = self.img_size / max(h0, w0) # resize image to img_size 将图像大小调整为 img_size。
# 如果缩放比例不等于 1，即需要调整图像大小。
if r != 1: # always resize down, only resize up if training with augmentation 始终缩小，只有使用增强训练时才放大。
# 选择插值方法。如果缩放比例小于 1 且不在数据增强阶段，则使用 cv2.INTER_AREA ；否则使用 cv2.INTER_LINEAR 。
interp = cv2.INTER_AREA if r < 1 and not self.augment else cv2.INTER_LINEAR
# 使用 OpenCV 的 resize 函数调整图像大小。
img = cv2.resize(img, (int(w0 * r), int(h0 * r)), interpolation=interp)
# 返回 加载的图像 以及它的 原始尺寸 和 调整后的尺寸 。
return img, (h0, w0), img.shape[:2] # img, hw_original, hw_resized
# 如果图像已经被缓存，则直接从缓存中返回图像和对应的尺寸。
else:
# 如果图像已经被缓存，则直接从缓存中返回图像和对应的尺寸
return self.imgs[index], self.img_hw0[index], self.img_hw[index] # img, hw_original, hw_resized
# load_image 函数是数据加载过程中的关键部分，它负责将图像从磁盘加载到内存中，并根据需要调整图像大小。这个函数还处理了图像的缓存，如果图像已经被加载到内存中，则直接从内存中获取，这样可以减少 I/O 操作，提高数据加载的效率。
12.def augment_hsv(img, hgain=0.5, sgain=0.5, vgain=0.5):
# 这段代码定义了一个名为 augment_hsv 的函数，它用于对图像进行HSV颜色空间的增强。这种增强通过随机调整图像的色调（Hue）、饱和度（Saturation）和亮度（Value）来实现，可以使模型训练更加鲁棒。
# 1.img ：输入的BGR格式图像。
# 2.hgain 、 3.sgain 、 4.vgain ： 色调 、 饱和度 和 亮度 的随机变化范围，默认分别为0.5。这些值表示相对于原始色调、饱和度和亮度的变化比例。
def augment_hsv(img, hgain=0.5, sgain=0.5, vgain=0.5):
# 生成随机增益。为 色调 、 饱和度 和 亮度 生成随机增益值，这些值在 [-hgain, hgain] 、 [-sgain, sgain] 和 [-vgain, vgain] 范围内。
r = np.random.uniform(-1, 1, 3) * [hgain, sgain, vgain] + 1 # random gains 随机增益。
# cv2.split(src)
# cv2.split 是 OpenCV 库中的一个函数，用于将多通道图像分割成单独的通道。这个函数通常与 cv2.merge 函数一起使用， cv2.merge 用于将多个单通道图像合并成一个多通道图像。
# 参数 ：
# src ：输入的多通道图像。这个图像可以是8位的（ uint8 ），16位的（ uint16 ），32位浮点的（ float32 ）等。
# 返回值 ：
# 返回一个元组，其中包含输入图像的每个通道作为单独的单通道图像。例如，如果输入图像是一个BGR三通道图像， cv2.split 将返回三个单通道图像，分别对应B、G和R通道。
# 分离HSV通道。将图像从BGR颜色空间转换为HSV颜色空间，并分离出色调、饱和度和亮度通道。
hue, sat, val = cv2.split(cv2.cvtColor(img, cv2.COLOR_BGR2HSV))
dtype = img.dtype # uint8
# 创建查找表（LUT）。
x = np.arange(0, 256, dtype=np.int16)
# 为色调创建查找表，应用随机增益并确保值在0到180之间。
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)
# cv2.merge(mtx)
# cv2.merge 是 OpenCV 库中的一个函数，用于将多个单通道图像合并成一个多通道图像。这个函数与 cv2.split 相对应， cv2.split 用于将多通道图像分割成单独的通道。
# 参数 ：
# mtx ：一个元组或者列表，其中包含了一个或多个单通道图像。这些图像必须具有相同的尺寸和数据类型。
# 返回值 ：
# 返回一个多通道图像，其中每个通道来自输入的单通道图像。
# cv2.merge 函数常用于处理图像的颜色空间转换（例如，从 HSV 转换回 BGR），或者在对图像的每个通道进行单独处理后重新组合它们。
# 应用查找表。使用查找表调整HSV通道的值，并将结果合并回一个HSV图像。
img_hsv = cv2.merge((cv2.LUT(hue, lut_hue), cv2.LUT(sat, lut_sat), cv2.LUT(val, lut_val))).astype(dtype)
# 转换回BGR颜色空间。将增强后的HSV图像转换回BGR颜色空间，并直接存储在输入图像 img 中。
cv2.cvtColor(img_hsv, cv2.COLOR_HSV2BGR, dst=img) # no return needed 无需返回值。
# augment_hsv 函数通过对图像的HSV通道进行随机调整，实现了颜色空间的增强。这种增强可以帮助模型更好地学习和适应不同的光照和颜色条件，提高模型在实际应用中的泛化能力。通过这种方式，可以模拟在不同环境下拍摄的图像，使模型训练更加全面。13.def hist_equalize(img, clahe=True, bgr=False):
# 这段代码定义了一个名为 hist_equalize 的函数，它用于对图像进行直方图均衡化处理，以改善图像的对比度。直方图均衡化是一种图像处理技术，用于增强图像中暗淡区域的细节。
# 1.img ：输入的图像，是一个具有形状 (n, m, 3) 的 BGR 或 RGB 图像数组，其中 n 和 m 分别是图像的高度和宽度，3 表示颜色通道。
# 2.clahe ：一个布尔值，表示是否使用对比度受限的自适应直方图均衡化（CLAHE），默认为 True 。
# 3.bgr ：一个布尔值，表示输入图像的颜色空间是 BGR 还是 RGB，默认为 False ，即假设图像是 RGB 格式。
def hist_equalize(img, clahe=True, bgr=False):
# 使用 img.shape(n,m,3) 和范围 0-255 均衡 BGR 图像“img”上的直方图
# Equalize histogram on BGR image 'img' with img.shape(n,m,3) and range 0-255
# 将输入图像从 BGR 或 RGB 颜色空间转换为 YUV 颜色空间。YUV 颜色空间将亮度信息（Y 通道）与色彩信息（U 和 V 通道）分开，这使得对亮度进行直方图均衡化处理更为方便。
yuv = cv2.cvtColor(img, cv2.COLOR_BGR2YUV if bgr else cv2.COLOR_RGB2YUV)
# 如果 clahe 为 True ，则使用 CLAHE 。
if clahe:
# 创建一个 CLAHE 对象， clipLimit 参数控制裁剪限制， tileGridSize 参数定义了用于计算直方图的区域大小。
c = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
# 对 Y 通道（亮度通道）应用 CLAHE。
yuv[:, :, 0] = c.apply(yuv[:, :, 0])
# 如果 clahe 为 False ，则使用标准的直方图均衡化。
else:
# 对 Y 通道应用直方图均衡化。
yuv[:, :, 0] = cv2.equalizeHist(yuv[:, :, 0]) # equalize Y channel histogram 均衡 Y 通道直方图。
# 将经过直方图均衡化处理的 YUV 图像转换回 BGR 或 RGB 颜色空间，并返回结果。
return cv2.cvtColor(yuv, cv2.COLOR_YUV2BGR if bgr else cv2.COLOR_YUV2RGB) # convert YUV image to RGB 将 YUV 图像转换为 RGB。
# 这个函数提供了两种直方图均衡化方法：标准的直方图均衡化和对比度受限的自适应直方图均衡化（CLAHE）。
# CLAHE 是一种改进的直方图均衡化方法，它在小区域内独立地进行直方图均衡化，可以更好地处理具有不均匀光照的图像。
# 函数允许用户根据需要选择使用哪种方法，并处理 BGR 或 RGB 格式的图像。14.def load_mosaic(self, index):
# 这段代码定义了一个名为 load_mosaic 的函数，它是 LoadImagesAndLabels 类的一个方法，用于以 4 幅马赛克格式加载图像。这种方法是一种数据增强技术，通过将四张图像拼接成一个大图像来增加数据集的多样性。
# 函数参数。
# 1.self ：类的实例本身。
# 2.index ：要加载的图像在数据集中的索引。
def load_mosaic(self, index):
# 以 4 幅马赛克格式加载图像。
# loads images in a 4-mosaic
# 初始化两个空列表，用于存储四张图像的标签和分割数据。
labels4, segments4 = [], []
# 获取图像的目标尺寸。
s = self.img_size
# random.uniform(a, b)
# random.uniform 是 Python 标准库 random 模块中的一个函数，用于生成一个指定范围内的随机浮点数。
# a ：范围的下限，函数生成的随机数将大于或等于 a 。
# b ：范围的上限，函数生成的随机数将小于或等于 b 。
# 返回值 ：
# 返回一个随机浮点数 n ，满足 a <= n <= b 。
# 功能 ：
# random.uniform 函数从半开区间 [a, b] 中均匀地生成一个随机浮点数。这意味着区间 [a, b] 内的所有浮点数被选中的概率是相等的。
# 随机生成马赛克图像的中心坐标 xc 和 yc 。
# self.mosaic_border ： 这是一个包含两个值的列表，表示马赛克图像中心的边界。通常，这些值用于确定马赛克图像中心的随机偏移范围。
# random.uniform(a, b) 函数生成一个在区间 [a, b] 内的随机浮点数。
# -x 是区间的下限， 2 * s + x 是区间的上限，其中 s 是图像的尺寸（通常是图像的高度或宽度）。
# int(...) ： 将 random.uniform 生成的随机浮点数转换为整数。这是因为图像坐标通常是整数。
# for x in self.mosaic_border ： 列表推导式遍历 self.mosaic_border 中的每个值 x ，并为每个值生成一个随机数。
# yc, xc = [...] ： 将列表推导式的结果分别赋值给 yc 和 xc ，它们分别表示马赛克图像中心的 y 坐标和 x 坐标。
yc, xc = [int(random.uniform(-x, 2 * s + x)) for x in self.mosaic_border] # mosaic center x, y
# random.choices(population, weights=None, cum_weights=None, k=1)
# random.choices 是 Python 标准库 random 模块中的一个函数，它用于从给定的序列中随机选择元素，可以有放回地选择多次，也可以指定每个元素被选择的概率。
# population ：一个序列，表示可供选择的元素集合。
# weights ：（可选）一个与 population 中元素数量相同的序列，表示每个元素被选择的相对概率。
# cum_weights ：（可选）一个与 population 中元素数量相同的序列，表示累积概率。这在创建加权随机选择时非常有用，其中每个元素的选择概率取决于前面所有元素的累积概率。
# k ：（可选）一个整数，表示需要选择的元素数量。
# 返回值 ：
# 返回一个列表，包含从 population 中随机选择的 k 个元素。
# 功能 ：
# random.choices 函数允许你从 population 中选择多个元素，可以是有放回的选择。如果提供了 weights 或 cum_weights ，则选择会根据这些权重进行加权，使得某些元素有更高的概率被选中。
# 注意事项 ：
# 如果同时提供了 weights 和 cum_weights ， random.choices 将使用 weights 而忽略 cum_weights 。
# k 的值可以大于 population 的长度，这意味着可能会选择重复的元素。
# 如果没有提供 weights 或 cum_weights ，则所有元素被选择的概率相等。
# 生成四个图像索引，包括传入的 index 和三个随机索引。
indices = [index] + random.choices(self.indices, k=3) # 3 additional image indices
# 遍历四个图像索引。
for i, index in enumerate(indices):
# Load image
# 使用 load_image 函数加载当前索引的图像和尺寸。
# def load_image(self, index):
# -> 负责从数据集中加载单个图像，并返回图像本身以及它的原始尺寸和调整后的尺寸。返回 加载的图像 以及它的 原始尺寸 和 调整后的尺寸 。
# -> return img, (h0, w0), img.shape[:2]
# -> return self.imgs[index], self.img_hw0[index], self.img_hw[index]
img, _, (h, w) = load_image(self, index)
# place img in img4
# 根据图像索引 i 的值，计算四张图像在马赛克大图中的位置，并将其放置在正确的位置。
# 这段代码是 load_mosaic 函数的一部分，它负责将四张图像（tiles）放置到一个 2x2 的马赛克布局中。每个 elif 块处理一个特定的位置，即左上、右上、左下和右下。
if i == 0: # top left
# 创建一个填充值为 114（通常是背景色）的空白图像 img4 ，大小为 s * 2 x s * 2 ，通道数与 img 相同。
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 的正确位置。
img4[y1a:y2a, x1a:x2a] = img[y1b:y2b, x1b:x2b] # img4[ymin:ymax, xmin:xmax]
# 计算当前图像的左右和上下填充。
padw = x1a - x1b
padh = y1a - y1b
# Labels
# 获取当前图像的标签和分割数据。
labels, segments = self.labels[index].copy(), self.segments[index].copy()
# 这个条件判断检查 labels 数组是否不为空。
if labels.size:
# 对于 labels 数组中的每一行（表示一个边界框），除了第一个元素（通常是类别标签），其余元素（边界框的 x, y, w, h ）被转换为 xyxy 格式。
# xywhn2xyxy 函数接受归一化的 x, y, w, h 坐标，并根据图像的 宽度 w 、 高度 h 以及 左右填充 padw 、 上下填充 padh 转换为像素坐标。
# def xywhn2xyxy(x, w=640, h=640, padw=0, padh=0):
# -> 用于将边界框的坐标从中心点和宽度/高度（即 xywh 格式）转换为左上角和右下角的坐标（即 xyxy 格式）。返回一个新的数组或张量 y ，其中包含了转换后的 xyxy 格式的边界框坐标。
# -> return y
labels[:, 1:] = xywhn2xyxy(labels[:, 1:], w, h, padw, padh) # normalized xywh to pixel xyxy format
# 这个列表推导式遍历 segments 列表中的每个元素 x ，这些元素可能表示分割掩码或与分割相关的坐标。
# xyn2xy 函数接受分割掩码的坐标，并将其从归一化形式转换为像素坐标，同时考虑图像的 宽度 w 、 高度 h 以及 填充 padw 和 padh 。
# def xyn2xy(x, w=640, h=640, padw=0, padh=0): -> 用于将归一化的分割掩码坐标转换为像素坐标。返回一个新的数组或张量 y ，其中包含了转换后的像素坐标。 -> return y
segments = [xyn2xy(x, w, h, padw, padh) for x in segments]
# 将当前图像的标签和分割数据添加到列表中。
labels4.append(labels)
segments4.extend(segments)
# Concat/clip labels
# 将四张图像的标签拼接成一个大的标签数组。
labels4 = np.concatenate(labels4, 0)
# 将标签和分割数据中的坐标限制在马赛克大图的范围内。
for x in (labels4[:, 1:], *segments4):
np.clip(x, 0, 2 * s, out=x) # clip when using random_perspective()
# img4, labels4 = replicate(img4, labels4) # replicate
# Augment
#img4, labels4, segments4 = remove_background(img4, labels4, segments4)
#sample_segments(img4, labels4, segments4, probability=self.hyp['copy_paste'])
# 应用复制粘贴数据增强。
# 这行代码调用了一个名为 copy_paste 的函数，这个函数是一个自定义的数据增强方法，用于在图像 img4 上执行复制粘贴类型的增强。这种类型的增强通过在图像中复制一部分内容并粘贴到另一部分来增加数据的多样性，有助于提高模型的泛化能力。
# 函数参数。
# img4 ：当前处理的图像，可能是一个已经通过马赛克或其他方法增强过的图像。
# labels4 ：与 img4 对应的边界框标签。
# segments4 ：与 img4 对应的分割数据。
# probability ：执行复制粘贴增强的概率，这个值从 self.hyp 字典中获取，其中 self.hyp 是一个存储超参数的字典， 'copy_paste' 是与复制粘贴增强相关的概率值。
# 复制粘贴增强可能会改变图像的某些属性，例如亮度和颜色，因此可能需要额外的步骤来确保增强后的图像与原始图像在这些属性上保持一致。
# def copy_paste(img, labels, segments, probability=0.5):
# -> 它实现了一种称为 Copy-Paste 数据增强的方法，用于实例分割任务。返回增强后的图像 img ，更新后的标签 labels 和分割掩码 segments 。
# -> return img, labels, segments
img4, labels4, segments4 = copy_paste(img4, labels4, segments4, probability=self.hyp['copy_paste'])
# 应用随机透视变换数据增强。 random_perspective 函数是一个数据增强技术，它通过随机应用一系列几何变换来增加数据集的多样性，这有助于模型学习到更加鲁棒的特征。
# img4 : 这是待增强的图像。
# labels4 : 这是与 img4 对应的标签，包含了图像中目标的类别和位置信息。
# segments4 : 这个参数可能用于分割任务，包含了图像中分割目标的相关信息。
# degrees : 这是随机旋转的度数范围，用于控制图像旋转的程度。
# translate : 这是随机平移的程度，用于在x和y方向上移动图像。
# scale : 这是随机缩放的程度，用于改变图像的大小。
# shear : 这是随机剪切的程度，用于在x或y方向上扭曲图像。
# perspective : 这是随机透视变换的程度，用于模拟从不同视角观察图像的效果。
# border : 这是在应用透视变换时需要移除的图像边界，以避免透视变换导致的目标信息丢失。
# def random_perspective(img, targets=(), segments=(), degrees=10, translate=.1, scale=.1, shear=10, perspective=0.0, border=(0, 0)):
# -> 它通过对图像和目标边界框应用随机的几何变换来增强数据。函数返回 变换后的图像 img 和 更新后的目标边界框 targets 。
# -> return img, targets
img4, labels4 = random_perspective(img4, labels4, segments4,
degrees=self.hyp['degrees'],
translate=self.hyp['translate'],
scale=self.hyp['scale'],
shear=self.hyp['shear'],
perspective=self.hyp['perspective'],
border=self.mosaic_border) # border to remove
# 返回处理后的图像拼贴 img4 和相应的标签 labels4 。
return img4, labels4
# load_mosaic 函数通过将四张图像拼接成一个大图像来实现马赛克数据增强，同时处理标签和分割数据的转换和拼接。这种数据增强技术有助于提高模型的泛化能力和鲁棒性。15.def load_mosaic9(self, index):
# 这段代码定义了一个名为 load_mosaic9 的函数，它用于加载并组合9张图像以创建一个3x3的图像拼贴（mosaic），同时处理相应的标签和分割信息。这种技术通常用于数据增强，以模拟从不同视角和条件下观察目标的效果。
# 1.self ：类的实例。
# 2.index ：中心图像的索引。
def load_mosaic9(self, index):
# loads images in a 9-mosaic
# 初始化变量。
# abels9 和 segments9 ：用于存储所有9张图像的标签和分割信息。
labels9, segments9 = [], []
# s ：图像的尺寸。
s = self.img_size
# indices ：包含中心图像索引和8个额外图像索引的列表。
indices = [index] + random.choices(self.indices, k=8) # 8 additional image indices
# 加载和处理每张图像。
# 遍历 indices 中的每个索引，加载图像，并将其放置在 img9 的相应位置。
for i, index in enumerate(indices):
# Load image
img, _, (h, w) = load_image(self, index)
# place img in img9
# 计算每张图像在 img9 中的坐标 c 。
if i == 0: # center
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
# 调整标签和分割信息，将归一化的坐标转换为像素坐标。
padx, pady = c[:2]
x1, y1, x2, y2 = [max(x, 0) for x in c] # allocate coords 分配坐标。
# Labels
# 处理标签和分割。
# 对于每张图像的标签，将其从归一化坐标转换为像素坐标，并调整分割信息。
labels, segments = self.labels[index].copy(), self.segments[index].copy()
if labels.size:
labels[:, 1:] = xywhn2xyxy(labels[:, 1:], w, h, padx, pady) # normalized xywh to pixel xyxy format 将 xywh 标准化为像素 xyxy 格式。
segments = [xyn2xy(x, w, h, padx, pady) for x in segments]
labels9.append(labels)
segments9.extend(segments)
# Image
# 创建图像拼贴。
# 将每张图像放置在 img9 的相应位置。
img9[y1:y2, x1:x2] = img[y1 - pady:, x1 - padx:] # img9[ymin:ymax, xmin:xmax]
hp, wp = h, w # height, width previous
# Offset
# 随机选择图像拼贴的中心 yc 和 xc 。
yc, xc = [int(random.uniform(0, s)) for _ in self.mosaic_border] # mosaic center x, y
img9 = img9[yc:yc + 2 * s, xc:xc + 2 * s]
# Concat/clip labels
# 调整标签和分割信息。
# 将所有标签合并，并调整其坐标以反映图像拼贴的中心。
labels9 = np.concatenate(labels9, 0)
labels9[:, [1, 3]] -= xc
labels9[:, [2, 4]] -= yc
# 调整分割信息，使其相对于图像拼贴的中心。
c = np.array([xc, yc]) # centers
segments9 = [x - c for x in segments9]
# 裁剪和复制。
# 对标签和分割信息进行裁剪，确保它们在图像拼贴的范围内。
for x in (labels9[:, 1:], *segments9):
np.clip(x, 0, 2 * s, out=x) # clip when using random_perspective()
# 可能的复制粘贴增强（注释掉的代码）。
# img9, labels9 = replicate(img9, labels9) # replicate
# Augment
# 应用透视变换。
# 对图像拼贴和标签应用随机透视变换。
#img9, labels9, segments9 = remove_background(img9, labels9, segments9)
img9, labels9, segments9 = copy_paste(img9, labels9, segments9, probability=self.hyp['copy_paste'])
img9, labels9 = random_perspective(img9, labels9, segments9,
degrees=self.hyp['degrees'],
translate=self.hyp['translate'],
scale=self.hyp['scale'],
shear=self.hyp['shear'],
perspective=self.hyp['perspective'],
border=self.mosaic_border) # border to remove
# 返回处理后的图像拼贴 img9 和相应的标签 labels9 。
return img9, labels9
# load_mosaic9 函数通过创建一个3x3的图像拼贴来增强数据，同时确保标签和分割信息与图像内容保持一致。这种技术可以增加模型训练时的数据多样性，提高模型对不同视角和条件下目标的识别能力。16.def load_samples(self, index):
# 这段代码定义了一个名为 load_samples 的函数，用于创建 4-mosaic 数据增强的函数。4-mosaic 是一种数据增强技术，通过将四张不同的图像拼接成一个大图像来增加数据集的多样性。
def load_samples(self, index):
# 以 4 幅马赛克格式加载图像。
# loads images in a 4-mosaic
# 初始化两个空列表，用于存储四张图像的标签和分割掩码。
labels4, segments4 = [], []
# 获取模型输入图像的大小。
s = self.img_size
# 随机生成马赛克中心的 x 和 y 坐标。
yc, xc = [int(random.uniform(-x, 2 * s + x)) for x in self.mosaic_border] # mosaic center x, y
# 选择一个索引（ index ）和三个额外的索引，用于创建 4-mosaic。
indices = [index] + random.choices(self.indices, k=3) # 3 additional image indices 3 个附加图像索引。
# 遍历索引列表，包括主图像和三个额外图像。
for i, index in enumerate(indices):
# Load image 载入图片。
# 加载每个索引对应的图像，并获取其高度和宽度。
# def load_image(self, index):
# -> 负责从数据集中加载单个图像，并返回图像本身以及它的原始尺寸和调整后的尺寸。返回 加载的图像 以及它的 原始尺寸 和 调整后的尺寸 。
# -> return img, (h0, w0), img.shape[:2]
# -> return self.imgs[index], self.img_hw0[index], self.img_hw[index]
img, _, (h, w) = load_image(self, index)
# place img in img4 将 img 放置在 img4 中。
# 这些条件语句处理四张图像在 2x2 马赛克布局中的放置位置。
if i == 0: # top left
# numpy.full(shape, fill_value, dtype=None, order='C')
# np.full 是 NumPy 库中的一个函数，用于创建一个指定形状和数据类型的新数组，并用给定的值填充。
# 参数说明 ：
# shape ：数组的形状。可以是一个整数（表示一维数组的长度），或者是一个元组（表示多维数组的形状）。
# fill_value ：用来填充新数组的值。
# dtype ：数组的所需数据类型。如果未指定，则通过 fill_value 推断数据类型。
# order ：数组元素的存储顺序，'C' 表示按行主序（C风格），'F' 表示按列主序（Fortran风格）。默认为 'C'。
# 返回值 ：
# 返回一个指定形状和数据类型的新数组，数组中的所有元素都被 fill_value 填充。
# 创建一个填充值为 114（通常是背景色）的 4-mosaic 基础图像。
img4 = np.full((s * 2, s * 2, img.shape[2]), 114, dtype=np.uint8) # base image with 4 tiles
# x1a, y1a, x2a, y2a 和 x1b, y1b, x2b, y2b ：计算大图像和小图像的坐标，以确定如何将小图像放置在大图像中。
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 的相应位置。
img4[y1a:y2a, x1a:x2a] = img[y1b:y2b, x1b:x2b] # img4[ymin:ymax, xmin:xmax]
# 计算图像在水平和垂直方向上的填充量。
padw = x1a - x1b
padh = y1a - y1b
# Labels
# 复制当前索引的 标签 和 分割掩码 。
labels, segments = self.labels[index].copy(), self.segments[index].copy()
if labels.size:
# 如果标签存在，将它们从归一化的 xywh 格式转换为像素的 xyxy 格式，并调整分割掩码的坐标。
# def xywhn2xyxy(x, w=640, h=640, padw=0, padh=0):
# -> 用于将边界框的坐标从中心点和宽度/高度（即 xywh 格式）转换为左上角和右下角的坐标（即 xyxy 格式）。返回一个新的数组或张量 y ，其中包含了转换后的 xyxy 格式的边界框坐标。
# -> return y
labels[:, 1:] = xywhn2xyxy(labels[:, 1:], w, h, padw, padh) # normalized xywh to pixel xyxy format
# 这个列表推导式遍历 segments 列表中的每个元素 x ，这些元素可能表示分割掩码或与分割相关的坐标。
# xyn2xy 函数接受分割掩码的坐标，并将其从归一化形式转换为像素坐标，同时考虑图像的 宽度 w 、 高度 h 以及 填充 padw 和 padh 。
# def xyn2xy(x, w=640, h=640, padw=0, padh=0): -> 用于将归一化的分割掩码坐标转换为像素坐标。返回一个新的数组或张量 y ，其中包含了转换后的像素坐标。 -> return y
segments = [xyn2xy(x, w, h, padw, padh) for x in segments]
# 将转换后的标签和分割掩码添加到列表中。
labels4.append(labels)
segments4.extend(segments)
# Concat/clip labels 连接/剪辑标签。
# 将所有标签合并为一个数组。
labels4 = np.concatenate(labels4, 0)
# 将所有标签和分割掩码的坐标限制在图像尺寸内。
for x in (labels4[:, 1:], *segments4):
np.clip(x, 0, 2 * s, out=x) # clip when using random_perspective()
# img4, labels4 = replicate(img4, labels4) # replicate
# Augment
#img4, labels4, segments4 = remove_background(img4, labels4, segments4)
# 使用 sample_segments 函数对图像和标签进行采样，以决定是否使用分割掩码。
# def sample_segments(img, labels, segments, probability=0.5):
# -> 它是实现 Copy-Paste 数据增强方法的一部分，特别是用于 实例分割任务 。这种方法通过随机选择图像中的一些对象，并将它们粘贴到其他图像上，从而生成新的训练样本。返回采样后的标签、图像和掩码。
# -> return sample_labels, sample_images, sample_masks
sample_labels, sample_images, sample_masks = sample_segments(img4, labels4, segments4, probability=0.5)
# 返回处理后的 标签 、 图像 和 掩码 。
return sample_labels, sample_images, sample_masks
# 这段代码的主要目的是通过创建 4-mosaic 图像来增强数据集，这有助于模型学习更多样化的场景和对象。通过随机选择和放置四张图像，可以生成新的训练样本，从而提高模型的泛化能力。17.def copy_paste(img, labels, segments, probability=0.5):
# 这段代码定义了一个名为 copy_paste 的函数，它实现了一种称为 Copy-Paste 数据增强的方法，用于实例分割任务。这种方法通过从一张图像中随机选择对象并将它们粘贴到另一张图像上，从而生成新的训练数据，增加数据的多样性。
# 函数参数。
# 1.img ：当前处理的图像，形状为 (高度, 宽度, 通道数)。
# 2.labels ：与 img 对应的边界框标签，形状为 (n, 5) 的 NumPy 数组，其中 n 是边界框的数量，每行包含一个边界框的类别和 xyxy 格式的坐标。
# 3.segments ：与 img 对应的分割掩码，形状为 (n, 2) 的 NumPy 数组，其中 n 是分割掩码的数量，每行包含分割掩码的坐标。
# 4.probability ：执行 Copy-Paste 增强的概率，默认为 0.5。
def copy_paste(img, labels, segments, probability=0.5):
# 实现复制粘贴增强 https://arxiv.org/abs/2012.07177，标记为 nx5 np.array(cls, xyxy)。
# Implement Copy-Paste augmentation https://arxiv.org/abs/2012.07177, labels as nx5 np.array(cls, xyxy)
# 获取分割掩码的数量。
n = len(segments)
# 如果设置了概率且有分割掩码，则执行 Copy-Paste 增强。
if probability and n:
# 获取图像的 高度 、 宽度 和 通道数 。
h, w, c = img.shape # height, width, channels
# 创建一个与 img 形状相同的空白图像，用于绘制新的分割掩码。
im_new = np.zeros(img.shape, np.uint8)
# 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 都会生成一个新的随机选择的列表，因为随机数生成器的状态在每次调用时都会改变。
# 随机选择一定比例的对象进行复制粘贴。
for j in random.sample(range(n), k=round(probability * n)):
# 获取随机选择的对象的标签和分割掩码。
l, s = labels[j], segments[j]
# 计算要粘贴的对象的边界框坐标。
box = w - l[3], l[2], w - l[1], l[4]
# 计算新粘贴的对象与现有对象之间的交并比（Intersection over Area, IoA）。
# def bbox_ioa(box1, box2): -> 用于计算一个边界框（ box1 ）与一组边界框（ box2 ）之间的交并比（Intersection over Area, IoA）。返回 IoA 值，表示 box1 与 box2 中每个边界框的交并比。 -> return inter_area / box2_area
ioa = bbox_ioa(box, labels[:, 1:5]) # intersection over area
# 检查新粘贴的对象是否与现有对象的重叠程度在允许的范围内，然后更新标签和分割掩码，并将新对象绘制到图像上。
# 这个条件判断检查 ioa （交并比）数组中的所有值是否都小于 0.30。 ioa 是一个数组，其中每个元素表示新粘贴的对象与现有对象之间的 IoA 值。如果所有值都小于 0.30，则表示新对象与现有对象的重叠程度在允许的范围内（允许 30% 的遮挡）。
if (ioa < 0.30).all(): # allow 30% obscuration of existing labels 允许现有标签遮挡 30%。
# 如果条件满足，将新对象的标签添加到 labels 数组中。 l[0] 是新对象的类别标签， *box 是新对象的 xyxy 格式坐标。 np.concatenate 用于沿第一个轴（行）连接数组。
labels = np.concatenate((labels, [[l[0], *box]]), 0)
# 更新分割掩码，将新对象的分割掩码添加到 segments 列表中。 w - s[:, 0:1] 计算新对象的 x 坐标， s[:, 1:2] 保持 y 坐标不变。 np.concatenate 用于沿第二个轴（列）连接数组。
segments.append(np.concatenate((w - s[:, 0:1], s[:, 1:2]), 1))
# 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 参数。
# 使用 OpenCV 的 drawContours 函数在 im_new 图像上绘制新对象的分割掩码。 segments[j].astype(np.int32) 确保分割掩码的坐标是整数类型。 (255, 255, 255) 指定绘制的颜色为白色， cv2.FILLED 表示填充轮廓。
cv2.drawContours(im_new, [segments[j].astype(np.int32)], -1, (255, 255, 255), cv2.FILLED)
# cv2.bitwise_and(src1, src2[, dst[, mask]])
# cv2.bitwise_and 是 OpenCV 库中的一个函数，它用于对两个图像进行按位与操作。这个函数将每个图像的像素值进行比较，并返回一个新的图像，其中每个像素是两个输入图像对应像素值的按位与结果。
# src1 ：第一个输入图像。
# src2 ：第二个输入图像，必须与 src1 有相同的尺寸和类型。
# dst ：（可选）输出图像，其尺寸和类型与输入图像相同。如果未指定，函数将创建一个新的图像作为输出。
# mask ：（可选）操作的掩码图像，必须与 src1 和 src2 有相同的尺寸。掩码图像中的非零像素指定了操作的区域。
# 返回值 :
# 返回一个新的图像，其中每个像素是两个输入图像对应像素值的按位与结果。
# 功能 :
# cv2.bitwise_and 函数对两个图像的每个像素值进行按位与操作。这意味着，只有当两个图像在某个像素位置的像素值都为 255（对于 8 位图像）时，输出图像在该位置的像素值才会是 255。否则，输出图像在该位置的像素值将为 0。
# 注意事项 ：
# 输入图像必须有相同的尺寸和类型。
# 如果提供了 mask 参数，它必须与输入图像有相同的尺寸。
# 按位与操作通常用于图像掩码操作，例如在某些区域应用滤镜或提取特定特征。
# 将原始图像与新绘制的分割掩码进行按位与操作。
result = cv2.bitwise_and(src1=img, src2=im_new)
# cv2.flip(src, flipCode, dst=None)
# cv2.flip 是 OpenCV 库中的一个函数，它用于翻转图像或视频帧。
# src ：输入图像或视频帧。
# flipCode ：指定翻转的方式，可以是以下值之一，0 ：沿 x 轴翻转。 1 ：沿 y 轴翻转。 -1 ：先沿 x 轴翻转，然后沿 y 轴翻转（或相反）。
# dst ：（可选）输出图像。如果未指定，函数将创建一个新的图像作为输出。
# 返回值 ：
# 返回翻转后的图像。
# 功能 ：
# cv2.flip 函数将输入图像按照指定的 flipCode 参数进行翻转。这个函数可以用于数据增强、图像预处理或其他需要翻转图像的场景。
# 注意事项 ：
# 输入图像可以是灰度图或彩色图，函数将相应地处理。
# 如果指定了 dst 参数，输出图像将被存储在该变量中，否则函数将返回一个新的图像。
# cv2.flip 函数不就地修改输入图像，而是返回一个新的翻转后的图像。
# 对结果进行左右翻转。
result = cv2.flip(result, 1) # augment segments (flip left-right)
# 获取需要替换的像素位置。
i = result > 0 # pixels to replace
# i[:, :] = result.max(2).reshape(h, w, 1) # act over ch
# 将原始图像中对应位置的像素替换为新绘制的分割掩码。
img[i] = result[i] # cv2.imwrite('debug.jpg', img) # debug
# 返回增强后的图像 img ，更新后的标签 labels 和分割掩码 segments 。
return img, labels, segments
# copy_paste 函数通过随机选择对象并将它们粘贴到另一张图像上，从而增加训练数据的多样性。这种方法有助于提高模型对不同场景和对象组合的泛化能力。
18.def remove_background(img, labels, segments):
# 这段代码定义了一个名为 remove_background 的函数，它实现了一种称为 Copy-Paste 数据增强技术，用于实例分割任务。这种技术通过将一个图像中的对象复制到另一个图像上，以增加数据集的多样性和训练模型的鲁棒性。
# 1.img ：输入的原始图像，是一个高度 h 、宽度 w 、颜色通道 c 的数组。
# 2.labels ：图像中每个对象的标签，格式为 nx5 的 numpy 数组，其中 n 是对象的数量，每行包含类别信息和对象的 xyxy 边界框坐标。
# 3.segments ：图像中每个对象的分割掩码，通常是一个包含多个多边形的数组，每个多边形代表一个对象的轮廓。
def remove_background(img, labels, segments):
# 实现复制粘贴增强 https://arxiv.org/abs/2012.07177，标记为 nx5 np.array(cls, xyxy)。
# Implement Copy-Paste augmentation https://arxiv.org/abs/2012.07177, labels as nx5 np.array(cls, xyxy)
# 获取对象的数量。
n = len(segments)
# 从输入图像中获取高度、宽度和颜色通道数。
h, w, c = img.shape # height, width, channels
# 创建一个新的全零图像，用于绘制对象的分割掩码。
im_new = np.zeros(img.shape, np.uint8)
# 创建一个新的图像，初始化为灰度值114，用于存储最终的合成图像。
img_new = np.ones(img.shape, np.uint8) * 114
# 循环遍历每个对象。
for j in range(n):
# 图像上绘制第 j 个对象的分割掩码，填充为白色（255, 255, 255）。
cv2.drawContours(im_new, [segments[j].astype(np.int32)], -1, (255, 255, 255), cv2.FILLED)
# 对原始图像 img 和绘制了分割掩码的 im_new 进行按位与操作，得到只包含目标对象的图像 result 。
result = cv2.bitwise_and(src1=img, src2=im_new)
# 找到 result 图像中非零的像素点，即目标对象的像素点。
i = result > 0 # pixels to replace 要替换的像素。
# 将 result 中的目标对象像素点复制到 img_new 中，从而实现背景移除。返回值
img_new[i] = result[i] # cv2.imwrite('debug.jpg', img) # debug
# 返回值。
# img_new ：移除背景后的新图像，只包含目标对象。
# labels ：原始图像中每个对象的标签。
# segments ：原始图像中每个对象的分割掩码。
return img_new, labels, segments
# 这个函数通过 Copy-Paste 数据增强技术，将原始图像中的目标对象复制到一个新的背景上，从而创建新的训练样本。这种方法可以增加数据集的多样性，提高模型对不同背景的适应能力。19.def sample_segments(img, labels, segments, probability=0.5):
# 这段代码定义了一个名为 sample_segments 的函数，它是实现 Copy-Paste 数据增强方法的一部分，特别是用于 实例分割任务 。这种方法通过随机选择图像中的一些对象，并将它们粘贴到其他图像上，从而生成新的训练样本。
# 定义了函数 sample_segments ，它接受四个参数。
# 1.img ：当前处理的图像。
# 2.labels ：图像中所有对象的标签。
# 3.segments ：图像中所有对象的分割掩码。
# 4.probability ：决定是否执行 Copy-Paste 增强的概率，默认为 0.5。
def sample_segments(img, labels, segments, probability=0.5):
# 实现复制粘贴增强 https://arxiv.org/abs/2012.07177，标记为 nx5 np.array(cls, xyxy)。
# Implement Copy-Paste augmentation https://arxiv.org/abs/2012.07177, labels as nx5 np.array(cls, xyxy)
# 获取分割掩码的数量，即图像中对象的数量。
n = len(segments)
# 初始化三个空列表，用于存储 采样后的标签 、 图像 和 掩码 。
sample_labels = []
sample_images = []
sample_masks = []
# 检查是否应该执行 Copy-Paste 增强（即 probability 为真且有对象）。
if probability and n:
# 获取图像的高度、宽度和通道数。
h, w, c = img.shape # height, width, channels
# 随机选择一定比例的对象进行 Copy-Paste 增强。
# random.sample(population, k) ：这是一个从 population 中随机选择 k 个不重复元素的函数，并返回一个新列表。
# range(n) ：生成一个从 0 到 n-1 的整数序列。这里的 n 是 segments 列表的长度，即图像中对象的数量。
# probability * n ：计算根据给定概率 probability 应该选择的对象数量。例如，如果 probability 是 0.5 且 n 是 10，那么 probability * n 的结果是 5。
# round(probability * n) ：由于 probability * n 的结果可能是一个浮点数，使用 round 函数将其四舍五入到最近的整数，以确保 k 是一个整数。
# for j in ... ：这是一个循环，它将遍历 random.sample 返回的索引列表，并在每次迭代中将当前索引赋值给变量 j 。
for j in random.sample(range(n), k=round(probability * n)):
# 获取被选中对象的标签和分割掩码。
l, s = labels[j], segments[j]
# 计算对象的边界框，并确保边界框的坐标在图像尺寸范围内。
# l[1].astype(int) ：将边界框的第一个坐标（x1）转换为整数类型。 l[1] 是一个浮点数，表示边界框左上角的 x 坐标。
# .clip(0, w-1) ：使用 clip 方法将坐标限制在 [0, w-1] 的范围内。这意味着如果坐标小于 0，则设置为 0；如果坐标大于 w-1 ，则设置为 w-1 。 clip 方法用于防止坐标超出图像的宽度。
# l[2].astype(int).clip(0, h-1) ：将边界框的第二个坐标（y1）转换为整数类型，并限制在 [0, h-1] 的范围内，以确保坐标不会超出图像的高度。
# l[3].astype(int).clip(0, w-1) ：将边界框的第三个坐标（x2）转换为整数类型，并限制在 [0, w-1] 的范围内，以确保坐标不会超出图像的宽度。
# l[4].astype(int).clip(0, h-1) ：将边界框的第四个坐标（y2）转换为整数类型，并限制在 [0, h-1] 的范围内，以确保坐标不会超出图像的高度。
# 最终， box 变量将包含四个整数坐标，分别表示边界框的左上角和右下角的 x 和 y 坐标，且这些坐标都在图像的尺寸范围内。这确保了在图像上绘制边界框或进行其他操作时不会出现越界错误。
box = l[1].astype(int).clip(0,w-1), l[2].astype(int).clip(0,h-1), l[3].astype(int).clip(0,w-1), l[4].astype(int).clip(0,h-1)
#print(box)
# 检查边界框是否有效（即宽度和高度必须为正）。
if (box[2] <= box[0]) or (box[3] <= box[1]):
continue
# 将选中对象的类别标签添加到采样标签列表中。
sample_labels.append(l[0])
# 创建一个与图像大小相同的掩码。
mask = np.zeros(img.shape, np.uint8)
# 在掩码上绘制选中对象的轮廓。
cv2.drawContours(mask, [segments[j].astype(np.int32)], -1, (255, 255, 255), cv2.FILLED)
# 将对象的掩码添加到采样掩码列表中。
sample_masks.append(mask[box[1]:box[3],box[0]:box[2],:])
# 对图像和掩码执行按位与操作，以获取对象的像素。
result = cv2.bitwise_and(src1=img, src2=mask)
# 找到对象的非零像素。
i = result > 0 # pixels to replace 要替换的像素。
# 将对象的像素替换到掩码中。
mask[i] = result[i] # cv2.imwrite('debug.jpg', img) # debug
#print(box)
# 将对象的图像添加到采样图像列表中。
sample_images.append(mask[box[1]:box[3],box[0]:box[2],:])
# 返回采样后的标签、图像和掩码。
return sample_labels, sample_images, sample_masks
# 这个函数的目的是从一个图像中随机选择一些对象，并将它们复制到其他图像上，以增加数据集的多样性和训练样本的数量。这种方法特别适用于实例分割任务，因为它可以创建新的训练样本，而无需人工标注新的数据。20.def replicate(img, labels):
# 这段代码定义了一个名为 replicate 的函数，它用于实现一种简单的数据增强技术，通过复制图像中的一部分对象到新的位置上，从而增加数据集的多样性。这种技术特别适用于实例分割任务，可以帮助模型学习到更加鲁棒的特征。
# 1.img ：输入的原始图像，是一个高度 h 、宽度 w 的数组。
# 2.labels ：图像中每个对象的标签，格式为 n x 5 的 numpy 数组，其中 n 是对象的数量，每行包含 类别信息 和对象的 xyxy 边界框坐标。
def replicate(img, labels):
# 复制标签。
# Replicate labels
# 从输入图像中获取高度和宽度。
h, w = img.shape[:2]
# 提取标签中的边界框坐标，并转换为整数类型。
boxes = labels[:, 1:].astype(int)
# 将边界框坐标分别赋值给 x1 , y1 , x2 , y2 。
x1, y1, x2, y2 = boxes.T
# 计算每个边界框的对角线长度的一半，作为对象的大小。
s = ((x2 - x1) + (y2 - y1)) / 2 # side length (pixels) 边长（像素）。
# 选择对象大小最小的一半对象进行复制。 argsort() 返回数组从小到大的索引值， round(s.size * 0.5) 计算对象数量的一半。
for i in s.argsort()[:round(s.size * 0.5)]: # smallest indices 最小指数。
# 获取当前对象的边界框坐标。
x1b, y1b, x2b, y2b = boxes[i]
# 计算当前对象的高度和宽度。
bh, bw = y2b - y1b, x2b - x1b
# 随机生成一个新的位置，确保新位置能够放下整个对象。
yc, xc = int(random.uniform(0, h - bh)), int(random.uniform(0, w - bw)) # offset x, y 偏移 x, y。
# 计算新位置的边界框坐标。
x1a, y1a, x2a, y2a = [xc, yc, xc + bw, yc + bh]
# 将原始对象复制到新位置。
img[y1a:y2a, x1a:x2a] = img[y1b:y2b, x1b:x2b] # img4[ymin:ymax, xmin:xmax]
# 将新对象的标签添加到标签数组中。
labels = np.append(labels, [[labels[i, 0], x1a, y1a, x2a, y2a]], axis=0)
# 返回值。
# img ：添加了复制对象的新图像。
# labels ：包含新对象标签的新标签数组。
return img, labels
# 这个函数通过复制图像中较小的对象到随机新位置，增加了数据集的多样性，有助于模型在训练过程中学习到更加鲁棒的特征。这种方法简单而有效，可以提高模型对不同场景下对象的识别能力。21.def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# letterbox 函数它用于对图像进行缩放和填充，以适应指定的尺寸，同时保持图像的宽高比。这种处理方式常用于深度学习中的目标检测和图像分类任务，以确保输入图像满足模型的尺寸要求。
# 1.img ：要处理的图像。
# 2.new_shape ：目标尺寸，可以是一个元组 (height, width) 或一个整数，表示将图像缩放到正方形。
# 3.color ：用于填充图像的背景颜色，默认为灰色 (114, 114, 114) 。
# 4.auto ：自动决定是否缩放图像以适应 new_shape 。
# 5.scaleFill ：如果为 True ，则缩放图像以填充整个 new_shape ，忽略宽高比。
# 6.scaleup ：如果为 True ，则在缩放图像时允许放大图像。
# 7.stride ：用于确保输出尺寸是 stride 的倍数。
def letterbox(img, new_shape=(640, 640), color=(114, 114, 114), auto=True, scaleFill=False, scaleup=True, stride=32):
# 调整图像大小并填充，同时满足步长倍数约束。
# Resize and pad image while meeting stride-multiple constraints
# 获取当前图像尺寸。获取图像的当前高度和宽度。
shape = img.shape[:2] # current shape [height, width]
# 处理新尺寸。
if isinstance(new_shape, int):
# 如果 new_shape 是一个整数，将其转换为一个元组，表示目标尺寸是一个正方形。
new_shape = (new_shape, new_shape)
# Scale ratio (new / old) 比例（新/旧）。
# 计算缩放比例。 r 是图像新尺寸与原始尺寸之间的最小缩放比例，这确保了图像在缩放时不会超出目标尺寸，同时保持宽高比。
r = min(new_shape[0] / shape[0], new_shape[1] / shape[1])
# 限制缩放比例。
if not scaleup: # only scale down, do not scale up (for better test mAP) 只缩小，不扩大（为了获得更好的测试 mAP）。
# 如果 scaleup 参数为 False ，则 r 的值被限制在 1.0 或更小，这意味着图像不会被放大，只会被缩小或保持原样。这通常用于测试阶段，以确保模型评估时的一致性。
r = min(r, 1.0)
# Compute padding 计算填充。
# 计算填充。 ratio 存储宽度和高度的缩放比例。
ratio = r, r # width, height ratios 宽度、高度比。
# new_unpad 计算缩放后的图像尺寸，但不包括填充。
new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r))
# 计算宽度和高度的填充量。 dw 和 dh 分别计算宽度和高度方向上需要填充的像素数。
dw, dh = new_shape[1] - new_unpad[0], new_shape[0] - new_unpad[1] # wh padding
# 自动调整填充。
if auto: # minimum rectangle
# y = np.mod(x1, x2[, out])
# 参数定义如下：
# x1 ：第一个输入数组。
# x2 ：第二个输入数组，其形状必须与 x1 相同，或者能够广播成 x1 的形状。
# out ：（可选）用于存放结果的数组，它必须有正确的形状和类型。
# 返回值 ：
# y ：是一个数组，其形状与输入数组 x1 和 x2 相同，且每个元素是 x1 和 x2 对应元素相除后的余数。
# 需要注意的是， np.mod 的行为与 Python 内置的 % 运算符略有不同，特别是在处理负数时。 np.mod 总是返回一个非负余数，而 % 运算符则返回的余数的符号与被除数相同。
# 如果 auto 参数为 True ，则使用 np.mod 函数确保填充后的图像尺寸是 stride 的倍数。这有助于满足某些深度学习模型对输入尺寸的要求。
dw, dh = np.mod(dw, stride), np.mod(dh, stride) # wh padding
# 填充以填充整个目标尺寸。
elif scaleFill: # stretch
# 如果 scaleFill 参数为 True ，则不进行填充，而是调整图像尺寸以完全填充目标尺寸。这意味着图像可能会被拉伸以适应目标尺寸，从而失去原始的宽高比。
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
# 平均分配填充。将宽度和高度的填充量除以2，这样填充会在图像的两侧平均分配。
dw /= 2 # divide padding into 2 sides
dh /= 2
# 缩放图像。
# shape[::-1] 反转图像的当前尺寸（宽、高）。
# new_unpad 是缩放后但不包括填充的图像尺寸。
# 如果原始图像尺寸与新尺寸不同，则使用 cv2.resize 函数进行缩放， interpolation=cv2.INTER_LINEAR 指定了线性插值方法。
if shape[::-1] != new_unpad: # resize
img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR)
# 计算填充的确切位置。
# 计算顶部、底部、左侧和右侧的填充量，这里通过减去和加上0.1来避免精确的一半，可能是为了避免精确除以2时的浮点数误差。
top, bottom = int(round(dh - 0.1)), int(round(dh + 0.1))
left, right = int(round(dw - 0.1)), int(round(dw + 0.1))
# cv2.copyMakeBorder(src: Mat, top, bottom, left, right, borderType, dts: Mat = ..., value=...)
# 在制作图像数据集时，有时需要调整图片的长和宽。采用 cv2.resize 函数会造成图像扭曲失真，因此需要采取填充图像短边的方法解决这个问题。
# cv2.copyMakeBorder(src: Mat, top, bottom, left, right, borderType, dts: Mat = ..., value=...)
# src ：为输入图像。
# top ：为图像顶部需要填充的边界宽度，单位为像素。
# bottom ：为图像底部需要填充的边界宽度，单位为像素。
# left ：为图像左侧需要填充的边界宽度，单位为像素。
# right ：为图像右侧需要填充的边界宽度，单位为像素。
# borderType ：为填充类型，如cv2.BORDER_CONSTANT，用常数填充；cv2.BORDER_ISOLATED，用黑色像素填充，等。
# dts ：为输出图像。
# value ：为常量填充的值，如value=(114，114，114)，灰度填充。
# 添加边框。
# 使用 cv2.copyMakeBorder 函数在图像周围添加边框， top 、 bottom 、 left 、 right 分别是上下左右需要添加的边框宽度。 cv2.BORDER_CONSTANT 指定了填充类型，这里使用常数填充。 value=color 指定了填充的颜色。
img = cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=color) # add border
# 返回结果。函数返回 缩放和填充后的图像 img ，缩放比例 ratio ，以及宽度和高度的填充量 (dw, dh) 。
return img, ratio, (dw, dh)22.def random_perspective(img, targets=(), segments=(), degrees=10, translate=.1, scale=.1, shear=10, perspective=0.0, border=(0, 0)):
# 这段代码是 random_perspective 函数的完整实现，它通过对图像和目标边界框应用随机的几何变换来增强数据。
# 参数解释。
# 1.img : 输入的图像。
# 2.targets : 与图像对应的目标标签，通常是类别和边界框信息。
# 3.segments : 用于图像分割的额外信息。
# 4.degrees : 随机旋转的度数范围。
# 5.translate : 随机平移的比例。
# 6.scale : 随机缩放的比例。
# 7.shear : 随机剪切的角度。
# 8.perspective : 随机透视变换的程度。
# 9.border : 在图像边缘添加的边界大小，用于在进行透视变换时避免裁剪掉图像的重要部分。
def random_perspective(img, targets=(), segments=(), degrees=10, translate=.1, scale=.1, shear=10, perspective=0.0,
border=(0, 0)):
# torchvision.transforms.RandomAffine(degrees=(-10, 10), translate=(.1, .1), scale=(.9, 1.1), shear=(-10, 10))
# targets = [cls, xyxy]
# 计算图像的新尺寸。 height 和 width 分别加上了 border 参数指定的边界，以确保在进行透视变换时，图像的边缘不会被裁剪掉。
height = img.shape[0] + border[0] * 2 # shape(h,w,c)
width = img.shape[1] + border[1] * 2
# 用于生成变换矩阵的部分。每个变换矩阵代表一种特定的几何变换，这些变换矩阵最终将被组合起来，对图像和目标边界框进行变换。
# Center
# 中心点平移矩阵（C）。 C 是一个3x3的单位矩阵，通过对x和y坐标进行平移，将图像的中心移动到坐标原点。这是为了简化后续的旋转和缩放操作。
C = np.eye(3)
C[0, 2] = -img.shape[1] / 2 # x translation (pixels)
C[1, 2] = -img.shape[0] / 2 # y translation (pixels)
# Perspective
# 透视变换矩阵（P）。 P 也是一个3x3的单位矩阵，通过在最后一行添加随机值来模拟透视变换。这些随机值代表图像在x和y方向上的透视偏移。
P = np.eye(3)
P[2, 0] = random.uniform(-perspective, perspective) # x perspective (about y)
P[2, 1] = random.uniform(-perspective, perspective) # y perspective (about x)
# Rotation and Scale
# 旋转和缩放矩阵（R）。 R 是一个3x3的单位矩阵，通过随机选择一个旋转角度 a 和缩放比例 s 来生成旋转和缩放矩阵。这个矩阵使用 cv2.getRotationMatrix2D 函数生成，该函数返回一个2x3的矩阵，因此只取前两行。
R = np.eye(3)
a = random.uniform(-degrees, degrees)
# a += random.choice([-180, -90, 0, 90]) # add 90deg rotations to small rotations
s = random.uniform(1 - scale, 1.1 + scale)
# s = 2 ** random.uniform(-scale, scale)
R[:2] = cv2.getRotationMatrix2D(angle=a, center=(0, 0), scale=s)
# Shear
# 剪切变换矩阵（S）。 S 是一个3x3的单位矩阵，通过在非对角线上添加随机值来模拟剪切变换。这些随机值是通过将随机选择的角度转换为弧度，然后计算其正切值得到的。
S = np.eye(3)
S[0, 1] = math.tan(random.uniform(-shear, shear) * math.pi / 180) # x shear (deg)
S[1, 0] = math.tan(random.uniform(-shear, shear) * math.pi / 180) # y shear (deg)
# Translation
# 平移矩阵（T）。 T 是一个3x3的单位矩阵，通过在最后一列添加随机值来模拟平移变换。这些随机值是基于图像宽度和高度的一定比例随机选择的。
T = np.eye(3)
T[0, 2] = random.uniform(0.5 - translate, 0.5 + translate) * width # x translation (pixels)
T[1, 2] = random.uniform(0.5 - translate, 0.5 + translate) * height # y translation (pixels)
# 将之前定义的所有变换矩阵组合起来，并应用到图像上。
# Combined rotation matrix
# 矩阵乘法。这行代码将所有的变换矩阵（平移 T 、 剪切 S 、 旋转和缩放 R 、 透视 P 、 中心点平移 C ）按照从右到左的顺序进行矩阵乘法，得到最终的变换矩阵 M 。矩阵乘法的顺序非常重要，因为它决定了变换的顺序。
M = T @ S @ R @ P @ C # order of operations (right to left) is IMPORTANT
# 检查图像是否需要变换。这个条件检查是否添加了边界或者变换矩阵 M 是否与单位矩阵不同。如果 border 不为0或者 M 不是单位矩阵，说明图像需要进行变换。
if (border[0] != 0) or (border[1] != 0) or (M != np.eye(3)).any(): # image changed
if perspective:
# dst = cv2.warpPerspective(src, M, dsize[, dst[, borderValue[, flags[, borderMode]]]])
# cv2.warpPerspective 函数是 OpenCV 库中用于对图像进行透视变换的函数。这个函数可以对图像应用一个3x3的变换矩阵，通常用于模拟相机视角的变化或者校正图像的透视失真。
# 参数 ：
# src ：输入图像，可以是灰度图或彩色图。
# M ：3x3的变换矩阵，表示透视变换。
# dsize ：输出图像的大小（宽度，高度）。如果为 None ，则输出图像的大小将与输入图像相同。
# dst ：输出图像。
# borderValue ：用于边界外像素的值，默认为 None 。如果指定，它将用于填充变换后图像边界外的像素。
# flags ：指定插值方法，可以是以下之一 ：
# cv2.INTER_LINEAR ：默认，双线性插值。
# cv2.INTER_NEAREST ：最近邻插值。
# cv2.INTER_CUBIC ：双三次插值。
# cv2.INTER_AREA ：像素区域关系插值。
# 其他插值方法。
# borderMode ：指定边界外像素填充方式，可以是以下之一 ：
# cv2.BORDER_CONSTANT ：使用 borderValue 指定的值填充。
# cv2.BORDER_REPLICATE ：复制边缘像素。
# cv2.BORDER_REFLECT ：反射边缘像素。
# cv2.BORDER_WRAP ：环绕边缘像素。
# cv2.BORDER_REFLECT_101 ：与 BORDER_REFLECT 类似，但反射0和-1像素。
# cv2.BORDER_TRANSPARENT ：指定透明边界模式。
# cv2.BORDER_REFLECT101 ：与 BORDER_REFLECT_101 相同。
# cv2.BORDER_DEFAULT ：与 BORDER_REFLECT_101 相同。
# cv2.BORDER_ISOLATED ：不复制图像的边界像素。
# 返回值 ：
# dst ：变换后的图像。
# cv2.warpPerspective 函数可以用于图像校正、3D效果模拟等多种应用场景。通过指定不同的变换矩阵 M ，可以实现不同的透视变换效果。
# 透视变换。如果 perspective 参数为真，说明需要进行透视变换。使用 cv2.warpPerspective 函数将变换矩阵 M 应用到图像上， dsize=(width, height) 指定变换后图像的尺寸， borderValue=(114, 114, 114) 指定变换后图像边界的填充值。
img = cv2.warpPerspective(img, M, dsize=(width, height), borderValue=(114, 114, 114))
else: # affine
# cv2.warpAffine(src, M, dsize, flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0, 0, 0))
# cv2.warpAffine 是 OpenCV 库中的一个函数，用于对图像应用仿射变换。这个函数通过指定的变换矩阵对图像进行几何变换，如旋转、缩放、平移和剪切等。
# 参数 ：
# src ：输入图像，可以是灰度图或彩色图。
# M ：变换矩阵，是一个 2x3 的数组，表示仿射变换。
# dsize ：输出图像的大小（宽度，高度）。可以与输入图像大小不同，以实现缩放效果。
# flags （可选）：插值方法，默认为 cv2.INTER_LINEAR ，表示双线性插值。
# 其他选项包括 ：
# cv2.INTER_NEAREST ：最近邻插值。
# cv2.INTER_CUBIC ：双三次插值。
# cv2.INTER_AREA ：区域插值，适用于缩放变换。
# borderMode （可选）：边界像素的填充方式，默认为 cv2.BORDER_CONSTANT ，表示以常数值填充。其他选项包括：
# cv2.BORDER_REPLICATE ：复制边缘像素。
# cv2.BORDER_REFLECT ：反射填充。
# cv2.BORDER_WRAP ：环绕填充。
# borderValue （可选）：用于边界填充的颜色值，默认为黑色（0, 0, 0）。对于灰度图像，只需提供一个值。
# 返回值 ：
# 输出图像，其大小和类型由 dsize 和输入图像的深度决定。
# 仿射变换。如果 perspective 参数为假，说明只需要进行仿射变换。使用 cv2.warpAffine 函数将变换矩阵 M 的前两行应用到图像上（因为仿射变换是2x3矩阵），同样指定变换后图像的尺寸和边界填充值。
img = cv2.warpAffine(img, M[:2], dsize=(width, height), borderValue=(114, 114, 114))
# 这部分代码将之前定义的所有变换矩阵组合起来，根据是否需要透视变换，选择使用 cv2.warpPerspective 或 cv2.warpAffine 函数将变换应用到图像上。
# 这样，图像就会根据随机生成的变换参数进行变换，增加了数据的多样性，有助于提高模型的泛化能力。同时，通过指定边界填充值，确保了变换后的图像边界不会是空白，而是有一定的背景色。
# Visualize
# import matplotlib.pyplot as plt
# ax = plt.subplots(1, 2, figsize=(12, 6))[1].ravel()
# ax[0].imshow(img[:, :, ::-1]) # base
# ax[1].imshow(img2[:, :, ::-1]) # warped
# Transform label coordinates
# 这段代码负责将相同的几何变换应用到目标的标签坐标上，确保变换后的图像和目标边界框保持一致。
# 检查目标数量。获取目标的数量。
n = len(targets)
# 确定是否使用分割。
if n:
# 检查是否有分割信息，如果有，则 use_segments 为真。
use_segments = any(x.any() for x in segments)
# 初始化新的标签数组。创建一个新的数组来存储变换后的目标边界框。
new = np.zeros((n, 4))
# 处理分割信息。
if use_segments: # warp segments
# 如果 use_segments 为真，对每个分割进行上采样并应用变换。
# def resample_segments(segments, n=1000): -> 它用于对输入的分割点（segments）进行上采样。返回上采样后的分割点数组。 -> return segments
segments = resample_segments(segments) # upsample
# 对于每个分割 segment 。
for i, segment in enumerate(segments):
# 创建一个增强的坐标数组 xy ，包含1作为第三维度。
xy = np.ones((len(segment), 3))
xy[:, :2] = segment
# 将变换矩阵 M 的转置 M.T 应用到 xy 上。
xy = xy @ M.T # transform
# 如果有透视变换，对坐标进行重新缩放；如果没有，直接使用变换后的坐标。
# xy ：这是一个 numpy 数组，其中包含了变换后的点的坐标和缩放因子。它的维度可能是 (n, 3) ，其中 n 是点的数量，第一列和第二列分别代表 x 和 y 坐标，第三列代表缩放因子（在透视变换中用于调整坐标）。
# perspective ：这是一个布尔变量，用于指示是否应用了透视变换。
# 如果 perspective 为 True （即应用了透视变换），则执行以下操作 ：
# xy[:, :2] / xy[:, 2:3] ：这个操作将 xy 数组的前两列（x 和 y 坐标）除以第三列（缩放因子）。这样做是为了将透视变换后的坐标重新缩放回原始图像空间。
# 如果 perspective 为 False （即没有应用透视变换或者应用的是仿射变换），则执行以下操作 ：
# xy[:, :2] ：直接使用 xy 数组的前两列（x 和 y 坐标），不进行任何缩放。
xy = xy[:, :2] / xy[:, 2:3] if perspective else xy[:, :2] # perspective rescale or affine
# clip
# 使用 segment2box 函数将变换后的分割坐标转换为边界框，并存储在 new[i] 中。
# def segment2box(segment, width=640, height=640):
# -> 它将一个分割标签（通常是由一系列点组成的线段）转换为一个边界框（box），这个边界框是由这些点形成的最小外接矩形。返回一个包含边界框坐标的 numpy 数组，形状为 (1, 4) ，其中包含 [x_min, y_min, x_max, y_max] 。
# -> return np.array([x.min(), y.min(), x.max(), y.max()]) if any(x) else np.zeros((1, 4)) # xyxy
new[i] = segment2box(xy, width, height)
# 处理边界框。
else: # warp boxes
# 如果 use_segments 为假，对边界框应用变换。
# 创建一个增强的坐标数组 xy ，包含目标的四个角点坐标。
xy = np.ones((n * 4, 3))
# 用于将目标（targets）数组中的边界框坐标重新排列并赋值给另一个数组（xy）的相关部分。
# xy ：这是一个 numpy 数组，其形状可能是 (n, 3) 或 (n, 4) ，取决于上下文，其中 n 是目标的数量。 xy[:, :2] 表示取 xy 数组的所有行和前两列，即每个目标的 x 和 y 坐标。
# targets ：这是一个包含边界框信息的 numpy 数组，每个边界框由四个坐标 [x1, y1, x2, y2] 表示，其中 (x1, y1) 是左上角点的坐标， (x2, y2) 是右下角点的坐标。
# reshape(n * 4, 2) ：这部分代码将 targets 数组中的坐标重新排列并重塑为一个新的形状。 n * 4 表示有 n 个目标，每个目标有 4 个坐标，因此总共有 n * 4 个坐标。 2 表示每个坐标点有两个值（x 和 y）。
# 所以，这个操作将 targets 中的边界框坐标重新排列成一个长数组，其中包含了所有目标的所有坐标点。
# targets[:, [1, 2, 3, 4, 1, 4, 3, 2]] ：这个索引操作从每个目标的边界框中取出特定的坐标，并按照新的顺序排列它们。具体来说，它取出每个目标的 [x1, y1, x2, y2] 坐标，并按照 [x1, y1, x2, y2, x1, y2, x2, y1] 的顺序排列。
# 这样做的目的是为了将边界框的坐标重新排列成连续的点对，这样可以方便后续的处理，例如应用透视变换或其他几何变换。
xy[:, :2] = targets[:, [1, 2, 3, 4, 1, 4, 3, 2]].reshape(n * 4, 2) # x1y1, x2y2, x1y2, x2y1
# 将变换矩阵 M 的转置 M.T 应用到 xy 上。
xy = xy @ M.T # transform
# 如果有透视变换，对坐标进行重新缩放；如果没有，直接使用变换后的坐标。
xy = (xy[:, :2] / xy[:, 2:3] if perspective else xy[:, :2]).reshape(n, 8) # perspective rescale or affine
# create new boxes
x = xy[:, [0, 2, 4, 6]]
y = xy[:, [1, 3, 5, 7]]
# 从变换后的坐标中创建新的边界框，并存储在 new 中。
new = np.concatenate((x.min(1), y.min(1), x.max(1), y.max(1))).reshape(4, n).T
# clip
# 对新的边界框进行裁剪，确保它们在图像尺寸范围内。
new[:, [0, 2]] = new[:, [0, 2]].clip(0, width)
new[:, [1, 3]] = new[:, [1, 3]].clip(0, height)
# 过滤掉那些在变换后与原边界框重叠面积过小的目标，以及更新目标边界框的坐标。
# filter candidates
# 计算变换后目标的索引。
# 这个函数调用 box_candidates 函数来确定哪些目标在变换后仍然有效。 box1 是原始目标边界框的坐标， box2 是变换后的目标边界框坐标， area_thr 是保留目标的最小重叠面积阈值。如果 use_segments 为真，则使用较小的阈值0.01；否则，使用0.10。
# def box_candidates(box1, box2, wh_thr=2, ar_thr=20, area_thr=0.1, eps=1e-16):
# -> 它用于确定在数据增强过程中，哪些变换后的目标边界框（box2）与原始目标边界框（box1）足够相似，可以被认为是候选框。返回一个布尔数组，形状为 (n,) ，其中 n 是目标的数量。数组中的每个元素表示对应的变换后边界框是否是候选框。
# -> return (w2 > wh_thr) & (h2 > wh_thr) & (w2 * h2 / (w1 * h1 + eps) > area_thr) & (ar < ar_thr)
i = box_candidates(box1=targets[:, 1:5].T * s, box2=new.T, area_thr=0.01 if use_segments else 0.10)
# 过滤目标。根据 box_candidates 函数返回的索引 i ，过滤掉那些重叠面积过小的目标，只保留那些仍然有效的目标。
targets = targets[i]
# 更新目标边界框。将变换后的目标边界框坐标更新到 targets 数组中。这里 1:5 表示目标数组中的第2列到第5列，即边界框的坐标。
targets[:, 1:5] = new[i]
# 这部分代码确保了只有那些在变换后仍然与原始边界框有足够重叠的目标被保留下来，并且它们的边界框坐标被更新以反映变换。这样可以避免在数据增强过程中丢失重要的目标信息，同时也确保了模型训练时的数据质量和一致性。
# 通过这种方式， random_perspective 函数不仅增强了图像数据，还确保了目标标注的准确性。
# 函数返回 变换后的图像 img 和 更新后的目标边界框 targets 。
return img, targets
# 这个函数通过随机应用旋转、缩放、剪切、平移和透视变换，增加了图像数据的多样性，有助于提高模型在不同视角和条件下的泛化能力。同时，它还确保了目标边界框与变换后的图像保持一致，这对于目标检测任务尤为重要。23.def box_candidates(box1, box2, wh_thr=2, ar_thr=20, area_thr=0.1, eps=1e-16):
# 这段代码定义了一个名为 box_candidates 的函数，它用于确定在数据增强过程中，哪些变换后的目标边界框（box2）与原始目标边界框（box1）足够相似，可以被认为是候选框。这个函数考虑了宽度、高度、面积比和宽高比（宽高比）的阈值来判断两个边界框是否相似。
# 1.box1 ：原始目标边界框的坐标，形状为 (4, n) ，其中 n 是目标的数量。每个边界框由 [x1, y1, x2, y2] 表示。
# 2.box2 ：变换后的目标边界框的坐标，形状与 box1 相同。
# 3.wh_thr ：宽度和高度的最小阈值（以像素为单位）。
# 4.ar_thr ：宽高比的最大阈值。
# 5.area_thr ：面积比的最小阈值。
# 6.eps ：用于防止除以零的小常数。
def box_candidates(box1, box2, wh_thr=2, ar_thr=20, area_thr=0.1, eps=1e-16): # box1(4,n), box2(4,n)
# 计算候选框：增强前的 box1、增强后的 box2、wh_thr（像素）、aspect_ratio_thr、area_ratio。
# Compute candidate boxes: box1 before augment, box2 after augment, wh_thr (pixels), aspect_ratio_thr, area_ratio
# 计算原始边界框的宽度和高度。
w1, h1 = box1[2] - box1[0], box1[3] - box1[1]
# 计算变换后边界框的宽度和高度。
w2, h2 = box2[2] - box2[0], box2[3] - box2[1]
# 计算宽高比。计算变换后边界框的宽高比，使用 np.maximum 来确保即使其中一个维度非常小，宽高比也不会变得非常大。
ar = np.maximum(w2 / (h2 + eps), h2 / (w2 + eps)) # aspect ratio
# 确定候选框。
# return (w2 > wh_thr) & (h2 > wh_thr) & (w2 * h2 / (w1 * h1 + eps) > area_thr) & (ar < ar_thr) ：返回一个布尔数组，表示哪些变换后的边界框是候选框。
# 候选框需要满足以下条件 ：
# 宽度 w2 和高度 h2 大于 wh_thr 。
# 变换后的边界框面积与原始边界框面积的比值大于 area_thr 。
# 宽高比 ar 小于 ar_thr 。
# 返回一个布尔数组，形状为 (n,) ，其中 n 是目标的数量。数组中的每个元素表示对应的变换后边界框是否是候选框。
return (w2 > wh_thr) & (h2 > wh_thr) & (w2 * h2 / (w1 * h1 + eps) > area_thr) & (ar < ar_thr) # candidates
# box_candidates 函数通过比较原始边界框和变换后边界框的尺寸和比例，来确定哪些变换后的边界框是有效的候选框。这个函数在数据增强和目标检测任务中非常有用，因为它可以帮助过滤掉那些在增强过程中变得不合理或与原始目标差异过大的边界框。24.def bbox_ioa(box1, box2):
# 这段代码定义了一个名为 bbox_ioa 的函数，用于计算一个边界框（ box1 ）与一组边界框（ box2 ）之间的交并比（Intersection over Area, IoA）。IoA 是一个衡量两个边界框重叠程度的指标，常用于目标检测和实例分割任务中。
# 函数参数。
# 1.box1 ：一个形状为 (4,) 的数组，表示单个边界框的 x1y1x2y2 坐标。
# 2.box2 ：一个形状为 (n, 4) 的数组，表示 n 个边界框的 x1y1x2y2 坐标。
def bbox_ioa(box1, box2):
# 返回给定 box1、box2 的 box2 区域的交集。box1 为 4，box2 为 nx4。boxes 为 x1y1x2y2。
# Returns the intersection over box2 area given box1, box2. box1 is 4, box2 is nx4. boxes are x1y1x2y2
# 将 box2 数组转置，使其列向量变为行向量，以便于后续计算。
box2 = box2.transpose()
# Get the coordinates of bounding boxes 获取边界框的坐标。
# box1 的左上角和右下角坐标。
b1_x1, b1_y1, b1_x2, b1_y2 = box1[0], box1[1], box1[2], box1[3]
# box2 的左上角和右下角坐标。
b2_x1, b2_y1, b2_x2, b2_y2 = box2[0], box2[1], box2[2], box2[3]
# Intersection area 交叉区域。
# 使用 np.minimum 和 np.maximum 函数计算两个边界框在 x 和 y 轴上的交集坐标。
# .clip(0) 确保交集面积非负。
# 将 x 轴和 y 轴的交集长度相乘得到交集面积。
inter_area = (np.minimum(b1_x2, b2_x2) - np.maximum(b1_x1, b2_x1)).clip(0) * \
(np.minimum(b1_y2, b2_y2) - np.maximum(b1_y1, b2_y1)).clip(0)
# box2 area box2 区域。
# 计算 box2 的宽度和高度，并相乘得到面积。加上 1e-16 防止除以零的错误。
box2_area = (b2_x2 - b2_x1) * (b2_y2 - b2_y1) + 1e-16
# Intersection over box2 area 与 box2 区域的交点。
# 将交集面积除以 box2 的面积，得到 IoA 值。
# 返回 IoA 值，表示 box1 与 box2 中每个边界框的交并比。
return inter_area / box2_area
# bbox_ioa 函数是一个实用的工具，用于计算单个边界框与一组边界框之间的 IoA 值。这个指标在许多计算机视觉任务中都非常重要，例如在非极大值抑制（NMS）中用于确定哪些边界框应该被保留或抑制。通过计算 IoA，可以评估预测边界框与真实边界框之间的重叠程度，从而评估模型的性能。25.def cutout(image, labels):
# 这段代码定义了一个名为 cutout 的函数，它实现了图像切割增强（cutout augmentation），这是一种数据增强技术，通过在训练过程中随机遮盖图像的一部分来提高模型的鲁棒性。
# 1.image ：输入的图像。
# 2.labels ：与图像对应的标签，通常包含边界框信息。
def cutout(image, labels):
# 应用图像剪切增强 https://arxiv.org/abs/1708.04552。
# Applies image cutout augmentation https://arxiv.org/abs/1708.04552
# 获取图像尺寸。获取图像的高度和宽度。
h, w = image.shape[:2]
# create random masks 创建随机掩膜。
# 定义遮盖尺度。 scales ：一个列表，包含了不同的遮盖尺度，这些尺度是图像大小的分数。
scales = [0.5] * 1 + [0.25] * 2 + [0.125] * 4 + [0.0625] * 8 + [0.03125] * 16 # image size fraction 图像尺寸分数。
# 遍历尺度并创建随机遮盖。
# 遍历 scales 中的每个尺度 s 。
for s in scales:
# random.randint(a, b)
# random.randint 是 Python 标准库中 random 模块提供的一个函数，用于生成一个指定范围内的随机整数。这个函数包含两个参数，分别是范围的起始值和结束值，并且返回一个在这个闭区间内的随机整数。
# 参数 ：
# a ：范围的起始值（包含）。
# b ：范围的结束值（包含）。
# 返回值 ：
# 返回一个在闭区间 [a, b] 内的随机整数。
# 根据尺度 s 随机生成遮盖的高度 mask_h 和宽度 mask_w 。
mask_h = random.randint(1, int(h * s))
mask_w = random.randint(1, int(w * s))
# box 边界框。
# 计算遮盖的左上角坐标 xmin 和 ymin ，以及右下角坐标 xmax 和 ymax 。
xmin = max(0, random.randint(0, w) - mask_w // 2)
ymin = max(0, random.randint(0, h) - mask_h // 2)
xmax = min(w, xmin + mask_w)
ymax = min(h, ymin + mask_h)
# apply random color mask 应用随机颜色掩膜。
# 应用随机颜色遮盖。将图像中遮盖区域内的像素值设置为随机颜色。
image[ymin:ymax, xmin:xmax] = [random.randint(64, 191) for _ in range(3)]
# return unobscured labels 返回未遮挡的标签。
# 处理标签。
# 如果存在标签，并且遮盖尺度 s 大于 0.03，则计算遮盖区域与每个标签边界框的交集面积比（IOA）。
if len(labels) and s > 0.03:
# numpy.array(object, dtype=None, copy=True, ndmin=0, order=None, subok=False, view_ok=False)
# np.array 是 NumPy 库中的一个函数，用于创建一个 NumPy 数组。这个函数非常灵活，可以接受多种类型的输入，包括列表、元组、另一个 NumPy 数组，甚至是其他迭代器，并将它们转换为一个 NumPy 数组。
# 参数 ：
# object ：要转换为数组的对象。可以是列表、元组、另一个 NumPy 数组，或者是任何其他迭代器。
# dtype ：数组中元素的数据类型。如果不指定，NumPy 将自动推断数据类型。
# copy ：布尔值，指示是否需要复制输入数据。如果为 True ，则总是复制输入数据；如果为 False ，则只有在需要时才复制。
# ndmin ：数组的最小维度。这可以用来确保结果至少有这么多的维度。
# order ：'C' 或 'F'，指定数组的内存布局。'C' 表示行主序（C-style），'F' 表示列主序（Fortran-style）。如果不指定，由 NumPy 自动决定。
# subok ：布尔值，指示是否允许返回子类数组。
# view_ok ：布尔值，指示是否允许返回输入数据的视图，而不是副本。
# 返回值 ：
# 返回一个 NumPy 数组。
box = np.array([xmin, ymin, xmax, ymax], dtype=np.float32)
# def bbox_ioa(box1, box2): -> 用于计算一个边界框（ box1 ）与一组边界框（ box2 ）之间的交并比（Intersection over Area, IoA）。返回 IoA 值，表示 box1 与 box2 中每个边界框的交并比。 -> return inter_area / box2_area
ioa = bbox_ioa(box, labels[:, 1:5]) # intersection over area
# 移除被遮盖超过 60% 的标签。
labels = labels[ioa < 0.60] # remove >60% obscured labels 去除 60% 以上的模糊标签。
# 返回处理后的标签 labels 。
return labels
# cutout 函数通过对图像应用随机遮盖并更新相应的标签来增强数据集。这种增强技术可以帮助模型学习在面对图像遮挡时如何更好地泛化。通过随机遮盖图像的不同区域，模型被迫学习图像的全局上下文，而不是依赖于特定的视觉特征。
# 这种方法在训练深度学习模型时被证明是有效的，特别是在目标检测和图像识别任务中。26.def pastein(image, labels, sample_labels, sample_images, sample_masks):
# 这段代码定义了一个名为 pastein 的函数，它实现了一种称为 Cutout 的数据增强技术，用于改善卷积神经网络（CNN）的泛化能力。Cutout 通过在训练期间随机遮盖输入图像的正方形区域来增加模型的鲁棒性。
# 这个函数的目的是将从其他图像中采样的对象（由 sample_images 和 sample_masks 表示）粘贴到当前处理的图像上，从而模拟对象被遮挡的情况。
# 定义了函数 pastein ，它接受五个参数。
# 1.image ：当前处理的图像。
# 2.labels ：当前图像的标签。
# 3.sample_labels ：采样图像的标签。
# 4.sample_images ：采样图像的内容。
# 5.sample_masks ：采样图像的掩码。
def pastein(image, labels, sample_labels, sample_images, sample_masks):
# 应用图像剪切增强 https://arxiv.org/abs/1708.04552。
# Applies image cutout augmentation https://arxiv.org/abs/1708.04552
# 获取图像的高度和宽度。
h, w = image.shape[:2]
# create random masks 创建随机掩膜。
# 定义了一个列表，包含了不同的概率和大小比例，用于确定遮盖区域的大小。
# 这个列表包含了以下几种比例 ：
# 0.75 出现 2 次，意味着有 2 个遮盖区域的大小将是图像大小的 75%。
# 0.5 出现 4 次，意味着有 4 个遮盖区域的大小将是图像大小的 50%。
# 0.25 出现 4 次，意味着有 4 个遮盖区域的大小将是图像大小的 25%。
# 0.125 出现 4 次，意味着有 4 个遮盖区域的大小将是图像大小的 12.5%。
# 0.0625 出现 6 次，意味着有 6 个遮盖区域的大小将是图像大小的 6.25%。
# 这种分布设置使得较小的遮盖区域更常见，而较大的遮盖区域较少见。这样的设计可能是为了模拟在真实世界中，对象被遮挡的程度是多种多样的，并且较小的遮挡更为常见。
# 在实际应用中，代码会随机选择这些比例值之一来确定遮盖区域的大小，然后根据这个比例值计算遮盖区域的具体尺寸（高度和宽度）。这种方法增加了数据增强的随机性和多样性，有助于训练更加鲁棒的模型。
scales = [0.75] * 2 + [0.5] * 4 + [0.25] * 4 + [0.125] * 4 + [0.0625] * 6 # image size fraction 图像尺寸分数。
# 遍历 scales 列表，对每个比例进行操作。
for s in scales:
# 以 80% 的概率跳过当前比例，这是一种随机性引入，以增加数据增强的多样性。
if random.random() < 0.2:
continue
# mask_h 和 mask_w 随机确定遮盖区域的高度和宽度。
mask_h = random.randint(1, int(h * s))
mask_w = random.randint(1, int(w * s))
# box
# xmin 、 ymin 、 xmax 、 ymax 计算遮盖区域的坐标。
xmin = max(0, random.randint(0, w) - mask_w // 2)
ymin = max(0, random.randint(0, h) - mask_h // 2)
xmax = min(w, xmin + mask_w)
ymax = min(h, ymin + mask_h)
# 创建一个包含遮盖区域坐标的数组。
box = np.array([xmin, ymin, xmax, ymax], dtype=np.float32)
if len(labels):
# 计算遮盖区域与现有标签的交集面积比（IOA）。
# def bbox_ioa(box1, box2): -> 用于计算一个边界框（ box1 ）与一组边界框（ box2 ）之间的交并比（Intersection over Area, IoA）。返回 IoA 值，表示 box1 与 box2 中每个边界框的交并比。 -> return inter_area / box2_area
ioa = bbox_ioa(box, labels[:, 1:5]) # intersection over area 交集面积比（IOA）。
else:
ioa = np.zeros(1)
# 确保遮盖区域不与现有标签重叠过多（<30%），并且采样队列中有足够的对象，同时遮盖区域的尺寸足够大。
# ioa < 0.30 ： ioa 代表 Intersection over Area，即遮盖区域与图像中现有标签的交集面积比。这个条件检查遮盖区域与任何现有标签的 IOA 是否小于 0.30。
# 如果小于 0.30，意味着遮盖区域与现有标签的重叠面积不超过 30%，这有助于确保遮盖区域不会覆盖太多已有的重要信息。
# .all() ：这个函数用于确保 ioa < 0.30 这个条件对所有标签都成立。如果图像中有多个标签，那么这个条件必须对每个标签都为真，才能继续执行粘贴操作。
# len(sample_labels) ：这个条件检查 sample_labels 列表是否非空，即是否有可用的采样标签。如果列表为空，表示没有对象可以粘贴，因此不执行粘贴操作。
# (xmax > xmin+20) and (ymax > ymin+20) ：这两个条件确保遮盖区域的宽度和高度都大于 20 个像素。这是为了确保遮盖区域足够大，可以容纳粘贴的对象。如果遮盖区域太小，粘贴的对象可能会被裁剪或不完整。
# 只有当所有这些条件都满足时，代码才会选择一个采样对象，并将其粘贴到遮盖区域。这样做的目的是确保粘贴操作不会过多地干扰图像中已有的重要信息，并且粘贴的对象有足够的空间显示。这种策略有助于提高模型对遮挡和不完整信息的鲁棒性。
if (ioa < 0.30).all() and len(sample_labels) and (xmax > xmin+20) and (ymax > ymin+20): # allow 30% obscuration of existing labels 允许现有标签遮挡 30%。
# 从采样队列中随机选择一个对象。
sel_ind = random.randint(0, len(sample_labels)-1)
#print(len(sample_labels))
#print(sel_ind)
#print((xmax-xmin, ymax-ymin))
#print(image[ymin:ymax, xmin:xmax].shape)
#print([[sample_labels[sel_ind], *box]])
#print(labels.shape)
hs, ws, cs = sample_images[sel_ind].shape
# r_scale 、 r_w 、 r_h 计算采样对象的缩放尺寸，以适应遮盖区域。
r_scale = min((ymax-ymin)/hs, (xmax-xmin)/ws)
r_w = int(ws*r_scale)
r_h = int(hs*r_scale)
# 确保缩放后的采样对象尺寸足够大。
if (r_w > 10) and (r_h > 10):
# r_mask 和 r_image 缩放采样对象的掩码和图像。
r_mask = cv2.resize(sample_masks[sel_ind], (r_w, r_h))
r_image = cv2.resize(sample_images[sel_ind], (r_w, r_h))
# temp_crop 获取当前图像的一个区域，准备替换其中的像素。
temp_crop = image[ymin:ymin+r_h, xmin:xmin+r_w]
# 找到掩码中非零的像素位置。
m_ind = r_mask > 0
# 确保掩码中有足够的像素点。
if m_ind.astype(np.int).sum() > 60:
# 将采样对象的像素复制到当前图像的遮盖区域。
temp_crop[m_ind] = r_image[m_ind]
#print(sample_labels[sel_ind])
#print(sample_images[sel_ind].shape)
#print(temp_crop.shape)
box = np.array([xmin, ymin, xmin+r_w, ymin+r_h], dtype=np.float32)
if len(labels):
# 更新标签信息，包括新粘贴的对象。
labels = np.concatenate((labels, [[sample_labels[sel_ind], *box]]), 0)
else:
labels = np.array([[sample_labels[sel_ind], *box]])
# 更新当前图像的遮盖区域。
image[ymin:ymin+r_h, xmin:xmin+r_w] = temp_crop
# 返回更新后的标签。
return labels
# 这个函数通过在图像上随机遮盖区域并从其他图像中粘贴对象来模拟遮挡，从而增强模型对遮挡的鲁棒性。这种方法可以提高模型在实际应用中的表现，尤其是在面对遮挡和不完整信息时。27.class Albumentations:
# 这段代码定义了一个名为 Albumentations 的类，它用于在使用 YOLOv5 目标检测模型时，通过 Albumentations 库来应用数据增强技术。Albumentations 是一个快速且灵活的图像增强库，它提供了许多用于图像预处理和增强的方法。
class Albumentations:
# YOLOv5 Albumentations 类（可选，仅在安装了包时使用）
# YOLOv5 Albumentations class (optional, only used if package is installed)
def __init__(self):
# self.transform 初始化为 None 。
self.transform = None
# 使用 import albumentations as A 导入 Albumentations 库。
import albumentations as A
# 定义数据增强的组合。
# 使用 A.Compose 创建一个数据增强的组合，其中包括 ：
self.transform = A.Compose([
# 对比度受限的自适应直方图均衡化，概率为 0.01。
A.CLAHE(p=0.01),
# 随机调整亮度和对比度，概率为 0.01。
A.RandomBrightnessContrast(brightness_limit=0.2, contrast_limit=0.2, p=0.01),
# 随机调整图像的伽马值，概率为 0.01。
A.RandomGamma(gamma_limit=[80, 120], p=0.01),
# 模糊图像，概率为 0.01。
A.Blur(p=0.01),
# 中值滤波模糊图像，概率为 0.01。
A.MedianBlur(p=0.01),
# 将图像转换为灰度图，概率为 0.01。
A.ToGray(p=0.01),
# 图像压缩，概率为 0.01。
A.ImageCompression(quality_lower=75, p=0.01),],
# bbox_params 参数设置为 A.BboxParams(format='pascal_voc', label_fields=['class_labels']) ，指定边界框参数和标签字段。
bbox_params=A.BboxParams(format='pascal_voc', label_fields=['class_labels']))
#logging.info(colorstr('albumentations: ') + ', '.join(f'{x}' for x in self.transform.transforms if x.p))
def __call__(self, im, labels, p=1.0):
# 检查是否应用变换。如果 self.transform 不为 None 且随机数小于 p ，则应用数据增强。
if self.transform and random.random() < p:
# 应用数据增强。 使用 self.transform 对图像 im 和标签 labels 应用数据增强。
# labels[:, 1:] ：提取边界框坐标。
# labels[:, 0] ：提取类别标签。
new = self.transform(image=im, bboxes=labels[:, 1:], class_labels=labels[:, 0]) # transformed
# 更新图像和标签。从增强后的输出中提取新的图像和标签。
# new['image'] ：获取增强后的图像。
# new['class_labels'] 和 new['bboxes'] ：获取增强后的类别标签和边界框坐标。
# 使用 zip 和 列表推导式 重新组合类别标签和边界框坐标。
im, labels = new['image'], np.array([[c, *b] for c, b in zip(new['class_labels'], new['bboxes'])])
# 返回 增强后的图像 im 和 更新后的标签 labels 。
return im, labels
# 这个类的设计使得在训练 YOLOv5 模型时可以灵活地应用多种数据增强技术，以提高模型的泛化能力和鲁棒性。28.def create_folder(path='./new'):
# 这段代码定义了一个名为 create_folder 的函数，它用于创建一个新的文件夹。如果指定的路径已经存在，该函数会先删除现有的文件夹，然后创建一个新的空文件夹。
# 1.create_folder ：是函数名。
# 2.path ：是函数的参数，默认值为 './new' ，表示文件夹的路径。
def create_folder(path='./new'):
# Create folder 创建文件夹。
# 检查路径是否存在。使用 os.path.exists(path) 检查指定路径的文件夹是否存在。
if os.path.exists(path):
# shutil.rmtree(path, ignore_errors=False, onerror=None)
# shutil.rmtree 是 Python 标准库 shutil 模块中的一个函数，用于递归地删除一个目录以及其中的所有内容。这个函数会删除指定的目录，包括其中的所有子目录和文件，以及这些子目录和文件的所有内容。
# 参数 ：
# path : 要删除的目录的路径。这个路径可以是字符串或者 Path 对象。
# ignore_errors (可选): 如果设置为 True ，则在删除文件或目录时，如果遇到任何错误（例如权限错误）， shutil.rmtree 会忽略这些错误。默认值为 False ，即在遇到错误时会抛出异常。
# onerror (可选): 一个回调函数，用于处理在删除过程中遇到的错误。
# 这个回调函数会接收三个参数 ：函数（即 onerror 本身）、路径和异常信息。如果提供了 onerror 回调函数，那么即使 ignore_errors 设置为 False ，也不会抛出异常，而是调用回调函数来处理错误。
# 注意事项 ：
# 使用 shutil.rmtree 时要非常小心，因为它会永久删除文件和目录，这个操作是不可逆的。
# 确保在调用 shutil.rmtree 之前，你确实希望删除指定的目录及其所有内容。
# 如果你只想删除空目录，可以使用 os.rmdir 或 pathlib.Path.rmdir 方法。 shutil.rmtree 是一个强大的工具，但也需要谨慎使用，以避免意外删除重要数据。
# 删除现有文件夹。如果文件夹存在，使用 shutil.rmtree(path) 删除整个文件夹及其内容。 shutil 是 Python 的一个标准库，用于文件和文件集合的高级操作。
shutil.rmtree(path) # delete output folder 删除输出文件夹。
# 创建新文件夹。使用 os.makedirs(path) 创建一个新的文件夹。 os 是 Python 的一个标准库，提供了许多与操作系统交互的功能。
os.makedirs(path) # make new output folder 创建新的输出文件夹。
# 这个函数非常有用，特别是在处理需要频繁创建和删除输出文件夹的场景，例如在机器学习或数据处理项目中，每次运行实验或处理数据时都需要一个新的输出目录。
29.def flatten_recursive(path='../coco'):
# 这段代码定义了一个名为 flatten_recursive 的函数，其目的是将一个递归目录（即包含子目录的目录）中的所有文件移动到一个新的目录中，使得所有文件都在新目录的顶级位置，没有子目录。
# 1.path ：是函数的参数，默认值为 '../coco' ，表示要扁平化的目录的路径。
def flatten_recursive(path='../coco'):
# 通过将所有文件移至顶层来展平递归目录。
# Flatten a recursive directory by bringing all files to top level
# 创建新目录。
# 使用 Path 对象创建一个新的目录路径，新目录的名称是原始目录名称后加上 _flat 。
new_path = Path(path + '_flat')
# 调用 create_folder 函数（如之前定义）来创建这个新目录。
# def create_folder(path='./new'): -> 用于创建一个新的文件夹。如果指定的路径已经存在，该函数会先删除现有的文件夹，然后创建一个新的空文件夹。
create_folder(new_path)
# tqdm(iterable=None, desc='', total=None, leave=True, unit='it', unit_scale=False, position=0, initial=0, disable=False, gui=False, **kwargs)
# tqdm 是一个快速、可扩展的Python进度条库，可以在长循环中添加一个进度条，以便用户实时查看迭代进度。它适用于命令行界面和Jupyter笔记本。
# tqdm 可以作为一个上下文管理器使用，也可以作为一个函数调用。
# 参数 ：
# iterable : 要包装的迭代器对象。如果为 None ，则需要提供 total 参数。
# desc : 进度条前的描述字符串。
# total : 迭代次数。如果提供，将用于显示整体进度。
# leave : 决定进度条在完成时是否消失。默认为 True ，即进度条在完成时消失。
# unit : 迭代单位的名称，默认为 'it' 。
# unit_scale : 是否自动选择合适的单位（如从 'it' 到 'kt' ）。
# position : 进度条在屏幕上的位置。
# initial : 迭代器的初始位置。
# disable : 是否禁用进度条。
# gui : 是否为图形用户界面（GUI）模式。
# **kwargs : 其他参数，用于自定义进度条的外观。
# 注意事项 ：
# tqdm 在命令行界面中效果最佳。
# 在Jupyter笔记本中，可以使用 tqdm.notebook.tqdm 来获得更好的显示效果。
# tqdm 也可以用于其他类型的迭代器，如文件对象等。
# tqdm 是一个非常实用的库，可以帮助用户在处理长时间运行的任务时更好地了解进度。
# 遍历原始目录中的所有文件。
# 使用 glob.glob 函数配合通配符 **/*.* 来匹配原始目录及其所有子目录中的所有文件。
# recursive=True 参数使得搜索是递归的，即包括所有子目录。
# tqdm 是一个进度条库，用于在控制台显示文件复制的进度。
for file in tqdm(glob.glob(str(Path(path)) + '/**/*.*', recursive=True)):
# 复制文件到新目录。
# 使用 shutil.copyfile 函数将每个文件从原始位置复制到新目录。
# new_path / Path(file).name 构造了新目录中的文件路径，其中 Path(file).name 获取原始文件的名称。
shutil.copyfile(file, new_path / Path(file).name)30.def extract_boxes(path='../coco/'):
# 这段代码是用于从目标检测数据集中提取边界框，并将其转换为分类数据集的函数。这个函数用于处理COCO数据集。
# 定义了一个函数 extract_boxes ，它接受一个参数。
# 1.path ：指定了数据集的路径，默认为 ../coco/ 。
def extract_boxes(path='../coco/'): # from utils.datasets import *; extract_boxes('../coco128') 从 utils.datasets 导入 *；extract_boxes('../coco128')。
# 将检测数据集转换为分类数据集，每个类一个目录。
# Convert detection dataset into classification dataset, with one directory per class
# 将传入的路径转换为 Path 对象，以便使用路径操作。
path = Path(path) # images dir 图片目录。
# shutil.rmtree(path, ignore_errors=False, onerror=None)
# shutil.rmtree 是 Python 标准库 shutil 模块中的一个函数，用于递归地删除一个目录以及其中的所有内容。这个函数会删除指定的目录，包括其中的所有子目录和文件，以及这些子目录和文件的所有内容。
# 参数 ：
# path : 要删除的目录的路径。这个路径可以是字符串或者 Path 对象。
# ignore_errors (可选): 如果设置为 True ，则在删除文件或目录时，如果遇到任何错误（例如权限错误）， shutil.rmtree 会忽略这些错误。默认值为 False ，即在遇到错误时会抛出异常。
# onerror (可选): 一个回调函数，用于处理在删除过程中遇到的错误。
# 这个回调函数会接收三个参数 ：函数（即 onerror 本身）、路径和异常信息。如果提供了 onerror 回调函数，那么即使 ignore_errors 设置为 False ，也不会抛出异常，而是调用回调函数来处理错误。
# 注意事项 ：
# 使用 shutil.rmtree 时要非常小心，因为它会永久删除文件和目录，这个操作是不可逆的。
# 确保在调用 shutil.rmtree 之前，你确实希望删除指定的目录及其所有内容。
# 如果你只想删除空目录，可以使用 os.rmdir 或 pathlib.Path.rmdir 方法。 shutil.rmtree 是一个强大的工具，但也需要谨慎使用，以避免意外删除重要数据。
# 如果 classifier 目录存在，则删除它。这是为了确保每次运行函数时，分类数据集目录都是从零开始构建的。
shutil.rmtree(path / 'classifier') if (path / 'classifier').is_dir() else None # remove existing
# pathlib.Path.rglob(pattern)
# rglob 是 Python pathlib 模块中的 Path 类的一个方法，用于递归地搜索给定目录下所有匹配特定模式的文件路径。
# 参数 :
# pattern ：一个字符串，表示要匹配的文件模式。这个模式遵循 Unix shell 的规则，例如 *.txt 会匹配所有以 .txt 结尾的文件。
# 返回值 :
# 返回一个生成器（generator），生成所有匹配模式的 Path 对象。
# rglob 方法是一个非常方便的工具，用于文件搜索和目录遍历，它允许你以一种简洁的方式获取所有匹配特定模式的文件路径。
# 递归地获取路径下所有文件，并存储在 files 列表中。
files = list(path.rglob('*.*'))
# 获取文件总数，用于 tqdm 进度条。
n = len(files) # number of files 文件数量。
# 遍历所有文件，并显示进度条。
for im_file in tqdm(files, total=n):
# 检查文件是否为图像格式（ img_formats 是一个包含图像文件扩展名的列表）。
if im_file.suffix[1:] in img_formats:
# image 图片。
# 读取图像文件，并将其从BGR（OpenCV的默认颜色顺序）转换为RGB。
im = cv2.imread(str(im_file))[..., ::-1] # BGR to RGB
# 获取图像的高度和宽度。
h, w = im.shape[:2]
# labels 标签。
# 获取与当前图像文件对应的标签文件路径。
# def img2label_paths(img_paths):
# -> 函数接受一个图像文件路径列表 img_paths ，并返回对应的标签文件路径列表。这是一个列表推导式，用于转换每个图像路径 x 到对应的标签路径。
# -> return ['txt'.join(x.replace(sa, sb, 1).rsplit(x.split('.')[-1], 1)) for x in img_paths]
lb_file = Path(img2label_paths([str(im_file)])[0])
# 检查标签文件是否存在。
if Path(lb_file).exists():
# 打开标签文件。
with open(lb_file, 'r') as f:
# 读取标签文件内容，并将其转换为浮点数数组。
lb = np.array([x.split() for x in f.read().strip().splitlines()], dtype=np.float32) # labels
# 遍历每个标签。
# enumerate(lb) 遍历 lb 数组，它包含当前图像文件的所有边界框信息。
# j :是边界框的索引。
# x :是当前边界框的数据，通常包含类别ID和边界框的坐标。
for j, x in enumerate(lb):
# 获取类别ID。
c = int(x[0]) # class
# 构建新文件的路径，该文件将存储裁剪后的图像。
# path / 'classifier' ：指定了分类数据集的根目录。
# f'{c}' ：类别ID对应的目录。
# f'{path.stem}_{im_file.stem}_{j}.jpg' ：新图像文件的名称，由原始图像文件的名称、类别ID和边界框索引组成。
f = (path / 'classifier') / f'{c}' / f'{path.stem}_{im_file.stem}_{j}.jpg' # new filename
if not f.parent.is_dir():
# 检查新文件的父目录是否存在，如果不存在，则创建它。 parents=True 参数确保创建所有必要的中间目录。
f.parent.mkdir(parents=True)
# 提取边界框的坐标（不包括类别ID），并将其乘以图像的宽度和高度。这通常是将边界框坐标从归一化形式转换为实际像素坐标。
b = x[1:] * [w, h, w, h] # box
# b[2:] = b[2:].max() # rectangle to square 矩形转正方形。
# 对边界框的宽度和高度进行扩展。这里，边界框的宽度和高度被放大了20%，并增加了3个像素的填充。这样做可以确保在裁剪图像时，目标对象周围有一些额外的空间，有助于分类模型的训练。
b[2:] = b[2:] * 1.2 + 3 # pad
# numpy.ndarray.ravel()
# ravel() 函数是 NumPy 库中的一个方法，它将多维数组（ndarray）展平成一维数组。这个方法不会复制数组的数据，而是返回一个新的视图（view），这个视图与原始数组共享相同的数据。
# 参数 :
# order ：可选参数，指定展平的顺序。默认是 'C'，表示按行主序（C-style），即按列优先顺序展平。如果设置为 'F'，则表示按列主序（Fortran-style），即按行优先顺序展平。如果设置为 'A'，则保持数组的原始顺序。
# 返回值 :
# 返回一个展平后的一维数组。
# 将边界框从中心点和宽高表示转换为左上角和右下角坐标表示。
# def xywh2xyxy(x): -> 用于将边界框的坐标从中心点坐标加宽高（x, y, w, h）格式转换为两个角点坐标（x1, y1, x2, y2）格式。返回转换后的坐标数组。 -> return y
b = xywh2xyxy(b.reshape(-1, 4)).ravel().astype(np.int)
# 确保边界框坐标不会超出图像边界。
b[[0, 2]] = np.clip(b[[0, 2]], 0, w) # clip boxes outside of image 图像外的剪辑框。
b[[1, 3]] = np.clip(b[[1, 3]], 0, h)
# 将裁剪后的图像保存到新文件中，并断言操作成功。
assert cv2.imwrite(str(f), im[b[1]:b[3], b[0]:b[2]]), f'box failure in {f}'
# 这个函数的目的是将目标检测数据集中的图像和标签转换为分类数据集，每个类别一个目录，目录中包含该类别的裁剪图像。这对于训练分类模型是有用的。31.def autosplit(path='../coco', weights=(0.9, 0.1, 0.0), annotated_only=False):
# 这段代码定义了一个名为 autosplit 的函数，它用于自动将数据集分割成训练集（train）、验证集（val）和测试集（test），并将分割结果保存为文本文件。
# 1.path ：数据集图像目录的路径，默认为 ../coco 。
# 2.weights ：一个元组，表示训练集、验证集和测试集的比例，默认为 (0.9, 0.1, 0.0) ，意味着90%的数据用于训练，10%用于验证，0%用于测试。
# 3.annotated_only ：一个布尔值，表示是否只使用有标注文件的图像，默认为 False 。
def autosplit(path='../coco', weights=(0.9, 0.1, 0.0), annotated_only=False):
# 自动将数据集拆分为训练/验证/测试拆分并保存 path/autosplit_*.txt 文件。
""" Autosplit a dataset into train/val/test splits and save path/autosplit_*.txt files
Usage: from utils.datasets import *; autosplit('../coco')
Arguments
path: Path to images directory
weights: Train, val, test weights (list)
annotated_only: Only use images with an annotated txt file
"""
# 将传入的路径转换为 Path 对象。
path = Path(path) # images dir
# 使用 rglob 递归搜索所有图像文件， img_formats 是一个包含支持的图像扩展名的列表。
files = sum([list(path.rglob(f"*.{img_ext}")) for img_ext in img_formats], []) # image files only 仅限图像文件。
# 计算图像文件的总数。
n = len(files) # number of files
# 使用 random.choices 根据提供的权重随机分配每个图像到训练集、验证集或测试集中。
indices = random.choices([0, 1, 2], weights=weights, k=n) # assign each image to a split 将每个图像分配给一个分割。
# 定义三个文本文件名，用于存储分割结果。
txt = ['autosplit_train.txt', 'autosplit_val.txt', 'autosplit_test.txt'] # 3 txt files 自动分割训练.txt' '自动分割值.txt' '自动分割测试.txt
# pathlib.Path.unlink()
# 在 Python 中， .unlink() 方法是 pathlib 模块的 Path 类的一个方法，用于删除指定的文件。如果路径指向的是一个文件， unlink() 方法会将其删除；如果路径指向的是一个目录，那么在没有错误的情况下，该目录必须为空才能被删除。
# 参数 ：没有参数。
# 返回值 ：没有返回值。
# 异常 ：
# 如果文件不存在，会抛出 FileNotFoundError 。
# 如果路径是一个非空目录，会抛出 IsADirectoryError 。
# 如果路径存在但是不是一个文件或目录，会抛出 OSError 。
# 如果分割结果文件已存在，则删除它们。
[(path / x).unlink() for x in txt if (path / x).exists()] # remove existing
# 打印分割信息。
print(f'Autosplitting images from {path}' + ', using *.txt labeled images only' * annotated_only) # 自动分割来自 {path}' + ' 的图像，仅使用 *.txt 标记图像' * annotated_only。
# 遍历图像文件和对应的分割索引，并显示进度条。
for i, img in tqdm(zip(indices, files), total=n):
# 如果 annotated_only 为 False ，或者对应的标注文件存在，则执行以下操作。
# # def img2label_paths(img_paths): -> 这个 img2label_paths 函数接受一个图像文件路径列表 img_paths ，并返回对应的标签文件路径列表。 -> return ['txt'.join(x.replace(sa, sb, 1).rsplit(x.split('.')[-1], 1)) for x in img_paths]
if not annotated_only or Path(img2label_paths([str(img)])[0]).exists(): # check label
# 打开对应的分割结果文件。
with open(path / txt[i], 'a') as f:
# 将图像文件的路径写入对应的分割结果文件。
f.write(str(img) + '\n') # add image to txt file
# 这个函数的目的是简化数据集的分割过程，使得用户可以通过简单的命令自动分割数据集，并根据需要调整训练集、验证集和测试集的比例。这对于机器学习和深度学习项目中的数据处理非常有用。32.def load_segmentations(self, index):
# 这段代码定义了一个函数 load_segmentations ，它是一个类的方法，用于根据给定的索引 index 加载对应的分割数据。
# 1.self ：指向类的实例，允许访问类的属性和方法。
# 2.index ：一个整数，表示要加载的分割数据的索引。
def load_segmentations(self, index):
# 构造一个键（ key ），这个键是文件路径的一部分，用于从某个数据结构中检索分割数据。
# self.img_files 是一个列表，存储了图像文件的名称或路径， index 参数用于从这个列表中选择特定的文件。
key = '/work/handsomejw66/coco17/' + self.img_files[index]
# 这是一个被注释掉的打印语句，如果取消注释，它会打印出构造的键。
#print(key)
# /work/handsomejw66/coco17/
# 返回 self.segs 字典中与 key 对应的值，这个值就是所需的分割数据。
# self.segs 是一个字典，它存储了图像文件名或路径与对应的分割数据之间的映射。
return self.segs[key]
# 这个函数的作用是从一个类的实例中，根据提供的索引加载对应的分割数据。这通常用于图像分割任务中，其中分割数据可能以掩码或像素级标签的形式存在，用于指示图像中每个像素的类别。