utils.py
ultralytics\data\utils.py
目录
utils.py
1.所需的库和模块
2.def img2label_paths(img_paths):
3.def get_hash(paths):
4.def exif_size(img: Image.Image):
5.def verify_image(args):
6.def verify_image_label(args):
7.def polygon2mask(imgsz, polygons, color=1, downsample_ratio=1):
8.def polygons2masks(imgsz, polygons, color, downsample_ratio=1):
9.def polygons2masks_overlap(imgsz, segments, downsample_ratio=1):
10.def find_dataset_yaml(path: Path) -> Path:
11.def check_det_dataset(dataset, autodownload=True):
12.def check_cls_dataset(dataset, split=""):
13.class HUBDatasetStats:
14.def compress_one_image(f, f_new=None, max_dim=1920, quality=50):
15.def autosplit(path=DATASETS_DIR / "coco8/images", weights=(0.9, 0.1, 0.0), annotated_only=False):
16.def load_dataset_cache_file(path):
17.def save_dataset_cache_file(prefix, path, x, version):
1.所需的库和模块
# Ultralytics YOLO 🚀, AGPL-3.0 licenseimport contextlib
import hashlib
import json
import os
import random
import subprocess
import time
import zipfile
from multiprocessing.pool import ThreadPool
from pathlib import Path
from tarfile import is_tarfileimport cv2
import numpy as np
from PIL import Image, ImageOpsfrom ultralytics.nn.autobackend import check_class_names
from ultralytics.utils import (DATASETS_DIR,LOGGER,NUM_THREADS,ROOT,SETTINGS_FILE,TQDM,clean_url,colorstr,emojis,is_dir_writeable,yaml_load,yaml_save,
)
from ultralytics.utils.checks import check_file, check_font, is_ascii
from ultralytics.utils.downloads import download, safe_download, unzip_file
from ultralytics.utils.ops import segments2boxesHELP_URL = "See https://docs.ultralytics.com/datasets for dataset formatting guidance."
# IMG_FORMATS 集合包含了常见的图像文件格式。这些格式用于存储动态视频内容。
IMG_FORMATS = {"bmp", "dng", "jpeg", "jpg", "mpo", "png", "tif", "tiff", "webp", "pfm"} # image suffixes
# VID_FORMATS 集合包含了常见的视频文件格式。这些格式用于存储动态视频内容。
# 这些集合可以用于文件类型的识别，例如在处理文件上传或下载时，可以通过检查文件后缀名是否在这些集合中来判断文件是否为图像或视频文件。
VID_FORMATS = {"asf", "avi", "gif", "m4v", "mkv", "mov", "mp4", "mpeg", "mpg", "ts", "wmv", "webm"} # video suffixes
# 这行代码是 Python 中的一个表达式，用于确定一个名为 PIN_MEMORY 的变量的值。这个变量通常用于配置 PyTorch 的 DataLoader ，以决定是否将数据加载到 CUDA 固定内存中。
# os.getenv("PIN_MEMORY", True) ：这是一个调用操作系统环境变量的函数，它尝试获取名为 PIN_MEMORY 的环境变量的值。如果该环境变量不存在，它将返回默认值 True 。
# str(...) ：将 os.getenv 函数的返回值转换为字符串。这是因为环境变量可以是任何类型，而 str.lower() 方法需要一个字符串作为输入。
# ....lower() == "true" ：将字符串转换为小写，并检查它是否等于字符串 "true" 。这是一个布尔表达式，如果字符串是 "true" （不区分大小写），则返回 True ；否则返回 False 。
# 综上所述，这行代码的作用是检查环境变量 PIN_MEMORY 是否被设置为 "true" （不区分大小写）。如果是， PIN_MEMORY 变量将被设置为 True ；否则，它将被设置为 False 。
PIN_MEMORY = str(os.getenv("PIN_MEMORY", True)).lower() == "true" # global pin_memory for dataloaders
FORMATS_HELP_MSG = f"Supported formats are:\nimages: {IMG_FORMATS}\nvideos: {VID_FORMATS}" # 支持的格式包括：\n图像：{IMG_FORMATS}\n视频：{VID_FORMATS}。2.def img2label_paths(img_paths):
# 这段代码定义了一个名为 img2label_paths 的函数，它将图像文件路径转换为对应的标签文件路径。这个函数假设图像文件和标签文件存放在不同的目录中，通常在计算机视觉项目中，图像和对应的标签（例如，边界框、分割掩码等）会被分别存储。
# 定义了一个函数 img2label_paths ，它接受一个参数。
# 1.img_paths ：这是一个包含图像文件路径的列表。
def img2label_paths(img_paths):# 将标签路径定义为图像路径的函数。"""Define label paths as a function of image paths."""# 创建两个字符串 sa 和 sb ，分别代表图像目录和标签目录的路径片段。 os.sep 是操作系统特定的路径分隔符（例如，在Windows上是 \ ，在Unix/Linux上是 / ）。sa, sb = f"{os.sep}images{os.sep}", f"{os.sep}labels{os.sep}" # /images/, /labels/ substrings# 这是一个列表推导式，用于转换每个图像路径 x 到对应的标签路径。# x.rsplit(sa, 1) ：从路径 x 的右侧开始分割，分割一次，分割出图像目录后的部分。# sb.join(...) ：将分割后的路径与标签目录路径 sb 连接起来。# .rsplit(".", 1)[0] ：再次从右侧分割路径，分割出文件扩展名之前的部分（即没有扩展名的文件名）。# + ".txt" ：在文件名后添加 .txt 扩展名，因为标签文件通常以 .txt 结尾。return [sb.join(x.rsplit(sa, 1)).rsplit(".", 1)[0] + ".txt" for x in img_paths]
# 例如，如果一个图像文件的路径是 /images/class1/001.jpg ，对应的标签文件路径将会是 /labels/class1/001.txt 。
# 这个函数的作用是自动化地根据图像文件路径生成标签文件路径，这样可以在读取图像和标签时减少重复的路径操作，使得代码更加简洁和易于维护。3.def get_hash(paths):
# 这段代码定义了一个名为 get_hash 的函数，它用于计算一个包含文件或目录路径列表的单一哈希值。这个哈希值可以用来验证文件列表的完整性，因为即使是微小的变化也会导致哈希值的显著变化。
# 定义了一个函数 get_hash ，它接受一个参数。
# 1.paths ：这是一个包含文件或目录路径的列表。
def get_hash(paths):# 返回路径列表（文件或目录）的单个哈希值。"""Returns a single hash value of a list of paths (files or dirs)."""# 计算列表中所有存在的文件的大小之和。 os.path.getsize(p) 获取文件 p 的大小， if os.path.exists(p) 确保只计算实际存在的文件的大小。size = sum(os.path.getsize(p) for p in paths if os.path.exists(p)) # sizes# hashlib.sha256([data])# hashlib.sha256() 函数是 Python 标准库 hashlib 模块中的一个函数，用于创建一个 SHA-256 哈希对象。SHA-256 是一种加密哈希函数，可以将任意长度的数据转换为一个固定长度（256位，即32字节）的唯一哈希值。# 参数 ：# data ：（可选）一个初始字节序列，用于初始化哈希对象。如果不提供此参数，则创建一个空的哈希对象。# 返回值 :# 返回一个新的 sha256 哈希对象。# 方法 :# 创建 sha256 哈希对象后，你可以使用以下方法 :# update(data) ：向哈希对象添加数据。 data 必须是字节序列或字节数组。# digest() ：返回当前哈希对象的二进制（十六进制编码）哈希值。# hexdigest() ：返回当前哈希对象的十六进制编码哈希值。# copy() ：返回当前哈希对象的一个副本。# hashlib.sha256() 函数在需要确保数据完整性、生成数据签名或验证数据未被篡改时非常有用。它是许多安全应用程序和协议中的一个基本组件。# str.encode(encoding='utf-8', errors='strict')# 在 Python 中， encode() 函数是一个字符串方法，它用于将字符串转换为特定编码的字节序列。这个方法对于处理文本数据和在不同系统或语言环境中传输数据时确保字符编码的一致性非常重要。# 参数 ：# encoding ：（可选）指定用于编码的字符集，默认为 'utf-8' 。常见的编码还包括 'ascii' 、 'latin-1' 、 'iso-8859-1' 等。# errors ：（可选）指定如何处理编码错误。默认为 'strict' ，这意味着在遇到编码问题时会抛出一个 UnicodeEncodeError 异常。其他选项包括 'ignore' （忽略错误）、 'replace' （用一个特殊字符替换无法编码的字符）等。# 返回值 ：# 返回一个字节对象（ bytes ），包含编码后的字节序列。# encode() 方法是 Python 字符串处理中的一个重要工具，特别是在涉及文件操作、网络通信或与其他系统交互时，确保文本数据的正确编码和解码至关重要。# 使用 Python 的 hashlib 模块创建一个新的 SHA-256 哈希对象 h 。 将文件大小之和转换为字符串，并编码为字节，然后使用 h.update() 方法更新哈希对象。h = hashlib.sha256(str(size).encode()) # hash sizes# 将所有路径连接成一个字符串，并编码为字节。然后更新哈希对象 h ，将路径信息纳入哈希计算。h.update("".join(paths).encode()) # hash paths# 计算最终的哈希值，并以十六进制格式返回。 h.hexdigest() 方法返回哈希对象的十六进制数字表示。return h.hexdigest() # return hash
# 这个函数通过结合文件大小和路径信息来生成一个哈希值，可以用来检测文件列表的任何变化。如果文件或目录的内容或路径发生变化，生成的哈希值也会不同。这使得 get_hash 函数成为一个有用的工具，用于确保数据的一致性和完整性。4.def exif_size(img: Image.Image):
# 这段代码定义了一个名为 exif_size 的函数，它用于获取经过 EXIF 信息校正的 PIL 图像尺寸。这个函数特别处理了 JPEG 图像，因为某些 JPEG 图像的 EXIF 信息中包含了旋转信息，这可能会影响图像的实际显示尺寸。
# 1.img ：输入的 PIL 图像对象。
def exif_size(img: Image.Image):# 返回经过 exif 校正的 PIL 大小。"""Returns exif-corrected PIL size."""# 获取图像的原始尺寸，这是一个元组，形式为 (width, height) 。s = img.size # (width, height)# 检查图像格式是否为 JPEG，因为只有 JPEG 图像可能包含 EXIF 旋转信息。if img.format == "JPEG": # only support JPEG images# 使用 contextlib 模块的 suppress 函数来忽略获取 EXIF 信息时可能发生的任何异常。这是一个异常处理上下文管理器，它允许代码块中的异常被静默处理。with contextlib.suppress(Exception):# PIL.Image.Image.getexif()# getexif() 函数是 Python Imaging Library (PIL) 的一个扩展库 Pillow 中的一个方法，它用于从 PIL 图像对象中提取 EXIF 数据。EXIF 数据包含了数字照片的元数据，例如拍摄设备、拍摄参数、拍摄日期等信息。# 参数 ：# Image ：PIL 或 Pillow 库中的 Image 类的一个实例。# 返回值 :# 返回一个 Exif 对象，该对象包含了图像的 EXIF 数据。这个对象可以像字典一样被访问，其中的键是 EXIF 标签的 ID，值是对应的数据。# 功能 :# getexif() 方法读取图像文件中的 EXIF 信息，并将其作为一个可读写的 Exif 对象返回。这个对象允许你访问、修改和删除 EXIF 信息。# 注意事项 :# EXIF 数据可能包含多个 IFD（Image File Directory）， getexif() 返回的对象默认只访问 IFD0。如果需要访问其他 IFD，可以使用 ExifTags 模块来获取标签的名称，并使用 get_ifd() 方法来访问特定的 IFD。# 某些图像可能不包含 EXIF 数据，或者在图像处理过程中 EXIF 数据可能被剥离，这种情况下 getexif() 方法可能返回 None 。# 尝试获取图像的 EXIF 信息。exif = img.getexif()# 如果图像有 EXIF 信息，继续处理。if exif:# 从 EXIF 信息中获取旋转标签的值。EXIF 键 274 对应于图像的方向（Orientation）标签。rotation = exif.get(274, None) # the EXIF key for the orientation tag is 274# 检查旋转标签的值是否为 6 或 8，这分别代表顺时针旋转 270 度和 90 度。if rotation in {6, 8}: # rotation 270 or 90# 如果图像需要旋转，交换原始尺寸的宽度和高度，以反映旋转后的实际尺寸。s = s[1], s[0]# 返回校正后的图像尺寸。return s
# exif_size 函数会检查 JPEG 图像的 EXIF 信息，并根据其中的旋转信息来调整图像尺寸的顺序，确保返回的尺寸反映了图像的实际显示尺寸。如果图像没有旋转信息或者不是 JPEG 格式，函数将返回原始的图像尺寸。5.def verify_image(args):
# 这段代码定义了一个名为 verify_image 的函数，它用于验证单个图像文件的有效性。这个函数可以作为 ThreadPool 或 ProcessPool 中的一个任务来并行处理数据集中的图像文件。
# 函数定义。
# 1.args ：函数的参数，它是一个元组，包含图像文件路径和类别标签。
def verify_image(args):# 验证一张图片。"""Verify one image."""# 解包参数。从 args 元组中解包 图像文件路径 im_file 和 类别 cls ，同时解包 前缀 prefix 。(im_file, cls), prefix = args# Number (found, corrupt), message# 初始化变量。# nf ：找到的图像数量，初始化为 0。 nc ：损坏的图像数量，初始化为 0。 msg ：消息字符串，初始化为空字符串。nf, nc, msg = 0, 0, ""# 尝试验证图像。# 这段代码是 verify_image 函数的核心部分，它负责验证单个图像文件的有效性。# 开始一个 try 块，用于捕获并处理在验证图像过程中可能发生的任何异常。try:# 使用 PIL（Python Imaging Library）库打开图像文件 im_file ，并将其存储在变量 im 中。im = Image.open(im_file)# im.verify()# 在 Python 的 PIL（Python Imaging Library）库中， .verify() 方法用于验证图像文件的完整性。当处理图像文件时，这个方法尝试确认文件是否未损坏并且可以被正确解码。# im ：一个 PIL Image 对象。# 功能 ：# .verify() 方法检查图像文件是否完整且未损坏。如果文件损坏或无法被识别，这个方法会抛出一个 IOError （输入/输出错误）异常。# 注意事项 ：# .verify() 方法只适用于某些图像格式，特别是那些 PIL 支持的格式。# 这个方法不会检查图像的元数据或内容，只检查图像文件的完整性和可读性。# 在处理大量图像文件时，使用 .verify() 方法可以帮助识别和排除损坏的文件，以避免在后续处理中出现问题。# 调用 PIL 图像对象的 verify() 方法，检查图像文件是否损坏。如果图像文件损坏，此方法将抛出一个 IOError 。im.verify() # PIL verify# 调用 exif_size() 函数获取图像的 EXIF 信息中的大小（宽度和高度）。# def exif_size(img: Image.Image): -> 用于获取经过 EXIF 信息校正的 PIL 图像尺寸。返回校正后的图像尺寸。 -> return sshape = exif_size(im) # image size# 将尺寸从（宽度，高度）格式转换为（高度，宽度）格式，以匹配通常的（高度，宽度）表示。shape = (shape[1], shape[0]) # hw# 使用 assert 语句确保 图像的尺寸 都大于9像素。如果任一维度小于或等于9像素，将抛出一个 AssertionError ，并显示错误消息。assert (shape[0] > 9) & (shape[1] > 9), f"image size {shape} <10 pixels" # 图像大小{形状} <10像素。# 再次使用 assert 语句，确保图像的格式在 IMG_FORMATS 列表中。如果不在，将抛出一个 AssertionError ，并显示错误消息，其中 FORMATS_HELP_MSG 是一个帮助信息。assert im.format.lower() in IMG_FORMATS, f"Invalid image format {im.format}. {FORMATS_HELP_MSG}" # 图像格式 {im.format} 无效。{FORMATS_HELP_MSG}。# 如果图像格式是 JPG 或 JPEG，执行以下操作。if im.format.lower() in {"jpg", "jpeg"}:# 以二进制读取模式打开图像文件，并将其文件对象存储在变量 f 中。with open(im_file, "rb") as f:# 移动文件指针到文件末尾前2个字节。f.seek(-2, 2)# 读取文件的最后两个字节。如果不是 JPEG 格式的结束标记 \xff\xd9 ，则认为 JPEG 文件已损坏。if f.read() != b"\xff\xd9": # corrupt JPEG# PIL.ImageOps.exif_transpose(image, *, in_place=False)# ImageOps.exif_transpose() 函数是 Python Imaging Library (PIL) 的一个扩展库 Pillow 中的一个函数，它用于根据图像的 EXIF 定向标签来调整图像的方向，使得图像按照 EXIF 标签中指定的方向进行正确的显示。如果图像没有 EXIF 定向标签或者标签值为 1（表示图像已经是正确的方向），则返回图像的一个副本。# 参数 ：# image ：要调整方向的 PIL 图像对象。# in_place ：（关键字参数）布尔值，如果设置为 True ，则在原图像对象上进行修改，并返回 None ；如果设置为 False （默认值），则返回一个新的图像对象，原图像对象不变。# 返回值 ：# 如果 in_place 参数为 False （默认），返回一个新的图像对象，该对象根据 EXIF 定向标签调整了方向。# 如果 in_place 参数为 True ，则原图像对象被修改，函数返回 None 。# 功能 ：# 读取图像的 EXIF 信息，特别是 Orientation 标签。# 根据 Orientation 标签的值，确定如何调整图像的方向。# 应用相应的变换（例如旋转、翻转）来调整图像的方向。# 如果 in_place 为 False ，则返回调整方向后的新图像对象；否则，修改原图像对象。# 使用 PIL 的 ImageOps.exif_transpose() 函数来校正图像的方向（基于 EXIF 信息），然后将修复后的图像保存回原文件，设置 JPEG 子采样为0，质量为100。ImageOps.exif_transpose(Image.open(im_file)).save(im_file, "JPEG", subsampling=0, quality=100)# 设置消息 msg ，包含前缀 prefix 、警告符号、图像文件路径和修复操作的描述。msg = f"{prefix}WARNING ⚠️ {im_file}: corrupt JPEG restored and saved" # {prefix}警告⚠️{im_file}：损坏的 JPEG 已恢复并保存。# 将 nf 设置为 1，表示图像已成功验证。nf = 1# 这段代码的目的是确保图像文件未损坏，格式正确，并且对于 JPEG 图像，确保它们有正确的结束标记。如果发现任何问题，代码将尝试修复这些问题，并记录相应的警告消息。如果图像验证成功， nf 将被设置为 1，表示图像有效。如果在验证过程中发生异常，代码将跳转到 except 块进行错误处理。# 异常处理。# 如果在验证过程中发生任何异常，将 nc 设置为 1，表示图像损坏，并记录错误消息。except Exception as e:nc = 1msg = f"{prefix}WARNING ⚠️ {im_file}: ignoring corrupt image/label: {e}" # {prefix}警告⚠️{im_file}：忽略损坏的图像/标签：{e}。# 返回结果。返回一个元组，包含 图像文件路径 和 类别 、找到的 图像数量 、 损坏的图像数量 以及 相关消息 。return (im_file, cls), nf, nc, msg
# 这个函数是数据集验证过程中的关键部分，它确保每个图像文件都是有效的，并且可以被模型正确读取。通过并行处理，可以显著提高数据集验证的效率。6.def verify_image_label(args):
# 这段代码定义了一个名为 verify_image_label 的函数，它用于验证图像和对应的标签文件是否有效。
# 这个函数接受一个参数。
# 1.args ：是一个元组，包含了验证图像和标签对所需的所有参数。
def verify_image_label(args):# 验证一对图像-标签。"""Verify one image-label pair."""# 这段代码是 verify_image_label 函数的开头部分，它执行了两个主要的操作。# 解包参数。# im_file ：图像文件的路径。# lb_file ：标签文件的路径。# prefix ：一个前缀字符串，通常用于打印消息时标识来源。# keypoint ：一个布尔值，表示是否处理关键点数据。# num_cls ：数据集中类别的数量。# nkpt ：关键点的数量（如果 keypoint 为 True ）。# ndim ：每个关键点的维度数（如果 keypoint 为 True ）。im_file, lb_file, prefix, keypoint, num_cls, nkpt, ndim = args# Number (missing, found, empty, corrupt), message, segments, keypoints# 初始化变量。# 接下来，代码初始化了一系列变量，用于在函数执行过程中跟踪和记录状态。# nm ：缺失的标签数量（ number missing ）。# nf ：找到的标签数量（ number found ）。# ne ：空的标签数量（ number empty ）。# nc ：损坏的标签数量（ number corrupt ）。# msg ：用于存储与当前图像-标签对相关的任何消息或警告。# segments ：用于存储段落信息，初始化为空列表。# keypoints ：用于存储关键点信息，初始化为 None 。nm, nf, ne, nc, msg, segments, keypoints = 0, 0, 0, 0, "", [], None# 这些变量将被用来收集关于图像和标签验证状态的信息，例如，如果标签文件缺失， nm 将增加；如果标签文件存在但为空， ne 将增加；如果图像或标签损坏， nc 将增加。# msg 变量用于收集任何警告或错误消息，这些消息可以在函数的最后返回，以供进一步处理或记录。 segments 和 keypoints 变量用于存储与图像相关的特定类型的标签数据，如果适用。# 开始一个 try 块，用于捕获并处理可能发生的任何异常。try:# Verify images# 这段代码是 verify_image_label 函数中用于验证图像文件的部分。# 使用 PIL（Python Imaging Library）库打开图像文件 im_file ，并将其存储在变量 im 中。im = Image.open(im_file)# im.verify()# 在 Python 的 PIL（Python Imaging Library）库中， .verify() 方法用于验证图像文件的完整性。当处理图像文件时，这个方法尝试确认文件是否未损坏并且可以被正确解码。# im ：一个 PIL Image 对象。# 功能 ：# .verify() 方法检查图像文件是否完整且未损坏。如果文件损坏或无法被识别，这个方法会抛出一个 IOError （输入/输出错误）异常。# 注意事项 ：# .verify() 方法只适用于某些图像格式，特别是那些 PIL 支持的格式。# 这个方法不会检查图像的元数据或内容，只检查图像文件的完整性和可读性。# 在处理大量图像文件时，使用 .verify() 方法可以帮助识别和排除损坏的文件，以避免在后续处理中出现问题。# 调用 PIL 图像对象的 verify() 方法，检查图像文件是否损坏。im.verify() # PIL verify# 调用 exif_size() 函数获取图像的 EXIF 信息中的大小（宽度和高度）。# def exif_size(img: Image.Image): -> 用于获取经过 EXIF 信息校正的 PIL 图像尺寸。返回校正后的图像尺寸。 -> return sshape = exif_size(im) # image size# 将尺寸从（宽度，高度）格式转换为（高度，宽度）格式，以匹配通常的（高度，宽度）表示。shape = (shape[1], shape[0]) # hw# 使用 assert 语句确保图像的尺寸都大于9像素。如果任一维度小于或等于9像素，将抛出异常，并显示错误消息。assert (shape[0] > 9) & (shape[1] > 9), f"image size {shape} <10 pixels" # 图像大小{形状} <10像素。# 再次使用 assert 语句，确保图像的格式在 IMG_FORMATS 列表中。如果不在，将抛出异常，并显示错误消息，其中 FORMATS_HELP_MSG 是一个帮助信息。assert im.format.lower() in IMG_FORMATS, f"invalid image format {im.format}. {FORMATS_HELP_MSG}" # 图像格式 {im.format} 无效。{FORMATS_HELP_MSG}。# 如果图像格式是 jpg 或 jpeg ，执行以下操作。if im.format.lower() in {"jpg", "jpeg"}:# 以二进制读取模式打开图像文件，并将其文件对象存储在变量 f 中。with open(im_file, "rb") as f:# file_object.seek(offset, whence=0)# seek() 函数是 Python 中文件对象的一个方法，它用于改变当前文件的读写位置。这个方法通常用于二进制文件操作，尤其是在需要随机访问文件内容时。# file_object ：文件对象，它必须是打开的文件，并且具有读写能力。# 参数 ：# offset ：偏移量，表示从 whence 指定的位置开始移动的字节数。正值表示向前（文件末尾方向），负值表示向后（文件开头方向）。# whence ：（可选）起始位置，指定 offset 从何处开始计算，默认值为0。它的值可以是 ：# 0 ：文件开头（默认值）， offset 表示从文件开头开始的字节数。# 1 ：当前位置， offset 表示从当前文件位置开始的字节数。# 2 ：文件末尾， offset 表示从文件末尾开始的字节数，通常用于移动到文件末尾之后的位置。# 返回值 ： seek() 方法没有返回值（返回 None ）。# seek() 方法是文件随机访问的关键，它允许程序在文件中快速定位到任意位置，而不需要从头开始读取或写入。# 移动文件指针到文件末尾前2个字节。f.seek(-2, 2)# 读取文件的最后两个字节。如果不是 JPEG 格式的结束标记 \xff\xd9 ，则认为 JPEG 文件已损坏。if f.read() != b"\xff\xd9": # corrupt JPEG# PIL.ImageOps.exif_transpose(image, *, in_place=False)# ImageOps.exif_transpose() 函数是 Python Imaging Library (PIL) 的一个扩展库 Pillow 中的一个函数，它用于根据图像的 EXIF 定向标签来调整图像的方向，使得图像按照 EXIF 标签中指定的方向进行正确的显示。如果图像没有 EXIF 定向标签或者标签值为 1（表示图像已经是正确的方向），则返回图像的一个副本。# 参数 ：# image ：要调整方向的 PIL 图像对象。# in_place ：（关键字参数）布尔值，如果设置为 True ，则在原图像对象上进行修改，并返回 None ；如果设置为 False （默认值），则返回一个新的图像对象，原图像对象不变。# 返回值 ：# 如果 in_place 参数为 False （默认），返回一个新的图像对象，该对象根据 EXIF 定向标签调整了方向。# 如果 in_place 参数为 True ，则原图像对象被修改，函数返回 None 。# 功能 ：# 读取图像的 EXIF 信息，特别是 Orientation 标签。# 根据 Orientation 标签的值，确定如何调整图像的方向。# 应用相应的变换（例如旋转、翻转）来调整图像的方向。# 如果 in_place 为 False ，则返回调整方向后的新图像对象；否则，修改原图像对象。# 使用 PIL 的 ImageOps.exif_transpose() 函数来校正图像的方向（基于 EXIF 信息），然后将修复后的图像保存回原文件，设置 JPEG 子采样为0，质量为100。ImageOps.exif_transpose(Image.open(im_file)).save(im_file, "JPEG", subsampling=0, quality=100)# 设置消息 msg ，包含前缀 prefix 、警告符号、图像文件路径和修复操作的描述。msg = f"{prefix}WARNING ⚠️ {im_file}: corrupt JPEG restored and saved" # {prefix}警告⚠️{im_file}：损坏的 JPEG 已恢复并保存。# 这段代码的目的是确保图像文件未损坏，格式正确，并且对于 JPEG 图像，确保它们有正确的结束标记。如果发现任何问题，代码将尝试修复这些问题，并记录相应的警告消息。# Verify labels# 这段代码是 verify_image_label 函数中用于验证标签文件的部分。# 检查 lb_file 指定的文件路径是否指向一个实际存在的文件。如果文件存在，继续执行；如果不存在，跳过后续代码。if os.path.isfile(lb_file):# 将 nf （number of found labels，找到的标签数量）设置为1，表示至少找到了一个标签文件。nf = 1 # label found# 使用 with 语句打开标签文件 lb_file ，这样可以确保文件在操作完成后正确关闭。with open(lb_file) as f:# 读取文件内容，去除首尾空白字符，按行分割，然后对每一行进行处理 ：# f.read().strip() ：读取文件内容并去除首尾空白字符。# splitlines() ：按行分割文件内容。# if len(x) ：确保忽略空行。# x.split() ：将每行按空格分割成列表。lb = [x.split() for x in f.read().strip().splitlines() if len(x)]# 检查 lb 列表中是否有任何列表的长度大于6，并且 keypoint 为 False （即不处理关键点数据）。 这个条件用于确定标签数据是否包含段落（segment）信息。if any(len(x) > 6 for x in lb) and (not keypoint): # is segment# 提取 lb 列表中每个子列表的第一个元素（类别索引），并将其转换为 NumPy 数组 classes 。classes = np.array([x[0] for x in lb], dtype=np.float32)# 对于 lb 列表中的每个子列表，提取除第一个元素之外的所有元素（即段落坐标），并将其转换为 NumPy 数组 segments ，然后重塑为 (-1, 2) 的形状，表示每个段落的坐标。segments = [np.array(x[1:], dtype=np.float32).reshape(-1, 2) for x in lb] # (cls, xy1...)# 将 classes 数组和 segments 数组转换为边界框格式（ segments2boxes 函数负责这一转换），然后沿着第二维（即列）连接这两个数组，形成新的 lb 数组。# def segments2boxes(segments): -> 将一系列线段（segments）转换为边界框（boxes）。将 boxes 列表转换为 NumPy 数组，然后调用 xyxy2xywh 函数将其从 xyxy 格式转换为 xywh 格式。 -> return xyxy2xywh(np.array(boxes)) # cls, xywhlb = np.concatenate((classes.reshape(-1, 1), segments2boxes(segments)), 1) # (cls, xywh)# 将 lb 列表转换为 NumPy 数组，并指定数据类型为 np.float32 。lb = np.array(lb, dtype=np.float32)# 计算 lb 数组的长度，即标签的数量，并将其存储在 nl 变量中。nl = len(lb)# 这段代码的主要目的是读取标签文件，解析标签数据，并将其转换为统一的格式（例如，将段落数据转换为边界框数据）。这样处理后的数据可以用于后续的图像处理或机器学习任务。# 这段代码是 verify_image_label 函数中用于验证标签数据的部分。# 检查 nl （标签数量）是否大于0，即是否有有效的标签数据。if nl:# 检查是否处理关键点数据。if keypoint:# 如果处理关键点数据，验证 lb 数组的第二维（列）是否等于5（类别、x、y、宽度、高度）加上每个关键点的维度数乘以关键点数量。如果不等，抛出异常。assert lb.shape[1] == (5 + nkpt * ndim), f"labels require {(5 + nkpt * ndim)} columns each" # 每个标签需要 {(5 + nkpt * ndim)} 列。# 提取 lb 数组中第5列之后的数据（即关键点数据），重塑为 -1, ndim 的形状，并取前两列（x, y）。points = lb[:, 5:].reshape(-1, ndim)[:, :2]# 如果不处理关键点数据。else:# 验证 lb 数组的列数是否为5（类别、x、y、宽度、高度）。如果不等，抛出异常。assert lb.shape[1] == 5, f"labels require 5 columns, {lb.shape[1]} columns detected" # 标签需要 5 列，检测到 {lb.shape[1]} 列。# 提取 lb 数组中第1列之后的数据（即x、y、宽度、高度）。points = lb[:, 1:]# 验证 points 数组中的最大值是否不超过1，即坐标是否归一化或在有效范围内。如果不在，抛出异常。assert points.max() <= 1, f"non-normalized or out of bounds coordinates {points[points > 1]}" # 非规范化或超出范围的坐标 {points[points > 1]}。# 验证 lb 数组中的最小值是否不小于0，即没有负值。如果不满足，抛出异常。assert lb.min() >= 0, f"negative label values {lb[lb < 0]}" # 负标签值 {lb[lb < 0]。# All labels# 计算 lb 数组中类别索引的最大值。max_cls = lb[:, 0].max() # max label count# 验证最大类别索引是否不超过数据集中的类别总数。如果不满足，抛出异常。assert max_cls <= num_cls, (f"Label class {int(max_cls)} exceeds dataset class count {num_cls}. " # 标签类别 {int(max_cls)} 超出数据集类别数量 {num_cls}。f"Possible class labels are 0-{num_cls - 1}" # 可能的类别标签为 0-{num_cls - 1}。)# 使用 NumPy 的 unique 函数找出 lb 数组中的唯一行，并返回这些行的索引。_, i = np.unique(lb, axis=0, return_index=True)# 检查是否有重复的标签行。if len(i) < nl: # duplicate row check# 如果有重复行，只保留唯一的行。lb = lb[i] # remove duplicates# 如果有段落数据。if segments:# 保留与唯一标签行对应的段落数据。segments = [segments[x] for x in i]# 设置警告消息，表示移除了重复的标签。msg = f"{prefix}WARNING ⚠️ {im_file}: {nl - len(i)} duplicate labels removed" # {prefix}警告 ⚠️ {im_file}: {nl - len(i)} 重复标签已删除。# 如果 nl 为0，即标签数据为空。else:# 将 ne （空的标签数量）设置为1。ne = 1 # label empty# 创建一个空的 lb 数组，列数根据是否处理关键点数据而定。lb = np.zeros((0, (5 + nkpt * ndim) if keypoint else 5), dtype=np.float32)# 这段代码的主要目的是验证标签数据的有效性，包括检查标签的格式、归一化坐标、类别索引的范围以及去除重复的标签行。如果标签数据为空或无效，会进行相应的处理，并设置警告消息。# 这段代码是 verify_image_label 函数中处理标签文件缺失情况的代码块。# 这个 else 块与前面的 if os.path.isfile(lb_file): 条件语句相对应。如果标签文件不存在（即 lb_file 不是一个实际存在的文件），则执行这个 else 块的代码。else:# 将 nm （number of missing labels，缺失的标签数量）设置为1，表示缺失了一个标签文件。nm = 1 # label missing# 创建一个空的 NumPy 数组 lb ，用于表示缺失的标签数据。# np.zeros() 函数创建一个填充有零的数组。# 第一个参数 (0, (5 + nkpt * ndim) if keypoints else 5) 指定了数组的形状 ：# 第一个元素 0 表示数组有0行，即没有标签数据。# 第二个元素根据是否处理关键点数据（ keypoints ）来确定 ：# 如果 keypoints 为 True ，则列数为 5 + nkpt * ndim ，其中 5 代表类别、x、y、宽度、高度这5个基本标签值， nkpt 是关键点数量， ndim 是每个关键点的维度数。# 如果 keypoints 为 False ，则列数为 5 ，即只有基本标签值。# dtype=np.float32 指定数组的数据类型为 float32 。lb = np.zeros((0, (5 + nkpt * ndim) if keypoints else 5), dtype=np.float32)# 这段代码的主要作用是在标签文件缺失的情况下，初始化一个空的标签数组，以便在后续处理中表示没有可用的标签数据。这样做可以保持代码的一致性，使得即使在标签文件缺失的情况下，函数也能返回一个统一格式的结果。# 这段代码是 verify_image_label 函数中处理关键点数据的部分。# 这个条件语句检查是否需要处理关键点数据。if keypoint:# 如果处理关键点数据，从 lb 数组中提取第5列之后的数据（因为前5列通常是类别和边界框坐标），并重塑数组形状为 -1 （行数自动计算以匹配原始数据行数）、 nkpt （关键点数量）和 ndim （每个关键点的维度数）。keypoints = lb[:, 5:].reshape(-1, nkpt, ndim)# 检查每个关键点的维度数是否为2。if ndim == 2:# 使用 np.where 创建一个掩码 kpt_mask ，检查关键点的 x 和 y 坐标是否小于0。如果是，则掩码值为0.0，否则为1.0。最后，将掩码转换为 float32 类型。kpt_mask = np.where((keypoints[..., 0] < 0) | (keypoints[..., 1] < 0), 0.0, 1.0).astype(np.float32)# 将掩码 kpt_mask 添加到 keypoints 数组的最后一个维度，形成一个新的数组，其中包含关键点的坐标和掩码值。keypoints = np.concatenate([keypoints, kpt_mask[..., None]], axis=-1) # (nl, nkpt, 3)# 将 lb 数组截断，只保留前5列，即类别和边界框坐标。lb = lb[:, :5]# 返回一个元组，包含以下信息。# im_file ：图像文件路径。# lb ：包含类别和边界框坐标的数组。# shape ：图像的形状（高度，宽度）。# segments ：段落数据（如果有）。# keypoints ：包含关键点坐标和掩码的数组。# nm ：缺失的标签数量。# nf ：找到的标签数量。# ne ：空的标签数量。# nc ：损坏的标签数量。# msg ：任何相关的消息或警告。return im_file, lb, shape, segments, keypoints, nm, nf, ne, nc, msg# 这段代码的主要作用是处理关键点数据，包括验证坐标值、添加掩码，并返回处理后的关键点数组。同时，它还确保只返回包含类别和边界框坐标的 lb 数组。这样处理后的数据可以用于后续的图像处理或机器学习任务。# 这段代码是 verify_image_label 函数中的异常处理部分，它位于函数的末尾，用于捕获在函数执行过程中可能发生的任何异常。# 这是一个 except 块，用于捕获 try 块中发生的任何异常。 Exception 是所有内置非系统退出异常的基类， as e 将捕获到的异常实例赋值给变量 e 。except Exception as e:# 将 nc （损坏的标签数量）设置为1，表示遇到了一个损坏的图像或标签文件。nc = 1# 创建一个警告消息 msg ，包含前缀 prefix 、警告符号、图像文件路径 im_file 、正在执行的操作（忽略损坏的图像或标签），以及异常的具体信息 e 。msg = f"{prefix}WARNING ⚠️ {im_file}: ignoring corrupt image/label: {e}" # {prefix}警告⚠️{im_file}：忽略损坏的图像/标签：{e}。# 返回一个列表，包含以下元素。# 五个 None 值 ：分别对应于函数正常情况下返回的 im_file 、 lb 、 shape 、 segments 和 keypoints 。# nm ：缺失的标签数量。# nf ：找到的标签数量。# ne ：空的标签数量。# nc ：损坏的标签数量（当前异常情况下为1）。# msg ：包含异常信息的警告消息。return [None, None, None, None, None, nm, nf, ne, nc, msg]# 这段代码的主要作用是在函数执行过程中遇到任何异常时，提供一个统一的错误处理机制。它记录了异常信息，并返回一个包含警告消息和计数器的结果列表，以便调用者可以了解发生了什么错误，并据此进行错误处理或日志记录。
# 这个函数是多线程环境中的一部分，通常与 ThreadPool.imap() 或 ThreadPool.imap_unordered() 方法一起使用，以并行验证多个图像-标签对。返回的结果可以用于更新进度条、记录日志或进一步处理。7.def polygon2mask(imgsz, polygons, color=1, downsample_ratio=1):
# 这段代码定义了一个名为 polygon2mask 的函数，它用于将一个或多个多边形（polygons）转换成一个掩码（mask）。这个函数在图像处理和计算机视觉中非常有用，尤其是在实例分割任务中，需要从多边形轮廓生成对象的掩码。
# 函数定义。
# 1.imgsz ：一个元组，表示输出掩码的尺寸，即 (高度, 宽度)。
# 2.polygons ：一个或多个多边形的坐标数组。每个多边形的坐标可以是一个形状为 (n, 2) 的数组，其中 n 是多边形的顶点数。
# 3.color ：用于填充多边形的颜色值，默认为 1，表示白色或完全覆盖。
# 4.downsample_ratio ：下采样比例，默认为 1，表示不进行下采样。
def polygon2mask(imgsz, polygons, color=1, downsample_ratio=1):# 将多边形列表转换为指定图像大小的二进制掩码。"""Convert a list of polygons to a binary mask of the specified image size.Args:imgsz (tuple): The size of the image as (height, width).polygons (list[np.ndarray]): A list of polygons. Each polygon is an array with shape [N, M], whereN is the number of polygons, and M is the number of points such that M % 2 = 0.color (int, optional): The color value to fill in the polygons on the mask. Defaults to 1.downsample_ratio (int, optional): Factor by which to downsample the mask. Defaults to 1.Returns:(np.ndarray): A binary mask of the specified image size with the polygons filled in."""# 初始化掩码数组。创建一个全零的掩码数组，其大小根据 imgsz 确定，数据类型为 np.uint8 ，这是图像掩码常用的数据类型。mask = np.zeros(imgsz, dtype=np.uint8)# 转换多边形坐标。将 polygons 转换为 NumPy 数组。polygons = np.asarray(polygons, dtype=np.int32)# 确保其形状为 (polygons_count, vertices_count, 2) ，其中每个多边形的坐标被重塑为 (vertices_count, 2) 的形式，以适配 cv2.fillPoly 函数的输入要求。polygons = polygons.reshape((polygons.shape[0], -1, 2))# cv2.fillPoly(img, pts, color)# cv2.fillPoly 是 OpenCV 库中的一个函数，它用于在图像中填充一个或多个多边形。# 参数说明 ：# img ：目标图像，它是一个 NumPy 数组，可以是灰度图或彩色图。这个函数会直接在原图像上进行操作，所以如果需要保留原始图像，应该先复制一份。# pts ：一个或多个多边形的顶点坐标。它是一个列表，其中每个元素是一个 NumPy 数组，包含多边形顶点的坐标。对于单个多边形， pts 可以是 (numpy_array,) 的形式，其中 numpy_array 包含多边形顶点的坐标。对于多个多边形， pts 可以是 (numpy_array1, numpy_array2, ...) 的形式，其中每个 numpy_array 包含一个多边形的顶点坐标。# color ：填充多边形的颜色。对于灰度图像，它是一个单通道的灰度值；对于彩色图像，它是一个 (B, G, R) 元组，分别代表蓝色、绿色和红色通道的值。# 返回值 ：该函数不返回任何值，它直接在输入的图像 img 上进行操作。# 填充多边形。使用 OpenCV 的 fillPoly 函数根据提供的多边形坐标填充掩码。 color 参数指定填充颜色，这里设置为 1（白色）。cv2.fillPoly(mask, polygons, color=color)# 调整掩码尺寸。根据下采样比例计算新的掩码高度和宽度。nh, nw = (imgsz[0] // downsample_ratio, imgsz[1] // downsample_ratio)# Note: fillPoly first then resize is trying to keep the same loss calculation method when mask-ratio=1# 返回调整尺寸后的掩码。使用 OpenCV 的 resize 函数将填充后的掩码调整到所需的尺寸，并返回结果。return cv2.resize(mask, (nw, nh))
# polygon2mask 函数的主要作用是将多边形坐标转换为掩码，这些掩码可以用于实例分割任务中表示对象的区域。通过调整掩码的尺寸和填充多边形，这个函数能够生成与图像尺寸相匹配的掩码，并且可以通过下采样比例来控制掩码的分辨率。这对于训练深度学习模型进行实例分割是非常有用的。8.def polygons2masks(imgsz, polygons, color, downsample_ratio=1):
# 这段代码定义了一个名为 polygons2masks 的函数，它用于将多个多边形（polygons）转换为对应的掩码（masks）。这个函数通过迭代 polygons 数组中的每个多边形，并调用 polygon2mask 函数来生成每个多边形的掩码。
# 函数定义。
# 1.imgsz ：一个元组，表示输出掩码的尺寸，即 (高度, 宽度)。
# 2.polygons ：一个多边形坐标数组的列表，每个元素是一个多边形的坐标数组。
# 3.color ：用于填充多边形的颜色值。
# 4.downsample_ratio ：下采样比例，默认为 1，表示不进行下采样。
def polygons2masks(imgsz, polygons, color, downsample_ratio=1):# 将多边形列表转换为一组指定图像大小的二进制掩码。s"""Convert a list of polygons to a set of binary masks of the specified image size.Args:imgsz (tuple): The size of the image as (height, width).polygons (list[np.ndarray]): A list of polygons. Each polygon is an array with shape [N, M], whereN is the number of polygons, and M is the number of points such that M % 2 = 0.color (int): The color value to fill in the polygons on the masks.downsample_ratio (int, optional): Factor by which to downsample each mask. Defaults to 1.Returns:(np.ndarray): A set of binary masks of the specified image size with the polygons filled in."""# 这行代码是一个列表推导式，它遍历 polygons 数组中的每个多边形 x ：# x.reshape(-1) ：将每个多边形的坐标数组 x 重塑为一维数组，以符合 polygon2mask 函数的输入要求。# [polygon2mask(imgsz, [x.reshape(-1)], color, downsample_ratio)] ：对于每个多边形，调用 polygon2mask 函数生成对应的掩码。 imgsz 是输出掩码的尺寸， [x.reshape(-1)] 是包含单个多边形坐标的列表， color 是填充颜色， downsample_ratio 是下采样比例。# np.array([...]) ：将列表推导式的结果转换为一个 NumPy 数组，并返回这个数组。这个数组包含了所有多边形对应的掩码。return np.array([polygon2mask(imgsz, [x.reshape(-1)], color, downsample_ratio) for x in polygons])
# polygons2masks 函数的主要作用是批量将多个多边形转换为对应的掩码。它通过迭代 polygons 数组中的每个多边形，并调用 polygon2mask 函数来生成每个多边形的掩码，然后将这些掩码存储在一个 NumPy 数组中返回。这种方式可以高效地处理多个多边形，并生成对应的掩码，适用于需要批量处理多边形掩码的场景，如实例分割任务中。9.def polygons2masks_overlap(imgsz, segments, downsample_ratio=1):
# 这段代码定义了一个名为 polygons2masks_overlap 的函数，它用于将多个多边形（polygons）转换为重叠的掩码（masks）。这个函数特别适用于处理实例分割任务中的对象掩码，其中对象可能相互重叠。
# 函数定义。
# 1.imgsz ：一个元组，表示图像的尺寸，即 (高度, 宽度)。
# 2.segments ：一个多边形数组，每个多边形定义了一个对象的轮廓。
# 3.downsample_ratio ：一个整数，表示下采样比例，默认为 1，意味着不进行下采样。
def polygons2masks_overlap(imgsz, segments, downsample_ratio=1):# 返回（640，640）重叠掩码。"""Return a (640, 640) overlap mask."""# 初始化掩码数组。# 创建一个全零的掩码数组，其大小根据图像尺寸和下采样比例确定。数据类型根据多边形的数量选择，如果多边形数量超过 255 ，则使用 np.int32 ，否则使用 np.uint8 。masks = np.zeros((imgsz[0] // downsample_ratio, imgsz[1] // downsample_ratio),dtype=np.int32 if len(segments) > 255 else np.uint8,)# 计算每个多边形的掩码和面积。# 这段代码是 polygons2masks_overlap 函数中的一部分，它负责遍历每个多边形（segment），将每个多边形转换成一个掩码（mask），并计算每个掩码的面积。# 初始化面积和掩码列表。这里初始化了两个空列表， areas 用于存储每个掩码的面积， ms 用于存储转换后的掩码。areas = []ms = []# 遍历多边形。这个 for 循环遍历 segments 数组中的每个多边形。 segments 数组包含了所有多边形的坐标信息，每个多边形都由一系列点定义。for si in range(len(segments)):# 转换多边形到掩码。对于每个多边形，调用 polygon2mask 函数将其转换为掩码。# imgsz ：图像的尺寸，用于确定掩码的大小。# [segments[si].reshape(-1)] ：当前多边形的坐标，使用 reshape(-1) 确保坐标是一维数组。# downsample_ratio ：下采样比例，用于调整掩码的分辨率。# color ：用于填充掩码的颜色值，这里设置为1，表示掩码中的所有像素值都将设置为1。# def polygon2mask(imgsz, polygons, color=1, downsample_ratio=1):# -> 用于将一个或多个多边形（polygons）转换成一个掩码（mask）。返回调整尺寸后的掩码。使用 OpenCV 的 resize 函数将填充后的掩码调整到所需的尺寸，并返回结果。# -> return cv2.resize(mask, (nw, nh))mask = polygon2mask(imgsz, [segments[si].reshape(-1)], downsample_ratio=downsample_ratio, color=1)# 存储掩码和计算面积。# 将转换后的掩码添加到 ms 列表中，并计算掩码中所有像素值的总和（即掩码的面积），然后将面积添加到 areas 列表中。ms.append(mask)areas.append(mask.sum())# 这段代码的目的是为每个多边形生成一个掩码，并计算每个掩码的面积。这些掩码和面积将用于后续的排序和掩码合并步骤，以处理掩码之间的重叠。通过计算掩码的面积，可以确定哪些掩码对应于较大的对象，这对于后续的排序和掩码合并是必要的。# 根据面积对掩码进行排序。# 这行代码将 areas 列表转换为一个 NumPy 数组。这样做可以利用 NumPy 的高效数组操作来处理后续的排序和计算。areas = np.asarray(areas)# 对面积进行排序并获取索引。这行代码使用 NumPy 的 argsort 函数对 areas 数组进行排序，并返回排序后的索引。 -areas 表示按照面积的降序排序，因为 argsort 默认是升序排序。index = np.argsort(-areas)# 根据排序索引重新排列掩码数组。# 首先， np.array(ms) 将 ms 列表转换为 NumPy 数组。然后，使用之前得到的 index 索引数组来重新排列 ms 数组，使得 ms 数组中的掩码顺序与面积从大到小的顺序一致。ms = np.array(ms)[index]# 合并掩码。# 循环定义。这个循环遍历 segments 数组中的每个多边形， i 是当前多边形的索引。for i in range(len(segments)):# 生成当前多边形的掩码。# 对于每个多边形，将对应的掩码 ms[i] 乘以一个唯一的标识符 i + 1 。这样做的目的是为每个对象分配一个唯一的值，以便在合并掩码时可以区分不同的对象。mask = ms[i] * (i + 1)# 合并当前多边形的掩码到总掩码。# 将当前多边形的掩码 mask 加到总掩码 masks 上。这一步是将所有对象的掩码合并成一个单一的掩码。masks = masks + mask# 确保掩码值在正确的范围内。# 使用 np.clip 函数确保 masks 中的值在0到 i + 1 的范围内。这一步是必要的，因为合并后的掩码可能包含大于 i + 1 的值，这些值需要被限制在正确的范围内，以确保每个对象的掩码值是唯一的。masks = np.clip(masks, a_min=0, a_max=i + 1)# 返回最终的掩码和索引。返回最终的重叠掩码和排序后的索引。return masks, index
# polygons2masks_overlap 函数的主要作用是将多个多边形转换为一个重叠的掩码，这对于处理重叠对象的实例分割任务非常有用。通过排序和合并掩码，这个函数能够生成一个包含所有对象的掩码，其中每个对象都有一个唯一的标识符，这有助于后续的分析和处理。10.def find_dataset_yaml(path: Path) -> Path:
# 这段代码定义了一个名为 find_dataset_yaml 的函数，它的目的是在给定的路径下查找一个特定的YAML文件。这个函数使用了 pathlib 模块中的 Path 类来处理文件路径。
# 定义了一个函数 find_dataset_yaml ，它接受一个 Path 对象作为参数，并返回一个 Path 对象。
# 1.path ：这个参数代表了函数将要搜索 YAML 文件的目录路径。
def find_dataset_yaml(path: Path) -> Path:# 查找并返回与 Detect、Segment 或 Pose 数据集关联的 YAML 文件。# 此函数首先在提供的目录的根级别搜索 YAML 文件，如果未找到，则执行递归搜索。它首选具有与提供的路径相同的词干的 YAML 文件。如果未找到 YAML 文件或找到多个 YAML 文件，则会引发 AssertionError。"""Find and return the YAML file associated with a Detect, Segment or Pose dataset.This function searches for a YAML file at the root level of the provided directory first, and if not found, itperforms a recursive search. It prefers YAML files that have the same stem as the provided path. An AssertionErroris raised if no YAML file is found or if multiple YAML files are found.Args:path (Path): The directory path to search for the YAML file.Returns:(Path): The path of the found YAML file."""# Path.rglob(pattern)# rglob() 是 Python pathlib 模块中 Path 类的一个方法，用于递归地搜索与给定模式匹配的所有文件路径。这个方法会遍历给定路径下的所有子目录，寻找匹配指定模式的文件。# 参数 ：# pattern ：一个字符串，表示要匹配的文件名模式。这个模式遵循 Unix shell 的规则，其中 * 匹配任意数量的字符（除了路径分隔符），而 ** 用于表示任意深度的目录。# 返回值 ：# 返回一个生成器（generator），生成所有匹配模式的 Path 对象。# rglob() 方法是递归的，因此它会搜索所有子目录，而不仅仅是当前目录。这使得它非常适合于在大型项目中查找特定类型的文件。# 尝试在给定路径的当前级别查找所有以 .yaml 结尾的文件。如果当前级别没有找到（ glob 返回空列表），则使用 rglob 在所有子目录中递归查找。files = list(path.glob("*.yaml")) or list(path.rglob("*.yaml")) # try root level first and then recursive# 确保至少找到了一个文件，如果没有找到，将抛出一个 AssertionError ，并显示一条消息说明在给定路径下没有找到YAML文件。assert files, f"No YAML file found in '{path.resolve()}'" # 在“{path.resolve()}”中未找到 YAML 文件。# 如果找到了多个文件。if len(files) > 1:# 则筛选出 文件名 （不包括扩展名）与给 定路径的文件名 相同的文件。files = [f for f in files if f.stem == path.stem] # prefer *.yaml files that match# 确保筛选后只有一个文件，如果不是，将抛出一个 AssertionError ，并显示一条消息说明预期找到一个YAML文件，但找到了多个，以及这些文件的列表。assert len(files) == 1, f"Expected 1 YAML file in '{path.resolve()}', but found {len(files)}.\n{files}" # '{path.resolve()}' 中预期有 1 个 YAML 文件，但找到了 {len(files)}。\n{files}。# 返回找到的第一个（也是唯一一个）YAML文件的 Path 对象。return files[0]
# 这个函数的目的是确保在给定的路径下找到一个特定的YAML文件，并且这个文件的文件名与路径的文件名相同。如果找不到文件或者找到多个文件，函数将抛出异常。这个函数适用于那些预期在给定路径下只有一个特定YAML文件的场景。11.def check_det_dataset(dataset, autodownload=True):
# 这这段代码定义了一个名为 check_det_dataset 的函数，它的目的是检查和处理数据集（dataset），确保数据集的YAML配置文件符合要求，并在需要时下载数据集。
# 定义一个函数 check_det_dataset ，它接受两个参数。
# 1.dataset ：数据集的路径或名称。
# 2.autodownload ：一个布尔值，指示是否自动下载数据集，默认为True。
def check_det_dataset(dataset, autodownload=True):# 如果在本地找不到数据集，则下载、验证和/或解压缩数据集。# 此函数检查指定数据集的可用性，如果未找到，则可选择下载并解压缩数据集。然后，它会读取并解析随附的 YAML 数据，确保满足关键要求，并解析与数据集相关的路径。"""Download, verify, and/or unzip a dataset if not found locally.This function checks the availability of a specified dataset, and if not found, it has the option to download andunzip the dataset. It then reads and parses the accompanying YAML data, ensuring key requirements are met and alsoresolves paths related to the dataset.Args:dataset (str): Path to the dataset or dataset descriptor (like a YAML file).autodownload (bool, optional): Whether to automatically download the dataset if not found. Defaults to True.Returns:(dict): Parsed dataset information and paths."""# 调用 check_file 函数来检查 dataset 参数，并返回文件路径。# def check_file(file, suffix="", download=True, download_dir=".", hard=True):# -> 检查文件存在性。如果文件路径为空，或者文件已经存在于本地，或者文件路径以 grpc:// 开头（表示 gRPC Triton 图像），则直接返回文件路径。# -> 如果文件路径以 http:// 、 https:// 、 rtsp:// 、 rtmp:// 或 tcp:// 开头，并且 download 参数为 True ，则下载文件。# -> 如果文件不需要下载，或者下载失败，则在文件系统中搜索文件。# -> return file / return str(file) / return files[0] if len(files) else [] # return filefile = check_file(dataset)# 这段代码是函数 check_det_dataset 中的一部分，它处理数据集文件的下载和解压，以及读取YAML配置文件。# Download (optional)# 初始化了一个变量 extract_dir ，它将用来存储解压后的目录路径。这个变量是可选的，因为不是所有的数据集都需要下载和解压。extract_dir = ""# 检查之前通过 check_file 函数获得的 file 变量是否指向一个ZIP或TAR格式的压缩文件。 zipfile.is_zipfile 和 is_tarfile 是Python标准库中的函数，用于检查文件是否为ZIP或TAR压缩文件。if zipfile.is_zipfile(file) or is_tarfile(file):# 如果 file 是一个压缩文件， safe_download 函数被调用来下载文件到 DATASETS_DIR 目录，并解压它。 unzip=True 参数指示函数需要解压文件， delete=False 参数指示不删除原始的压缩文件。new_dir = safe_download(file, dir=DATASETS_DIR, unzip=True, delete=False)# 解压后， find_dataset_yaml 函数被用来在解压目录中查找YAML配置文件。这里 DATASETS_DIR / new_dir 表示路径拼接，即解压后的目录路径。# def find_dataset_yaml(path: Path) -> Path: -> 在给定的路径下查找一个特定的YAML文件。返回找到的第一个（也是唯一一个）YAML文件的 Path 对象。 -> return files[0]file = find_dataset_yaml(DATASETS_DIR / new_dir)# 一旦找到YAML配置文件，更新 extract_dir 为YAML文件的父目录，这通常是数据集的根目录。同时，将 autodownload 设置为 False ，因为数据集已经被手动或自动下载和解压了，不需要再次下载。extract_dir, autodownload = file.parent, False# Read YAML# 最后，使用 yaml_load 函数读取YAML配置文件的内容，并将其存储在字典 data 中。 append_filename=True 参数意味着函数会在字典中添加 YAML 文件的路径。# def yaml_load(file="data.yaml", append_filename=False):# -> 从 YAML 文件中加载数据，并根据需要将文件名附加到数据字典中。返函数返回一个字典，包含从 YAML 文件中加载的数据。如果 append_filename 为 True ，则字典中还包括一个键 "yaml_file" ，其值为 YAML 文件的路径。# -> return datadata = yaml_load(file, append_filename=True) # dictionary# 这部分代码的目的是确保数据集文件（如果需要的话）被正确下载和解压，并且读取YAML配置文件，以便后续的数据处理和验证。# 这段代码是函数 check_det_dataset 中的一部分，它负责检查YAML配置文件中的关键信息是否完整，并进行必要的数据校验和调整。# Checks# 开始一个循环，检查 train 和 val （训练和验证集）这两个键是否存在于YAML配置文件中。for k in "train", "val":# 如果当前键（ train 或 val ）不存在于 data 字典中。if k not in data:# 如果当前键不是 val 或者 data 字典中没有 validation （验证） 键。if k != "val" or "validation" not in data:# 抛出 SyntaxError 异常，指出YAML文件中缺少必要的键。 emojis 函数用于在错误信息中添加表情符号。raise SyntaxError(# def emojis(string=""):# -> 确保传入的字符串在不同操作系统平台上能够安全地显示，特别是在不支持复杂字符（如表情符号）的平台上。返回处理过的字符串。如果操作系统是 Windows，返回处理过的字符串，否则直接返回原始字符串。# -> return string.encode().decode("ascii", "ignore") if WINDOWS else stringemojis(f"{dataset} '{k}:' key missing ❌.\n'train' and 'val' are required in all data YAMLs.") # {dataset} '{k}:' 键缺少 ❌。\n所有数据 YAML 中都需要 'train' 和 'val'。)# 如果 val 键不存在但 validation 键存在，记录一条警告信息，表示将 validation 键重命名为 val 以符合YOLO格式。LOGGER.info("WARNING ⚠️ renaming data YAML 'validation' key to 'val' to match YOLO format.") # 警告⚠️将数据 YAML“validation”键重命名为“val”以匹配 YOLO 格式。# 将 validation 键的值赋给新键 val ，并从字典中删除 validation 键。data["val"] = data.pop("validation") # replace 'validation' key with 'val' key# 检查 data 字典中是否同时缺少 names 和 nc 键。if "names" not in data and "nc" not in data:# 如果两者都缺失，抛出 SyntaxError 异常，指出YAML文件中缺少必要的键。raise SyntaxError(emojis(f"{dataset} key missing ❌.\n either 'names' or 'nc' are required in all data YAMLs.")) # {dataset} 键缺失 ❌。\n 所有数据 YAML 中都需要“names”或“nc”。# 如果 data 字典中同时存在 names 和 nc 键，但 names 列表的长度与 nc 的值不匹配。if "names" in data and "nc" in data and len(data["names"]) != data["nc"]:# 抛出 SyntaxError 异常，指出 names 的长度必须与 nc 的值相匹配。raise SyntaxError(emojis(f"{dataset} 'names' length {len(data['names'])} and 'nc: {data['nc']}' must match.")) # {dataset} ‘names’ 长度 {len(data['names'])} 和 ‘nc: {data['nc']}’ 必须匹配。# 如果 data 字典中没有 names 键，但有 nc 键，创建一个默认的类别名称列表，名称格式为 class_0 , class_1 等。if "names" not in data:data["names"] = [f"class_{i}" for i in range(data["nc"])]# 如果 data 字典中有 names 键，更新 nc 的值为 names 列表的长度。else:data["nc"] = len(data["names"])# 调用 check_class_names 函数来检查和可能修改 names 列表，确保类别名称是有效的。# def check_class_names(names): -> 验证和处理类别名称。返回值。函数返回处理后的 names 字典。 -> return namesdata["names"] = check_class_names(data["names"])# 这部分代码的目的是确保YAML配置文件中包含了执行目标检测所需的所有关键信息，并且在格式上符合预期，以便后续的数据处理和模型训练可以顺利进行。# Resolve paths# 这段代码负责确定数据集的根路径，并将其转换为绝对路径。# Path ：使用 Path 类（来自Python的 pathlib 模块）来处理路径，这样可以跨平台地处理文件路径。# extract_dir or data.get("path") or Path(data.get("yaml_file", "")).parent ：这是一个条件表达式，它尝试从三个可能的来源中确定数据集的根路径 :# extract_dir ：之前代码中可能已经确定的解压目录。# data.get("path") ：从YAML配置文件中获取的路径。# Path(data.get("yaml_file", "")).parent ：如果上述两个来源都没有提供路径，那么使用YAML文件自身的目录作为数据集的根路径。 data.get("yaml_file", "") 尝试从 data 字典中获取 yaml_file 键的值，如果不存在则默认为空字符串，然后 Path(...).parent 获取该文件的父目录。path = Path(extract_dir or data.get("path") or Path(data.get("yaml_file", "")).parent) # dataset root# 这个表达式的目的是确定数据集的根目录，这是后续路径解析的基础。# 如果 path 不是一个绝对路径，那么执行以下操作。if not path.is_absolute():# 将 path 与 DATASETS_DIR （一个预定义的目录，通常用于存储数据集）合并，并使用 resolve() 方法将其转换为绝对路径。 DATASETS_DIR / path 是路径拼接操作，它将 DATASETS_DIR 和 path 合并成一个新路径，然后 resolve() 方法将这个新路径解析为一个绝对路径。path = (DATASETS_DIR / path).resolve()# 这部分代码的目的是确保无论用户提供的路径是相对的还是绝对的，最终都能被转换为一个绝对路径，这样就可以在文件系统中准确地定位到数据集的位置。这对于后续的文件操作（如读取或写入数据集文件）是非常重要的。# 解析路径 通常指的是将一个文件路径从相对形式转换为绝对形式，或者从一种格式转换为另一种格式，以便操作系统能够识别并定位到文件系统中的确切位置。# 这个过程包括以下几个步骤 ：# 识别路径类型 ：# 确定给定的路径是绝对路径还是相对路径。 绝对路径 ：从根目录开始的完整路径，如 /home/user/documents/file.txt 。 相对路径 ：相对于当前工作目录的路径，如 ./file.txt 或 ../folder/file.txt 。# 路径合并 ：# 将相对路径与一个基准路径（通常是当前工作目录或指定的根目录）合并，形成完整的路径。# 解析为绝对路径 ：# 通过解析合并后的路径，将其转换为从文件系统根目录开始的绝对路径。这通常涉及到处理路径中的 . （当前目录）和 .. （上级目录）等特殊元素。# 规范化路径 ：# 去除路径中的冗余部分，如多余的分隔符或重复的目录跳转，以得到最简洁的路径形式。# 验证路径存在性 ：# 检查解析后的路径是否确实指向文件系统中的一个有效位置。# 在编程中，特别是在处理文件和目录时，解析路径是一个常见的操作，因为它确保了程序能够正确地找到和操作文件。在不同的编程语言中，这个过程可能由内置的库或函数来处理，例如Python中的 os.path 模块或 pathlib 模块。# 这段代码负责设置数据集的路径，并确保所有相关的文件路径都是正确的绝对路径。# Set paths# 将之前解析得到的绝对路径 path 存储在 data 字典的 "path" 键中。这个路径通常用作数据集的根目录，后续会用它来下载脚本或执行其他操作。data["path"] = path # download scripts# 开始一个循环，遍历几个常见的数据集分割键 ： train （训练集）、 val （验证集）、 test （测试集）和 minival （小型验证集）。for k in "train", "val", "test", "minival":# 对于每个键，如果它存在于 data 字典中，这意味着数据集配置文件中指定了这个分割的路径。if data.get(k): # prepend path# 检查 data[k] 的值是否为字符串类型，即路径是否以单个字符串的形式给出。if isinstance(data[k], str):# 如果是字符串，将数据集根目录 path 与当前分割的相对路径 data[k] 合并，并使用 resolve() 方法将其转换为绝对路径。x = (path / data[k]).resolve()# 如果合并后的路径不存在，并且原始路径 data[k] 以 "../" 开头（表示它是一个相对路径）。if not x.exists() and data[k].startswith("../"):# 那么尝试去掉 "../" 再次解析路径。这通常用于处理那些相对路径指向上级目录的情况。x = (path / data[k][3:]).resolve()# 最后，将解析后的绝对路径转换为字符串，并更新 data 字典中对应的键值。data[k] = str(x)# 如果 data[k] 的值不是字符串而是列表类型，那么对列表中的每个路径元素执行相同的操作else:# 将数据集根目录 path 与相对路径合并，并解析为绝对路径，然后将结果转换为字符串列表，并更新 data 字典中对应的键值。data[k] = [str((path / x).resolve()) for x in data[k]]# 这部分代码的目的是确保 data 字典中的所有路径都是正确的绝对路径，这样可以在后续的数据处理和模型训练中无误地访问这些文件。这对于确保数据集的正确加载和使用至关重要。# 这段代码是函数 check_det_dataset 的最后部分，它处理YAML文件中的特定字段，包括验证路径的存在性、自动下载数据集（如果需要），以及检查和下载字体文件。# Parse YAML# 使用列表推导式从 data 字典中获取 "val" 和 "download" 两个键的值。 val 包含验证集的路径， s 包含下载数据集的相关信息（如URL或脚本）。val, s = (data.get(x) for x in ("val", "download"))# 如果 val （验证集路径）存在。if val:# 将 val 中的每个路径解析为绝对路径。如果 val 是字符串，则将其放入列表中进行处理。val = [Path(x).resolve() for x in (val if isinstance(val, list) else [val])] # val path# 检查 val 中的所有路径是否都存在。if not all(x.exists() for x in val):# 如果路径不存在，使用 clean_url 函数来清理数据集名称，移除URL中的认证信息。# def clean_url(url):# -> 清除 URL 中的认证信息（如用户名和密码）以及其他可能的查询参数，只保留 URL 的基本部分。函数返回一个清理后的 URL 字符串，不包含认证信息和查询参数。# -> return urllib.parse.unquote(url).split("?")[0] # '%2F' to '/', split https://url.com/file.txt?authname = clean_url(dataset) # dataset name with URL auth stripped# 构建一条消息，指出数据集中的图片未找到，并显示缺失的第一个路径。m = f"\nDataset '{name}' images not found ⚠️, missing path '{[x for x in val if not x.exists()][0]}'" # 未找到数据集“{name}”图像⚠️，缺少路径“{[x for x in val if not x.exists()][0]}”。# 如果 s （下载信息）存在且 autodownload 为True，则记录一条警告信息。if s and autodownload:LOGGER.warning(m)# 否则，抛出 FileNotFoundError 异常，并提供更多关于数据集下载目录的信息。else:m += f"\nNote dataset download directory is '{DATASETS_DIR}'. You can update this in '{SETTINGS_FILE}'" # 注意数据集下载目录为“{DATASETS_DIR}”。您可以在“{SETTINGS_FILE}”中更新此目录。raise FileNotFoundError(m)# 记录当前时间，并初始化一个变量 r 来存储下载或执行脚本的结果。t = time.time()r = None # success# 如果 s 是一个以 .zip 结尾的URL，使用 safe_download 函数下载数据集。if s.startswith("http") and s.endswith(".zip"): # URLsafe_download(url=s, dir=DATASETS_DIR, delete=True)# 如果 s 以 bash 开头，表示它是一个bash脚本，执行该脚本。elif s.startswith("bash "): # bash scriptLOGGER.info(f"Running {s} ...") # 正在运行 {s} ...r = os.system(s)# 否则，执行Python脚本。else: # python script# exec(object, globals=None, locals=None)# 在Python中， exec() 函数用于执行存储在字符串或对象中的Python代码。这个函数非常强大，但也需谨慎使用，因为它会执行任意的代码，这可能导致安全风险。# 参数说明 ：# object ：必需，要执行的代码，可以是字符串或代码对象。# globals ：可选，用于执行代码时的全局变量字典。如果为 None ，则使用当前环境的全局变量。# locals ：可选，用于执行代码时的局部变量字典。如果为 None ，则使用 globals 作为局部变量环境。# 返回值 ：# exec() 函数没有返回值（即返回 None ），因为它直接执行代码，而不是返回执行结果。# 安全注意事项 ：# 由于 exec() 可以执行任意代码，因此它可能会被用来执行恶意代码。因此，只有在完全信任代码来源的情况下才应该使用 exec() ，并且永远不要对用户提供的输入使用 exec() ，除非经过了严格的验证和清理。exec(s, {"yaml": data})# 计算下载或执行脚本所花费的时间。dt = f"({round(time.time() - t, 1)}s)"# 根据执行结果，构建成功或失败的消息。s = f"success ✅ {dt}, saved to {colorstr('bold', DATASETS_DIR)}" if r in {0, None} else f"failure {dt} ❌" # 成功✅{dt}，保存至{colorstr('bold', DATASETS_DIR)}” if r in {0, None} else f“失败{dt} ❌。# 记录数据集下载或执行脚本的结果。LOGGER.info(f"Dataset download {s}\n") # 数据集下载 {s}。# 调用 check_font 函数来检查是否需要下载字体文件，如果类别名称包含非ASCII字符，则下载 Arial.Unicode.ttf ，否则下载 Arial.ttf 。# def check_font(font="Arial.ttf"):# -> 用于检查指定的字体文件是否存在于用户配置目录中，如果不存在，则尝试从系统字体中查找，如果仍然找不到，最后尝试从 GitHub 上的 Ultralytics assets 仓库下载。# -> 如果文件存在，则返回该文件路径。如果找到了匹配的系统字体路径，返回第一个匹配项。返回下载的字体文件路径。# -> return file / return matches[0] / return filecheck_font("Arial.ttf" if is_ascii(data["names"]) else "Arial.Unicode.ttf") # download fonts# 函数返回处理后的 data 字典，其中包含了 数据集的 配置信息 和 路径 。return data # dictionary# 这段代码的目的是确保数据集的路径正确无误，如果需要，自动下载数据集，并检查必要的资源（如字体文件）是否已经就绪。这样可以确保数据集可以被正确加载和使用。
# 这个函数的主要目的是确保数据集的配置文件（YAML 文件）是有效的，并且数据集文件（如图像）可以被正确地下载和访问。它还处理了一些常见的数据集配置问题，如路径解析和类别名称的生成。12.def check_cls_dataset(dataset, split=""):
# 这段代码定义了一个名为 check_cls_dataset 的函数，其目的是检查分类数据集的完整性，并在必要时下载数据集。
# 定义一个函数 check_cls_dataset ，接受两个参数。
# 1.dataset ：数据集的路径或名称。
# 2.split ：数据集的分割类型，默认为空字符串。
def check_cls_dataset(dataset, split=""):# 检查分类数据集，例如 Imagenet。# 此函数接受 `dataset` 名称并尝试检索相应的数据集信息。# 如果在本地找不到数据集，它会尝试从互联网上下载数据集并将其保存在本地。"""Checks a classification dataset such as Imagenet.This function accepts a `dataset` name and attempts to retrieve the corresponding dataset information.If the dataset is not found locally, it attempts to download the dataset from the internet and save it locally.Args:dataset (str | Path): The name of the dataset.split (str, optional): The split of the dataset. Either 'val', 'test', or ''. Defaults to ''.Returns:(dict): A dictionary containing the following keys:- 'train' (Path): The directory path containing the training set of the dataset.- 'val' (Path): The directory path containing the validation set of the dataset.- 'test' (Path): The directory path containing the test set of the dataset.- 'nc' (int): The number of classes in the dataset.- 'names' (dict): A dictionary of class names in the dataset."""# 这段代码是 check_cls_dataset 函数的一部分，它处理数据集的下载和路径解析。# Download (optional if dataset=https://file.zip is passed directly)# 如果 dataset 参数是一个字符串，并且以 http:// 或 https:// 开头，这意味着它是一个直接指向数据集文件的URL。if str(dataset).startswith(("http:/", "https:/")):# safe_download 函数被用来下载这个文件到 DATASETS_DIR 目录，并解压它（如果需要），同时不删除原始文件。dataset = safe_download(dataset, dir=DATASETS_DIR, unzip=True, delete=False)# 如果 dataset 参数指向的是一个本地文件，并且文件扩展名是 .zip 、 .tar 或 .gz 。elif Path(dataset).suffix in {".zip", ".tar", ".gz"}:# check_file 函数被用来检查文件的有效性。# def check_file(file, suffix="", download=True, download_dir=".", hard=True):# -> 检查文件存在性。如果文件路径为空，或者文件已经存在于本地，或者文件路径以 grpc:// 开头（表示 gRPC Triton 图像），则直接返回文件路径。# -> 如果文件路径以 http:// 、 https:// 、 rtsp:// 、 rtmp:// 或 tcp:// 开头，并且 download 参数为 True ，则下载文件。# -> 如果文件不需要下载，或者下载失败，则在文件系统中搜索文件。# -> return file / return str(file) / return files[0] if len(files) else [] # return filefile = check_file(dataset)# safe_download 函数被用来下载（实际上是复制或解压）这个文件到 DATASETS_DIR 目录，并解压它（如果需要），同时不删除原始文件。dataset = safe_download(file, dir=DATASETS_DIR, unzip=True, delete=False)# 将 dataset 参数转换为 Path 对象，以便使用 pathlib 模块提供的方法来处理路径。dataset = Path(dataset)# 确定数据集的实际目录路径。如果 dataset 已经是一个目录，则直接使用；否则，将其视为 DATASETS_DIR 目录下的文件或目录，并使用 resolve 方法将其转换为绝对路径。data_dir = (dataset if dataset.is_dir() else (DATASETS_DIR / dataset)).resolve()# 这段代码是 check_cls_dataset 函数的一部分，它处理数据集目录不存在时的情况，包括尝试下载数据集。# 检查 data_dir 变量是否不指向一个存在的目录。if not data_dir.is_dir():# 如果目录不存在，记录一条警告信息，指出数据集未找到，并告知用户程序将尝试下载数据集。LOGGER.warning(f"\nDataset not found ⚠️, missing path {data_dir}, attempting download...") # 未找到数据集⚠️，缺少路径 {data_dir}，正在尝试下载...# 记录当前时间，以便后续计算下载所需的时间。t = time.time()# 如果数据集是 imagenet ，则运行一个bash脚本（位于 ROOT/data/scripts/get_imagenet.sh ）来下载数据集。if str(dataset) == "imagenet":subprocess.run(f"bash {ROOT / 'data/scripts/get_imagenet.sh'}", shell=True, check=True)# 对于非 imagenet 数据集。else:# 构建一个GitHub releases页面的URL，用于下载名为 {dataset}.zip 的文件，并将其下载到 data_dir 的父目录中。这里使用的 download 函数是自定义的，用于执行实际的下载操作。url = f"https://github.com/ultralytics/assets/releases/download/v0.0.0/{dataset}.zip"download(url, dir=data_dir.parent)# 计算下载所需的时间，并记录一条信息，告知用户数据集下载成功，并显示保存位置。s = f"Dataset download success ✅ ({time.time() - t:.1f}s), saved to {colorstr('bold', data_dir)}\n" # 数据集下载成功✅ ({time.time() - t:.1f}s)，保存至{colorstr('bold', data_dir)}。LOGGER.info(s)# 定义训练集的路径为 data_dir 下的 train 目录。train_set = data_dir / "train"# 定义验证集的路径。首先检查 data_dir 下是否存在 val 目录，如果存在，则使用它；如果不存在，再检查是否存在 validation 目录，如果存在，则使用它；如果两者都不存在，则将 val_set 设置为 None 。val_set = (data_dir / "val"if (data_dir / "val").exists()else data_dir / "validation"if (data_dir / "validation").exists()else None) # data/test or data/val# 这段代码继续处理数据集的路径和元数据。# 定义测试集的路径。如果 data_dir 目录下存在 test 目录，则 test_set 变量被设置为该路径；如果不存在，则 test_set 被设置为 None 。test_set = data_dir / "test" if (data_dir / "test").exists() else None # data/val or data/test# 如果用户请求的数据集分割类型为 val （验证集），但实际上 val_set 为 None （即验证集不存在），则记录一条警告信息，告知用户将使用测试集（ test ）代替验证集。if split == "val" and not val_set:LOGGER.warning("WARNING ⚠️ Dataset 'split=val' not found, using 'split=test' instead.") # 警告⚠️未找到数据集“split=val”，请改用“split=test”。# 如果用户请求的数据集分割类型为 test （测试集），但实际上 test_set 为 None （即测试集不存在），则记录一条警告信息，告知用户将使用验证集（ val ）代替测试集。elif split == "test" and not test_set:LOGGER.warning("WARNING ⚠️ Dataset 'split=test' not found, using 'split=val' instead.") # 警告⚠️未找到数据集“split=test”，请改用“split=val”。# 计算训练集中的类别数量 nc 。这通过遍历 data_dir/train 目录下的所有项目，并计算其中是目录的项目数量来实现。这些目录通常代表不同的类别。nc = len([x for x in (data_dir / "train").glob("*") if x.is_dir()]) # number of classes# path.iterdir()# path.iterdir() 是 Python pathlib 模块中 Path 类的一个方法，它用于遍历指定路径下的目录内容。这个方法返回一个迭代器，该迭代器产生路径下的所有文件和子目录的 Path 对象。# 参数 ：# path ：一个 Path 对象，表示你想要遍历的目录。# 返回值 ：# 返回一个迭代器，产生路径下每个文件和子目录的 Path 对象。# iterdir() 方法是处理文件系统时非常有用的工具，它提供了一种简洁的方式来访问目录内容，并且能够以面向对象的方式操作路径。# 创建一个包含所有类别名称的列表 names 。这通过遍历 data_dir/train 目录下的项目，并收集那些是目录的项目名称来实现。names = [x.name for x in (data_dir / "train").iterdir() if x.is_dir()] # class names list# 将类别名称列表 names 转换为一个字典，并按照名称的字母顺序进行排序。字典的键是类别的索引（从0开始），值是类别的名称。这样便于后续通过索引访问特定的类别名称。names = dict(enumerate(sorted(names)))# 这部分代码的目的是确保数据集的路径被正确设置，并且在数据集的分割不存在时提供替代方案。同时，它还收集了训练集中的类别信息，这对于后续的数据加载和模型训练是必要的。# 这段代码是 check_cls_dataset 函数的最后一部分，它负责将数据集的相关信息打印到控制台，并返回一个包含数据集信息的字典。# Print to console# 这一行开始一个循环，遍历一个包含训练集、验证集和测试集路径的字典。for k, v in {"train": train_set, "val": val_set, "test": test_set}.items():# 对于每个数据集分割（ train 、 val 、 test ），构建一个前缀字符串，其中 colorstr 函数用于给文本添加颜色， k 是分割类型的名称， v 是对应的路径。prefix = f'{colorstr(f"{k}:")} {v}...'# 如果对应的路径 v 为 None ，说明该分割不存在，记录一条信息。if v is None:LOGGER.info(prefix)# 如果路径存在，使用 rglob 方法递归地搜索所有文件，并筛选出文件扩展名在 IMG_FORMATS 列表中的文件（图片文件）。else:files = [path for path in v.rglob("*.*") if path.suffix[1:].lower() in IMG_FORMATS]# 计算找到的文件数量。nf = len(files) # number of files# 计算这些文件所在的不同目录数量，这里使用集合({})来自动去除重复的目录。nd = len({file.parent for file in files}) # number of directories# 如果没有找到文件。if nf == 0:# 对于训练集，抛出 FileNotFoundError 异常。if k == "train":raise FileNotFoundError(emojis(f"{dataset} '{k}:' no training images found ❌ ")) # {dataset} ‘{k}：’未找到训练图像❌。# 对于验证集或测试集，记录一条警告信息。else:LOGGER.warning(f"{prefix} found {nf} images in {nd} classes: WARNING ⚠️ no images found") # {prefix} 在 {nd} 个类别中找到 {nf} 个图像：警告 ⚠️ 未找到图像。# 如果目录数量与类别数量不匹配，记录一条错误信息。elif nd != nc:LOGGER.warning(f"{prefix} found {nf} images in {nd} classes: ERROR ❌️ requires {nc} classes, not {nd}") # {prefix} 在 {nd} 个类别中找到了 {nf} 个图像：错误 ❌️ 需要 {nc} 个类别，而不是 {nd}。# 如果一切正常，记录一条信息，表明找到了多少文件和类别。else:LOGGER.info(f"{prefix} found {nf} images in {nd} classes ✅ ") # {prefix} 在 {nd} 个类别中找到 {nf} 张图片✅。# 函数返回一个字典，包含 训练集 、 验证集 和 测试集 的 路径 、 类别数量 和 类别名称 。return {"train": train_set, "val": val_set, "test": test_set, "nc": nc, "names": names}# 这段代码的目的是确保数据集的完整性，并为用户提供关于数据集结构和内容的反馈。通过检查每个分割中的文件数量和类别数量，它帮助用户识别数据集可能存在的问题。13.class HUBDatasetStats:
# 这段代码定义了一个名为 HUBDatasetStats 的类，其目的是为从 HUB（一个数据集仓库或平台）加载的数据集提供统计信息和相关操作。
# 定义了一个名为 HUBDatasetStats 的类。
class HUBDatasetStats:# 用于生成 HUB 数据集 JSON 和 `-hub` 数据集目录的类。"""A class for generating HUB dataset JSON and `-hub` dataset directory.Args:path (str): Path to data.yaml or data.zip (with data.yaml inside data.zip). Default is 'coco8.yaml'.task (str): Dataset task. Options are 'detect', 'segment', 'pose', 'classify'. Default is 'detect'.autodownload (bool): Attempt to download dataset if not found locally. Default is False.Example:Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasetsi.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip.```pythonfrom ultralytics.data.utils import HUBDatasetStatsstats = HUBDatasetStats("path/to/coco8.zip", task="detect") # detect datasetstats = HUBDatasetStats("path/to/coco8-seg.zip", task="segment") # segment datasetstats = HUBDatasetStats("path/to/coco8-pose.zip", task="pose") # pose datasetstats = HUBDatasetStats("path/to/dota8.zip", task="obb") # OBB datasetstats = HUBDatasetStats("path/to/imagenet10.zip", task="classify") # classification datasetstats.get_json(save=True)stats.process_images()```"""# 这是类的构造函数，它接受三个参数。# path ：数据集配置文件的路径，默认为 "coco8.yaml" 。# task ：任务类型，可以是 "detect" 、 "segment" 、 "pose" 或 "classify" ，默认为 "detect" 。# autodownload ：一个布尔值，指示是否自动下载数据集，默认为 False 。def __init__(self, path="coco8.yaml", task="detect", autodownload=False):# 初始化类。"""Initialize class."""# 将 path 参数转换为 Path 对象，并使用 resolve() 方法将其解析为绝对路径。path = Path(path).resolve()# 记录一条信息，表示开始检查 HUB 数据集。LOGGER.info(f"Starting HUB dataset checks for {path}....") # 正在启动 HUB 数据集检查 {path}....# 将 task 参数存储在实例变量 self.task 中。self.task = task # detect, segment, pose, classify# 如果任务类型为 "classify" ，则执行以下操作。if self.task == "classify":# 调用 unzip_file 函数来解压文件。unzip_dir = unzip_file(path)# 调用 check_cls_dataset 函数来检查分类数据集。# def check_cls_dataset(dataset, split=""):# -> 检查分类数据集的完整性，并在必要时下载数据集。函数返回一个字典，包含 训练集 、 验证集 和 测试集 的 路径 、 类别数量 和 类别名称 。# -> return {"train": train_set, "val": val_set, "test": test_set, "nc": nc, "names": names}data = check_cls_dataset(unzip_dir)# 将解压后的目录路径存储在 data 字典的 "path" 键中。data["path"] = unzip_dir# 如果任务类型不是 "classify" ，则执行以下操作。else: # detect, segment, pose# 调用实例方法 _unzip 来解压 YAML 文件，并获取数据目录和 YAML 文件的路径。_, data_dir, yaml_path = self._unzip(Path(path))# 尝试执行以下操作，以便在出现异常时捕获并处理。try:# Load YAML with checks# 调用 yaml_load 函数来加载 YAML 文件内容。# def yaml_load(file="data.yaml", append_filename=False):# -> 从 YAML 文件中加载数据，并根据需要将文件名附加到数据字典中。返函数返回一个字典，包含从 YAML 文件中加载的数据。如果 append_filename 为 True ，则字典中还包括一个键 "yaml_file" ，其值为 YAML 文件的路径。# -> return datadata = yaml_load(yaml_path)# 将 data 字典中的 "path" 键设置为空字符串，因为 YAML 文件应该位于所有 HUB 数据集的根目录。data["path"] = "" # strip path since YAML should be in dataset root for all HUB datasets# 调用 yaml_save 函数来保存 YAML 文件。# def yaml_save(file="data.yaml", data=None, header=""): -> 是将 Python 数据结构保存为 YAML 格式的文件。yaml_save(yaml_path, data)# def check_det_dataset(dataset, autodownload=True):# -> 是检查和处理数据集（dataset），确保数据集的YAML配置文件符合要求，并在需要时下载数据集。函数返回处理后的 data 字典，其中包含了 数据集的 配置信息 和 路径 。# -> return data # dictionarydata = check_det_dataset(yaml_path, autodownload) # dict# 将数据目录路径存储在 data 字典的 "path" 键中。data["path"] = data_dir # YAML path should be set to '' (relative) or parent (absolute)# 如果出现异常，则捕获它并抛出一个新的异常。except Exception as e:# 抛出一个新的异常，指示在初始化 HUB 数据集统计时出错，并包含原始异常作为原因。raise Exception("error/HUB/dataset_stats/init") from e# 创建一个实例变量 self.hub_dir ，表示 HUB 数据集目录的路径。self.hub_dir = Path(f'{data["path"]}-hub')# 创建一个实例变量 self.im_dir ，表示 HUB 数据集图像目录的路径。self.im_dir = self.hub_dir / "images"# 创建一个实例变量 self.stats ，存储统计信息，包括 类别数量 和 类别名称 列表。self.stats = {"nc": len(data["names"]), "names": list(data["names"].values())} # statistics dictionary# 将 data 字典存储在实例变量 self.data 中。self.data = data# 这个类的目的是为 HUB 数据集提供初始化检查和统计信息，包括类别数量和名称。它根据不同的任务类型执行不同的检查和操作，并在出现错误时提供错误处理。# 这段代码是一个名为 HUBDatasetStats 类的成员函数，定义为静态方法 _unzip 。这个函数的目的是处理ZIP文件的解压操作，并返回相关的解压信息。@staticmethod# 定义一个静态方法 _unzip ，它接受一个参数。# 1.path ：表示要解压的文件的路径。def _unzip(path):# 解压缩 data.zip。"""Unzip data.zip."""# 检查传入的 path 是否以 .zip 结尾，如果不是（例如，可能是 data.yaml 文件），则返回 False ， None 和 原始 path 。if not str(path).endswith(".zip"): # path is data.yaml# 返回值解释。 False 表示 path 不是ZIP文件。 None 表示没有解压目录（因为不需要解压）。 path 原始传入的路径。return False, None, path# 如果 path 是ZIP文件，调用 unzip_file 函数来解压ZIP文件。解压目录设置为ZIP文件的父目录。unzip_dir = unzip_file(path, path=path.parent)# 使用 assert 语句确保 unzip_dir 是一个存在的目录。assert unzip_dir.is_dir(), (# 如果 unzip_dir 不是一个目录，抛出一个错误，说明解压失败，并且指出ZIP文件应该解压到与其同名的目录中。f"Error unzipping {path}, {unzip_dir} not found. " f"path/to/abc.zip MUST unzip to path/to/abc/" # 解压 {path} 时出错，未找到 {unzip_dir}。“f”path/to/abc.zip 必须解压至 path/to/abc/。)# 返回值解释。# True ：表示 path 是ZIP文件且已成功解压。# str(unzip_dir) ：解压目录的路径字符串。# find_dataset_yaml(unzip_dir) ：在解压目录中查找YAML配置文件的路径。这个函数返回YAML文件的路径。# def find_dataset_yaml(path: Path) -> Path: -> 在给定的路径下查找一个特定的YAML文件。返回找到的第一个（也是唯一一个）YAML文件的 Path 对象。 -> return files[0]return True, str(unzip_dir), find_dataset_yaml(unzip_dir) # zipped, data_dir, yaml_path# 这个方法的目的是处理ZIP文件的解压，并提供解压目录和YAML配置文件的路径，这些信息对于后续的数据集检查和加载是必要的。通过静态方法的方式，它不需要类的实例就可以被调用，提供了灵活性。# 这段代码定义了一个名为 _hub_ops 的方法，它是 HUBDatasetStats 类的一个实例方法，用于处理图像文件的压缩操作。# 定义一个方法 _hub_ops ，它接受两个参数.# 1.self ：类的实例自身。# 2.f ：要处理的文件的路径。def _hub_ops(self, f):# 保存压缩图像以供 HUB 预览。"""Saves a compressed image for HUB previews."""# def compress_one_image(f, f_new=None, max_dim=1920, quality=50): -> 压缩一张图片，减少其尺寸和文件大小。# 调用 compress_one_image 函数，传入两个参数 ：# f ：要压缩的图像文件的路径。# self.im_dir / Path(f).name ：压缩后的图像文件的保存路径。这里使用 Path 对象的 / 运算符来连接 self.im_dir （一个类实例变量，指向图像的存储目录）和原始文件的名称（通过 Path(f).name 获取）。这意味着压缩后的图像将保存在 self.im_dir 指定的目录中，并且保持原始文件的名称。compress_one_image(f, self.im_dir / Path(f).name) # save to dataset-hub# 这个方法的目的是将指定的图像文件压缩并保存到类实例变量 self.im_dir 指定的目录中。这个方法可能是数据集处理流程的一部分，用于优化存储在数据集中心（dataset-hub）的图像文件的大小。通过压缩图像，可以减少存储空间的使用，同时保持图像的质量。# 这段代码定义了一个名为 get_json 的方法，它是 HUBDatasetStats 类的一个实例方法，用于生成和处理数据集的统计信息，并以JSON格式返回。# 定义一个方法 get_json ，它接受三个参数。# 1.self ：类的实例自身。# 2.save ：一个布尔值，指示是否保存统计信息为JSON文件，默认为 False 。# 3.verbose ：一个布尔值，指示是否在控制台打印统计信息，默认为 False 。def get_json(self, save=False, verbose=False):# 返回 Ultralytics HUB 的数据集 JSON。"""Return dataset JSON for Ultralytics HUB."""# 这段代码定义了一个名为 _round 的内部函数，它用于处理数据集中的标签，将类别标签转换为整数，并将坐标值四舍五入到四位小数。这个函数根据不同的任务类型（检测、分割、姿态估计）处理不同的标签格式。# 定义一个名为 _round 的函数，它接受一个参数。# 1.labels ：这是一个包含标签信息的字典。def _round(labels):# 将标签更新为整数类和 4 位小数浮点数。"""Update labels to integer class and 4 decimal place floats."""# 如果任务类型是目标检测（ "detect" ），则从 labels 字典中获取边界框坐标（ "bboxes" ）。if self.task == "detect":coordinates = labels["bboxes"]# 如果任务类型是图像分割（ "segment" ）或方向边界框（OBB， "obb" ），则从 labels 字典中获取分割或OBB坐标，并使用 flatten() 方法将它们展平。elif self.task in {"segment", "obb"}: # Segment and OBB use segments. OBB segments are normalized xyxyxyxycoordinates = [x.flatten() for x in labels["segments"]]# 如果任务类型是姿态估计（ "pose" ），则从 labels 字典中获取关键点坐标，并将其与边界框坐标连接起来。elif self.task == "pose":n, nk, nd = labels["keypoints"].shapecoordinates = np.concatenate((labels["bboxes"], labels["keypoints"].reshape(n, nk * nd)), 1)# 如果任务类型不是上述任何一种，则抛出一个 ValueError 异常，指出任务类型未定义。else:# 未定义数据集任务={self.task}。raise ValueError(f"Undefined dataset task={self.task}.")# 将 类别标签 （ "cls" ）和 坐标值 打包在一起。zipped = zip(labels["cls"], coordinates)# 对于每一对类别标签和坐标值，将类别标签转换为整数，并将坐标值四舍五入到四位小数，然后返回一个包含这些值的新列表。return [[int(c[0]), *(round(float(x), 4) for x in points)] for c, points in zipped]# 这个函数的目的是统一标签的格式，确保类别标签是整数，坐标值是四位小数的浮点数，这对于数据集的一致性和后续处理非常重要。# 这段代码是 get_json 方法的一部分，它负责为分类任务的数据集生成统计信息。# 遍历 训练集 （ train ）、 验证集（ val ）和 测试集 （ test ）。for split in "train", "val", "test":# 在统计字典 self.stats 中为当前分割预定义一个空值。self.stats[split] = None # predefine# 尝试从 self.data 字典中获取当前分割的路径。path = self.data.get(split)# Check split# 如果当前分割没有路径（即没有数据），则跳过当前循环。if path is None: # no splitcontinue# 使用 Path 类的 rglob 方法递归地搜索所有文件，并筛选出文件扩展名在 IMG_FORMATS 列表中的图像文件。files = [f for f in Path(path).rglob("*.*") if f.suffix[1:].lower() in IMG_FORMATS] # image files in split# 如果没有找到图像文件，则跳过当前分割。if not files: # no imagescontinue# Get dataset statistics# 如果任务类型是分类（ "classify" ），则执行以下操作。if self.task == "classify":# 导入 torchvision 库中的 ImageFolder 类。from torchvision.datasets import ImageFolder# 创建一个 ImageFolder 数据集实例，它会自动加载目录中的图像并为每个类别创建标签。dataset = ImageFolder(self.data[split])# 创建一个零数组 x ，其长度等于类别数，用于存储每个类别的图像数量。x = np.zeros(len(dataset.classes)).astype(int)# 遍历 ImageFolder 数据集的 imgs 属性，它是一个包含 图像路径 和 对应类别索引 的元组列表。对于每个图像，增加 对应类别 的计数。for im in dataset.imgs:x[im[1]] += 1# 构建统计信息字典，存储在 self.stats[split] 中。self.stats[split] = {# 计算 总图像数 和 每个类别的 图像数 。"instance_stats": {"total": len(dataset), "per_class": x.tolist()},# 计算 总图像数 、 未标记图像数 （对于分类任务，所有图像都有标签，所以为0） 和 每个类别的图像数 。"image_stats": {"total": len(dataset), "unlabelled": 0, "per_class": x.tolist()},# 创建一个包含 图像文件名 和 对应类别索引 的字典列表，作为标签信息。"labels": [{Path(k).name: v} for k, v in dataset.imgs],}# 这段代码的目的是为分类任务的数据集生成统计信息，包括总图像数、每个类别的图像数和标签信息，并将这些信息存储在 self.stats 字典中。这些统计信息可以用于进一步的数据分析和模型评估。# 这段代码处理非分类任务的数据集统计信息，特别适用于目标检测、分割和姿态估计等任务。# 如果任务不是分类任务，从 ultralytics.data 模块导入 YOLODataset 类。else:from ultralytics.data import YOLODataset# 创建一个 YOLODataset 实例，传入图像路径、数据集信息和任务类型。# class YOLODataset(BaseDataset):# -> YOLODataset 的类，它继承自 BaseDataset 类。这个类是用于初始化一个与 YOLO 相关的数据集。# -> def __init__(self, *args, data=None, task="detect", **kwargs):dataset = YOLODataset(img_path=self.data[split], data=self.data, task=self.task)x = np.array([# np.bincount(x, minlength=None)# np.bincount 是 NumPy 库中的一个函数，它用于计算非负整数数组中每个值的出现次数。# 参数 ：# x ：输入数组，其中的元素必须是非负整数。# minlength （可选） ：输出数组的最小长度。如果提供，数组 x 中小于 minlength 的值将被忽略，而 x 中等于或大于 minlength 的值将导致数组被扩展以包含这些值。如果未提供或为 None ，则输出数组的长度将与 x 中的最大值加一相匹配。# 返回值 ：# 返回一个数组，其中第 i 个元素代表输入数组 x 中值 i 出现的次数。# 功能 ：# np.bincount 函数对输入数组 x 中的每个值进行计数，返回一个一维数组，其长度至少与 x 中的最大值一样大。# 如果 x 中的某个值没有出现，那么在返回的数组中对应的位置将为 0。# 例：# x = np.array([1, 2, 3, 3, 0, 1, 4])# np.bincount(x)# '''# array([1, 2, 1, 2, 1], dtype=int64)# '''# 统计索引出现次数：索引0出现1次，1出现2次，2出现1次，3出现2次，4出现1次。# 使用 np.bincount 计算每个类别的实例数。 label["cls"] 是类别标签， astype(int) 确保它们是整数类型， flatten() 将它们展平。# minlength=self.data["nc"] 确保 bincount 的范围至少包含所有类别。np.bincount(label["cls"].astype(int).flatten(), minlength=self.data["nc"])# 这个计算在 tqdm 进度条中进行，显示统计进度。for label in TQDM(dataset.labels, total=len(dataset), desc="Statistics")]) # shape(128x80)# 构建统计信息字典，存储在 self.stats[split] 中。self.stats[split] = {# 计算总实例数和每个类别的实例数。"instance_stats": {"total": int(x.sum()), "per_class": x.sum(0).tolist()},# 计算 总图像数 、 未标记图像数 （所有类别标签都为0的图像数）和 每个类别的图像数 。"image_stats": {"total": len(dataset),"unlabelled": int(np.all(x == 0, 1).sum()),"per_class": (x > 0).sum(0).tolist(),},# 为每个图像文件生成标签信息，其中 Path(k).name 是图像文件的名称， _round(v) 是处理后的标签数据（四舍五入坐标值和转换类别标签为整数）。"labels": [{Path(k).name: _round(v)} for k, v in zip(dataset.im_files, dataset.labels)],}# 这段代码的目的是为非分类任务的数据集生成统计信息，包括总实例数、每个类别的实例数、总图像数、未标记图像数、每个类别的图像数和标签信息，并将这些信息存储在 self.stats 字典中。这些统计信息对于数据分析和模型评估非常有用。# Save, print and return# 这段代码是 get_json 方法的最后部分，它负责保存和打印统计信息，并返回统计数据。# 检查是否设置了 save 参数为 True ，如果是，则执行以下操作来保存统计信息。if save:# 确保 self.hub_dir 指向的目录存在，如果不存在，则创建它。 parents=True 允许创建多级目录， exist_ok=True 表示如果目录已存在则不抛出异常。self.hub_dir.mkdir(parents=True, exist_ok=True) # makes dataset-hub/# 构建统计信息文件的路径，将 stats.json 文件放在 self.hub_dir 目录下。stats_path = self.hub_dir / "stats.json"# 记录一条信息，指出正在保存统计信息文件。LOGGER.info(f"Saving {stats_path.resolve()}...") # 正在保存 {stats_path.resolve()}...# 打开 stats.json 文件进行写入，使用 json.dump 将 self.stats 字典转换为JSON格式并保存到文件中。with open(stats_path, "w") as f:# json.dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)# 在Python中， dump() 函数通常与序列化相关，特别是在处理JSON数据时。 dump() 函数可以将Python对象序列化为JSON格式的字符串。这个函数是 json 模块的一部分，用于将Python的数据结构转换为JSON格式。# 参数说明 ：# obj ：要序列化的Python对象。# fp ：一个文件类对象，具有 .write() 方法，例如 open() 函数返回的文件对象。# skipkeys ：如果为 True ，则 dict 类型的键值对中，如果键不是字符串，则跳过该键值对。# ensure_ascii ：如果为 True ，则所有非ASCII字符将被转义。# check_circular ：如果为 True ，则检查循环引用的对象，如果发现循环引用，则抛出 TypeError 。# allow_nan ：如果为 True ，则允许序列化 NaN 、 Infinity 和 -Infinity 。# cls ：一个自定义的 JSONEncoder 类，用于自定义序列化过程。# indent ：用于美化输出的缩进级别，如果为 None ，则不美化输出。# separators ：一个元组，包含分隔符，用于控制美化输出时的行和值之间的分隔符。# default ：一个函数，用于处理无法被序列化的类型。# sort_keys ：如果为 True ，则在美化输出时，字典的键将被排序。# **kw ：传递给 JSONEncoder 的其他参数。# 返回值 ：# 无返回值，因为 dump() 直接将序列化后的JSON数据写入到提供的文件对象中。# 异常 ：# 如果在序列化过程中遇到无法被序列化的类型，且未提供 default 函数，则抛出 TypeError 。# 需要注意的是， dump() 函数是用于写入文件的，如果你需要获取JSON字符串而不是写入文件，可以使用 json.dumps() 函数，它与 json.dump() 类似，但返回序列化后的JSON字符串而不是写入文件。json.dump(self.stats, f) # save stats.json# 检查是否设置了 verbose 参数为 True ，如果是，则执行以下操作来打印统计信息。if verbose:# json.dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)# json.dumps() 是 Python 中 json 模块的一个函数，用于将 Python 对象转换成 JSON 格式的字符串。# 参数说明 ：# obj ：要被序列化的 Python 对象。# skipkeys ：（默认 False ）如果为 True ，则在序列化时会跳过字典中的非字符串键。# ensure_ascii ：（默认 True ）如果为 True ，则所有非 ASCII 字符将被转义。# check_circular ：（默认 True ）如果为 True ，则会检查对象中是否存在循环引用。# allow_nan ：（默认 True ）如果为 True ，则 NaN 和 Infinity 值会被序列化成有效 JSON。# cls ：（默认 None ）一个自定义的 JSON 编码器类的实例。# indent ：（默认 None ）如果是一个非负整数，那么它指定了每个层级的缩进数，用于美化输出。# separators ：（默认 None ）一个元组，指定了分隔符，用于替代默认的 ", " 和 ": " 。# default ：（默认 None ）一个函数，用于处理未被 json 模块支持的类型。# sort_keys ：（默认 False ）如果为 True ，则字典的键在序列化时会被排序。# **kw ：其他关键字参数，会被传递给自定义的编码器。# 返回值 ：# 返回一个 JSON 格式的字符串。# json.dumps() 函数是 Python 中处理 JSON 数据的常用工具，它允许开发者轻松地在 Python 对象和 JSON 格式之间进行转换。# 使用 json.dumps 将 self.stats 字典转换为格式化的JSON字符串，并记录这条信息。 indent=2 使输出的JSON字符串缩进两层， sort_keys=False 表示不排序键。LOGGER.info(json.dumps(self.stats, indent=2, sort_keys=False))# 返回 self.stats 字典，它包含了数据集的统计信息。return self.stats# 这段代码的目的是提供灵活性，允许用户选择是否保存统计信息到文件和/或在控制台打印统计信息。通过这种方式，用户可以根据需要获取和使用统计数据。# 这个方法的目的是为Ultralytics HUB生成数据集的统计信息，包括实例统计、图像统计和标签信息，并将这些信息保存为JSON文件或打印到控制台。# 这段代码定义了一个名为 process_images 的方法，它是 HUBDatasetStats 类的一个实例方法，用于压缩图像并为 Ultralytics HUB 准备图像数据。# 定义一个方法 process_images ，它接受 self ，即类的实例自身。def process_images(self):# 压缩 Ultralytics HUB 的图像。"""Compress images for Ultralytics HUB."""# 导入 ultralytics.data 模块中的 YOLODataset 类。from ultralytics.data import YOLODataset # ClassificationDataset# 确保 self.im_dir 指向的目录存在，如果不存在，则创建它。 parents=True 允许创建多级目录， exist_ok=True 表示如果目录已存在则不抛出异常。self.im_dir.mkdir(parents=True, exist_ok=True) # makes dataset-hub/images/# 遍历 训练集 （ train ） 、 验证集（ val ） 和 测试集 （ test ）。for split in "train", "val", "test":# 如果当前分割没有数据，则跳过当前循环。if self.data.get(split) is None:continue# 创建一个 YOLODataset 实例，传入图像路径和数据集信息。# class YOLODataset(BaseDataset):# -> YOLODataset 的类，它继承自 BaseDataset 类。这个类是用于初始化一个与 YOLO 相关的数据集。# -> def __init__(self, *args, data=None, task="detect", **kwargs):dataset = YOLODataset(img_path=self.data[split], data=self.data)# 创建一个 ThreadPool 实例， NUM_THREADS 是一个定义线程数量的常量。 with 语句确保线程池的正确创建和退出。# NUM_THREADS -> 用于设置 OpenMP（一个用于多平台共享内存并行编程的API）的线程数。with ThreadPool(NUM_THREADS) as pool:# 使用 pool.imap 方法并行地对 dataset.im_files 中的每个图像文件应用 self._hub_ops 方法。# TQDM 用于显示进度条。# imap 方法将 self._hub_ops 函数应用于 dataset.im_files 中的每个元素，并返回一个迭代器。 for 循环遍历这个迭代器，但使用 _ 作为占位符，因为我们不关心返回值，只关心进度条。for _ in TQDM(pool.imap(self._hub_ops, dataset.im_files), total=len(dataset), desc=f"{split} images"):pass# 记录一条信息，指出所有图像已成功保存到 self.im_dir 指定的目录。LOGGER.info(f"Done. All images saved to {self.im_dir}") # 完成。所有图像已保存至 {self.im_dir}。# 返回 self.im_dir ，即保存压缩图像的目录路径。return self.im_dir# 这个方法的目的是为 Ultralytics HUB 压缩和准备图像数据，通过并行处理提高效率，并使用 TQDM 显示进度。压缩后的图像保存在 self.im_dir 指定的目录中。14.def compress_one_image(f, f_new=None, max_dim=1920, quality=50):
# 这段代码定义了一个名为 compress_one_image 的函数，其目的是压缩一张图片，减少其尺寸和文件大小。
# 定义一个函数 compress_one_image ，它接受四个参数。
# 1.f ：要压缩的图片文件的路径。
# 2.f_new ：压缩后的图片文件的保存路径。如果为 None ，则覆盖原文件。
# 3.max_dim ：压缩后图片的最大尺寸，默认为 1920 像素。
# 4.quality ：JPEG 压缩质量，范围从 1（最差）到 100（最佳），默认为 50。
def compress_one_image(f, f_new=None, max_dim=1920, quality=50):# 使用 Python 图像库 (PIL) 或 OpenCV 库将单个图像文件压缩为较小尺寸，同时保留其纵横比和质量。如果输入图像小于最大尺寸，则不会调整其大小。"""Compresses a single image file to reduced size while preserving its aspect ratio and quality using either the PythonImaging Library (PIL) or OpenCV library. If the input image is smaller than the maximum dimension, it will not beresized.Args:f (str): The path to the input image file.f_new (str, optional): The path to the output image file. If not specified, the input file will be overwritten.max_dim (int, optional): The maximum dimension (width or height) of the output image. Default is 1920 pixels.quality (int, optional): The image compression quality as a percentage. Default is 50%.Example:```pythonfrom pathlib import Pathfrom ultralytics.data.utils import compress_one_imagefor f in Path("path/to/dataset").rglob("*.jpg"):compress_one_image(f)```"""# 尝试使用 Python Imaging Library (PIL) 来处理图片压缩。try: # use PIL# 使用 PIL 的 Image.open 方法打开图片文件。im = Image.open(f)# 计算压缩比率 r ，即 max_dim 与图片较高和较宽尺寸中的最大值的比率。r = max_dim / max(im.height, im.width) # ratio# 使用 PIL 的 resize 方法按比率 r 压缩图片。if r < 1.0: # image too large# Image.resize(size, resample=Image.BICUBIC, box=None, reducing_gap=None)# 在Python的Pillow库（PIL的更新和更活跃的分支）中， resize() 方法用于更改图像的尺寸。这个方法是 Image 类的一个实例方法，可以在加载图像后调用它来改变图像的大小。# 参数 ：# size ：一个元组，包含新的宽度和高度，格式为 (width, height) 。# resample ：一个可选参数，指定重采样滤镜。默认值为 Image.BICUBIC 。其他选项包括 Image.NEAREST , Image.BILINEAR , Image.LANCZOS 等。# box ：一个可选参数，用于指定裁剪区域的元组，格式为 (left, upper, right, lower) 。如果提供， size 将指定裁剪区域的尺寸，而不是整个图像的尺寸。# reducing_gap ：一个可选参数，用于控制Lanczos滤镜在缩小图像时的加速因子。# resize() 方法是非常强大的，因为它允许开发者精确控制图像的尺寸变化，并且可以选择不同的重采样滤镜来优化结果。这对于图像预处理、缩略图生成等场景非常有用。im = im.resize((int(im.width * r), int(im.height * r)))# Image.save(filename, format=None, dpi=None, quality=None, optimize=False,icc_profile=None, **kwargs)# 在Python的Pillow库（PIL的后继库）中， save() 方法是 Image 类的一个实例方法，用于将图像保存到文件中。# 参数 ：# filename ：保存的文件名，可以是路径字符串或 Path 对象。# format ：保存的文件格式。如果为 None ，则根据文件扩展名自动检测格式。例如， .jpg 或 .jpeg 会被认为是JPEG格式。# dpi ：一个元组 (x_dpi, y_dpi) 指定图像的DPI（每英寸点数）。默认为 None 。# quality ：对于JPEG格式，这个参数指定保存图像的质量，范围从1（最差）到95（最佳），默认为75。对于PNG格式，这个参数指定压缩级别，范围从0（无压缩）到9。# optimize ：一个布尔值，指示是否优化文件大小。对于JPEG，这通常意味着在不显著降低质量的情况下减少文件大小。# icc_profile ：指定要嵌入到图像文件中的ICC颜色配置文件。默认为 None 。# **kwargs ：其他关键字参数，这取决于保存的图像格式。# save() 方法是Pillow库中用于图像文件输出的关键方法，它提供了灵活的选项来控制输出文件的格式、质量和压缩。# 使用 PIL 的 save 方法保存压缩后的图片。如果 f_new 为 None ，则覆盖原文件。设置图片格式为 JPEG，压缩质量为 quality ，并启用优化。im.save(f_new or f, "JPEG", quality=quality, optimize=True) # save# 如果使用 PIL 处理图片时出现异常，则捕获异常并尝试使用 OpenCV 来处理。except Exception as e: # use OpenCV# 记录一条警告信息，指出 PIL 处理失败，并提供失败的文件路径和异常信息。LOGGER.info(f"WARNING ⚠️ HUB ops PIL failure {f}: {e}") # 警告 ⚠️ HUB 操作 PIL 失败 {f}：{e}。# 使用 OpenCV 的 imread 函数读取图片文件。im = cv2.imread(f)# 获取图片的高度和宽度。im_height, im_width = im.shape[:2]# 重新计算压缩比率 r 。r = max_dim / max(im_height, im_width) # ratio# 如果比率 r 小于 1，说明图片尺寸需要压缩。if r < 1.0: # image too large# 使用 OpenCV 的 resize 函数按比率 r 压缩图片。im = cv2.resize(im, (int(im_width * r), int(im_height * r)), interpolation=cv2.INTER_AREA)# 使用 OpenCV 的 imwrite 函数保存压缩后的图片。如果 f_new 为 None ，则覆盖原文件。cv2.imwrite(str(f_new or f), im)
# 这个函数的目的是提供一个灵活的图片压缩工具，它首先尝试使用 PIL 来处理图片，如果失败则回退到使用 OpenCV。这样的设计可以在 PIL 可用时提供更好的性能和兼容性，同时保证了在 PIL 不可用时的鲁棒性。15.def autosplit(path=DATASETS_DIR / "coco8/images", weights=(0.9, 0.1, 0.0), annotated_only=False):
# 这段代码定义了一个名为 autosplit 的函数，其目的是自动将一个图像数据集分割成训练集、验证集和测试集。
# 定义一个函数 autosplit ，它接受三个参数。
# 1.path ：图像数据集的路径，默认为 DATASETS_DIR / "coco8/images" 。
# 2.weights ：一个三元组，表示训练集、验证集和测试集的比例，默认为 (0.9, 0.1, 0.0) ，意味着90%的图像用于训练，10%用于验证，0%用于测试。
# 3.annotated_only ：一个布尔值，指示是否只使用已标注的图像，默认为 False 。
def autosplit(path=DATASETS_DIR / "coco8/images", weights=(0.9, 0.1, 0.0), annotated_only=False):# 自动将数据集拆分为训练/验证/测试拆分并将结果拆分保存到 autosplit_*.txt 文件中。"""Automatically split a dataset into train/val/test splits and save the resulting splits into autosplit_*.txt files.Args:path (Path, optional): Path to images directory. Defaults to DATASETS_DIR / 'coco8/images'.weights (list | tuple, optional): Train, validation, and test split fractions. Defaults to (0.9, 0.1, 0.0).annotated_only (bool, optional): If True, only images with an associated txt file are used. Defaults to False.Example:```pythonfrom ultralytics.data.utils import autosplitautosplit()```"""# 将 path 参数转换为 Path 对象。path = Path(path) # images dir# 使用 rglob 方法递归地搜索所有文件，并筛选出文件扩展名在 IMG_FORMATS 列表中的图像文件，然后进行排序。files = sorted(x for x in path.rglob("*.*") if x.suffix[1:].lower() in IMG_FORMATS) # image files only# 计算图像文件的数量。n = len(files) # number of files# 设置随机种子，以确保结果的可重复性。random.seed(0) # for reproducibility# 使用 random.choices 方法根据给定的权重随机分配每个图像到一个分割中。 [0, 1, 2] 分别代表训练集、验证集和测试集的索引。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# 检查这三个文本文件是否已存在，如果存在，则删除它们。for x in txt:if (path.parent / x).exists():(path.parent / x).unlink() # remove existing# 记录一条信息，指出正在自动分割图像，并根据 annotated_only 参数决定是否只使用已标注的图像。LOGGER.info(f"Autosplitting images from {path}" + ", using *.txt labeled images only" * annotated_only) # 自动从 {path}" + " 分割图像，仅使用 *.txt 标签图像。# 使用 zip 函数将索引和图像文件名配对，并使用 TQDM 显示进度条。for i, img in TQDM(zip(indices, files), total=n):# 如果 annotated_only 参数为 False ，或者对应的图像有标注文件存在（通过 img2label_paths 函数检查），则执行以下操作。if not annotated_only or Path(img2label_paths([str(img)])[0]).exists(): # check label# 将图像的相对路径写入对应的文本文件中。这里使用 relative_to 方法获取图像相对于父目录的相对路径，并使用 as_posix 方法将其转换为 POSIX 风格的路径。with open(path.parent / txt[i], "a") as f:# path.as_posix()# 在 Python 的 pathlib 模块中， Path 类的 .as_posix() 方法用于将 Path 对象表示的路径转换为 POSIX 风格的字符串。POSIX 是一个操作系统标准，它规定了文件路径应该使用正斜杠（ / ）作为目录分隔符。# path ： Path 类的实例。# 返回值 ：# 返回一个字符串，表示 Path 对象的路径，其中所有的路径分隔符都被替换为正斜杠（ / ）。# 方法功能 ：# .as_posix() 方法将 Path 对象中的路径转换为一个字符串，这个字符串使用正斜杠（ / ）作为所有目录的分隔符，无论在原始路径中使用的是哪种操作系统的路径分隔符（例如，在 Windows 中可能是反斜杠 \ ）。# 此外，该方法还会处理路径中的一些特殊情况，例如，将相对路径（如 ./ 或 ../ ）转换为简化形式，但不改变它们的相对性。 去除路径中多余的分隔符。# 注意事项 ：# .as_posix() 方法不检查路径的实际存在性，它仅仅进行字符串层面的转换。# 如果你需要在不同的操作系统之间移植代码，或者与期望 POSIX 路径风格的外部工具或库交互，使用 .as_posix() 方法可以帮助确保路径的兼容性。f.write(f"./{img.relative_to(path.parent).as_posix()}" + "\n") # add image to txt file
# 这个函数的目的是自动将一个图像数据集分割成训练集、验证集和测试集，并将分割结果写入文本文件中。这在机器学习和计算机视觉项目中是一个常见的预处理步骤。16.def load_dataset_cache_file(path):
# 这段代码定义了一个名为 load_dataset_cache_file 的函数，它用于从指定路径加载 Ultralytics 的 .cache 字典文件。
# 定义了一个函数 load_dataset_cache_file ，它接受一个参数.
# 1.path ：这是要加载的 .cache 文件的路径。
def load_dataset_cache_file(path):# 从路径加载 Ultralytics *.cache 字典。"""Load an Ultralytics *.cache dictionary from path."""# 导入 Python 的垃圾回收模块 gc 。import gc# 禁用垃圾回收。这是为了减少使用 pickle 加载对象时的时间，因为在加载大型对象时，垃圾回收可能会引起性能下降。这个优化是在 GitHub 上的一个拉取请求（PR #1585）中提出的。gc.disable() # reduce pickle load time https://github.com/ultralytics/ultralytics/pull/1585# numpy.load(file, mmap_mode=None, allow_pickle=False, fix_imports=False, encoding='bytes')# np.load() 函数是 NumPy 库中用于加载 .npy 或 .npz 文件的函数。这些文件格式用于存储单一的 NumPy 数组或多个数组（分别对应 .npy 和 .npz 文件）。 np.load() 函数可以读取这些文件中存储的数组数据。# 参数 ：# file ：要加载的文件路径，可以是字符串路径或文件对象。# mmap_mode ：（可选）内存映射模式，用于控制如何将文件内容映射到内存中。默认为 None ，表示不使用内存映射。# allow_pickle ：（可选）布尔值，指示是否允许加载 pickle 对象。默认为 False ，出于安全考虑，防止执行不受信任的数据。# fix_imports ：（可选）布尔值，指示是否修复导入路径。默认为 False ，仅在加载 pickle 对象时相关。# encoding ：（可选）字符串，指定文件编码。默认为 'bytes' ，表示文件内容被读取为字节字符串。# 返回值 ：# 返回加载的 NumPy 数组或包含多个数组的字典（对于 .npz 文件）。# np.load() 函数是 NumPy 数据持久化和读取数据的重要工具，特别适用于需要保存和恢复大型数组数据的场景。# numpy.ndarray.item(*args)# item() 是一个 Python 函数，它用于将一个 numpy ndarray 对象转换为 Python 的标准数据类型（如整数、浮点数、复数、字符串等）。# 参数 ：# args ：（可选）用于指定要提取的元素的位置索引。如果未提供任何索引，则返回整个数组作为一个 Python 标量。# 返回值 ：# 返回一个 Python 标量对象，它是从数组中提取的元素。# 描述 ：# item() 方法将 numpy 数组中的单个元素提取出来，并将其转换为等效的 Python 标量类型。如果数组中只有一个元素，你可以直接使用 item() 方法来获取这个元素。如果数组中有多个元素，你需要指定要提取的元素的索引。# item() 方法是将 numpy 数据类型转换为 Python 原生数据类型的一种简便方式，特别适用于需要将数值从 numpy 数组中提取出来并作为 Python 标量处理的情况。# 使用 NumPy 的 load 函数加载 path 指定的 .cache 文件。# str(path) 确保路径是字符串格式，因为 np.load 需要一个文件名字符串作为输入。 allow_pickle=True 允许加载被 pickle 序列化的对象。出于安全考虑，默认情况下， np.load 不允许 pickle，因为加载恶意的 pickle 数据可能导致安全问题。# .item() 是一个将 NumPy 数组转换为 Python 原生数据类型（如字典、列表等）的方法。在这里，它将加载的缓存数据转换为字典。cache = np.load(str(path), allow_pickle=True).item() # load dict# 重新启用垃圾回收。gc.enable()# 返回加载的缓存字典。return cache
# 这个函数的作用是快速加载 .cache 文件中的数据，这些数据通常是在训练过程中预先计算和存储的，以便在后续的训练或验证过程中快速访问。通过禁用垃圾回收，可以减少加载这些大型对象时的开销，从而提高性能。17.def save_dataset_cache_file(prefix, path, x, version):
# 这段代码定义了一个名为 save_dataset_cache_file 的函数，它用于将一个名为 x 的数据集缓存字典保存到指定的路径。
# 定义了一个函数 save_dataset_cache_file ，它接受四个参数。
# 1.prefix ：用于日志消息的前缀。
# 2.path ：要保存缓存文件的路径。
# 3.x ：要缓存的数据集字典。
# 4.version ：缓存的版本号。
def save_dataset_cache_file(prefix, path, x, version):# 将 Ultralytics 数据集 *.cache 字典 x 保存到路径。"""Save an Ultralytics dataset *.cache dictionary x to path."""# 在字典 x 中添加一个键 "version" ，其值为传入的 version 参数，用于标记缓存的版本。x["version"] = version # add cache version# 调用 is_dir_writeable 函数检查 path 的父目录是否可写。if is_dir_writeable(path.parent):# 检查 path 指定的文件是否已经存在。if path.exists():# 如果文件存在，则使用 unlink 方法删除它，为创建新的缓存文件做准备。path.unlink() # remove *.cache file if exists# 使用 NumPy 的 save 函数将字典 x 保存到 path 指定的路径，以便下次使用。np.save(str(path), x) # save cache for next time# 将保存的 .npy 文件重命名为 .cache 扩展名，以符合文件命名约定。path.with_suffix(".cache.npy").rename(path) # remove .npy suffix# 使用 LOGGER 记录一个信息级别的日志，表明新的缓存文件已创建，并显示文件路径。LOGGER.info(f"{prefix}New cache created: {path}") # {prefix} 创建新缓存：{path}。# 如果 path 的父目录不可写，执行 else 块的代码。else:# 使用 LOGGER 记录一个警告级别的日志，表明缓存目录不可写，因此缓存文件未被保存。LOGGER.warning(f"{prefix}WARNING ⚠️ Cache directory {path.parent} is not writeable, cache not saved.") # {prefix}警告 ⚠️ 缓存目录 {path.parent} 不可写入，缓存未保存。
# 这个函数的主要作用是将数据集的元数据或处理结果缓存起来，以便加快后续的处理速度或避免重复计算。通过保存缓存文件，程序可以在下次运行时直接加载缓存，而不是重新处理整个数据集。
