Supervision Notebook 绘图工具：plot_image 与 plot_images

Supervision Notebook 绘图工具：plot_image 与 plot_images_grid 使用指南

【免费下载链接】supervisionWe write your reusable computer vision tools. 💜项目地址: https://gitcode.com/GitHub_Trending/su/supervision

在 Jupyter Notebook 中可视化计算机视觉处理结果是调试与展示模型效果的常见需求。Supervision（仓库根目录）在 src/supervision/utils/notebook.py 中提供了两个专门面向 Notebook 场景的绘图助手——plot_image与plot_images_grid，它们统一接收numpy.ndarray与PIL.Image.Image两种图像类型，内部自动完成 BGR→RGB 颜色通道转换与格式归一，并把 matplotlib 的导入推迟到真正绘图时，从而避免无关开销。读完本文，你将掌握这两个 API 的参数语义、输入类型兼容规则、网格容量校验逻辑，以及它们在检测可视化、数据集抽查、模型对比等典型工作流中的组合用法。

概览与典型应用场景

Notebook 辅助模块位于 src/supervision/utils/notebook.py，对外暴露两个函数：

plot_image(image, size=(12, 12), cmap="gray")：在 matplotlib 画布上展示单张图像；
plot_images_grid(images, grid_size, titles=None, size=(12, 12), cmap="gray")：将多张图像按行列排列在一个网格中统一展示，可附加标题。

两者均通过 supervision 包顶层命名空间导出，即import supervision as sv后即可直接以sv.plot_image、sv.plot_images_grid方式调用（见 src/supervision/init.py 与公共 API 白名单 src/supervision/init.py）。在 GitHub Trending 的 su/supervision 仓库中，这两个助手被广泛用于各流程式示例文档（docs/how_to 与 docs/utils 目录）：

检测与标注结果展示：将BoxAnnotator、LabelAnnotator、MaskAnnotator等标注器产出的标注帧直接送入sv.plot_image渲染（见检测与标注指南）；
数据集抽查：遍历sv.DetectionDataset前 N 张图，批量标注后经sv.plot_images_grid拼成网格快速目检标签质量（见数据集处理指南）；
模型对比：把同一批图片上 Ground Truth 与模型预测的标注结果按网格并排输出，直观评估检测偏差（见模型基准测试指南）。

输入图像类型：numpy.ndarray 与 PIL.Image 的自动归一

两个函数在参数类型上使用ImageType（numpy.ndarray或PIL.Image.Image），并在入口统一归一为 numpy 数组，相关类型别名与转换实现可参考 src/supervision/draw/base.py 与 pillow_to_cv2 转换工具。

在 plot_image 的源码中，函数先判断输入是否为PIL.Image.Image实例，若是则调用pillow_to_cv2转成 numpy 数组，否则直接使用原数组；随后根据通道数分流渲染：

二维灰度/单通道数组：直接plt.imshow(image_np, cmap=cmap)，颜色映射由cmap控制（默认"gray"）；
三维彩色数组：因 Supervision 生态统一约定图像为BGR 布局（与 OpenCV 一致），而 matplotlib 期望 RGB，故渲染前先经cv2.cvtColor(image_np, cv2.COLOR_BGR2RGB)转换后再调用plt.imshow（见 src/supervision/utils/notebook.py）。

plot_images_grid采用相同的归一策略：对images列表中每个元素逐项做pillow_to_cv2转换（src/supervision/utils/notebook.py），后续按ndim == 2区分单通道与三通道渲染（src/supervision/utils/notebook.py）。这意味着你可以放心把模型返回的 OpenCV 帧、增强后的PIL.Image混排在同一个列表里，无需手动统一格式或翻转通道。

单图展示：sv.plot_image

plot_image用 matplotlib 打开一个尺寸为size（单位为英寸）的画布，绘制图像后关闭坐标轴并调用plt.show()显示。其签名与完整参数如下（与 Notebook 工具 API 文档中supervision.utils.notebook.plot_image的 mkdocstrings 生成内容一一对应）：

