YOLO基于图像块的推理

这个Python库简化了类似SAHI的实例分割任务推理,使得能够检测图像中的小物体。它适用于目标检测和实例分割任务,支持多种Ultralytics模型。

该库还为所有模型的推理结果可视化提供了优雅的定制,包括标准方法(直接网络运行)和独特的基于图像块的变体。

模型支持: 该库支持多种ultralytics深度学习模型,如YOLOv8、YOLOv8-seg、YOLOv9、YOLOv9-seg、YOLOv10、FastSAM和RTDETR。用户可以选择预训练选项或使用自定义训练的模型来最好地满足他们的任务需求。

基于图像块推理的工作原理解释:

安装

你可以通过pip安装该库:

pip install patched_yolo_infer

- 点击此处访问patched-yolo-infer的PyPI页面。

注意:如果有CUDA支持,建议在安装该库之前先安装支持CUDA的PyTorch。否则,默认将安装CPU版本。

交互式笔记本

提供了交互式笔记本来展示该库的功能。这些笔记本涵盖了检测、实例分割、自定义推理可视化等的批量推理程序。每个笔记本都配有YouTube上的教程,方便学习和实现功能。

主题	笔记本	YouTube
[基于图像块推理示例][nb_example1]	[![在Colab中打开][colab_badge]][colab_ex1]	<div align="center">[<img width=30% alt="Youtube视频" src=https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-youtube-rect.png>][yt_link1]
[常规推理结果自定义可视化示例][nb_example2]	[![在Colab中打开][colab_badge]][colab_ex2]	<div align="center">[<img width=30% alt="Youtube视频" src=https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-youtube-rect.png>][yt_link2]

对于俄罗斯用户,有一个详细的项目视频演示。俄语YouTube视频可在此链接获得。

示例:

检测示例:

实例分割示例 1:

实例分割示例 2:

使用方法

1. 基于图像块的推理

要使用我们的库进行YOLO模型的基于图像块的推理,你需要遵循一个顺序过程。首先,创建一个MakeCropsDetectThem类的实例,提供所有与YOLO推理和图像块分割原理相关的所需参数。<br/>随后,将这个类的对象传递给CombineDetections,它促进了来自每个重叠图像块的所有预测的合并,然后智能地抑制重复项。<br/>完成后,你会得到结果,从中可以提取所需的帧处理结果。

从这个过程中获得的输出包含几个可以用于进一步分析或可视化的属性:

img: 此属性包含进行推理的原始图像。它为检测到的对象提供了上下文。
confidences: 此属性保存与每个检测到的对象相关的置信度分数。这些分数表示模型对其预测准确性的信心水平。
boxes: 这些边界框表示为列表的列表,其中每个列表包含四个值:[x_min, y_min, x_max, y_max]。这些值对应于每个边界框左上角和右下角的坐标。
polygons: 如果可用,此属性提供一个包含NumPy数组的列表,这些数组是对应于检测到的对象的分割掩码的多边形坐标。这些多边形可用于准确勾勒每个对象的边界。
classes_ids: 此属性包含分配给每个检测到的对象的类别ID。这些ID对应于模型训练阶段定义的特定对象类别。
classes_names: 这些是与类别ID相对应的人类可读名称。它们为检测到的对象提供语义标签,使结果更容易解释。

import cv2
from patched_yolo_infer import MakeCropsDetectThem, CombineDetections
# 加载图像
img_path = "test_image.jpg"
img = cv2.imread(img_path)

element_crops = MakeCropsDetectThem(
    image=img,
    model_path="yolov8m.pt",
    segment=False,
    shape_x=640,
    shape_y=640,
    overlap_x=50,
    overlap_y=50,
    conf=0.5,
    iou=0.7,
)
result = CombineDetections(element_crops, nms_threshold=0.25)  

# 最终结果：
img=result.image
confidences=result.filtered_confidences
boxes=result.filtered_boxes
polygons=result.filtered_polygons
classes_ids=result.filtered_classes_id
classes_names=result.filtered_classes_names

可能的输入参数说明：

MakeCropsDetectThem 实现裁剪和将裁剪后的图像传递给神经网络进行检测/分割的类：

