Rerun Asset3D 架构类型完全指南在 Rerun 中可视化与实例化 glTF/OBJ/STL 三维资产【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读Asset3D是 Rerun 中用于将预打包prepacked的三维资产.gltf、.glb、.obj、.stl等直接作为单个实体记录并渲染的架构类型Archetype。与需要逐个字段顶点、法线、纹理坐标拆开记录的Mesh3D不同Asset3D以原始二进制Blob的形式整体携带文件数据由查看器端负责解析与上屏。读完本文你将掌握Asset3D的字段结构与 MediaType 类型推导规则、Python/Rust/C 三种 SDK 的构造与记录方式、与InstancePoses3D配合实现实例化渲染的方法以及其底层从数据解析到 GPU 网格生成的完整渲染链路。Asset3D 是什么根据类型定义文档 asset3d.mdAsset3D是一个预打包的三维资产类型支持.gltf、.glb、.obj、.stl等格式。其核心定位是一次记录、整体渲染文件字节作为单个Blob组件记录到实体上查看器在渲染时才解析网格数据与Mesh3D互补Mesh3D需要你把网格几何顶点位置、索引、法线、颜色、UV拆成多个组件字段手动记录而Asset3D直接消费原始文件字节两者可参见 Mesh3D 文档 对比使用天然支持实例化如果同一实体上还记录了多个 InstancePoses3D 实例位姿那么资产网格会为每一个位姿各绘制一份实例instancing 行为这在后文会详细展开。从源码结构看该类型的权威定义位于类型定义源文件 asset3d.def.rs该文件被re_types_builder解析用于统一生成 Rust、Python、C 三套绑定文档页面同样由 website.rs 自动生成因此文档、SDK 与查看器三方保持一致。字段结构Required / Recommended / OptionalAsset3D一共只有三个字段按 Rerun 的组件约定分为三档级别字段组件类型说明Required必需blobBlob资产的原始字节数据Recommended推荐media_typeMediaType资产的媒体类型MIME影响查看器如何解析字节Optional可选albedo_factorAlbedoFactor应用到整个资产的颜色乘数在自动生成的 Rust 实现 asset3d.rs 中可以明确看到三档组件的描述符列表分别被注册为REQUIRED_COMPONENTS、RECOMMENDED_COMPONENTS、OPTIONAL_COMPONENTS总组件数为 3。blob资产的原始字节Blob组件本质上是一个二进制数据块其 Arrow 数据类型为List(non-null UInt8)即非空的uint8列表。它是Asset3D唯一必需的字段——没有字节数据就没有资产可言。media_type决定解析路径的 MIME 类型MediaType是 RFC2046 标准化的媒体类型字符串编码为Utf8Arrow 类型Utf8。对于三维资产定义文件中明确列出的受支持取值包括model/gltf-binary对应.glbmodel/gltfjson对应.gltfmodel/obj对应 Wavefront.obj注意.mtl材质文件目前尚不支持其中的引用会被静默忽略model/stl对应 STL二进制或 ASCII 均可此外在 media_type_ext.rs 中还定义了常量MediaType::DAE model/vnd.colladaxmlCOLLADA.dae并在渲染器端被支持详见下文渲染链路。MediaType 的推导优先级从 asset3d_ext.rs 和 media_type_ext.rs 可以完整还原由调用方显式传入优先级最高若未传入SDK 先尝试MediaType::guess_from_path——基于文件扩展名推断源码中为.obj、.stl做了特判因为它们常被通用 MIME 库误判仍无法确定时由查看器在渲染期调用MediaType::guess_from_data基于文件内容magic bytes猜测例如glTF魔数、ASCII STL 的solid头、COLLADA标签等若最终仍无法猜出类型则查看器无法渲染该资产会报错提示。值得一提的实现细节guess_from_data中的glb_matcher通过检查前 4 个字节是否为g、l、T、F即glTF魔数来识别二进制 glTF而 ASCII 与二进制 STL 中二进制 STL 因以 80 字节可忽略的文件头开头很难可靠推断源码注释明确说明了这一限制。albedo_factor整体颜色乘数AlbedoFactor组件编码为Rgba32Arrow 类型UInt32语义是通常应用到整个实体如网格的颜色乘数。定义文件特别强调对于材质中已带albedo_factor的网格若Asset3D显式指定了albedo_factor将以Asset3D的实际值为准进行覆盖。在渲染链路中这一点由 mesh_loader.rs 的override_albedo_factor调用实现。三种 SDK 的构造与记录方式Asset3D在三个语言 SDK 中均提供了从文件路径与从字节内容两种构造入口。PythonPython 端通过扩展类 asset3d_ext.py 提供path与contents两种互斥参数import rerun as rr rr.init(rerun_example_asset3d, spawnTrue) # 设置 3D 视图的上方向 rr.log(world, rr.ViewCoordinates.RIGHT_HAND_Z_UP, staticTrue) # 方式一直接给文件路径media_type 会基于扩展名自动推断 rr.log(world/asset, rr.Asset3D(pathpath/to/asset.glb)) # 方式二传入字节内容可配合显式 media_type with open(path/to/asset.obj, rb) as f: rr.log(world/asset, rr.Asset3D(contentsf, media_typemodel/obj)) # 方式三整体颜色乘数 rr.log( world/asset, rr.Asset3D(pathpath/to/asset.glb, albedo_factor(0xEE, 0x11, 0x22, 0x33)), )参数约定来自Asset3DExt.__init__的 docstring 与实现path本地文件系统路径与contents二选一且必须恰好提供一个否则抛出ValueErrorcontents文件内容可为BufferedReader、BytesIO或bytesmedia_type受支持取值如model/gltf-binary、model/gltfjson、model/obj、model/stl省略时优先根据path扩展名猜测否则留给查看器在渲染期按内容猜测albedo_factor可选的整体颜色乘数。rr.Asset3D(path...)路径形式下SDK 会以pathlib.Path(path).read_bytes()读取文件并在media_type为None时调用MediaType.guess_from_path(path)自动补全。RustRust 端通过 asset3d_ext.rs 提供两个构造函数use rerun::external::anyhow; fn main() - anyhow::Result() { let args std::env::args().collect::Vec_(); let Some(path) args.get(1) else { anyhow::bail!(Usage: {} path_to_asset.[gltf|glb|obj|stl], args[0]); }; let rec rerun::RecordingStreamBuilder::new(rerun_example_asset3d).spawn()?; // 设置 3D 视图的上方向 rec.log_static(world, rerun::ViewCoordinates::RIGHT_HAND_Z_UP())?; // 从文件路径构造media_type 先按扩展名猜测必要时再按内容猜测 rec.log(world/asset, rerun::Asset3D::from_file_path(path)?)?; // 从字节内容构造media_type 通过内容 magic bytes 猜测 let bytes std::fs::read(path)?; rec.log(world/asset, rerun::Asset3D::from_file_contents(bytes, None::rerun::components::MediaType))?; Ok(()) }两个构造函数的语义在源码注释中写明from_file_path(filepath)返回io::ResultSelf文件读取失败会返回错误MediaType先按扩展名猜测再按内容猜测若当时无法猜出查看器会在渲染期再尝试仍失败则渲染报错。注意该函数标注了#[cfg(not(target_arch wasm32))]即不适用于 WebAssembly 目标。from_file_contents(contents, media_type)给定字节与可选的MediaType内部会调用MediaType::or_guess_from_data尝试基于 magic bytes 补全类型。CC 端通过 asset3d_ext.cpp 提供对应的构造 API#include rerun.hpp #include iostream int main(int argc, char* argv[]) { if (argc 2) { std::cerr Usage: argv[0] path_to_asset.[gltf|glb|obj|stl] std::endl; return 1; } const auto path argv[1]; const auto rec rerun::RecordingStream(rerun_example_asset3d); rec.spawn().exit_on_failure(); // 设置 3D 视图的上方向 rec.log_static(world, rerun::ViewCoordinates::RIGHT_HAND_Z_UP); // 从文件路径构造失败时抛出异常 rec.log(world/asset, rerun::Asset3D::from_file_path(path).value_or_throw()); }C 端的实现细节from_file_path以二进制模式打开文件并整体读入std::vectoruint8_t然后调用Asset3D::from_file_contents(...)并传入MediaType::guess_from_path(path)from_file_contents则在media_type有值时通过with_media_type写入源码注释提到 C 侧暂未像 Rust 那样基于 magic bytes 猜测属于两端实现差异但查看器渲染期仍会兜底猜测。官方最小示例三种语言的完整可运行示例分别位于docs/snippets/all/archetypes/asset3d_simple.pydocs/snippets/all/archetypes/asset3d_simple.rsdocs/snippets/all/archetypes/asset3d_simple.cpp运行方式均为python/rust/cpp程序 path_to_asset.[gltf|glb|obj|stl]命令行参数。示例还会先以staticTrue记录ViewCoordinates::RIGHT_HAND_Z_UP来设定 3D 视图的上方向再把资产记录到world/asset实体下。显示在哪些视图中根据类型定义中的docs(view_types ...)属性与文档页的 Can be shown in 小节Asset3D可以在以下视图显示视图显示条件Spatial3DView默认的三维空间视图直接显示Spatial2DView当资产被记录在活动投影active projection例如 Pinhole 相机之上时可投影显示DataframeView以表格形式查看组件数据其中 Spatial3DView 文档 的 Visualized archetypes 列表明确把Asset3D列为可直接可视化的架构类型之一。与 InstancePoses3D 配合实例化渲染这是Asset3D文档强调的关键行为如果同一实体上记录了多个 InstancePoses3D 实例位姿则资产网格会为每一个位姿各绘制一份实例。也就是说你可以在同一个实体上同时记录# 假设 asset 实体上先记录了 Asset3D rr.log(world/asset, rr.Asset3D(pathasset.glb)) # 再记录多个实例位姿每个位姿绘制一份资产网格 rr.log( world/asset, rr.InstancePoses3D( translations[(0.0, 0.0, 0.0), (1.0, 0.0, 0.0), (2.0, 0.0, 0.0)], quaternions[(1, 0, 0, 0), (1, 0, 0, 0), (1, 0, 0, 0)], ), )InstancePoses3D与层级变换Transform3D的关键区别见 instance_poses3d.md它是施加在当前实体变换帧上的一个或多个变换不会在变换层级中向下传播并且每次记录该架构类型时整体位姿状态会完全重置为新的记录不会按组件独立做 latest-at 合并。这一instancing行为在查看器端由 assets3d.rs 的Asset3DVisualizer::process_data实现它从ent_context.transform_info.target_from_instances()取出每个实例的变换将网格实例与位姿变换逐个组合生成GpuMeshInstance源码中标注了TODO(#7026)指出这是一种罕见的混合连接形式同时为每个实例计算并登记 3D 包围盒。这也印证了文档中为每个 transform 各绘制一份 mesh 实例的描述。查看器端渲染链路从 Blob 到 GPU 网格Asset3D的解析与渲染并不发生在 SDK 端而是在查看器运行时进行链路如下对应源码 assets3d.rs 与 mesh_loader.rs查询组件Asset3DVisualizer::visualizer_query_info声明其唯一必需组件为BlobAsset3D::descriptor_blob()execute阶段通过range_zip_1x2把blob字节切片、media_type字符串、albedo_factoru32RGBA按时间/RowId 对齐打包成Asset3DComponentData缓存命中以实体路径 查询结果哈希 media_type 组成MeshCacheKey经由MeshCache记忆化memoize复用已解析的网格避免同帧重复解析格式分发LoadedMesh::load_asset3d先调用MediaType::or_guess_from_data兜底猜测类型然后按 media_type 分发到不同的 importermodel/vnd.colladaxmlDAE→dae::load_dae_from_buffermodel/gltfjson与model/gltf-binaryGLTF/GLB→gltf::load_gltf_from_buffermodel/objOBJ→obj::load_obj_from_buffermodel/stlSTL→stl::load_stl_from_buffer其他类型 →anyhow::bail!({media_type} files are not supported)直接报错颜色覆盖若指定了albedo_factor调用cpu_model.override_albedo_factor(albedo_factor)覆盖材质中的颜色乘数上屏计算包围盒bbox把 CPU 网格into_gpu_meshes(render_ctx)转为 GPU 网格实例随MeshDrawData提交渲染。因此实际受支持的格式是 DAE GLTF/GLB OBJ STL其中 GLTF 的二进制GLB与 JSON 两种形式、STL 的二进制与 ASCII 两种形式均被覆盖。序列化与往返测试验证Asset3D的序列化行为由自动生成的 asset3d.rs 提供as_serialized_batches按blob → media_type → albedo_factor顺序输出组件批次from_arrow_components则从 Arrow 数组反序列化回结构体同时实现了Archetype、AsComponents与VisualizableArchetypetrait。对应的往返测试位于 crates/store/re_sdk_types/tests/types/asset3d.rs测试用[1, 2, 3, 4, 5, 6]字节、MediaType::GLTF与AlbedoFactor(Rgba32::from_unmultiplied_rgba(0xEE, 0x11, 0x22, 0x33))构造Asset3D::from_file_contents(...)经to_arrow序列化后再from_arrow反序列化断言两者完全相等从而保证 SDK 与存储格式的稳定性。此外仓库还内置了该示例的运行结果快照 tests/assets/rrd/snippets/archetypes/asset3d_simple.rrd可直接用 Rerun 查看器打开复现示例画面。实战对照Asset3D vs 手动解析的 Mesh3D仓库中的 Rust 示例 examples/rust/raw_mesh/src/main.rs 提供了绝佳的对照实验它默认读取 glTF 场景并把每个 primitive 手动转换为Mesh3D拆出顶点位置、索引、法线、顶点颜色、UV、albedo_factor 等组件逐一记录而加上--asset3d参数后则改为直接rr.log(world/asset, Asset3D::from_file_path(scene_path))整体记录原始文件。# 默认解析 glTF 并按 Mesh3D 组件逐字段记录 cargo run -p raw_mesh -- --scene buggy # 加 --asset3d直接记录预打包资产 cargo run -p raw_mesh -- --scene buggy --asset3d两种方式的取舍从源码中可以清晰看出Asset3D代码量极小、与源文件格式保持一一对应、渲染前由查看器集中解析并带缓存适合展示/回放原始三维资产Mesh3D需要把几何拆成组件字段但换来的是对几何数据的查询、筛选与后续程序化处理能力组件可被 DataframeView 查询、可被查询语言按字段操作适合需要对网格数据本身做分析或变换的场景。总结与快速上手清单核心要点回顾Asset3D以blob必需media_type推荐albedo_factor可选三个组件承载一个完整的预打包三维资产media_type支持model/gltf-binary、model/gltfjson、model/obj忽略.mtl、model/stl渲染器另支持 DAE类型可按扩展名、内容魔数逐级猜测三种 SDK 均提供from_file_path/from_file_contentsPython 为path/contents关键字参数两种构造入口同一实体配合多个InstancePoses3D可对资产做实例化渲染可显示在 Spatial3DView、Spatial2DView投影之上与 DataframeView 中。10 秒上手# Python 一行命令查看任意三维资产需要已安装 rerun-sdk python -c import sys, rerun as rr rr.init(view_asset, spawnTrue) rr.log(world, rr.ViewCoordinates.RIGHT_HAND_Z_UP, staticTrue) rr.log(world/asset, rr.Asset3D(pathsys.argv[1])) path/to/asset.glb如果查看器报无法渲染优先检查两点文件格式是否属于上述受支持列表media_type是否无法被自动猜测此时应显式传入或确认文件扩展名/魔数是否标准。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考