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.PyTorch functions 

6.def torch_load(*args, **kwargs): 

7.def torch_save(*args, **kwargs): 

---

1.所需的库和模块

# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
# 使用 Monkey 补丁来更新/扩展现有功能。
"""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 多语言友好功能------------------------------------------------------------------------------
# 这段代码定义了一个别名 _imshow ，用于 OpenCV 的 cv2.imshow 函数。这种做法通常是为了避免在后续代码中直接调用原函数时可能出现的递归错误。
# 定义了一个别名 _imshow ，它指向 OpenCV 的 cv2.imshow 函数。
# 目的 ：通过这种方式，可以避免在后续代码中直接调用 cv2.imshow ，从而防止可能出现的递归错误。
# 递归错误 ：递归错误通常发生在函数调用自身时，如果没有正确的退出条件，会导致无限递归，最终导致栈溢出错误。在某些情况下，如果开发者需要对 cv2.imshow 函数进行包装或修改其行为，直接调用原函数可能会导致递归调用问题。
# 应用场景 ：在对 cv2.imshow 函数进行扩展或修改时，使用别名可以安全地调用原函数，确保代码的逻辑清晰且不会出现递归问题。
_imshow = cv2.imshow  # copy to avoid recursion errors    复制以避免递归错误。
# 这段代码通过定义 _imshow 别名，为 OpenCV 的 cv2.imshow 函数创建了一个安全的代理。这种做法的主要目的是避免在后续代码中直接调用原函数时可能出现的递归错误。通过使用别名，开发者可以在不影响原函数功能的前提下，对这些函数进行扩展或修改，从而实现更灵活的功能。

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."""# 这是函数的核心部分，使用了 OpenCV 的 cv2.imdecode 函数来读取图像。# np.fromfile(filename, np.uint8) ：从文件中读取二进制数据，并将其转换为 NumPy 数组。 np.uint8 表示数据类型为无符号8位整数。# cv2.imdecode ：将从文件中读取的二进制数据解码为图像。 flags 参数决定了图像的读取模式（例如彩色、灰度等）。return cv2.imdecode(np.fromfile(filename, np.uint8), flags)
# 这段代码实现了一个自定义的 imread 函数，用于从文件中读取图像。它通过 np.fromfile 读取文件的二进制数据，并将其转换为 NumPy 数组，然后使用 cv2.imdecode 将其解码为图像。这种方法特别适用于处理非标准文件路径或需要支持多种文件格式的场景。与 OpenCV 的默认 cv2.imread 函数相比，这种方法更加灵活，能够更好地处理文件路径和编码问题。

3.def imwrite(filename: str, img: np.ndarray, params=None): 

# 这段代码定义了一个自定义的 imwrite 函数，用于将图像保存到文件中。
# 定义了一个函数 imwrite ，它接受三个参数。
# 1.filename ：一个字符串，表示要保存的目标图像文件路径。
# 2.img ：一个 NumPy 数组，表示要保存的图像。
# 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 块来尝试执行保存图像的操作。如果在执行过程中发生异常，将捕获异常并返回 False 。try:# Path(filename).suffix ：使用path lib.Path 模块获取文件的扩展名（例如 .jpg 、 .png 等）。这用于确定保存图像的格式。# cv2.imencode ：将图像编码为指定格式的二进制数据。 Path(filename).suffix 提供了文件扩展名， img 是要保存的图像， params 是附加参数。# cv2.imencode(...)[1] ： cv2.imencode 返回一个元组，其中第二个元素是编码后的二进制数据。# .tofile(filename) ：将编码后的二进制数据写入目标文件。cv2.imencode(Path(filename).suffix, img, params)[1].tofile(filename)# 如果图像成功保存，返回 True 。return True# 如果在保存图像的过程中发生任何异常，将捕获异常。except Exception:# 如果发生异常，返回 False ，表示图像保存失败。return False
# 这段代码实现了一个自定义的 imwrite 函数，用于将图像保存到文件中。它通过 cv2.imencode 将图像编码为指定格式的二进制数据，然后使用 .tofile 方法将数据写入目标文件。函数还通过 try-except 块来处理可能发生的异常，确保在保存失败时能够返回错误信息。这种方法特别适用于需要处理文件路径和格式的场景，比 OpenCV 的默认 cv2.imwrite 函数更加灵活和健壮。

