Rerun Python SDK完全手册：从安装到三维点云可视化全流程

【免费下载链接】rerun Visualize streams of multimodal data. Fast, easy to use, and simple to integrate. Built in Rust using egui. 项目地址: https://gitcode.com/GitHub_Trending/re/rerun

1. 引言：解决多模态数据可视化的痛点

你是否还在为机器人传感器数据、三维点云或多模态数据流的实时可视化而烦恼？传统工具要么配置复杂，要么性能不足，无法满足动态数据的实时呈现需求。Rerun Python SDK提供了一站式解决方案，通过简单的API即可将图像、点云、文本等多模态数据流式传输到Rerun Viewer，实现高效可视化。本文将带你从环境搭建到三维点云渲染，掌握Rerun的核心功能与高级技巧。

读完本文后，你将能够：

• 快速安装并配置Rerun Python开发环境
• 理解Rerun的核心数据模型与实体组件系统（ECS）
• 实现从简单几何图形到复杂三维点云的完整可视化流程
• 掌握数据录制、存储与回放的高级操作
• 解决常见的性能优化与故障排除问题

2. 环境准备：安装与配置指南

2.1 系统要求

• Python 3.8+
• 支持Windows、macOS、Linux操作系统
• 最低GPU要求：支持OpenGL 3.3或WebGL 2.0的图形卡

2.2 快速安装

# 基础安装（包含SDK与Viewer）
pip3 install rerun-sdk

# Jupyter Notebook集成（可选）
pip3 install rerun-notebook

注意：PyPI上的包名称为rerun-sdk，但导入时需使用import rerun。

2.3 源码编译（高级用户）

如需从最新源码构建：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/re/rerun.git
cd rerun

# 使用pixi构建（推荐）
pixi run py-build --release

# 生成可安装wheel包
pixi run py-build-wheel

2.4 验证安装

import rerun as rr

# 初始化并启动Viewer
rr.init("installation_check", spawn=True)
rr.log("hello", rr.Text("Rerun Python SDK安装成功！"))

执行后将自动启动Rerun Viewer，并显示"hello"实体下的文本信息。

3. 核心概念：数据模型与架构设计

3.1 时间感知的实体组件系统（ECS）

Rerun采用时间感知的ECS模型组织数据，这是理解其工作原理的关键：

• 实体（Entity）：具有唯一ID的对象，如/lidar或/camera/left
• 组件（Component）：附加到实体的数据单元，如PointCloud3D或Transform3D
• 时间序列（TimeSeries）：支持多时间戳数据，实现动态回放与对比分析

3.2 坐标系统与空间变换

Rerun使用右手坐标系，支持多空间视图同步：

空间类型	X轴方向	Y轴方向	Z轴方向	典型应用场景
2D屏幕	右	下	-	图像渲染
3D世界	右	上	前	点云可视化
机器人	前	左	上	里程计数据

4. 基础操作：从初始化到数据录制

4.1 核心API工作流

4.2 初始化与配置

import rerun as rr
import numpy as np

# 基础初始化（自动启动Viewer）
rr.init(
    application_id="my_app",  # 应用唯一标识
    spawn=True,               # 自动启动Viewer
    recording_id="session_001" # 可选：指定录制会话ID
)

# 高级配置：自定义Viewer端口与数据传输方式
rr.init(
    "advanced_app",
    spawn=False,  # 不自动启动Viewer
    connect="127.0.0.1:9876"  # 连接远程Viewer
)
rr.spawn()  # 手动启动本地Viewer

4.3 基础数据录制示例

# 记录3D立方体
rr.log(
    "cube",  # 实体路径
    rr.Cube3D(half_size=[0.5, 0.5, 0.5]),  # 立方体组件
    rr.Transform3D(translation=[1.0, 2.0, 3.0])  # 空间变换
)

# 记录时间序列数据（如传感器读数）
for t in range(10):
    rr.set_time_sequence("frame", t)  # 设置时间序列
    rr.log(
        "sensor/temperature",
        rr.Scalar(np.sin(t * 0.5) * 10 + 25)  # 模拟温度数据
    )

5. 三维点云可视化：从基础到高级

5.1 点云数据结构解析

Rerun支持多种点云数据格式，核心参数包括：

