Rerun Tensor View 深度解析：任意维度张量的 2D 切片可视化实现与使用指南

Rerun Tensor View 深度解析任意维度张量的 2D 切片可视化实现与使用指南【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读re_view_tensor是 Rerun一个面向多模态机器人数据可视化、查询与流式传输的开源工具家族中的一个专用 View视图crate其核心职责是将任意维度N-D的张量以 2D 切片 自定义色彩映射colormap的方式渲染出来。本文将结合该 crate 的源码、参考文档与测试用例深入讲解 Tensor View 的架构与数据流、维度映射slice selection的启发式规则、标量到颜色的映射参数以及如何通过 Blueprint 编程式地创建和使用 Tensor View帮助你直接在 Rerun 中可视化神经网络特征图、深度图、体积数据切片等高维张量数据。一、模块定位一个专为任意维度张量设计的视图crates/viewer/re_view_tensor/README.md 给出了这个 crate 最精炼的定义A View dedicated to visualizing tensors with arbitrary dimensionality.即一个专门用于可视化任意维度张量的视图。它是 Rerun 众多视图View之一对应 Rerun 官方类型体系中的TensorView见 docs/content/reference/types/views/tensor_view.md官方文档同时注明该类型当前仍处于unstable阶段后续可能发生不向后兼容的变化。在 Rerun 中View 是蓝图Blueprint层面的概念一个 View 决定了一块视口viewport区域如何解释并渲染某个 entity实体的数据。从源码结构看crates/viewer/re_view_tensor/src/lib.rs该 crate 对外只暴露一个核心类型TensorView内部由五个模块协作完成渲染模块职责view_class.rsTensorView视图类的整体实现布局、帮助信息、选区面板、渲染入口visualizer_system.rsTensorSystem可视化器负责从数据存储Chunk Store中查询张量数据dimension_mapping.rsTensorSliceSelection切片选择宽/高/索引/滑杆的加载与合法性修正tensor_dimension_mapper.rs维度映射的拖拽式 UIDimension Mapping 面板tensor_slice_to_gpu.rs将 2D 切片上传为 GPU 纹理并做色彩映射TensorView的显示名为Tensor见 view_class.rs视图的帮助文本对其功能做了最直接的概括An N-dimensional tensor displayed as a 2D slice with a custom colormap. Set the displayed dimensions in a selection panel.任意 N 维张量 → 选取其中两维作为宽/高 → 其余维度固定索引 → 得到一个 2D 切片 → 用自定义 colormap 渲染。这就是 Tensor View 的全部核心逻辑下面各节将逐一展开其实现细节。二、核心数据流从 Chunk Store 到 GPU 纹理的完整链路从源码结构看一次 Tensor View 的渲染大致经过以下四步查询张量TensorSystemvisualizer_system.rs作为可视化器Visualizer通过VisualizerQueryInfo::single_required_component::TensorData声明自己依赖TensorData这一必需组件关联到Tensorarchetype。执行时使用LatestAtQuery查询当前时间点上每个数据结果的张量数据并顺便读取可选的ValueRange组件作为数值范围若未提供则使用typed_fallback_for提供的回退值。组装可视结果查询结果被包装为TensorVisualization包含tensor_row_id、tensor: TensorData、data_range: ValueRange三个字段供视图类使用。切片选择与合法性修正TensorView从当前 View 的 Blueprint 属性中读取TensorSliceSelection通过load_and_make_valid将其修正为对当前张量形状合法有效的切片配置。GPU 上传与渲染tensor_slice_to_gpu.rs中colormapped_texture先按切片配置取出 2D 子视图上传为GpuTexture2D再与 colormap、gamma 等参数组装成ColormappedTexture最终由gpu_bridge::render_image绘制到视图画布上view_class.rs。值得注意的实现细节是 GPU 纹理的缓存策略upload_texture_slice_to_gpu以(tensor_row_id, slice_selection)的哈希作为纹理缓存 keytensor_slice_to_gpu.rs这意味着只要张量数据行或切片配置不变纹理就不会重复上传拖动滑杆浏览各切片时开销很低。2.1 数据类型与 GPU 纹理格式映射张量数据最终必须变成 GPU 纹理因此TensorData的各种底层类型在 tensor_slice_to_gpu.rs 中被一一映射为 wgpu 纹理格式张量数据类型纹理格式说明U8R8Uint原样拷贝U16R16Uint原样拷贝U32R32Uint原样拷贝U64R32Float收窄为 f32I8/I16/I32R8Sint/R16Sint/R32Sint原样拷贝I64R32Float收窄为 f32F16R16Float原样拷贝F32R32Float原样拷贝F64R32Float收窄为 f32因此从实现事实看U64、I64、F64这三种高精度类型在 GPU 渲染阶段会被收窄为 f32可能带来精度损失而其余类型保持原样。这也是为什么 Tensor View 帮助文本强调色彩映射是scalar 到 color的转换——纹理本质上承载的是标量强度值。三、维度映射Slice Selection如何把 N 维张量摊成 2D 图片这是 Tensor View 最核心的交互与配置概念对应 Blueprint 属性slice_selection。参考文档 tensor_view.md 将其拆解为四部分width映射到宽度的维度height映射到高度的维度indices其余所有维度上选取的固定索引slider出现在这个列表里的维度会获得一个滑杆用于交互式切换该维度的索引。在源码中这四个概念被序列化为TensorSliceSelection结构体dimension_mapping.rspub struct TensorSliceSelection { pub width: OptionTensorWidthDimension, pub height: OptionTensorHeightDimension, pub indices: VecTensorDimensionIndexSelection, pub slider: OptionVecTensorDimensionIndexSlider, }3.1 默认启发式自动挑选宽高维度用户不手动指定时make_width_height_valid与find_width_height_dim_indicesdimension_mapping.rs负责猜出合理的宽高。其规则按优先级排列按维度名匹配维度名小写属于w / width / right / left则视为宽度候选属于h / height / up / down则视为高度候选其中名为left的维度会自动设置invert翻转名为up的维度也会自动设置invert以便图像方向符合直觉。按长度兜底取张量中最长与次长的两个维度作为宽高。NumPy 约定当最长的两个维度恰好是第 0、1 维即二者长度并列第一时采用 NumPy 的[h, w, ...]排布约定——即第 0 维作为高度、第 1 维作为宽度。这一点在单元测试中有明确断言assert_eq!(wh([dim(800), dim(50)]), (1, 0), numpy ordering)见 dimension_mapping.rs。3.2 合法性修正make valid越界即修正绝不崩溃load_and_make_valid是防御式设计的集中体现它把 Blueprint 中存储的切片配置就地修正为一个对当前张量形状合法且自洽的配置越界维度收敛width/height的维度下标超过张量维数时被收敛到最大合法维dimension_mapping.rs宽高不能同维若 width 与 height 指向同一维度则移除 height维数不足时补齐二维以上张量强制同时设置 width 与 height一维张量至少保证 width 或 height 之一被设置索引越界收敛indices中与 width/height 相同维度或越界的条目被移除其余索引被钳制到size - 1以内缺失索引补中间未被 width/height/indices 覆盖的维度自动补充取中间索引size / 2的条目dimension_mapping.rs滑杆自动生成若未指定slider则为每个未被宽高覆盖的维度默认生成一个滑杆。这些规则都配有单元测试dimension_mapping.rs例如测试验证了空配置能产出好的默认值、越界索引被钳制1000 → 99/199/299、宽高覆盖的维度从 indices 中被剔除等行为。3.3 交互方式拖拽重映射 滑杆浏览在视图的 Selection选区面板中Dimension Mapping 区域view_class.rs通过dimension_mapping_uitensor_dimension_mapper.rs提供可视化编辑拖拽张量的每个维度被渲染为一个可拖拽的标签可拖到Image → width、Image → height槽位或拖入/拖出Selectors列表从而把任意维度重新映射为宽、高或索引选择器Flip翻转width/height 各有翻转开关翻转后轴方向反转滑杆开关每个 selector 右侧有一个眼睛按钮控制该维度是否显示滑杆Reset 按钮Reset to default blueprint 恢复默认蓝图配置Reset to heuristic 则把自定义映射清空、回到启发式默认值view_class.rs。需要说明的是从源码结构看NewSelector把维度暂存到一个新槽位功能当前被注释禁用tensor_dimension_mapper.rs代码注释表示它暂时没有价值、未来可能需要时再启用。3.4 切片在代码里如何发生一旦确定了TensorSliceSelection实际的切片操作由selected_tensor_slice完成view_class.rs一维张量会被 reshape 成[len, 1]的二维形状以统一处理将[height, width] indices组合为新的轴顺序并做permuted_axes重排对每个索引选择沿第 2 轴Axis(2)固定对应索引逐层降维根据invert标志对高度轴Axis 0/宽度轴Axis 1做翻转。四、标量映射Scalar Mapping从数值到颜色的视觉编码参考文档将scalar_mapping拆为三个参数mag_filter放大查看张量时使用的纹理过滤方式colormap标量值到颜色的映射方案gamma颜色映射前对归一化数值施加的gamma 指数。在paint_tensor_sliceview_class.rs中这三个参数从 Blueprint 属性读取并组装为ColormapWithRangecolormap [data_range.start, data_range.end]数值范围传给 GPU 渲染。值得注意的实现细节colormap 的默认值是 Viridison_register中通过 fallback provider 注册未指定 colormap 时默认使用Colormap::Viridisview_class.rsmag_filter 的取值Nearest映射为纹理的Nearest过滤Linear与Bicubic都被映射为Linear过滤minification 固定为Linearmipmap 当前未启用见 view_class.rs纹理采样wrap mode 为ClampToEdge颜色解码为 opaque、非 sRGB。五、视图适配View Fit切片如何填入视图区域view_fit属性决定 2D 切片在视图中的摆放方式源码view_class.rs支持三种模式view_fit取值行为Original按切片原始像素尺寸 1:1 显示Fill拉伸填满整个可用区域忽略宽高比FillKeepAspectRatio等比缩放填满取宽高缩放比的较小者三种模式都需要从TensorViewFitblueprint 属性或回退值中读取Original模式还做了最小 1×1 的尺寸保护Vec2::max(Vec2::splat(1.0), img_size)防止空张量导致的除零等问题。六、实战用 Blueprint 编程式创建 Tensor ViewRerun 的官方示例 docs/snippets/all/views/tensor.py 给出了完整的端到端用法——先记录一个四维张量再用 Blueprint 显式配置 TensorView 的切片、标量映射与视图适配import numpy as np import rerun as rr import rerun.blueprint as rrb rr.init(rerun_example_tensor, spawnTrue) # 记录一个 4 维张量(batch, x, y, channel)并给维度起名 tensor np.random.randint(0, 256, (32, 240, 320, 3), dtypenp.uint8) rr.log(tensor, rr.Tensor(tensor, dim_names(batch, x, y, channel))) blueprint rrb.Blueprint( rrb.TensorView( origintensor, nameTensor, # 显式挑选要显示的维度 slice_selectionrrb.TensorSliceSelection( # 用第 1 个维度作为宽度 width1, # 用第 2 个维度作为高度并翻转 heightrr.TensorDimensionSelection(dimension2, invertTrue), # 为其余维度设置固定索引 indices[ rr.TensorDimensionIndexSelection(dimension2, index4), rr.TensorDimensionIndexSelection(dimension3, index5), ], # 只为维度 2 显示滑杆不指定则 indices 里所有维度都会有滑杆 slider[2], ), # 自定义 colormap、gamma 与放大过滤 scalar_mappingrrb.TensorScalarMapping( colormapturbo, gamma1.5, mag_filterlinear ), # 填满视图、忽略宽高比 view_fitfill, ), collapse_panelsTrue, ) rr.send_blueprint(blueprint)这个示例覆盖了本文前面讲到的全部概念width/height/indices/slider四个切片参数、colormap/gamma/mag_filter三个标量映射参数以及view_fit。运行后即可在视口中看到该四维张量在当前索引组合下的 2D 切片图像并可通过滑杆交互切换batch/channel等维度的索引。七、测试验证行为如何被保证该 crate 的测试既能验证渲染管线也能验证数据转换的正确性1D 张量渲染tests/tensor_1d.rs记录 100 个 f32 标量构成的 1D 张量创建根通配的 TensorView 并截图快照tensor_1d验证一维数据也能被展示2D 张量渲染tests/tensor_2d.rs用(i ^ j)生成经典的 XOR 测试纹理16×16 与 8×8 两个张量分别在tensors/t1、tensors/t2、tensors同时命中两个与根实体四种 origin 下截图tensor_2d_t1、tensor_2d_t2、tensor_2d_both、tensor_2d_root——其中同时命中两个张量的场景会触发视图的一次只能显示一个张量错误提示路径数据转换src/tensor_tests.rs验证TensorData与ndarray::ArrayViewD的双向转换、三维张量的逐元素索引正确性z * 4 * 5 y * 5 x的内存布局、形状不匹配与类型不匹配时的TensorCastError等。测试对应的快照文件位于 crates/viewer/re_view_tensor/tests/snapshots/可以直接查看 Tensor View 在不同维度输入下的真实渲染效果。八、已知限制与使用提示从 view_class.rs 的实现可以看出一个明确限制每个 Tensor View 一次只能显示一个张量。如果查询结果命中多个张量实体视图会显示错误提示Can only show one tensor at a time; was given N. Update the query so that it returns a single tensor entity and create additional views for the others.因此在使用时需要注意通过 Blueprint 中 View 的 origin / 查询过滤器例如$origin/**把范围收敛到单个张量实体需要同时查看多个张量时为每个张量单独创建 TensorView从spawn_heuristics的实现看自动生成视图时也会每个张量一个视图见 view_class.rs另外如前文所述U64/I64/F64类型的张量在 GPU 渲染阶段会被收窄为 f32对精度敏感的场景需要留意。结语re_view_tensor以任意维度张量 → 2D 切片 colormap这一简洁抽象配合完善的启发式默认值、防御式的合法性修正与拖拽式维度映射 UI为 Rerun 生态提供了实用的张量可视化能力。无论是想要快速浏览神经网络的中间特征图还是深入调教哪个维度做宽、哪个维度做高、其余维度取哪个索引理解本文介绍的slice_selection/scalar_mapping/view_fit三组蓝图属性及其背后的实现逻辑都能让你在 Rerun 中高效地观察和排查高维数据。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考