4.def imshow(winname: str, mat: np.ndarray): 

# 这段代码定义了一个自定义的 imshow 函数，用于在指定窗口中显示图像。
# 定义了一个函数 imshow ，它接受两个参数。
# 1.winname ：一个字符串，表示显示图像的窗口名称。
# 2.mat ：一个 NumPy 数组，表示要显示的图像。
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.encode("unicode_escape").decode() ： winname.encode("unicode_escape") 将窗口名称字符串编码为 Unicode 转义序列。例如， "图像" 会被编码为 "\u56fe\u50cf" 。 .decode() 将编码后的 Unicode 转义序列解码回普通字符串。这一步是为了确保窗口名称在不同操作系统和语言环境下都能正确显示。# mat ：传递给 _imshow 的图像数据。_imshow(winname.encode("unicode_escape").decode(), mat)
# 这段代码实现了一个自定义的 imshow 函数，用于在指定窗口中显示图像。它通过将窗口名称进行 Unicode 转义编码和解码，确保窗口名称在多语言环境下能够正确显示。这种方法特别适用于需要支持多语言窗口标题的场景。

5.PyTorch functions 

# PyTorch functions ----------------------------------------------------------------------------------------------------
# 这段代码定义了两个别名 _torch_load 和 _torch_save ，分别用于 PyTorch 的 torch.load 和 torch.save 函数。这种做法通常是为了避免在后续代码中直接调用原函数时可能出现的递归错误。
# 定义了一个别名 _torch_load ，它指向 PyTorch 的 torch.load 函数。
# 目的 ：通过这种方式，可以避免在后续代码中直接调用 torch.load ，从而防止可能出现的递归错误。递归错误通常发生在函数调用自身时，如果没有正确的退出条件，会导致无限递归，最终导致栈溢出错误。
# 应用场景 ：在某些情况下，开发者可能需要对 torch.load 函数进行包装或修改其行为，而直接调用原函数可能会导致递归调用问题。通过定义别名，可以安全地调用原函数。
_torch_load = torch.load  # copy to avoid recursion errors
# 定义了一个别名 _torch_save ，它指向 PyTorch 的 torch.save 函数。
# 目的 ：与 _torch_load 类似，为了避免在后续代码中直接调用 torch.save ，从而防止递归错误。
# 应用场景 ：在对 torch.save 函数进行扩展或修改时，使用别名可以避免直接调用原函数，确保代码的逻辑清晰且不会出现递归问题。
_torch_save = torch.save
# 这段代码通过定义 _torch_load 和 _torch_save 别名，为 PyTorch 的 torch.load 和 torch.save 函数创建了安全的代理。这种做法的主要目的是避免在后续代码中直接调用原函数时可能出现的递归错误。通过使用别名，开发者可以在不影响原函数功能的前提下，对这些函数进行扩展或修改，从而实现更灵活的功能。

6.def torch_load(*args, **kwargs): 