参数	类型	默认值	含义
`image`	`ImageType`	必填	待显示的图像，接受`numpy.ndarray`或`PIL.Image.Image`
`size`	`tuple[int, int]`	`(12, 12)`	画布大小，单位为英寸（宽度, 高度）
`cmap`	`str \\| None`	`"gray"`	单通道图像使用的颜色映射

源码参考 src/supervision/utils/notebook.py。其中size的单位为英寸这一语义在仓库演进中曾被专门澄清，可参考更新日志中相关修复记录（plot_image明确说明 size 单位为英寸）。

典型用法示例（摘自函数 docstring，src/supervision/utils/notebook.py）：

>>> import numpy as np >>> import matplotlib >>> matplotlib.use('Agg') # 阻止 GUI 窗口弹出 >>> import supervision as sv >>> image = np.zeros((100, 100, 3), dtype=np.uint8) >>> sv.plot_image(image=image, size=(16, 16))

两点实用建议：

若运行环境无桌面显示，可预先调用matplotlib.use('Agg')使用非交互后端，避免弹出 GUI 窗口阻塞脚本；
若你的图像是 PIL 对象或二维灰度数组，也无需预处理，直接传入即可；彩色数组请保持 OpenCV 的 BGR 布局，函数会自动完成通道转换。

网格多图展示：sv.plot_images_grid

当需要一次性对比多张图片（例如批量抽样、预测与真值对照）时，使用plot_images_grid可在同一画布上按行列排布若干子图。其完整签名与参数如下（对应 Notebook 工具 API 文档中的supervision.utils.notebook.plot_images_grid）：

参数	类型	默认值	含义
`images`	`list[ImageType]`	必填	待展示的图像列表，元素可为`numpy.ndarray`或`PIL.Image.Image`
`grid_size`	`tuple[int, int]`	必填	网格行列数`(rows, columns)`
`titles`	`list[str] \\| None`	`None`	每张图片的标题，按列表顺序对应
`size`	`tuple[int, int]`	`(12, 12)`	整个画布的尺寸，单位为英寸
`cmap`	`str \\| None`	`"gray"`	单通道图像使用的颜色映射

实现细节与边界行为（src/supervision/utils/notebook.py）：

网格容量校验：函数会先比较len(images)与nrows * ncols。当图片数量超过网格容量时抛出ValueError，提示信息为"The number of images exceeds the grid size. Please increase the grid size or reduce the number of images."（见 src/supervision/utils/notebook.py）；
空位自动隐藏：若图片数量少于网格容量，多余的子图坐标轴会被关闭（ax.axis("off")），不会渲染空白内容（src/supervision/utils/notebook.py）；
标题按序对应：titles非空时，第idx张图使用titles[idx]作为子图标题（src/supervision/utils/notebook.py）；
延迟导入设计：matplotlib 的pyplot在函数内部才被导入，因此仅导入supervision或本模块并不会加载 matplotlib 依赖。对应测试 tests/utils/test_notebook.py 中的test_notebook_import_does_not_import_matplotlib_pyplot明确断言：importlib.import_module("supervision.utils.notebook")之后"matplotlib.pyplot"不在sys.modules中，保证轻量加载。

docstring 中的示例（src/supervision/utils/notebook.py）：

>>> import numpy as np >>> import matplotlib >>> matplotlib.use('Agg') # 阻止 GUI 窗口弹出 >>> import supervision as sv >>> from PIL import Image >>> image1 = np.zeros((100, 100, 3), dtype=np.uint8) >>> image2 = Image.new('RGB', (100, 100)) >>> image3 = np.zeros((100, 100, 3), dtype=np.uint8) >>> images = [image1, image2, image3] >>> titles = ["Image 1", "Image 2", "Image 3"] >>> sv.plot_images_grid(images, grid_size=(2, 2), titles=titles, size=(16, 16))

注意示例中列表含 3 张图、网格为 2×2=4 格：这是“图片数小于网格容量、空位自动隐藏”的合法场景；若换成 5 张图则会触发上述ValueError。

实战工作流一：数据集标注结果抽查

在数据集处理指南中，plot_images_grid被用于对sv.DetectionDataset做可视化质检——逐张画框、贴标签，再以 4×4 网格整体呈现前 16 张样本：

