esc
Start typing to search the docs
Navigate Open

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 the 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.

It is possible to log multiple archetypes on the same entity path. Each component is tagged with its archetype (e.g. Points3D:positions vs. Mesh3D:vertex_positions), so they don't overwrite each other. See the Entity Component section for more information.

For example, it's common to log a Transform3D along with some geometry it relates to (see the Transforms & Coordinate Frames for more info).

Rerun treats entity 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 usually omitted.

In the file path analogy, each entity is a folder, and a component is a file. This implies that any entity in a hierarchy can contain components.

For example (this uses the Python SDK but the same applies for all supported languages):

rr.log("image", rr.Image(img))
rr.log("image/points", rr.Points2D(points))

It is also acceptable to leave implicitly "empty" entities in your paths as well.

rr.log("camera/image", rr.Image(img))
rr.log("camera/image/detections/points", rr.Points2D(points))

Nothing needs to be explicitly logged to "camera" or "camera/image/detections" to make the above valid. In other words, the log call is akin to creating a folder with mkdir -p and then writing files (components) to it. Existing components of the same name will be overwritten.

Path parts

Each "part" of a path must be a non-empty string. Any character is allowed, but special characters need to be escaped using \. Characters that need NOT be escaped are letters, numbers, and underscore, dash, and dot (_, -, .). Any other character should be escaped, including symbols (\:, \$, …) and whitespace (\ , \n, \t, …).

You can insert an arbitrary unicode code point into an entity path using \u{262E}.

So for instance, world/3D/My\ Image.jpg/detection is a valid path (note the escaped space!).

Path hierarchy functions

Path hierarchy plays an important role in a number of different functions within Rerun:

  • With the Transform System, a Transform3D logged to an entity without explicit parent_frame/child_frame describes the relationship between that entity and its direct parent.
  • When resolving the meaning of ClassId and KeypointId 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 rr.log("entity/path", rr.Clear(recursive=True)), it marks 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).

Entity path filters

An entity path filter selects entities with a list of expressions. Rerun uses them for view contents, filter_contents() on datasets, and the content argument of the chunk processing API.

Each expression is either an inclusion, which starts with an optional +, or an exclusion, which always starts with a -.

Expressions are also allowed to end with an optional /**. The /** suffix matches the whole subtree, i.e. self and any child, recursively. For example, /world/** matches both /world and /world/car/driver. Other uses of * are not yet supported.

When combining multiple expressions, the rules are sorted by entity path, from least to most specific:

  • If there are multiple matching rules, the most specific rule wins.
  • If there are multiple rules of the same specificity, the last one wins.
  • If no rules match, the path is excluded.

Consider the following example:

+ /world/**
- /world
- /world/car/**
+ /world/car/driver
  • The last rule matching /world/car/driver is + /world/car/driver, so it is included.
  • The last rule matching /world/car/hood is - /world/car/**, so it is excluded.
  • The last rule matching /world is - /world, so it is excluded.
  • The last rule matching /world/house is + /world/**, so it is included.

Reserved paths

The path prefix __ is considered reserved for use by the Rerun SDK itself and should not be used for logging user data. This is where Rerun will log additional information such as properties (__properties) and warnings (__warnings).