# 这段代码定义了一个自定义的 torch_load 函数，用于加载 PyTorch 模型或对象，并通过添加额外的参数来避免警告。
# 定义了一个函数 torch_load ，它接受可变长度的参数列表 *args 和任意关键字参数 **kwargs 。这种参数形式允许函数接受任意数量和类型的参数，并将它们传递给 torch.load 。
def torch_load(*args, **kwargs):# 使用更新的参数加载 PyTorch 模型以避免出现警告。# 此函数包装 torch.load 并为 PyTorch 1.13.0+ 添加“weights_only”参数以防止出现警告。# 注意：# 对于 PyTorch 2.0 及更高版本，如果未提供参数，此函数会自动设置“weights_only=False”，以避免出现弃用警告。"""Load a PyTorch model with updated arguments to avoid warnings.This function wraps torch.load and adds the 'weights_only' argument for PyTorch 1.13.0+ to prevent warnings.Args:*args (Any): Variable length argument list to pass to torch.load.**kwargs (Any): Arbitrary keyword arguments to pass to torch.load.Returns:(Any): The loaded PyTorch object.Note:For PyTorch versions 2.0 and above, this function automatically sets 'weights_only=False'if the argument is not provided, to avoid deprecation warnings."""# 从 ultralytics.utils.torch_utils 模块中导入 TORCH_1_13 。 TORCH_1_13 是一个布尔值，用于检查当前安装的 PyTorch 版本是否为 1.13.0 或更高版本。from ultralytics.utils.torch_utils import TORCH_1_13# 检查当前 PyTorch 版本是否为 1.13.0 或更高版本，并且检查 kwargs 中是否已经提供了 weights_only 参数。if TORCH_1_13 and "weights_only" not in kwargs:# 如果没有提供 weights_only 参数，将其设置为 False 。# 这一步是为了避免在 PyTorch 1.13.0 及以上版本中出现的警告，特别是关于 weights_only 参数的弃用警告。kwargs["weights_only"] = False# 调用 _torch_load 函数（这是 torch.load 的别名），并将 *args 和 **kwargs 传递给它。 返回加载的 PyTorch 对象。return _torch_load(*args, **kwargs)
# 这段代码实现了一个自定义的 torch_load 函数，用于加载 PyTorch 模型或对象。它通过检查 PyTorch 版本，并在必要时添加 weights_only=False 参数，避免了在 PyTorch 1.13.0 及以上版本中可能出现的警告。这种方法特别适用于需要兼容多个 PyTorch 版本的场景，确保代码的健壮性和兼容性。

7.def torch_save(*args, **kwargs): 

# 这段代码定义了一个自定义的 torch_save 函数，用于保存 PyTorch 模型或对象。它通过增加重试机制和指数退避策略来提高保存操作的鲁棒性。
# 定义了一个函数 torch_save ，它接受可变长度的参数列表 *args 和任意关键字参数 **kwargs 。这种参数形式允许函数接受任意数量和类型的参数，并将它们传递给 torch.save 。
def torch_save(*args, **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.**kwargs (Any): Keyword arguments to pass to torch.save."""# 使用 for 循环实现最多 3 次重试。循环变量 i 的范围是 0, 1, 2, 3 ，因此总共尝试 4 次（包括第一次尝试）。for i in range(4):  # 3 retries# 在 try 块中调用 _torch_save 函数（这是 torch.save 的别名），并将 *args 和 **kwargs 传递给它。 如果保存操作成功，返回保存的结果。try: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 ），则重新抛出异常，表示保存操作失败。if i == 3:raise e# 如果不是最后一次尝试，则使用指数退避策略等待一段时间后再尝试保存。# time.sleep((2**i) / 2) ：根据尝试次数 i ，计算等待时间。例如 ：# 第一次失败后等待 0.5 秒。# 第二次失败后等待 1.0 秒。# 第三次失败后等待 2.0 秒。# 这种策略可以减少因设备忙或杀毒软件扫描导致的连续失败。time.sleep((2**i) / 2)  # exponential standoff: 0.5s, 1.0s, 2.0s
# 这段代码实现了一个自定义的 torch_save 函数，用于保存 PyTorch 模型或对象。它通过增加重试机制和指数退避策略来提高保存操作的鲁棒性。这种方法特别适用于在某些情况下可能会失败的保存操作，例如磁盘空间不足、设备正在刷新或杀毒软件正在扫描文件等。通过重试和等待，可以显著提高保存操作的成功率。