参数	类型	默认值	描述
image	np.ndarray		BGR格式的输入图像。
model_path	str	"yolov8m.pt"	YOLO模型的路径。
model	ultralytics model	None	预初始化的模型对象。如果提供，将直接使用该模型，而不是从model_path加载。
imgsz	int	640	YOLO推理的输入图像大小。
conf	float	0.5	YOLO检测的置信度阈值。
iou	float	0.7	单个裁剪图像YOLOv8非极大值抑制的IoU阈值。
classes_list	List[int] or None	None	用于过滤检测结果的类别列表。如果为None，则考虑所有类别。
segment	bool	False	是否执行分割（如果模型支持）。
shape_x	int	700	x坐标上的裁剪大小。
shape_y	int	600	y坐标上的裁剪大小。
overlap_x	float	25	x轴上的重叠百分比。
overlap_y	float	25	y轴上的重叠百分比。
show_crops	bool	False	是否可视化裁剪过程。
resize_initial_size	bool	True	是否将结果调整回原始输入图像大小（注：操作较慢）。
memory_optimize	bool	True	分割的内存优化选项（启用时结果精度较低）。
inference_extra_args	dict	None	包含额外ultralytics 推理参数的字典（可能的键：half, device, max_det, augment, agnostic_nms 和 retina_masks）
batch_inference	bool	False	通过神经网络对图像裁剪进行批量推理，而不是顺序传递裁剪（注：推理更快，但GPU内存使用更高）。

CombineDetections 实现合并多个裁剪的掩码/边界框并进行NMS（非极大值抑制）的类：

参数	类型	默认值	描述
element_crops	MakeCropsDetectThem		包含裁剪信息的对象。
nms_threshold	float	0.3	非极大值抑制的IoU/IoS阈值。值越小，抑制后保留的对象越少。
match_metric	str	IOS	匹配度量，可选'IOU'或'IOS'。
class_agnostic_nms	bool	True	决定目标检测中的NMS模式。当设为True时，NMS跨所有类别操作，忽略类别区别，全局抑制置信度较低的边界框。否则，NMS将分别应用于每个类别。
intelligent_sorter	bool	True	启用按面积和四舍五入的置信度参数排序。如果为False，则仅按置信度排序（常规NMS）。
sorter_bins	int	5	intelligent_sorter使用的分箱数。分箱数越少，NMS更依赖于对象大小而非置信度分数。

2. 自定义推理结果可视化：

在图像上可视化基于分块的目标检测或分割结果。
visualize_results 函数的可能参数：

参数	类型	默认值	描述
img	numpy.ndarray		BGR格式的输入图像。
boxes	list		边界框列表，格式为[x_min, y_min, x_max, y_max]。
classes_ids	list		每个检测结果的类别ID列表。
confidences	list	[]	对应每个边界框的置信度分数列表。
classes_names	list	[]	对应类别ID的类别名称列表。
polygons	list	[]	包含表示分割掩码的多边形坐标NumPy数组的列表。
masks	list	[]	分割二值掩码列表。
segment	bool	False	是否执行实例分割可视化。
show_boxes	bool	True	是否显示边界框。
show_class	bool	True	是否显示类别标签。
fill_mask	bool	False	是否用颜色填充分割区域。
alpha	float	0.3	填充掩码的透明度。
color_class_background	tuple	(0, 0, 255)	类别标签的背景BGR颜色。
color_class_text	tuple	(255, 255, 255)	类别标签的文本颜色。
thickness	int	4	边界框和文本的粗细。
font	cv2.font	cv2.FONT_HERSHEY_SIMPLEX	类别标签的字体类型。
font_scale	float	1.5	字体大小的缩放因子。
delta_colors	int	seed=0	颜色变化的随机种子偏移。
dpi	int	150	最终可视化大小（dpi越高，绘图越大）。
random_object_colors	bool	False	如果为真，每个对象的颜色将随机选择。
show_confidences	bool	False	如果为真且show_class=True，将在类别旁显示置信度。
axis_off	bool	True	如果为真，最终可视化中将关闭坐标轴。
show_classes_list	list	[]	如果为空，可视化所有类别。否则，只可视化列表中的类别。
list_of_class_colors	list	None	表示每个类别BGR格式颜色的元组列表。如果提供，将使用这些颜色显示类别，而不是随机颜色。
return_image_array	bool	False	如果为True，函数将返回图像（BGR np.array）而不是显示它。

使用示例：

from patched_yolo_infer import visualize_results

# 假设result是CombineDetections类的一个实例
result = CombineDetections(...) 

# 使用visualize_results函数可视化结果
visualize_results(
    img=result.image,
    confidences=result.filtered_confidences,
    boxes=result.filtered_boxes,
    polygons=result.filtered_polygons,
    classes_ids=result.filtered_classes_id,
    classes_names=result.filtered_classes_names,
    segment=False,
)

获得最佳基于补丁推理结果的技巧

