Rerun Rust 示例模板详解：用 examples/rust/template 快速搭建你自己的 Rerun 示例工程

Rerun Rust 示例模板详解用 examples/rust/template 快速搭建你自己的 Rerun 示例工程【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun在 Rerun 仓库中examples/rust/template并不是一个真正可演示的示例而是官方提供的Rust 示例工程脚手架scaffolding它规定了示例的标准目录结构、README 元数据格式、标签tags规范与运行方式。读完本文你将掌握如何基于该模板复制出自己的 Rerun Rust 示例、正确填写 README 前置元数据title/tags/thumbnail/channel并通过cargo run在本地 Viewer 中运行或保存为.rrd文件。一、模板的定位脚手架而非示例examples/rust/template/README.md 开门见山地说明This is an example template. It is not a real example. You can duplicate the directory and use it as a starting point for writing a real example.也就是说模板目录本身不应被当作正式示例发布而是供贡献者或使用者复制后在此基础上编写真正的示例。examples/README.md 中 “Adding a new example” 一节也明确指出You can base your example off ofpython/templateorrust/template.因此模板的核心价值在于“定规范”目录结构、README 骨架、运行命令、标签体系全部预先给出让新示例与仓库现有 examples/rust/minimal、examples/rust/objectron 等示例保持同构。二、目录结构约定从 examples/README.md 给出的目录规范看每个 Rust 示例必须满足examples/ rust/ name/ README.md Cargo.toml src/ main.rs模板目录正是这一结构的最小实现examples/rust/template/Cargo.tomlexamples/rust/template/README.mdexamples/rust/template/src/main.rs其中 README.md 是“关键部分”——仓库文档说明“The important part is that each example has aREADME.mdfile. The contents of thisREADME.mdis used to render the examples in the documentation.”即 README 的内容会被用来在示例站点上渲染展示所以其格式本身就是一种契约。三、Cargo.toml依赖与版本约束模板的 Cargo.toml 非常精简但对新示例作者有几处值得留意的约定[package] name template version 0.38.0-alpha.1dev edition 2024 rust-version 1.96 license MIT OR Apache-2.0 publish false [dependencies] rerun { path ../../../crates/top/rerun }要点解析publish false所有示例都是仓库内部 crate不发布到注册表依赖通过 workspace 相对路径引用rerun { path ../../../crates/top/rerun }直接指向仓库内的 crates/top/rerun 源码保证示例与 SDK 版本严格一致。这也呼应了 examples/README.md 中的提醒“Make sure your SDK version matches the code in the examples.”——示例代码对应的 SDK 版本由仓库 checkout 决定例如 SDK0.4.0应配合git checkout v0.4.0version/edition/rust-version跟随仓库当前发布线当前为0.38.0-alpha.1dev、Rust edition 2024、MSRV 1.96新建示例时应照抄模板中的取值避免与 workspace 配置冲突。对照 examples/rust/README.md 可确认Rust 示例整体通过cargo run -p example_name运行模板对应的包名就是template。四、src/main.rs最小可运行骨架模板的 main.rs 只有十几行展示了接入 Rerun 的最短路径//! Example template. fn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new(rerun_example_my_example_name).spawn()?; // … example code _ rec; Ok(()) }从源码结构看这个骨架包含两个要素RecordingStreamBuilder::new(应用名)创建录制流。示例命名惯例为rerun_example_你的示例名Viewer 会用它作为应用/数据源名称显示请照此替换.spawn()?以“自动启动”模式打开即按 examples/rust/README.md 所述默认行为是拉起一个 Rerun Viewer 并实时向其流式发送日志数据。debug 构建下优先使用target/debug/rerun若存在否则从PATH中查找rerun。// … example code处即为你后续添加rec.log(...)调用记录点云、图像、Transform 等 archetypes的位置。五、README 前置元数据frontmatter 逐字段讲解模板 README 的第一段是 HTML 注释包裹的[metadata]前置块这是示例站点的“数据源”必须逐字段对待!--[metadata] title Template # Tags must come from examples/tags.toml — reuse an existing tag, or add a new one to that list. tags [Human case, Comma, Separated, ACRONYM, Respect brand names, Hugging Face, Coca-Cola] thumbnail https://static.rerun.io/template/f53a939567970272cf7c740f1efe5c72f20de7ab/480w.png thumbnail_dimensions [480, 359] # channel main # uncomment if this example can be run fast an easily # include_in_manifest true # uncomment if this example should be on the Viewer homescreen --1.title与tagstitle是示例在文档站上的显示名tags必须来自 examples/tags.toml——这是标签主清单同一主题的示例必须拼写完全一致以便在站点上归组。examples/tags.toml 头部注释还给出了书写规范Human case人类可读大小写、Comma逗号、Separated分词、ACRONYM全大写缩写、Respect brand names尊重品牌名如Hugging Face、Coca-Cola。模板里这一串标签实际上就是在示范这些规范。标签合法性由 CI 检查scripts/ci/example_tags.py 提供三种用法见 examples/README.md# 检查未知标签并给出最接近的候选 pixi run uvpy scripts/ci/example_tags.py check # 报告可能互为重复的标签 pixi run uvpy scripts/ci/example_tags.py similar # 查看每个标签的使用频率与使用它的示例 pixi run uvpy scripts/ci/example_tags.py list --paths如果确实需要新标签应先在tags.toml的tags数组中登记tags.toml还维护了一个distinct_pairs用于声明“看起来重复但语义不同”的标签对例如[Egocentric, Exocentric]。2.thumbnail与thumbnail_dimensionsthumbnail指向缩略图的静态托管地址注意模板中用的是外部静态资源 URL这是渲染站点的展示资源不是仓库内文件thumbnail_dimensions为[宽, 高]的像素尺寸模板中用一段 HTML 注释提示正式示例应上传真实运行截图上传方式参考pixi run upload-image --help对应仓库脚本 scripts/upload_image.py并同步更新 frontmatter 的thumbnail字段。3.channelCI 构建通道channel决定示例是否在 CI 上构建并出现在 Viewer 内置的示例页。examples/README.md 列出了三个通道channel构建频率适用场景main每次合入 main 构建简单、运行快的示例nightly每天一次较重的示例release每次发布一次非常重的示例如果channel缺失示例永远不会被 CI 构建。模板默认注释掉了这一行因为模板本身不可运行、也无需构建。4.include_in_manifest与 manifest.tomlinclude_in_manifest true表示该示例应出现在 examples/manifest.toml 中。manifest 按spatial-computing、robotics、generative-vision等类别组织示例每个类别含order、title、prelude描述与examples列表只有进入 manifest 的示例才会出现在生成的示例文档中且manifest.toml本身不影响示例是否出现在应用内——应用内展示取决于上文提到的channel。六、README 正文骨架三个标准小节模板 README 在元数据之后给出了正文骨架正式示例应保留这三节并填充内容开头一句话简介“Put a short description at the top, like this.”——站点卡片展示的正是这段文字## Used Rerun types列出示例用到的 Rerun archetype 类型模板中给出Image作为格式示范帮助读者一眼判断示例与自己的数据类型是否相关## Run the code给出运行命令。模板写的是cargo run --release -p template即“包名 目录名”的cargo run -p example_name惯例release 与否按需选择。此外 examples/README.md 还建议在主程序入口加一段简短的DESCRIPTION文档并记录为 Markdown 文本Python 示例的示范为rr.log(description, rr.TextDocument(...), staticTrue)让 Viewer 打开示例时就能看到背景说明。七、运行行为spawn / save / connect / serveexamples/rust/README.md 说明几乎所有 Rust 示例都内置了一组互斥的预定义 Rerun 命令行参数模板复制后同样适用参数行为--spawn启动 Viewer 并实时喂数据默认行为--save SAVE将数据保存为.rrd文件而非直接可视化--connect [IP:PORT]连接并发送到远程 Rerun Viewer--serve连接到基于 Web 的 Rerun Viewer例如保存再打开cargo run -p template -- --save data.rrd rerun data.rrd注意事项原文引用.rrd文件不保证跨版本的向前/向后兼容一个版本的 Rerun 很可能无法打开另一个版本生成的.rrd文件——这是使用录制文件时必须知道的前提限制。若示例需要示例专用参数可通过cargo run -p example_name -- --help查看完整列表。八、从模板到正式示例的落地步骤综合以上各部分基于模板新建一个 Rust 示例的完整流程为复制目录把examples/rust/template复制为examples/rust/your_example改名与改代码修改Cargo.toml的name、src/main.rs中的应用名在// … example code处写真实的rec.log(...)调用可参照 examples/rust/minimal 的点云示例或 examples/rust/objectron 的多类型日志示例填写 README更新 frontmatter 的titletags只用 examples/tags.toml 中已有标签必要时先登记新标签运行示例后用pixi run upload-image --help所述方式上传截图回填thumbnail与thumbnail_dimensions正文补全“简介 Used Rerun types Run the code”三节可选接入 CI 与站点可运行的示例按重量级选择channel main | nightly | release要出现在示例文档站则加入 examples/manifest.toml 对应类别的examples列表本地验证cargo run -p your_example检查 Viewer 实时流cargo run -p your_example -- --save out.rrd检查录制文件。九、与 Python 模板的对应关系仓库同时维护了 examples/python/template/README.md两者 frontmatter 字段完全同构title/tags/thumbnail/thumbnail_dimensions/channel/include_in_manifest仅运行方式不同# Python 模板 pip install -e examples/python/template python -m template # Rust 模板 cargo run --release -p template这意味着同一示例若同时提供 Rust/Python 两个版本应保持相同的title与tags拼写使站点上的两个入口归入同一主题分组。小结examples/rust/template是 Rerun Rust 示例生态的“格式契约”它以 Cargo.toml 固化了 workspace 内依赖与版本约束以 main.rs 给出RecordingStreamBuilderspawn的最短接入路径以 README.md 规定了 frontmatter 元数据、标签主清单tags.toml、CI 构建通道channel与站点清单manifest.toml三套展示机制并借 examples/rust/README.md 定义的--spawn/--save/--connect/--serve参数族提供统一的运行体验。掌握这套模板你就拥有了与仓库所有 Rust 示例对齐的、可复制可运行的新示例工程起点。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考