import supervision as sv ds = sv.DetectionDataset(...) box_annotator = sv.BoxAnnotator() label_annotator = sv.LabelAnnotator() annotated_images = [] for i in range(16): _, image, annotations = ds[i] labels = [ds.classes[class_id] for class_id in annotations.class_id] annotated_image = image.copy() annotated_image = box_annotator.annotate(annotated_image, annotations) annotated_image = label_annotator.annotate(annotated_image, annotations, labels) annotated_images.append(annotated_image) sv.plot_images_grid( annotated_images, grid_size=(4, 4), )

这里grid_size=(4, 4)恰好等于 16 个样本的容量，属于图片数与网格容量完全匹配的用法。如需抽查其他数量，例如展示 9 张，可将grid_size调整为(3, 3)（如模型基准测试指南中N = 9、GRID_SIZE = (3, 3)的做法）。

实战工作流二：模型预测与真值并排对比

在基准测试场景（docs/how_to/benchmark_a_model.md）中，先用sv.PolygonAnnotator以不同颜色标注目标真值与模型预测，累积成annotated_images列表后统一交给plot_images_grid展示：

import supervision as sv N = 9 GRID_SIZE = (3, 3) target_annotator = sv.PolygonAnnotator(color=sv.Color.from_hex("#8315f9"), thickness=8) prediction_annotator = sv.PolygonAnnotator( color=sv.Color.from_hex("#00cfc6"), thickness=6 ) annotated_images = [] for image_path, predictions, targets in zip( image_paths[:N], predictions_list[:N], targets_list[:N] ): annotated_image = cv2.imread(image_path) annotated_image = target_annotator.annotate( scene=annotated_image, detections=targets ) annotated_image = prediction_annotator.annotate( scene=annotated_image, detections=predictions ) annotated_images.append(annotated_image) sv.plot_images_grid(images=annotated_images, grid_size=GRID_SIZE)

配合彩色标注后，紫色多边形为真值（ground truth）、青色多边形为模型预测，同一网格中即可快速定位漏检、误检与框位偏移。该指南还提示：检测任务可用sv.BoxAnnotator，旋转框（OBB）任务可改用sv.OrientedBoxAnnotator，相关标注器列表可查阅检测标注器文档。

实战工作流三：单张检测结果快速展示

配合MaskAnnotator等分割标注器时，单张结果通常直接用plot_image收尾（见检测与标注指南与 docs/how_to/detect_and_annotate.md）：

import cv2 import supervision as sv from rfdetr.detr import RFDETRSegSmall model = RFDETRSegSmall() image = cv2.imread("dog.jpeg") detections = model.predict(image[:, :, ::-1]) mask_annotator = sv.MaskAnnotator() label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER_OF_MASS) annotated_image = mask_annotator.annotate( scene=image, detections=detections, ) annotated_image = label_annotator.annotate( scene=annotated_image, detections=detections, ) sv.plot_image(annotated_image)

无论底层模型来自 RF-DETR、Inference 还是 Ultralytics，只要先将模型输出包装为sv.Detections，标注与展示链路完全一致。

边界情况与注意事项小结

结合源码、测试与文档示例，使用这两个工具时请注意：

容量限制：plot_images_grid的图片数超过rows × cols时抛ValueError，务必先校验长度或留出余量；
尺寸单位：size的单位是英寸而非像素，过小会挤压子图可读性，可按展示内容多少酌情调整（默认(12, 12)）；
颜色空间：彩色 numpy 数组请按 BGR 布局传入，函数内部自动转换为 matplotlib 所需的 RGB；单通道图像用cmap控制伪彩色映射（默认灰度"gray"）；
PIL 兼容：PIL.Image.Image输入会被自动归一，可与 numpy 数组混用；
轻量导入：仅 import supervision 不会连带加载 matplotlib.pyplot，绘图开销仅在真正调用时产生（tests/utils/test_notebook.py 有专门回归测试）；
无头环境：服务器或无显示器环境建议预先matplotlib.use('Agg')以禁用 GUI。