最佳裁剪大小和重叠: 要确保高质量的结果，需要仔细选择裁剪（补丁）的大小和它们的重叠程度。建议不要创建过多的裁剪，并将重叠设置在15%到40%之间。
可视化裁剪: 要查看生成的裁剪，在初始化MakeCropsDetectThem元素时设置show_crops=True。这将显示补丁数量和一张图像，展示基于您初始化的参数（shape_x、shape_y、overlap_x和overlap_y）这些补丁的样子。
裁剪大小考虑: 每个裁剪的大小必须超过图像中预期检测的最大物体的大小。否则，可能无法检测到该物体。
增强补丁内检测: 要在单个裁剪中检测更多物体，增加imgsz参数并降低置信度阈值（conf）。所有可用于配置Ultralytics模型推理的参数在初始化MakeCropsDetectThem元素时也可访问。
处理重复抑制问题: 如果遇到重叠补丁的重复抑制问题，考虑调整CombineDetections中的nms_threshold和sorter_bins参数，或修改补丁本身的重叠和大小参数。（注：通常将sorter_bins降低到4或2可能会有帮助）。
处理多类检测问题: 如果您正在进行多类检测或实例分割任务，将CombineDetections参数中的模式切换为class_agnostic_nms=False可能会有帮助。默认模式（class_agnostic_nms设为True）在处理预训练YOLO网络中大量密切相关的类别时特别有效（例如，经常混淆"汽车"和"卡车"类别）。如果在您的场景中，一个类别的物体可以物理上位于另一个类别的物体内部，那么对于这种情况，您绝对应该设置class_agnostic_nms=False。
高质量实例分割: 对于需要高质量实例分割结果的任务，在README的下一节提供了详细指导。

如何提高实例分割任务的算法质量：

在这种方法中，底层的所有操作都是在已识别对象的二进制掩码上进行的。存储这些掩码会消耗大量内存，因此这种方法需要更多的RAM和略微更长的处理时间。然而，识别的准确性显著提高，这在存在许多不同大小的密集排列对象的情况下尤为明显。因此，如果准确性比速度更重要，且您的计算资源允许在RAM中存储数百个二进制掩码，我们建议在生产环境中使用这种方法。

使用该函数的方法差异在于在MakeCropsDetectThem类中指定参数memory_optimize=False。在这种情况下，处理后的信息值将是以下内容：

img：此属性包含执行推理的原始图像。它为检测到的对象提供上下文。
confidences：此属性包含与每个检测到的对象相关的置信度分数。这些分数表示模型对其预测准确性的信心水平。
boxes：这些边界框表示为列表的列表，其中每个列表包含四个值：[x_min, y_min, x_max, y_max]。这些值对应于每个边界框左上角和右下角的坐标。
masks：此属性提供与检测到的对象相对应的分割二进制掩码。这些掩码可用于精确描绘对象边界。
classes_ids：此属性包含分配给每个检测到的对象的类别ID。这些ID对应于模型训练阶段定义的特定对象类别。
classes_names：这些是与类别ID对应的人类可读名称。它们为检测到的对象提供语义标签，使结果更易于理解。

以下是获取这些信息的方法：

img=result.image
confidences=result.filtered_confidences
boxes=result.filtered_boxes
masks=result.filtered_masks
classes_ids=result.filtered_classes_id
classes_names=result.filtered_classes_names

在Google Colab笔记本中提供了使用此模式的示例 - [![Open In Colab][colab_badge]][colab_ex1_memory_optimize]

如何自动确定patches（裁剪）的最佳参数：

要高效处理大量不同大小和内容的图像，手动选择最佳的patch大小和重叠可能很困难。为解决这个问题，开发了一种算法来自动计算patches（裁剪）的最佳参数。

auto_calculate_crop_values函数有两种运行模式：

基于分辨率的分析：此模式评估源图像的分辨率来确定最佳的patch大小和重叠。它更快，但可能不会产生最高质量的结果，因为它不考虑图像中实际存在的对象。
基于神经网络的分析：这种高级模式使用神经网络来分析图像。算法在整个图像上执行标准的网络推理，并识别最大的检测对象。基于这些对象的大小，算法选择patch参数，以确保最大的对象完全包含在一个patch内，而重叠的patches确保全面覆盖。在这种模式下，需要输入将在后续步骤中用于基于patch的推理的模型。

auto_calculate_crop_values函数的可能参数：

参数	类型	默认值	描述
image	np.ndarray		BGR格式的输入图像。
mode	str	"network_based"	要执行的分析类型。可以是"resolution_based"（基于分辨率的分析）或"network_based"（基于神经网络的分析）。
model	ultralytics model	YOLO("yolov8m.pt")	"network_based"模式下的预初始化模型对象。如果未提供，将使用默认的YOLOv8m模型。
classes_list	list	None	在"network_based"模式下要考虑的类别索引列表。如果为None，将考虑所有类别。
conf	float	0.25	"network_based"模式下的检测置信度阈值。

使用示例：

import cv2
from ultralytics import YOLO
from patched_yolo_infer import auto_calculate_crop_values

# 加载图像
img_path = "test_image.jpg"
img = cv2.imread(img_path)

# 计算图像的最佳裁剪大小和重叠
shape_x, shape_y, overlap_x, overlap_y = auto_calculate_crop_values(
    image=img, mode="network_based", model=YOLO("yolov8m.pt")
)