rerun-io--rerun/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/rerun-io/rerun) · [上游 README](https://github.com/rerun-io/rerun/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<h3 align="center">
  <a href="https://www.rerun.io/">
    <img width="1000" height="200" alt="Banner with Rerun logo" src="https://static.rerun.io/d0f5443d4803cac65c73fcc064936c09f5e7f208_rerun_banner.png" />

  </a>
</h3>

<h3 align="center">
  <a href="https://pypi.org/project/rerun-sdk/">                        <img alt="PyPi"           src="https://img.shields.io/pypi/v/rerun-sdk.svg">                              </a>
  <a href="https://crates.io/crates/rerun">                             <img alt="crates.io"      src="https://img.shields.io/crates/v/rerun.svg">                                </a>
  <a href="https://github.com/rerun-io/rerun/blob/main/LICENSE-MIT">    <img alt="MIT"            src="https://img.shields.io/badge/license-MIT-blue.svg">                        </a>
  <a href="https://github.com/rerun-io/rerun/blob/main/LICENSE-APACHE"> <img alt="Apache"         src="https://img.shields.io/badge/license-Apache-blue.svg">                     </a>
  <a href="https://discord.gg/Gcm8BbTaAj">                              <img alt="Rerun Discord"  src="https://img.shields.io/discord/1062300748202921994?label=Rerun%20Discord"> </a>
</h3>

# 物理 AI 的数据层

在专为多模态数据构建的共享列式存储上记录、查询、可视化，并流式传输至训练。

**功能概述：** Rerun 摄取多速率、多模态数据（图像、点云、变换、时间序列、关节状态、视频），来源和格式多样（机器人日志、人体数据采集设备、仿真、网络视频；MCAP、rrd、LeRobot）。内置查看器可实时同步渲染一切：拖动回放片段、并排对比传感器、实时观看 CV 流水线运行。同一批数据可通过 [dataframes](https://rerun.io/docs/howto/query-and-transform/get-data-out) 或 SQL 查询，并直接流式传输到训练中。基于 Rust 构建，采用专为多速率物理数据设计的列块（column-chunk）存储。提供 Python、Rust 和 C++ SDK。

**快速入门：** `pip install rerun-sdk` — 在 2 分钟内记录你的第一条多模态数据，并在查看器中看到它。

* [在浏览器中运行 Rerun Viewer](https://www.rerun.io/viewer)
* [了解 Rerun 是什么以及面向哪些用户](https://www.rerun.io/docs/overview/what-is-rerun)

### 使用场景
- 将机器人日志、第一人称/UMI 采集设备、仿真和网络视频摄入同一底层存储
- 将 CV 流水线（SLAM、手部追踪、动作重定向）作为表编辑运行
- 使用 dataframes 或 SQL 查询原始、中间和派生数据
- 在整条流水线中可视化多速率、多模态序列
- 将数据集混合直接流式传输到训练 — 无需导出任务，无需陈旧副本

### 数据类型
多速率、多模态、空间数据：图像、点云、时间序列、张量、变换、关节状态、视频。端到端完整保留。

### 快速体验
```py
import rerun as rr  # pip install rerun-sdk

rr.init("rerun_example_app")

rr.spawn()  # Spawn a child process with a viewer and connect
# rr.save("recording.rrd")  # Stream all logs to disk
# rr.connect_grpc()  # Connect to a remote viewer

# Associate subsequent data with 42 on the “frame” timeline
rr.set_time("frame", sequence=42)

# Log colored 3D points to the entity at `path/to/points`
rr.log("path/to/points", rr.Points3D(positions, colors=colors))
…
```

<p align="center">
  <picture>
    <img src="https://static.rerun.io/opf_screenshot/bee51040cba93c0bae62ef6c57fa703704012a41/full.png" alt="">
    <source media="(max-width: 480px)" srcset="https://static.rerun.io/opf_screenshot/bee51040cba93c0bae62ef6c57fa703704012a41/480w.png">
    <source media="(max-width: 768px)" srcset="https://static.rerun.io/opf_screenshot/bee51040cba93c0bae62ef6c57fa703704012a41/768w.png">
    <source media="(max-width: 1024px)" srcset="https://static.rerun.io/opf_screenshot/bee51040cba93c0bae62ef6c57fa703704012a41/1024w.png">
    <source media="(max-width: 1200px)" srcset="https://static.rerun.io/opf_screenshot/bee51040cba93c0bae62ef6c57fa703704012a41/1200w.png">
  </picture>
</p>

## 入门指南
* [**C++**](https://www.rerun.io/docs/getting-started/data-in/cpp)
* [**Python**](https://www.rerun.io/docs/getting-started/data-in/python): `pip install rerun-sdk` 或 [`conda`](https://github.com/conda-forge/rerun-sdk-feedstock)
* [**Rust**](https://www.rerun.io/docs/getting-started/data-in/rust): `cargo add rerun`

### 安装 Rerun Viewer 二进制程序
若要通过网络流式传输日志数据或加载我们的 `.rrd` 数据文件，你还需要 `rerun` 二进制程序。
可通过 `pip install rerun-sdk` 或 `cargo install rerun-cli --locked --features nasm` 安装（见下方说明）。
请注意，只有 Python SDK 自带 Viewer，而 C++ 和 Rust 始终需要单独安装。

**说明**：`nasm` Cargo 功能要求已安装 [`nasm`](https://github.com/netwide-assembler/nasm) CLI，并在 PATH 中可用。
你也可以选择不启用该功能，但这可能导致视频解码性能下降。

现在你应该可以在任意终端中运行 `rerun --help`。


### 文档
- 📚 [高层文档](https://rerun.io/docs)
- ⏃ [可记录类型（Loggable Types）](https://www.rerun.io/docs/reference/types)
- ⚙️ [示例](https://rerun.io/examples)
- 📖 [代码片段](./docs/snippets/INDEX.md)
- 🌊 [C++ API 文档](https://ref.rerun.io/docs/cpp)
- 🐍 [Python API 文档](https://ref.rerun.io/docs/python)
- 🦀 [Rust API 文档](https://docs.rs/rerun/)
- ⁉️ [故障排除](https://www.rerun.io/docs/overview/installing-rerun/troubleshooting)


### Agent 技能
本仓库提供一组 agent 技能，帮助编码 agent 编写 Rerun 代码。

使用 `skills` CLI 将其安装到你的 agent 中：

```sh
npx skills add rerun-io/rerun
```

如需直接阅读，技能文件位于 [`skills/`](./skills)。


## 状态
我们正处于积极开发中。
还有许多功能计划添加，API 仍在演进。
_预计会有破坏性变更！_

部分已知不足：
* [实体过多时查看器会变慢](https://github.com/rerun-io/rerun/issues/7115)
* [数百万点规模的点云可能较慢](https://github.com/rerun-io/rerun/issues/1136)


## Rerun 适用于什么场景？

Rerun 旨在帮助你理解和改进包含丰富多模态数据的复杂流程，例如 2D、3D、文本、时间序列、张量等。
它广泛应用于机器人、仿真、计算机视觉等行业，
或任何涉及大量随时间演化的传感器或其他信号的领域。

### 示例用场景
假设你正在开发一台吸尘机器人，它总是撞墙。为什么会这样？你需要某种调试工具，但普通调试器帮不上忙。同样，仅记录文本也作用有限。机器人可能记录「正在穿过门道」，但这无法解释它为何把墙当成门。

你需要的是一种可视化、时序化的调试器，能够记录机器人「小脑袋」里对世界的一切不同表征，例如：

* RGB 摄像头画面
* 深度图像
* 激光雷达扫描
* 分割图像（机器人如何解读所见内容）
* 公寓的 3D 地图
* 机器人检测到（或自认为检测到）的所有物体，以 3D 形状呈现在 3D 地图中
* 对其预测的置信度
* 等等

你还希望看到这些数据流如何随时间演化，以便回溯并精确定位出了什么问题、何时发生以及原因。

也许最终发现是阳光眩光以错误方式照射了某个传感器，导致分割网络混淆并引发错误的物体检测。也可能是激光雷达扫描代码中的 bug。或者机器人以为自己位于公寓的其他位置，因为里程计出了问题。也可能是上千种其他原因之一。Rerun 会帮你找出答案！

但从机器人视角观察世界不仅用于调试 — 它还能启发你改进算法、设计新的测试用例或收集数据集。它还能让你向同事、老板和客户解释机器人的「大脑」。诸如此类。眼见为实，一图胜千言，而多模态时序日志的价值又胜过千张图像 :)

虽然查看和理解数据是机器人领域取得进展的核心，还有一点也很重要：
你还可以将用于可视化的采集数据，用来创建新的数据集，以训练和评估在机器人上运行的模型与算法。
Rerun 提供查询 API，可轻松从你的录制数据中提取干净的数据集，正是为了这一目的。

当然，Rerun 的用途远不止机器人。只要你拥有任何形式的传感器，或随时间演变的 2D/3D 状态，Rerun 都是一款出色的工具。

### Rerun vs. Rviz

若你习惯了 [RViz](https://docs.ros.org/en/rolling/Tutorials/Intermediate/RViz/RViz-Main.html), 等纯可视化工具，可能只会看到最新数据。
Rerun 不仅仅是纯可视化方案，它提供了多模态数据平台，配备强大的可视化器、存储模型和查询引擎（另见：[*"What is Rerun?"*](https://rerun.io/docs/overview/what-is-rerun)).
在机器人领域，你可以用 Rerun 例如记录测试运行、管理和查询训练数据、可视化调试实时流或录制（也包括 [MCAP](https://rerun.io/docs/howto/logging-and-ingestion/mcap)) 等第三方格式）等等。

因此，虽然 Rerun 能让你的数据流在查看器中可视化，将 Rerun 日志集成到机器人应用中，还能开启利用 Rerun 更广泛能力的大门。

如果你只对可视化感兴趣，Rerun 查看器拥有强大的功能，例如凭借其具备时间感知能力的内存数据库，可以回溯历史时间。
你可以根据需求调整该缓冲区的大小（参见[此处](https://rerun.io/docs/howto/visualization/limit-ram)),，例如在长时间运行或内存受限的应用中，若想将 Rerun 用作 RViz 的替代方案，可将其调小。


## 商业模式
Rerun 采用 open-core（开放核心）模式。本仓库中的所有内容将保持开源且免费（既指免费啤酒，也指自由使用）。

我们还在构建 Rerun Hub，一个可扩展的机器人数据目录。
目前它仅向少数精选的设计合作伙伴开放。
[如有兴趣请点击此处](https://rerun.io/pricing).

Rerun 开源项目面向个人开发者的需求。
商业产品则面向构建和运行计算机视觉与机器人产品的团队所特有的需求。

## 如何引用 Rerun

在研究中使用 Rerun 时，请引用它以认可其对你工作的贡献。你可以
在论文的软件或方法部分加入对 Rerun 的引用。

建议引用格式：

```bibtex
@software{RerunSDK,
  title = {Rerun: A Visualization SDK for Multimodal Data},
  author = {{Rerun Development Team}},
  url = {https://www.rerun.io},
  version = {insert version number},
  date = {insert date of usage},
  year = {2024},
  publisher = {{Rerun Technologies AB}},
  address = {Online},
  note = {Available from https://www.rerun.io/ and https://github.com/rerun-io/rerun}
}
```

请将 "insert version number" 替换为你所使用的 Rerun 版本，将 "insert date of usage" 替换为你在研究中
使用该工具的日期。
该引用格式有助于确保 Rerun 开发团队获得应有的认可，
并便于其他研究者发现这一工具。

# 开发
* [`ARCHITECTURE.md`](ARCHITECTURE.md)
* [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
* [`CODE_STYLE.md`](CODE_STYLE.md)
* [`CONTRIBUTING.md`](CONTRIBUTING.md)
* [`BUILD.md`](BUILD.md)
* [`rerun_py/README.md`](rerun_py/README.md) - Python SDK 使用说明
* [`rerun_cpp/README.md`](rerun_cpp/README.md) - C++ SDK 使用说明


## 安装预发布版 Python SDK

1. 从 [GitHub Releases](https://github.com/rerun-io/rerun/releases) 下载正确的 `.whl`
2. 运行 `pip install rerun_sdk<…>.whl`（将 `<…>` 替换为实际文件名）
3. 测试：`rerun --version`