Open3D TensorBoard 插件总结 API 完全指南:用 `summary.add_3d` 将 3D 几何数据写入 TensorBoard

原创2026-09-21 22:50:521,624 阅读
文章标签:计算机视觉点云图形学3D渲染科学计算深度学习

Open3D TensorBoard 插件总结 API 完全指南:用 summary.add_3d 将 3D 几何数据写入 TensorBoard

Open3D 为 TensorBoard 提供了官方可视化插件(plugin_name 为 Open3D),其核心入口是 open3d.visualization.tensorboard_plugin.summary 模块中的 add_3d 函数。本文以该 API 为主线,系统讲解如何在 TensorFlow 与 PyTorch 训练/日志流程中,将点云、三角网格、线集乃至带 PBR 材质与纹理贴图的 3D 场景写入 TensorBoard 事件文件,并通过浏览器中的 Open3D 渲染窗口交互式回放不同 step 的几何数据。读完本文你将掌握 add_3d 的完整参数语义、data 字典支持的全部几何与材质属性键、批处理与步进引用的高级用法,以及底层异步序列化写入的实现机制。

一、模块定位:summary 模块与 add_3d 函数

summary 模块位于 python/open3d/visualization/tensorboard_plugin/summary.py,是整个 Open3D TensorBoard 插件的数据写入端。它只对外暴露一个核心函数:

  • add_3d:将 3D 几何数据作为 TensorBoard summary 写入事件文件,供 Open3D for TensorBoard 插件可视化。

该模块与插件的其他组件共同构成完整的读写链路:

  • summary.py:写入端,负责数据转换、序列化与异步落盘;
  • util.py:读取端辅助工具(Open3DPluginDataReader 读取 msgpack 几何数据、RenderUpdate 应用渲染状态、to_dict_batch 把 Eigen 几何转为张量字典);
  • plugin.py:TensorBoard 服务端插件,负责 WebRTC 窗口管理与 HTTP API;
  • metadata.py:插件常量(PLUGIN_NAME = "Open3D")与支持属性清单;
  • plugin_data.proto:几何元数据与批索引的 protobuf 定义。

add_3d 有两种调用形态:

  • TensorFlow 下调用模块级函数 summary.add_3d(...)(需要传入 logdir);
  • PyTorch 下调用 torch.utils.tensorboard.SummaryWriter 的绑定方法 writer.add_3d(...)(logdir 可自动推断)。

从源码看,PyTorch 形态是通过 monkey-patching 实现的:在 summary.py 中,当检测到 torch 已安装且 SummaryWriter 尚无 add_3d 方法时,会把内部函数 _add_3d_torch 绑定为 SummaryWriter.add_3d。因此 PyTorch 用户只需 import summary(即使不直接使用)即可激活该绑定方法——官方文档字符串中也特别注明“the import summary is needed to make add_3d() available, even though summary is not used”。

二、函数签名与参数详解

def add_3d(name,
           data,
           step,
           logdir=None,
           max_outputs=1,
           label_to_names=None,
           description=None):
参数 类型 说明
name str summary 的标签(tag)。TensorBoard 中实际的 tag 会以此名为前缀,并叠加当前活跃的 name scope。
data dict 表示 3D 数据的张量字典,支持 TensorFlow、PyTorch、Numpy 与 Open3D 张量。支持的键详见第三节。
step int 显式的、可转为 int64 的单调递增步数。TensorFlow 下若为 None,默认取 tf.summary.experimental.get_step(),且该值不能为 None。
logdir str 创建 SummaryWriter 时使用的日志目录。TensorFlow 下必须显式提供(为 None 会抛出 ValueError);PyTorch 下缺省时从 writer 自动推断。
max_outputs int 每个 step 最多输出的 3D 元素个数,超出部分静默丢弃;0 表示全部保存(源码中 max_outputs == 0 会被替换为 np.iinfo(np.int32).max),小于 1 的非零值会抛出 ValueError。
label_to_names dict 可选的标签(如 bbox 或顶点标签的 int 值)到类别名称的映射。当前实现中,每个 tag 在一次运行中只保存首个 step 的映射。
description str summary 的长文本描述,支持 Markdown,默认空字符串。目前尚未被前端使用(reserved for future use)。

