尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

深入理解 Rerun 数据模型:Entity、Component 与 Archetype 的完整解析

深入理解 Rerun 数据模型:Entity、Component 与 Archetype 的完整解析 深入理解 Rerun 数据模型Entity、Component 与 Archetype 的完整解析【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本篇文章基于 Rerun 官方概念文档 entity-component.md 展开系统讲解 Rerun 的核心数据模型——实体Entity与组件Component以及在此基础上衍生出的 Archetype、Encodings、ECS 系统等概念。读完本文你将掌握 Rerun 中数据如何被组织、记录与查询能够熟练使用rr.log()进行结构化日志记录并通过AnyValues与AsComponents协议注入自定义数据真正理解实体即文件夹、组件即文件的底层设计哲学。数据模型概述从 ECS 到 RerunRerun 数据模型的核心理念源自 Entity Component System (ECS) 架构模式。ECS 是一种面向组合composition-oriented的框架实体Entities代表通用的对象组件Components描述与这些对象关联的数据。Rerun 借鉴了这一思想并将其落地为可视化和数据查询的基础设施。在 Rerun 中实体Entities是你通过rr.log()字符串唯一标识。组件Components是真正承载与这些事物关联的数据的部分例如位置position、颜色color、像素数据pixel data等。文档中给出了一句非常形象的类比实体就像文件夹组件就像文件。这意味着实体本身不携带数据它只是一个挂载点数据全部以组件的形式附着在实体路径之下。任何实体在层级结构中都可以包含组件正如任何文件夹都可以包含文件。此外Rerun SDK 还暴露了两个补充概念Archetypes原型一组逻辑自洽的组件集合对应诸如 2D 点、3D 盒子之类的图元primitive。在 Rerun SDK 中archetype 以构造器对象builder object的形式出现帮助用户便捷地创建这类组件集合。它们是高层次的便捷工具高级用户完全可以绕过它们直接操作组件。Encodings编码当基础数据类型float、uint32等不足以表达某些组件时组件所依赖的常规数据结构。例如 RGB 颜色编码、灰度图像编码等都属于 encoding 的范畴。完整的类型清单可以在 Types 参考文档 中查阅其中分别列出了 archetypes、components 与 encodings 三张清单。记录与查看数据一个点的完整旅程你在 Rerun 中记录的所有数据都会映射到实体和组件的概念上。以记录一个 2D 点为例rr.log(my_point, rr.Points2D([32.7, 45.9], colors[255, 0, 0]))这条语句使用了rr.Points2Darchetype。在其内部这个 archetype 构建了一个包含两个组件的集合Points2D:positions类型为 Position2DPoints2D:colors类型为 Color。随后rr.log()函数会记录这两个组件并把它们与my_point这个实体关联起来。之后负责空间类数据的 View视图会向数据存储查询所有带有Points2D:positions组件的实体——在本例中它会找到my_point实体。由于Points2D:colors组件与同一实体关联查询会一并返回它。这两个组件通过附加在组件上的**元数据metadata**被识别为对应Points2Darchetype从而告知 Viewer 应当如何渲染这个实体。这里提到的附加在组件上的元数据在源码中体现为ComponentDescriptor。在 component_descriptor.rs 中可以看到它的定义它由三个字段构成——archetype可选数据来源的 Archetype 名称例如rerun.archetypes.Points3D如果数据不是通过 archetype 记录的就为Nonecomponent组件在给定实体路径下的唯一标识符例如Points3D:positionscomponent_type可选组件的类型信息用于告知应用如何解释数据例如rerun.components.Position3D。从源码注释可以确认每一个位于给定实体路径下的组件都由 descriptor 的component字段唯一标识而archetype与component_type字段则提供数据的附加语义信息。这正是两个组件被识别为对应 Points2D archetype这一机制的技术基础。实体路径数据的层级组织由于实体路径是理解实体概念的前提这里补充其要点详见 entity-path.md实体路径以/作为层级分隔符遵循常规的根root、父parent/子child语义在日志 API 中写路径时通常省略开头的/。路径的每个部分必须是非空字符串允许任意字符但除字母、数字以及_、-、.之外的字符需要以\转义也可以通过\u{262E}插入任意 Unicode 码点。例如world/3D/My\ Image.jpg/detection就是一个合法路径注意空格被转义了。路径前缀__被保留给 Rerun SDK 内部使用如__properties、__warnings用户不应以此记录业务数据。实体路径与文件路径并非同一概念..不代表父目录也不应把文件路径尤其在 Windows 上直接当作实体路径使用。添加自定义数据从 AnyValues 到 AsComponents虽然 SDK 的 archetype 对象和 Viewer 基于同一份 archetype 定义且都是根据该定义自动生成代码实现的但它们都运行在任意的组件集合之上。SDK 和 Viewer 都不强制要求一个实体必须包含某一组特定的组件Rerun Viewer 会以通用形式展示任何数据但它的视图只对它能理解的组件集合生效你的实体可以携带任意数量的额外组件与当前视图场景无关的组件会被安全地忽略Rerun 甚至允许你完全绕过 archetype记录自己定义的组件集合。方式一使用 AnyValues 附加/记录自定义组件在 Python 中rr.AnyValues帮助对象既可以为 archetype 附加自定义组件也可以单独记录一组完全自定义的组件。为 archetype 附加额外值对应 extra_values.pyimport rerun as rr import rerun.blueprint as rrb rr.init(rerun_example_extra_values, spawnTrue) rr.log( extra_values, rr.Points2D([[-1, -1], [-1, 1], [1, -1], [1, 1]]), rr.AnyValues( confidence[0.3, 0.4, 0.5, 0.6], ), ) # Set view bounds: rr.send_blueprint( rrb.Spatial2DView( visual_boundsrrb.VisualBounds2D( x_range[-1.5, 1.5], y_range[-1.5, 1.5] ) ) )这里rr.AnyValues(confidence[...])作为rr.log的第二个参数传入与Points2D一起记录——四个点的 confidence 值被作为额外组件挂到同一个extra_values实体上但不会影响 Points2D 视图的渲染。记录一组完全自定义的组件对应 any_values.pyimport rerun as rr rr.init(rerun_example_any_values, spawnTrue) rr.log( any_values, rr .AnyValues( # Using arbitrary Arrow data. homepagehttps://www.rerun.io, repositoryhttps://github.com/rerun-io/rerun, ) # Using Reruns builtin components. .with_component_override( confidence, rr.components.ScalarBatch._COMPONENT_TYPE, [1.2, 3.4, 5.6] ) .with_component_override( description, rr.components.TextBatch._COMPONENT_TYPE, Bla bla bla… ), )从 any_value.py 的源码实现可以看到AnyValues的底层行为每个关键字参数都会被记录为独立的组件批次component batch键作为组件名值必须能转换为 Arrow 数组——一般来说只要能传给pyarrow.array就能作为扩展组件记录Rerun 要求同一个组件只能有一种类型首次记录的类型将作为该组件以后所有记录的类型API 会尽力通过 numpy 和 Arrow 做类型转换无法转换的组件会产生警告严格模式下抛异常None值因为没有类型信息默认会被丢弃drop_untyped_nonesTrue除非该组件此前已被记录过某种类型——这主要是为了避免乱序日志场景下的歧义with_component_override(field, component_type, value)可以为组件显式指定名称和组件类型从而复用 Rerun 内置组件如ScalarBatch、TextBatch。AnyValues内部通过DynamicArchetype构造器实现并支持columns()类方法返回ComponentColumnList从而配合rr.send_columns以列式columnar方式直接发送数据见 send-columns.md。方式二实现 AsComponents 协议/特征对于更复杂的使用场景可以自定义对象实现rr.AsComponents协议Python或rerun::AsComponentstraitRust。在 Python 侧该协议的定义位于 _baseclasses.pyruntime_checkable class AsComponents(Protocol): Describes interface for interpreting an object as a bundle of Components. def as_component_batches(self) - list[DescribedComponentBatch]: Returns an iterable of ComponentBatchLike objects... ...即核心只需实现一个方法as_component_batches()返回一组 DescribedComponentBatch。每个DescribedComponentBatch由一个ComponentBatchLike能输出 Arrow 数组的批次和一个ComponentDescriptor语义描述见上文 Rust 源码组成同时支持partition()方法分割成子批次以用于send_columns。方式三定义完整自定义 archetype 与组件结合 custom_data.py可以实现一个完全由用户代码定义的、扩展内置Points3D的自定义 archetype无需重新编译 Rerunfrom __future__ import annotations import numpy as np import numpy.typing as npt import pyarrow as pa import rerun as rr class ConfidenceBatch(rr.ComponentBatchMixin): A batch of confidence data. def __init__(self, confidence: npt.ArrayLike) - None: self.confidence confidence def as_arrow_array(self) - pa.Array: The arrow batch representing the custom component. return pa.array(self.confidence, typepa.float32()) class CustomPoints3D(rr.AsComponents): A custom archetype extending the builtin Points3D with extra data. def __init__(self, positions: npt.ArrayLike, confidences: npt.ArrayLike) - None: self.points3d rr.Points3D(positions) self.confidences ConfidenceBatch(confidences).described( rr.ComponentDescriptor( user.CustomPoints3D:confidences, archetypeuser.CustomPoints3D, component_typeuser.Confidence, ) ) def as_component_batches(self) - list[rr.DescribedComponentBatch]: return [ # The components from Points3D *self.points3d.as_component_batches(), # Custom confidence data self.confidences, ]随后即可像使用内置 archetype 一样直接记录rr.log( left/my_confident_point_cloud, CustomPoints3D( positionspoint_grid, # a 3D point grid confidences[42], ), )关键点在于ConfidenceBatch通过ComponentBatchMixin实现as_arrow_array()将自定义的 float32 数组序列化为 Arrow 数组再通过.described(ComponentDescriptor(...))给批次打上自定义 archetype 自定义组件类型的语义标签。由于 Rerun 的数据层基于 Apache Arrow 构建任何能被 Arrow 序列化的数据都可以直接记录——这也就是 custom-data.md 中强调的只要你的数据能分解为 Rerun 组件或能用 Apache Arrow 序列化就能直接记录无需重新编译 Rerun。更轻量的做法是直接复用内置 archetype 的as_component_batches()把自己的数据结构重映射为已有 archetypedataclass class LabeledPoints: points: np.ndarray labels: List[str] def as_component_batches(self) - list[rr.ComponentBatch]: return rr.Points3D(positionsself.points, labelsself.labels).as_component_batches()空实体没有组件的数据身份没有组件的实体不过是一个身份identity——由它的实体路径表示。它不包含任何数据也没有类型。当你记录一条数据时你实际上做的只是设置与该实体关联的一个或多个组件的值。这一点与实体即文件夹的类比完全吻合一个空文件夹实体本身没有意义只有当向其中写入文件组件后才有内容。这也解释了为什么同一个实体路径可以在不同时间点被不同类型的组件填充——实体本身并不记住任何类型信息。混合 archetype 的注意点由于实体不强制组件集合理论上可以在同一实体路径上记录多种 archetype但需要格外小心例如在记录过Mesh3D的实体路径上再记录Points3D会覆盖网格的Position3D组件却保留triangle_indices组件不动最终可能导致 Viewer 无法正确显示。不过也有合理的混合场景比如将Transform3D与相关几何体记录在同一个实体路径上。ECS Systems视图背后的处理系统ECS 架构还有第三个概念尚未提及系统systems——即基于实体所拥有的组件来对实体进行处理的进程。Rerun 仍在确定形式化系统的确切形态目前除了 Rust Viewer 代码之外还不能编写自己的系统。但视图views在底层确实使用了多种系统来工作。想要了解如何在 Rust 中扩展 Viewer可以参考 Extend the Viewer in Rust 一节。从文档与源码结构可以推断Rerun 的查询与视图层正是围绕组件集合运转的Viewer 的视图如空间视图、时间序列视图本质上是一类消费特定组件集合的系统组件映射component mappings机制则决定某个组件如何被某个可视化器消费详见 component-mappings.md 与 plot-any-scalar.md。文档还提示未来版本将把更多 Lenses 的功能直接暴露在 Viewer 中从而支持更复杂的映射例如从标量到颜色的映射。小结Rerun 的数据模型可以用一句话概括实体是身份的容器组件是数据的载体archetype 是组件的便捷打包descriptor 是组件语义的身份证。理解这一模型是掌握 Rerun 一切高级功能查询、视图、自定义数据、列式发送的前提。建议继续阅读 实体路径层级、发送用户自定义数据 以及 Type 参考并结合 extra_values.py、any_values.py、custom_data.py 三个示例动手实验即可快速建立对 Rerun 数据模型的完整实操认知。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表