# 点云数据结构示意
class PointCloud3D:
    positions: np.ndarray  # 形状为[N, 3]的float32数组，存储三维坐标
    colors: Optional[np.ndarray]  # 可选，形状为[N, 3/4]的uint8数组，RGB/RGBA颜色
    radii: Optional[np.ndarray]  # 可选，形状为[N]的float32数组，点大小
    class_ids: Optional[np.ndarray]  # 可选，形状为[N]的uint32数组，分类ID

5.2 基础点云渲染示例

import rerun as rr
import numpy as np

# 初始化
rr.init("point_cloud_basics", spawn=True)

# 生成随机点云数据
np.random.seed(42)
num_points = 10000
positions = np.random.randn(num_points, 3)  # 正态分布的点坐标
colors = np.random.randint(0, 255, (num_points, 3), dtype=np.uint8)  # 随机颜色

# 记录点云
rr.log(
    "random_points",
    rr.Points3D(
        positions=positions,
        colors=colors,
        radii=0.05  # 点大小
    )
)

# 保持程序运行以查看结果
input("按Enter键退出...")

5.3 高级点云功能

5.3.1 点云分类与颜色映射

# 基于高度的颜色映射
heights = positions[:, 2]
normalized_heights = (heights - heights.min()) / (heights.max() - heights.min())
colors = (plt.cm.viridis(normalized_heights) * 255).astype(np.uint8)

# 添加分类ID
class_ids = np.random.randint(0, 5, num_points, dtype=np.uint32)

rr.log(
    "classified_points",
    rr.Points3D(
        positions=positions,
        colors=colors,
        radii=0.05,
        class_ids=class_ids
    ),
    rr.AnnotationContext(  # 定义分类标签与颜色
        [
            rr.AnnotationInfo(id=0, label="地面", color=[0, 255, 0]),
            rr.AnnotationInfo(id=1, label="建筑", color=[255, 0, 0]),
            rr.AnnotationInfo(id=2, label="植被", color=[0, 0, 255]),
            rr.AnnotationInfo(id=3, label="车辆", color=[255, 255, 0]),
            rr.AnnotationInfo(id=4, label="未知", color=[128, 128, 128]),
        ]
    )
)

5.3.2 点云与三维模型融合

# 记录参考坐标系
rr.log("world", rr.Transform3D(translation=[0, 0, 0]))

# 记录点云
rr.log("world/point_cloud", rr.Points3D(positions=positions, colors=colors))

# 记录三维模型（如车辆）
rr.log(
    "world/vehicle",
    rr.Transform3D(translation=[5, 0, 0]),
    rr.Mesh3D.from_file("vehicle_model.glb")  # 加载外部3D模型
)

5.4 激光雷达数据可视化案例

以下是处理真实激光雷达数据的完整流程：

import rerun as rr
import numpy as np
import open3d as o3d  # 使用Open3D加载点云文件

def visualize_lidar_data(file_path):
    # 初始化Rerun
    rr.init("lidar_visualization", spawn=True)
    
    # 加载点云数据（.pcd文件）
    pcd = o3d.io.read_point_cloud(file_path)
    points = np.asarray(pcd.points)
    colors = np.asarray(pcd.colors) * 255  # 转换为0-255范围
    
    # 设置时间轴
    rr.set_time_seconds("capture_time", 0.0)  # 起始时间
    
    # 记录点云
    rr.log(
        "lidar",
        rr.Points3D(
            positions=points,
            colors=colors.astype(np.uint8),
            radii=0.02
        )
    )
    
    # 添加坐标系和参考网格
    rr.log("lidar", rr.AxisAlignment3D(axis_length=1.0))
    rr.log("ground", rr.Grid3D(
        origin=[0, 0, points[:, 2].min()],
        width=10,
        height=10,
        resolution=0.5
    ))
    
    input("按Enter键退出...")

if __name__ == "__main__":
    visualize_lidar_data("lidar_scan.pcd")

6. 数据录制与回放

6.1 录制到文件

# 录制到文件
rr.init("data_recording", spawn=False)
rr.save("recording.rrd")  # 开始录制到文件

# 记录数据...
for i in range(100):
    rr.set_time_frame("frame", i)
    rr.log("dynamic_points", rr.Points3D(positions=np.random.randn(1000, 3)))

