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), cmapgray)在 matplotlib 画布上展示单张图像plot_images_grid(images, grid_size, titlesNone, size(12, 12), cmapgray)将多张图像按行列排列在一个网格中统一展示可附加标题。两者均通过 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 的自动归一两个函数在参数类型上使用ImageTypenumpy.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, cmapcmap)颜色映射由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_imageplot_image用 matplotlib 打开一个尺寸为size单位为英寸的画布绘制图像后关闭坐标轴并调用plt.show()显示。其签名与完整参数如下与 Notebook 工具 API 文档 中supervision.utils.notebook.plot_image的 mkdocstrings 生成内容一一对应参数类型默认值含义imageImageType必填待显示的图像接受numpy.ndarray或PIL.Image.Imagesizetuple[int, int](12, 12)画布大小单位为英寸宽度, 高度cmapstr \| Nonegray单通道图像使用的颜色映射源码参考 src/supervision/utils/notebook.py。其中size的单位为英寸这一语义在仓库演进中曾被专门澄清可参考 更新日志 中相关修复记录plot_image明确说明 size 单位为英寸。典型用法示例摘自函数 docstringsrc/supervision/utils/notebook.py import numpy as np import matplotlib matplotlib.use(Agg) # 阻止 GUI 窗口弹出 import supervision as sv image np.zeros((100, 100, 3), dtypenp.uint8) sv.plot_image(imageimage, 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参数类型默认值含义imageslist[ImageType]必填待展示的图像列表元素可为numpy.ndarray或PIL.Image.Imagegrid_sizetuple[int, int]必填网格行列数(rows, columns)titleslist[str] \| NoneNone每张图片的标题按列表顺序对应sizetuple[int, int](12, 12)整个画布的尺寸单位为英寸cmapstr \| Nonegray单通道图像使用的颜色映射实现细节与边界行为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), dtypenp.uint8) image2 Image.new(RGB, (100, 100)) image3 np.zeros((100, 100, 3), dtypenp.uint8) images [image1, image2, image3] titles [Image 1, Image 2, Image 3] sv.plot_images_grid(images, grid_size(2, 2), titlestitles, size(16, 16))注意示例中列表含 3 张图、网格为 2×24 格这是“图片数小于网格容量、空位自动隐藏”的合法场景若换成 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(colorsv.Color.from_hex(#8315f9), thickness8) prediction_annotator sv.PolygonAnnotator( colorsv.Color.from_hex(#00cfc6), thickness6 ) 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( sceneannotated_image, detectionstargets ) annotated_image prediction_annotator.annotate( sceneannotated_image, detectionspredictions ) annotated_images.append(annotated_image) sv.plot_images_grid(imagesannotated_images, grid_sizeGRID_SIZE)配合彩色标注后紫色多边形为真值ground truth、青色多边形为模型预测同一网格中即可快速定位漏检、误检与框位偏移。该指南还提示检测任务可用sv.BoxAnnotator旋转框OBB任务可改用sv.OrientedBoxAnnotator相关标注器列表可查阅 检测标注器文档。实战工作流三单张检测结果快速展示配合MaskAnnotator等分割标注器时单张结果通常直接用plot_image收尾见 检测与标注指南 与 docs/how_to/detect_and_annotate.mdimport 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_positionsv.Position.CENTER_OF_MASS) annotated_image mask_annotator.annotate( sceneimage, detectionsdetections, ) annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections, ) 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控制伪彩色映射默认灰度grayPIL 兼容PIL.Image.Image输入会被自动归一可与 numpy 数组混用轻量导入仅 import supervision 不会连带加载 matplotlib.pyplot绘图开销仅在真正调用时产生tests/utils/test_notebook.py 有专门回归测试无头环境服务器或无显示器环境建议预先matplotlib.use(Agg)以禁用 GUI。相关资源本模块 API 文档docs/utils/notebook.md源码实现src/supervision/utils/notebook.py惰性导入回归测试tests/utils/test_notebook.py图像通道转换依赖src/supervision/utils/conversion.py实际调用示例检测与标注指南、数据集处理指南、模型基准测试指南【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Supervision Notebook 绘图工具：plot_image 与 plot_images_grid 使用指南
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), cmapgray)在 matplotlib 画布上展示单张图像plot_images_grid(images, grid_size, titlesNone, size(12, 12), cmapgray)将多张图像按行列排列在一个网格中统一展示可附加标题。两者均通过 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 的自动归一两个函数在参数类型上使用ImageTypenumpy.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, cmapcmap)颜色映射由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_imageplot_image用 matplotlib 打开一个尺寸为size单位为英寸的画布绘制图像后关闭坐标轴并调用plt.show()显示。其签名与完整参数如下与 Notebook 工具 API 文档 中supervision.utils.notebook.plot_image的 mkdocstrings 生成内容一一对应参数类型默认值含义imageImageType必填待显示的图像接受numpy.ndarray或PIL.Image.Imagesizetuple[int, int](12, 12)画布大小单位为英寸宽度, 高度cmapstr \| Nonegray单通道图像使用的颜色映射源码参考 src/supervision/utils/notebook.py。其中size的单位为英寸这一语义在仓库演进中曾被专门澄清可参考 更新日志 中相关修复记录plot_image明确说明 size 单位为英寸。典型用法示例摘自函数 docstringsrc/supervision/utils/notebook.py import numpy as np import matplotlib matplotlib.use(Agg) # 阻止 GUI 窗口弹出 import supervision as sv image np.zeros((100, 100, 3), dtypenp.uint8) sv.plot_image(imageimage, 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参数类型默认值含义imageslist[ImageType]必填待展示的图像列表元素可为numpy.ndarray或PIL.Image.Imagegrid_sizetuple[int, int]必填网格行列数(rows, columns)titleslist[str] \| NoneNone每张图片的标题按列表顺序对应sizetuple[int, int](12, 12)整个画布的尺寸单位为英寸cmapstr \| Nonegray单通道图像使用的颜色映射实现细节与边界行为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), dtypenp.uint8) image2 Image.new(RGB, (100, 100)) image3 np.zeros((100, 100, 3), dtypenp.uint8) images [image1, image2, image3] titles [Image 1, Image 2, Image 3] sv.plot_images_grid(images, grid_size(2, 2), titlestitles, size(16, 16))注意示例中列表含 3 张图、网格为 2×24 格这是“图片数小于网格容量、空位自动隐藏”的合法场景若换成 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(colorsv.Color.from_hex(#8315f9), thickness8) prediction_annotator sv.PolygonAnnotator( colorsv.Color.from_hex(#00cfc6), thickness6 ) 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( sceneannotated_image, detectionstargets ) annotated_image prediction_annotator.annotate( sceneannotated_image, detectionspredictions ) annotated_images.append(annotated_image) sv.plot_images_grid(imagesannotated_images, grid_sizeGRID_SIZE)配合彩色标注后紫色多边形为真值ground truth、青色多边形为模型预测同一网格中即可快速定位漏检、误检与框位偏移。该指南还提示检测任务可用sv.BoxAnnotator旋转框OBB任务可改用sv.OrientedBoxAnnotator相关标注器列表可查阅 检测标注器文档。实战工作流三单张检测结果快速展示配合MaskAnnotator等分割标注器时单张结果通常直接用plot_image收尾见 检测与标注指南 与 docs/how_to/detect_and_annotate.mdimport 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_positionsv.Position.CENTER_OF_MASS) annotated_image mask_annotator.annotate( sceneimage, detectionsdetections, ) annotated_image label_annotator.annotate( sceneannotated_image, detectionsdetections, ) 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控制伪彩色映射默认灰度grayPIL 兼容PIL.Image.Image输入会被自动归一可与 numpy 数组混用轻量导入仅 import supervision 不会连带加载 matplotlib.pyplot绘图开销仅在真正调用时产生tests/utils/test_notebook.py 有专门回归测试无头环境服务器或无显示器环境建议预先matplotlib.use(Agg)以禁用 GUI。相关资源本模块 API 文档docs/utils/notebook.md源码实现src/supervision/utils/notebook.py惰性导入回归测试tests/utils/test_notebook.py图像通道转换依赖src/supervision/utils/conversion.py实际调用示例检测与标注指南、数据集处理指南、模型基准测试指南【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考