异常行为(来自 docstring 与源码):

  • 使用模块级 add_3d 但未安装 TensorFlow 时,抛出 RuntimeError(提示改用 PyTorch 的 SummaryWriter.add_3d);
  • TensorFlow 下 step 与 logdir 均不能为 None,否则抛出 ValueError;
  • data 不是字典、缺少主键 vertex_positions、或包含未知属性键时,_write_geometry_data 抛出 TypeError / ValueError。

三、data 字典支持的键:几何与材质属性的完整清单

data 是一个“属性名 → 张量”的字典。批维度统一记作 B。下表是 add_3d 支持的全部键(源码 docstring 与 metadata.py 中 GEOMETRY_PROPERTY_DIMS、SUPPORTED_PROPERTIES 定义相互印证):

3.1 顶点属性(几何基础)

键 形状 说明
vertex_positions (B, N, 3) 顶点坐标,必填主键,转为 float32。
vertex_colors (B, N, 3) 顶点颜色,转为 uint8。
vertex_normals (B, N, 3) 顶点法线,转为 float32。
vertex_texture_uvs (B, N, 2) 逐顶点 UV 坐标,用于应用材质纹理贴图,转为 float32。与 triangle_texture_uvs 二选一。
vertex_<a href="https://link.gitcode.com/i/de38ab2cca6675ed9c0c7c4bb98ada30" target="_blank">FEATURE] (B, N, _) 自定义顶点特征。浮点转 float32、整数转 int32。在源码中,凡是以 vertex_ 为前缀的键都会被当作自定义顶点属性处理([summary.py)。

3.2 三角面属性(构成 TriangleMesh)

键 形状 说明
triangle_indices (B, Nf, 3) 三角面索引,转为 uint32。
triangle_colors (B, Nf, 3) 面颜色,转为 uint8。
triangle_normals (B, Nf, 3) 面法线,转为 float32。
triangle_texture_uvs (B, Nf, 3, 2) 逐三角形 UV 坐标,转为 float32。与 vertex_texture_uvs 二选一。

3.3 线段属性(构成 LineSet)

键 形状 说明
line_indices (B, Nl, 2) 线段索引,转为 uint32。
line_colors (B, Nl, 3) 线段颜色,转为 uint8。

3.4 边界框(3D 目标检测)

键 形状 说明
bboxes (B, Nbb) 元素 dtype 应为 open3d.ml.vis.BoundingBox3D。框的颜色在 TensorBoard 中按其标签分配;置信度暂不支持可视化;不支持步进引用;必须与其他 3D 数据分开单独调用(源码中若 data 同时含 bboxes 与其他键会抛 ValueError)。

从源码 summary.py 可以看到,bboxes 会被 _convert_bboxes 转换为 14 个顶点/框 的线框几何(vertices_per_bbox = 14),并分离出 bbox_labels 与 bbox_confidences,同时校验标签数、置信度数、顶点数三者的一致性。

3.5 材质属性(PBR 渲染)

要指定任何材质属性,必须先提供 material_name(material_name 为空但存在其他材质属性时会抛 ValueError)。

键 形状 说明
material_name (B,),dtype str 基础 PBR 材质名。Open3D 内置材质:defaultLit、defaultUnlit、unlitLine、unlitGradient、unlitSolidColor。
material_scalar_[PROPERTY] (B,) 浮点 标量材质属性,如 material_scalar_metallic。
material_vector_[PROPERTY] (B, 4) 浮点 4 维向量材质属性,如 material_vector_base_color。
material_texture_map_[PROPERTY] (B, Nr, Nc, C) PBR 纹理贴图,如 material_texture_map_metallic。几何必须带 `[vertex

metadata.py 完整列出了可用的标量属性(point_size、line_width、metallic、roughness、reflectance、clear_coat、clear_coat_roughness、anisotropy、ambient_occlusion、transmission、thickness、absorption_distance)、向量属性(base_color、normal、absorption_color)与纹理贴图(albedo、ao_rough_metal)。完整属性语义遵循 Filament 材质规范。

3.6 尺寸收缩与数据类型转换规则

  • B=1 时允许降秩:当批大小 batch_size == 1 时,张量可去掉一个秩,如 vertex_positions 用 (N,3)、向量材质属性用 (4,)、标量材质属性用 ()。
  • 批内变长元素:批次中元素尺寸可以不同,此时传入张量序列(tuple),例如 {'vertex_positions': (pcd1, pcd2)},其中 pcd1.shape = (8, 3)、pcd2.shape = (16, 3)。源码中 _to_o3d(..., max_len=max_outputs) 会沿第一维切分并把每个元素独立转换(summary.py)。
  • 颜色与纹理:浮点颜色/纹理数据会被裁剪到 [0,1] 并转为 uint8 的 [0,255];uint16 数据压缩到 [0,255](_color_to_uint8 中 uint16 // 256)。
  • 索引:*_indices 统一转为 int32;float64 几何数据统一降为 float32。

四、步进引用(Step Reference):避免重复写入不变数据

data 中的任意张量(ndim >= 2,含批维度)都可以用一个指向先前 step 的 int 标量替代。这允许在某属性在不同 step 间不变化时复用之前写入的数据,从而显著减少事件文件体积。官方示例 tensorboard_pytorch.py 的 property_reference 演示了该用法:step 0 写入完整几何,后续 step 用 cube_summary['vertex_positions'] = 0、cube_summary['vertex_normals'] = 0 引用 step 0 的数据。

适用限制(源码 summary.py 与 docstring):

  • material_name、material_scalar_*、自定义顶点特征(vertex_[FEATURE])不支持步进引用;
  • 引用值必须满足 0 <= step_ref < step,否则抛 ValueError(“Out of order step reference”);
  • 读取端在 read_geometry 中会解析 property_references,把引用 step 的属性拷贝到当前几何(util.py),并检查“未来引用”以防御数据损坏。

五、TensorFlow 用法示例

import tensorflow as tf
import open3d as o3d
from open3d.visualization.tensorboard_plugin import summary
from open3d.visualization.tensorboard_plugin.util import to_dict_batch

logdir = "demo_logs/"
writer = tf.summary.create_file_writer(logdir)

cube = o3d.geometry.TriangleMesh.create_box(1, 2, 4)
cube.compute_vertex_normals()
colors = [(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]

with writer.as_default():
    for step in range(3):
        cube.paint_uniform_color(colors[step])
        summary.add_3d('cube',
                       to_dict_batch([cube]),
                       step=step,
                       logdir=logdir)

要点:

  • to_dict_batch(来自 util.py)把 Open3D Eigen 几何序列转成属性张量字典,支持 PointCloud、TriangleMesh、LineSet,会自动剔除空数组;
  • TensorFlow 下 logdir 必须显式传入;
  • 内部实现上,add_3d 使用 lazy_tensor_creator.LazyTensorCreator 把繁重的序列化工作延迟到 tf.summary.write() 真正写盘时执行(即仅在 record_if() 返回 True 时触发),并通过 summary_scope(name, "open3d_summary", ...) 为 tag 添加作用域。

六、PyTorch 用法示例

from torch.utils.tensorboard import SummaryWriter
import open3d as o3d
from open3d.visualization.tensorboard_plugin import summary  # noqa
from open3d.visualization.tensorboard_plugin.util import to_dict_batch

writer = SummaryWriter("demo_logs/")

cube = o3d.geometry.TriangleMesh.create_box(1, 2, 4)
cube.compute_vertex_normals()
colors = [(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]

for step in range(3):
    cube.paint_uniform_color(colors[step])
    writer.add_3d('cube', to_dict_batch([cube]), step=step)

要点:

  • 必须先 import summary 使 add_3d 绑定到 SummaryWriter(即使代码中未直接引用 summary);
  • logdir 自动从 writer 推断(_add_3d_torch 中 logdir = writer.get_logdir());
  • 写入路径直接构造 Summary protobuf 并通过 writer.add_summary(...) 提交。

七、底层实现原理:从张量到浏览器渲染

7.1 数据预处理与序列化

add_3d 内部调用 _write_geometry_data(write_dir, tag, step, data, max_outputs):

  1. 校验:检查未知属性、vertex_positions 是否存在、max_outputs 合法性、UV 键互斥(triangle_texture_uvs 与 vertex_texture_uvs 二选一)、材质属性必须有 material_name、纹理贴图必须有 UV 坐标;
  2. 形状核对:get_or_check_shape 保证各属性的批大小、元素数量在 batch 内一致,并依据 metadata.py 中的维度表 GEOMETRY_PROPERTY_DIMS 校验;
  3. RPC 序列化:每个 batch 元素调用 o3d.io.rpc.set_mesh_data,把顶点/面/线及其属性、材质标量/向量/纹理贴图打包为 msgpack 二进制(写入 o3d.io.rpc.BufferConnection);
  4. 异步落盘:二进制经 _async_data_writer.enqueue() 写入独立的 .msgpack 文件(文件名遵循 TensorFlow event 格式 {tag}.{时间戳}.{hostname}.{PID}.msgpack),同时记录偏移量、大小与 masked_crc32c 校验和,写入 Open3DPluginData 的 batch_index;几何元数据(含 bbox 的 InferenceData 辅助数据)最终序列化为 summary 的字符串张量。

7.2 异步写入器

_AsyncDataWriter(summary.py)是一个进程级单例:

  • 写队列上限 max_queue=10,enqueue 在队列满时阻塞;
  • 默认 flush_secs=120 周期性 flush 到磁盘(数据可能暂存于 OS 缓冲区);
  • idle_secs=0.25 空闲超时后自动停止写线程,下次 enqueue 再启动(避免长驻线程);
  • 有 TensorFlow 时用 tf.io.gfile(支持 gs://、hdfs:// 远程路径),否则回退到 Python I/O;
  • 单元测试 test_tensorboard_plugin_summary.py 验证了写线程空闲退出后重启、数据不丢失且追加位置正确的行为。

7.3 读取与渲染

TensorBoard 侧 plugin.py 的 Open3DPlugin 注册为 /data/plugin/Open3D/ 路由,Open3DPluginDataReader 通过 EventMultiplexer 读取事件文件,按 batch_index 中的偏移量与 CRC32c 从 msgpack 文件读取几何(LRU 缓存 128 项),通过 RenderUpdate 将渲染状态(shader、property、colormap)应用到 O3DVisualizer 窗口,最后经 WebRTC 推流到浏览器。

7.4 平台与运行说明

  • 写入(summary 生成)在所有平台可用,浏览器端可视化同样跨平台;
  • 运行 tensorboard 进程本身目前在 macOS 上尚不支持(见 add_3d docstring 的 Note);
  • 可视化命令:tensorboard --logdir demo_logs,然后浏览器访问 TensorBoard 的 Open3D 插件页;若浏览器与本机间 WebRTC 连接失败(外部 ICE 服务器不可达或本地网络接口干扰候选选择),可用 WEBRTC_STUN_SERVER="" tensorboard --logdir /path/to/logs 以仅回环模式启动(详见 tensorboard_plugin.rst)。

八、参考示例与延伸阅读

实践建议:训练循环中若几何每步都在变,直接传完整 to_dict_batch(...) 即可;若只有颜色/材质变化而顶点坐标与法线不变,用步进引用可大幅压缩日志体积;max_outputs 用于控制每个 step 保存的批元素数量,超大场景(如 demo 中分辨率随 step 线性增长的 Mobius 曲面)建议设 0 全量保存并按需在浏览器端筛选。

登录后查看全文
Open3D