rr.close()  # 完成录制

6.2 从文件回放

# 方法1：使用Python API
rr.init("data_playback", spawn=True)
rr.load("recording.rrd")  # 加载录制文件
rr.play()  # 开始回放

# 方法2：使用命令行工具
# rerun recording.rrd

6.3 实时数据流与远程查看

# 发送端：发送数据到远程Viewer
rr.init("remote_stream", spawn=False)
rr.connect("192.168.1.100:9876")  # 连接到远程Viewer

# 接收端：启动远程Viewer
# rerun --server

7. 性能优化与最佳实践

7.1 点云降采样与压缩

# 体素网格降采样
pcd = o3d.geometry.PointCloud()
pcd.points = o3d.utility.Vector3dVector(positions)
downsampled_pcd = pcd.voxel_down_sample(voxel_size=0.1)
downsampled_positions = np.asarray(downsampled_pcd.points)

rr.log(
    "downsampled_points",
    rr.Points3D(positions=downsampled_positions)
)

7.2 数据分块与批处理

# 大型点云分块处理
BLOCK_SIZE = 10000
for i in range(0, num_points, BLOCK_SIZE):
    block = positions[i:i+BLOCK_SIZE]
    rr.log(f"point_cloud/block_{i//BLOCK_SIZE}", rr.Points3D(positions=block))

7.3 内存管理与资源释放

# 使用上下文管理器自动释放资源
with rr.RecordingStream("memory_optimized", spawn=True) as stream:
    for frame in frames:
        stream.log("frame", rr.Image(frame))
        
# 手动控制内存使用
rr.memory_limit(1024 * 1024 * 1024)  # 设置1GB内存限制
rr.purge()  # 手动清理不再需要的历史数据

8. 故障排除与常见问题

8.1 安装问题

错误	解决方案
ImportError: No module named rerun	确认使用pip install rerun-sdk而非pip install rerun
GLIBCXX not found	安装较新版本的libstdc++: sudo apt-get install libstdc++6
Failed to spawn viewer	手动启动Viewer: rerun，然后在代码中使用rr.connect()

8.2 性能问题

• Viewer卡顿：降低点云分辨率或启用视锥体剔除
• 数据传输缓慢：启用压缩传输 rr.init(..., compression=rr.CompressionLevel.LZ4)
• 高CPU占用：减少日志频率或使用多线程录制

8.3 可视化问题

• 点云不显示：检查坐标系变换是否正确，尝试添加rr.AxisAlignment3D作为参考
• 颜色异常：确认颜色数组格式为uint8且范围在0-255之间
• Viewer崩溃：更新显卡驱动或降低渲染质量 rr.init(..., render_quality=rr.RenderQuality.LOW)

9. 总结与展望

本文详细介绍了Rerun Python SDK从安装配置到三维点云可视化的完整流程，涵盖了核心概念、基础操作、高级功能及性能优化技巧。通过Rerun的时间感知ECS模型，你可以轻松构建复杂的多模态数据可视化系统，满足机器人、计算机视觉等领域的开发需求。

未来，Rerun将持续优化数据处理性能，增加更多高级可视化功能（如体积渲染、动态标注），并扩展对更多数据格式的支持。建议定期关注项目更新，以获取最新特性与改进。

10. 扩展资源

• 官方文档：访问Rerun官方文档获取API详细说明
• 示例库：探索项目仓库中的examples/python目录，包含各类应用场景
• 社区支持：加入Rerun社区论坛与开发者交流经验
• 源码仓库：https://gitcode.com/GitHub_Trending/re/rerun

收藏本文，随时查阅Rerun Python SDK使用指南。关注更新，获取更多高级可视化技巧！

附录：常用API速查表

功能	代码示例
初始化	rr.init("app_name", spawn=True)
记录点云	rr.log("points", rr.Points3D(positions, colors))
记录图像	rr.log("image", rr.Image(rgb_data))
设置时间	rr.set_time_frame("frame", 123)
保存数据	rr.save("data.rrd")
加载数据	rr.load("data.rrd")

【免费下载链接】rerun Visualize streams of multimodal data. Fast, easy to use, and simple to integrate. Built in Rust using egui. 项目地址: https://gitcode.com/GitHub_Trending/re/rerun