patches.py
ultralytics\utils\patches.py
目录
patches.py
1.所需的库和模块
2.def imread(filename: str, flags: int = cv2.IMREAD_COLOR):
3.def imwrite(filename: str, img: np.ndarray, params=None):
4.def imshow(winname: str, mat: np.ndarray):
5.def torch_save(*args, use_dill=True, **kwargs):
1.所需的库和模块
# Ultralytics YOLO 🚀, AGPL-3.0 license
"""Monkey patches to update/extend functionality of existing functions."""import time
from pathlib import Pathimport cv2
import numpy as np
import torch# OpenCV Multilanguage-friendly functions OpenCV 多语言友好函数------------------------------------------------------------------------------
# 将 cv2.imshow 函数赋值给 _imshow 变量。这样做的目的是创建一个对 cv2.imshow 函数的备份引用。在后续的代码中，如果对 cv2.imshow 进行了修改或重写，通过 _imshow 仍然可以访问到原始的 cv2.imshow 函数，从而避免递归错误或其他潜在的问题。
_imshow = cv2.imshow # copy to avoid recursion errors 复制以避免递归错误。2.def imread(filename: str, flags: int = cv2.IMREAD_COLOR):
# 这段代码定义了一个名为 imread 的函数，用于读取图像文件。
# 定义函数 imread ，它接受两个参数。
# 1.filename ：字符串类型，表示要读取的图像文件的路径。
# 2.flags ：整数类型，默认值为 cv2.IMREAD_COLOR ，用于指定读取图像的方式，如颜色模式等。
def imread(filename: str, flags: int = cv2.IMREAD_COLOR):# 从文件中读取图像。"""Read an image from a file.Args:filename (str): Path to the file to read.flags (int, optional): Flag that can take values of cv2.IMREAD_*. Defaults to cv2.IMREAD_COLOR.Returns:(np.ndarray): The read image."""# np.fromfile(file, dtype=float, count=-1, sep='', offset=0)# np.fromfile 是 NumPy 库中的一个函数，它用于从二进制文件中读取数据，并将其作为一维数组返回。这个函数特别适合于读取那些以二进制形式存储的数值数据，例如图像文件。# 参数 ：# file ：文件路径或者一个类似文件的对象。可以是字符串路径或者一个具有 read 方法的对象。# dtype ：数组元素的数据类型，默认为 float 。也可以指定为其他类型，如 np.int32 、 np.uint8 等。# count ：要读取的元素数量。如果设置为 -1 （默认值），则读取整个文件。# sep ：仅当文件是文本文件时使用，指定行与行之间的分隔符。# offset ：从文件开头开始读取之前要跳过的字节数。# 返回值 ：# 返回一个一维 NumPy 数组，包含从文件中读取的数据。# 注意事项 ：# np.fromfile 默认以二进制模式读取文件，因此不需要以 'rb' 模式打开文件。# 如果文件中的数据类型不是 float ，需要正确指定 dtype 参数，以确保数据被正确解释。# 如果文件很大，读取整个文件可能会消耗大量内存。在这种情况下，可以考虑分块读取文件。# np.fromfile 不适用于文本文件。对于文本文件，可以使用 np.loadtxt 或 np.genfromtxt 等函数。# cv2.imdecode(buf, flags)# cv2.imdecode() 是 OpenCV 库中的一个函数，它用于从图像内存缓冲区中解码图像数据。这个函数通常与 cv2.imencode() 搭配使用，用于在内存中处理图像数据，而不是直接读写文件。# 参数 ：# buf ：一个包含图像数据的内存缓冲区，通常是一个 NumPy 数组。# flags ：一个标志，指定解码图像的模式，例如 cv2.IMREAD_COLOR 、 cv2.IMREAD_GRAYSCALE 或 cv2.IMREAD_UNCHANGED 。# 返回值 ：# 返回一个包含解码图像的 NumPy 数组，如果解码失败，则返回 None 。# 注意事项 ：# cv2.imdecode() 接受的 buf 参数应该是一个一维 NumPy 数组，其中包含了图像的原始字节数据。# 函数的行为取决于 flags 参数，它决定了图像的解码方式和输出格式。例如， cv2.IMREAD_COLOR 表示以彩色模式读取图像， cv2.IMREAD_GRAYSCALE 表示以灰度模式读取图像。# 如果 buf 参数为空或者图像数据损坏， cv2.imdecode() 将返回 None 。# cv2.imdecode() 是处理图像数据流或从网络接收图像时的有用工具，因为它允许在不直接操作文件的情况下对图像进行解码。# 函数的返回语句。# 首先使用 np.fromfile(filename, np.uint8) 读取文件内容，将其转换为 np.uint8 类型的数组，这是因为图像文件通常是以字节形式存储的。# 然后使用 cv2.imdecode() 函数将这个数组解码为图像， flags 参数决定了解码的方式，如是否读取为彩色图像、灰度图像等。最后将解码得到的图像作为函数的返回值。return cv2.imdecode(np.fromfile(filename, np.uint8), flags)
# 这段代码通过自定义 imread 函数，利用 numpy 和 opencv 库，实现了读取图像文件的功能。它能够根据指定的路径和读取方式，将图像文件加载为可以进行后续处理的图像数据。相比直接使用 cv2.imread() ，这种方式可以更好地处理中文路径等特殊情况。3.def imwrite(filename: str, img: np.ndarray, params=None):
# 这段代码定义了一个名为 imwrite 的函数，用于将图像数据写入到文件中。
# 定义函数 imwrite ，它接收三个参数。
# 1.filename ：字符串类型，表示要写入的文件名。
# 2.img ： np.ndarray 类型，即图像数据。
# 3.params ：可选参数，用于指定图像编码的参数，默认为 None 。
def imwrite(filename: str, img: np.ndarray, params=None):# 将图像写入文件。"""Write an image to a file.Args:filename (str): Path to the file to write.img (np.ndarray): Image to write.params (list of ints, optional): Additional parameters. See OpenCV documentation.Returns:(bool): True if the file was written, False otherwise."""# 开始一个 try 块，用于捕获可能出现的异常。try:# cv2.imencode(ext, img, params=None)# cv2.imencode() 是 OpenCV 库中的一个函数，用于将图像编码为特定格式的内存缓冲区。这个函数常用于准备图像数据以便存储或传输。# 参数 ：# ext ：一个字符串，指定图像的文件扩展名，例如 .jpg 、 .png 等。这个扩展名决定了编码的格式。# img ：要编码的图像，必须是一个有效的图像矩阵。# params ：一个元组或列表，包含特定编码格式的参数。例如，对于 JPEG 图像，可以包含压缩质量（ [cv2.IMWRITE_JPEG_QUALITY, 90] ）。# 返回值 ：# 返回一个元组，其中包含两个元素 ：# 一个布尔值，表示编码是否成功。# 编码后的图像数据，如果成功，它是一个内存缓冲区（即一个字节数组）；如果失败，则为 None 。# 注意事项 ：# cv2.imencode() 需要一个有效的图像矩阵作为输入。如果图像未正确加载或为空，编码将失败。# 编码参数 params 是可选的，但对于一些格式（如 JPEG）来说，可能需要提供额外的参数来控制编码过程。# 编码后的图像数据是一个内存缓冲区，可以直接写入文件或通过网络发送，而不需要先保存到磁盘。# cv2.imencode() 返回的布尔值 ret 可以用来检查编码操作是否成功。如果失败，应进行错误处理。# np.ndarray.tofile(fname, sep="", format="%s")# np.ndarray.tofile() 这是一个 NumPy 数组的方法，用于将数组保存到二进制文件中。# 参数 ：# fname ：要写入的文件名。# sep ：（可选）用于分隔数组元素的字符串，默认为空字符串。# format ：（可选）用于格式化每个元素的字符串，默认为 "%s" 。# 功能 ：# tofile() 方法将 NumPy 数组的内容写入到指定的文件中。该方法按照数组在内存中的布局（通常是行优先顺序）来写入数据。文件被写入的数据是二进制格式的，因此只能使用相同的数据类型和数组形状来读取。# 返回值 ：tofile() 方法不返回任何值。# 注意事项 ：# tofile() 方法只能用于保存二进制数据，因此读取文件时也必须使用相同的数据类型和形状。# 如果需要保存文本格式的数组，可以使用 numpy.savetxt() 函数。# 文件被写入的数据不包含任何形状或类型的元数据，因此读取时需要确保使用正确的形状和数据类型。# 使用 cv2.imencode 函数对图像进行编码。# Path(filename).suffix 获取文件名的扩展名，用于确定编码格式； img 是待编码的图像数据； params 是编码参数。# cv2.imencode 返回一个元组，其中第二个元素是编码后的图像数据，通过 [1] 获取它，然后调用 tofile 方法将其写入到 filename 指定的文件中。cv2.imencode(Path(filename).suffix, img, params)[1].tofile(filename)# 如果图像写入成功，返回 True 。return True# 捕获 try 块中可能出现的任何异常。except Exception:# 如果出现异常，说明图像写入失败，返回 False 。return False
# 这段代码通过 cv2.imencode 对图像进行编码，并将编码后的图像数据写入到指定文件中。如果过程中出现任何异常，如文件写入错误、图像编码失败等，函数会捕获异常并返回 False ，否则返回 True 表示写入成功。它提供了一种简单的方式来将图像数据保存到文件，同时通过异常处理机制保证了函数的健壮性。4.def imshow(winname: str, mat: np.ndarray):
# 这段代码定义了一个名为 imshow 的函数，用于显示图像。
# 定义函数 imshow ，它接收两个参数。
# 1.winname ：字符串类型，表示显示图像的窗口名称。
# 2.mat ： np.ndarray 类型，即要显示的图像数据。
def imshow(winname: str, mat: np.ndarray):# 在指定窗口中显示图像。"""Displays an image in the specified window.Args:winname (str): Name of the window.mat (np.ndarray): Image to be shown."""# 调用 _imshow 函数来实际显示图像。# 首先，对 winname 进行编码和解码操作， winname.encode("unicode_escape") 将窗口名称字符串编码为Unicode转义序列，然后 .decode() 将其解码回普通字符串。这样做的目的是处理窗口名称中可能存在的特殊字符，确保窗口名称在显示时不会出现乱码或其他问题。# 接着，将处理后的窗口名称和图像数据 mat 传递给 _imshow 函数，由 _imshow 函数负责创建窗口并显示图像。_imshow(winname.encode("unicode_escape").decode(), mat)
# 这段代码通过定义 imshow 函数来实现图像的显示功能。它对窗口名称进行了编码和解码处理，以确保窗口名称的正确性，然后调用 _imshow 函数来创建窗口并显示图像数据。这种设计模式使得图像显示功能更加灵活和健壮，同时通过编码解码操作提高了对窗口名称的兼容性。5.def torch_save(*args, use_dill=True, **kwargs):
# PyTorch functions ----------------------------------------------------------------------------------------------------
# 将 torch.save 函数赋值给 _torch_save 变量。这样做的目的是创建一个对 torch.save 函数的备份引用。在后续的代码中，如果对 torch.save 进行了修改或重写，通过 _torch_save 仍然可以访问到原始的 torch.save 函数，从而避免递归错误或其他潜在的问题。
_torch_save = torch.save # copy to avoid recursion errors# 这段代码定义了一个名为 torch_save 的函数，用于保存 PyTorch 模型或数据，并提供了重试机制以处理可能的保存错误。
# 定义函数 torch_save ，它接收任意数量的位置参数 *args 和关键字参数 **kwargs 。此外，还有一个布尔参数 use_dill ，默认值为 True ，用于指定是否使用 dill 库来代替 pickle 库进行序列化。
def torch_save(*args, use_dill=True, **kwargs):# 可选择使用 dill 序列化 lambda 函数（pickle 不支持），通过 3 次重试和指数对峙来增加稳健性，以防保存失败。"""Optionally use dill to serialize lambda functions where pickle does not, adding robustness with 3 retries andexponential standoff in case of save failure.Args:*args (tuple): Positional arguments to pass to torch.save.use_dill (bool): Whether to try using dill for serialization if available. Defaults to True.**kwargs (any): Keyword arguments to pass to torch.save."""# 开始一个 try 块，用于捕获可能出现的异常。try:# 断言 use_dill 为 True 。如果 use_dill 为 False ，则会触发 AssertionError 。assert use_dill# 如果 use_dill 为 True ，则导入 dill 库，并将其别名为 pickle 。 dill 库比 pickle 库更强大，可以序列化更多类型的对象。import dill as pickle# 捕获 AssertionError 或 ImportError 。如果 use_dill 为 False 或者 dill 库未安装，则会执行此块。except (AssertionError, ImportError):# 如果 use_dill 为 False 或者 dill 库未安装，则导入 pickle 库。import pickle# 检查关键字参数 kwargs 中是否包含 pickle_module 。如果不存在，则设置 pickle_module 为 pickle 。if "pickle_module" not in kwargs:# 将 pickle_module 设置为 pickle ，无论是 dill 还是 pickle 。kwargs["pickle_module"] = pickle# 开始一个循环，最多尝试 4 次（3 次重试）。for i in range(4): # 3 retries# 开始一个 try 块，用于捕获可能出现的异常。try:# 调用 _torch_save 函数，传入所有位置参数 *args 和关键字参数 **kwargs 。如果保存成功，返回 True 。return _torch_save(*args, **kwargs)# 捕获 RuntimeError 异常。这通常是因为设备正在刷新或被杀毒软件扫描，导致保存失败。except RuntimeError as e: # unable to save, possibly waiting for device to flush or antivirus scan# 如果这是第 4 次尝试（即 i == 3 ），则重新抛出异常 e 。if i == 3:raise e# time.sleep(seconds)# time.sleep() 是 Python 标准库 time 模块中的一个函数，用于让当前线程暂停执行指定的秒数。# 参数 ：# seconds : 一个浮点数或整数，表示线程暂停的秒数。# 返回值 ：time.sleep() 函数没有返回值，它只是简单地让调用它的线程休眠。# 注意事项 ：# time.sleep() 函数接受的参数是秒数，可以是整数或浮点数，表示精确的暂停时间。# 在多线程程序中， time.sleep() 只暂停当前线程，不影响程序中的其他线程。# 在某些操作系统上， time.sleep() 的实现可能无法精确到微秒级别，实际的暂停时间可能会比指定的时间长一点点。# 在需要精确控制时间的场合，可能需要结合其他同步机制，如 threading 模块中的 Event 或 Condition 对象。# 如果保存失败，等待一段时间再重试。等待时间采用指数退避策略，分别为 0.5 秒、1.0 秒、2.0 秒。time.sleep((2**i) / 2) # exponential standoff: 0.5s, 1.0s, 2.0s
# 这段代码通过定义 torch_save 函数，提供了一种健壮的方式来保存 PyTorch 模型或数据。它支持使用 dill 库来序列化更多类型的对象，并且在保存过程中提供了重试机制，以处理可能的保存错误。通过指数退避策略，每次重试的等待时间逐渐增加，提高了保存操作的成功率。这种设计模式使得函数在面对不稳定环境（如设备刷新或杀毒软件扫描）时更加健壮。