Open3D TensorBoard 插件总结 API 完全指南:用 `summary.add_3d` 将 3D 几何数据写入 TensorBoard
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());- 写入路径直接构造
Summaryprotobuf 并通过writer.add_summary(...)提交。
七、底层实现原理:从张量到浏览器渲染
7.1 数据预处理与序列化
add_3d 内部调用 _write_geometry_data(write_dir, tag, step, data, max_outputs):
- 校验:检查未知属性、
vertex_positions是否存在、max_outputs合法性、UV 键互斥(triangle_texture_uvs与vertex_texture_uvs二选一)、材质属性必须有material_name、纹理贴图必须有 UV 坐标; - 形状核对:
get_or_check_shape保证各属性的批大小、元素数量在 batch 内一致,并依据 metadata.py 中的维度表GEOMETRY_PROPERTY_DIMS校验; - RPC 序列化:每个 batch 元素调用
o3d.io.rpc.set_mesh_data,把顶点/面/线及其属性、材质标量/向量/纹理贴图打包为 msgpack 二进制(写入o3d.io.rpc.BufferConnection); - 异步落盘:二进制经
_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_3ddocstring 的 Note); - 可视化命令:
tensorboard --logdir demo_logs,然后浏览器访问 TensorBoard 的 Open3D 插件页;若浏览器与本机间 WebRTC 连接失败(外部 ICE 服务器不可达或本地网络接口干扰候选选择),可用WEBRTC_STUN_SERVER="" tensorboard --logdir /path/to/logs以仅回环模式启动(详见 tensorboard_plugin.rst)。
八、参考示例与延伸阅读
- tensorboard_pytorch.py:PyTorch 侧五个示例——
small_scale(基础立方体/圆柱)、property_reference(步进引用)、large_scale(高分辨率大场景,展示max_outputs批处理)、with_material(读取带纹理贴图的 OBJ 模型并写入 PBR 材质)、demo_scene(把demo_scene.py的丰富材质场景直接转存); - tensorboard_tensorflow.py:与上面对应的 TensorFlow 版本,注意其
add_3d调用均需logdir; - test_tensorboard_plugin_summary.py 与 test_tensorboard_plugin.py:读写两端的单元测试;
- plugin_data.proto:
Open3DPluginData、BatchIndex、InferenceData等数据结构的官方定义; - API 索引页面 open3d.visualization.tensorboard_plugin.summary.rst 与 tensorboard_plugin.rst 教程页。
实践建议:训练循环中若几何每步都在变,直接传完整 to_dict_batch(...) 即可;若只有颜色/材质变化而顶点坐标与法线不变,用步进引用可大幅压缩日志体积;max_outputs 用于控制每个 step 保存的批元素数量,超大场景(如 demo 中分辨率随 step 线性增长的 Mobius 曲面)建议设 0 全量保存并按需在浏览器端筛选。