---

Torchshow 只需一行代码即可可视化你的数据。它专为帮助调试计算机视觉项目而设计。

Torchshow 会自动推断张量的类型，例如 RGB 图像、灰度图像、二值掩码、分类掩码（自动应用调色板）等，并在必要时执行去归一化操作。

支持的类型：

• RGB 图像
• 灰度图像
• 二值掩码
• 分类掩码（整数标签）
• 多张图像
• 视频
• 多段视频
• 光流（由 flow_vis 提供支持）

v0.5.2 新特性

• 修复了 set_window_title 函数中的版本比较错误（#24）。
• 支持更多 PyTorch 张量的数据类型。

完整变更日志请参见 changelogs.md。

安装

从 PyPI 安装：

pip install torchshow

或者，你也可以直接从本仓库安装以体验最新功能：

pip install git+https://github.com/xwying/torchshow.git@master

基本用法

TorchShow 的使用非常简单。只需导入该包，然后用一行代码即可可视化你的数据：

import torchshow as ts
ts.show(tensor)

如果你在没有显示设备的无头服务器上工作，可以使用 ts.save(tensor) 命令（自 0.3.2 版起）。

import torchshow as ts
ts.save(tensor) # 图像将保存到 ./_torchshow/***.png
ts.save(tensor, './vis/test.jpg') # 你可以指定保存路径。

API 参考

详细的 API 参考请查看 API.md 页面。

示例

目录

• 可视化图像张量
• 可视化掩码张量
• 可视化张量批次
• 可视化特征图中的通道
• 使用自定义布局可视化多个张量
• 查看包含丰富信息的像素
• 将张量可视化为视频片段
• 在 Jupyter Notebook 中显示视频动画
• 可视化光流
• 更改通道顺序（RGB/BGR）
• 更改去归一化预设
• 叠加可视化效果

1. 可视化图像张量

可视化类似图像的张量并不难，但可能会非常繁琐。通常你需要将张量转换为具有正确形状的 NumPy 数组。在许多情况下，图像在数据加载器中已经被归一化，这意味着你需要先将其去归一化才能正确显示。

如果你需要频繁检查张量的样子，TorchShow 是一个非常有用的工具。

使用 Matplotlib	使用 TorchShow
图像张量已被归一化，因此 Matplotlib 无法正确显示。	TorchShow 会自动完成转换。

2. 可视化掩码张量

对于语义分割或实例分割相关的项目，我们经常需要可视化掩码张量——无论是真实标注还是模型预测结果。这可以轻松地通过 TorchShow 实现。

使用 Matplotlib	使用 TorchShow
不同实例的颜色相同，部分类别缺失。	TorchShow 在可视化过程中会自动应用调色板。

3. 可视化张量批次

当张量是一批图像时，TorchShow 会自动创建网格布局来可视化它们。你也可以手动控制行数和列数。

4. 可视化特征图

如果输入张量的通道数超过 3 个，TorchShow 会像处理张量批次一样分别可视化每个通道。这对于可视化特征图非常有用。

5. 使用自定义布局可视化多个张量

TorchShow 在使用自定义布局可视化多个张量方面更加灵活。

要控制布局，只需将张量放入二维列表中。以下示例将创建一个 2×3 的网格布局：

ts.show([[tensor1, tensor2, tensor3],
         [tensor4, tensor5, tensor6]])

值得注意的是，网格中不需要填满所有位置。以下示例在一个 2×3 的网格布局中可视化了 5 个张量：

ts.show([[tensor1, tensor2],
         [tensor3, tensor4, tensor5]])

6. 查看包含丰富信息的像素

自 v0.4.1 起，TorchShow 允许你通过将鼠标悬停在感兴趣的像素上来获取更丰富的信息。这对于某些类型的张量，如分类掩码和光流，非常有帮助。

目前，Torchshow 会显示以下信息：

• Mode: 可视化模式。
• Shape: 张量的形状。
• X, Y: 鼠标光标的像素位置。
• Raw: (X, Y) 处的原始张量值。
• Disp: (X, Y) 处的显示值。

注意：如果状态栏未显示相关信息，请尝试调整窗口大小，使其更宽一些。

