The Entity Path Hierarchy
Entity Paths
As mentioned in the Entity Component overview, all Entities within Rerun have a unique Entity Path.
The first argument to each log function is this path. Each time you log to a specific entity path you will update the entity, i.e. log a new instance of it along the timeline. Each logging to a path must be of the same type (you cannot log an image to the same path as a point cloud).
Rerun treats these paths as being arranged in a hierarchy with the "/" character acting as a separator between path elements. The conventional path semantics including concepts of "root" and "parent" / "child" generally apply.
When writing paths in logging APIs the leading "/" is omitted.
Note that there is no path-level distinction between "file-like" and "directory-like" concepts. Any path may be an entity, and entities may be direct children of other entities. For example:
rr.log_image("image", img) rr.log_points("image/points", points)
However, it is also acceptable to leave implicitly "empty" elements in your paths as well.
rr.log_image("camera/image", img) rr.log_points("camera/image/detections/points", points)
Nothing needs to be explicitly logged to "camera"
or "camera/image/detection"
to make the above valid.
Path parts
A path can look like this: camera/"left"/detection/#42/bbox
. Each part (between the slashes) can either be:
- A name (e.g.
camera
), intended for hard-coded names. - A
"quoted string"
, intended for dynamic strings, like serials numbers. - An integer, intended for hashes or similar.
- A number sequence, prefixed by
#
, intended for indices. - A UUID.
So for instance, foo/bar/#42/5678/"CA426571"/a6a5e96c-fd52-4d21-a394-ffbb6e5def1d
is a valid path.
Path Hierarchy Functions
Path hierarchy plays an important role in a number of different functions within Rerun:
- With the Transform System the
transform
component logged to any Entity always describes the relationship between that Entity and its direct parent. - When resolving the meaning of Class ID and Keypoint ID components, Rerun uses the Annotation Context from the nearest ancestor in the hierarchy.
- When adding data to Blueprints, it is common to add a path and all of its descendants.
- When using the
log_cleared
API, it is possible to mark an entity and all of its descendants as being cleared. - In the future, it will also be possible to use path-hierarchy to set default-values for descendants. #1158