可以通过 ts.show_rich_info(False) 关闭此功能。

7. 将张量可视化为视频片段

张量可以被可视化为视频片段，这对于序列帧张量非常有用。这可以通过 show_video 函数实现。

ts.show_video(video_tensor)

你还可以使用自定义网格布局来可视化多段视频。

8. 在 Jupyter Notebook 中显示视频动画

TorchShow 将视频片段可视化为 matplotlib.func_animation 对象，默认情况下可能无法在笔记本中显示。以下示例展示了一个简单的技巧来显示它。

import torchshow as ts
from IPython.display import HTML

ani = ts.show_video(video_tensor)
HTML(ani.to_jshtml())

9. 可视化光流

TorchShow 支持可视化光流（由 flow_vis 提供支持）。以下是使用远程连接到 SSH 服务器（已配置 X-server）的 VSCode 调试器进行演示的示例。同时，也支持在 Jupyter Notebook 中运行。

10. 更改通道顺序（RGB/BGR）

默认情况下，TensorFlow 会以 RGB 模式可视化图像张量。如果您使用 OpenCV 加载图像，可以将设置切换为 BGR。

ts.set_color_mode('bgr')

11. 更改反归一化预设

图像张量可能已经过归一化处理。如果未指定，torchshow 会自动将其重新缩放到 0-1 的范围。

要将预设更改为 ImageNet 归一化，可以使用以下代码：

ts.show(tensor, unnormalize='imagenet')

如果需要使用自定义的均值和标准差，可以使用以下命令：

ts.set_image_mean([0., 0., 0.])
ts.set_image_std([1., 1., 1.])

请注意，一旦设置完成，torchshow 将在后续的可视化中使用这些值。这非常有用，因为通常整个项目只会使用一种归一化预设。

12. 叠加可视化

在计算机视觉项目中，我们经常会处理场景的不同表示形式，包括但不限于 RGB 图像、深度图、红外图像、语义分割掩码、实例分割掩码等。有时，为了更好地理解数据，将这些不同的数据叠加在一起进行可视化会非常有帮助。自 v0.5.0 版本起，TorchShow 提供了一个非常实用的 API ts.overlay() 来实现这一功能。

在下面的例子中，我们有一张 RGB 图像及其对应的语义分割掩码。首先让我们使用 TorchShow 分别查看它们的外观。

import torchshow as ts
ts.show(["example_rgb.jpg", "example_category_mask.png"])

现在，我想将掩码叠加到 RGB 图像之上，以便获得更深入的洞察。使用 TorchShow，只需一行代码即可轻松完成。

import torchshow as ts
ts.overlay(["example_rgb.jpg", "example_category_mask.png"], alpha=[1, 0.6])

TorchShow 快速上手指南

TorchShow 是一个专为计算机视觉项目设计的调试工具，只需一行代码即可自动识别并可视化 PyTorch 张量（如 RGB 图像、灰度图、掩码、光流等），自动处理反归一化和颜色映射。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.6+
• 核心依赖：
  • torch (PyTorch)
  • matplotlib
  • numpy
• 显示环境：
  • 本地开发：需具备图形界面显示能力。
  • 无头服务器（Headless Server）：支持直接保存为图片文件，无需显示器。

安装步骤

推荐使用 pip 从 PyPI 安装稳定版：

pip install torchshow

如需体验最新功能，可直接从 GitHub 安装：

pip install git+https://github.com/xwying/torchshow.git@master

提示：国内用户若下载缓慢，可添加国内镜像源加速安装，例如：

pip install torchshow -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 快速可视化张量

导入库后，调用 ts.show() 即可自动识别张量类型并显示：

import torchshow as ts
ts.show(tensor)

TorchShow 会自动判断张量是 RGB 图像、灰度图、二值掩码还是类别掩码，并执行必要的反归一化操作。

2. 在无头服务器上保存结果

如果在没有显示器的服务器上使用，可以使用 ts.save() 将可视化结果保存为图片：

import torchshow as ts
ts.save(tensor) # 默认保存至 ./_torchshow/***.png
ts.save(tensor, './vis/test.jpg') # 指定保存路径