Bundles User Guide

Introduction

Prior to the 1.59.0 version, the following nodes: Read Prim and Read Prim into Bundle used to read UsdPrims from a UsdStage as a single primitive in a bundle. Meaning, the attributes of the primitive were saved directly in the output bundle. As a consequence, Read Prim* node instances were able to read only one primitive at the time.

Since the 1.59.0 version, the new nodes were introduced that read UsdPrims as multiple primitives in a bundle. To make this feature possible, some important changes had to be made to the bundle interface. The most prominent is that the bundle interface gained an ability to build a hierarchy of bundles. Each bundle is allowed to have children, and those child bundles are allowed to have children on their own, making bundles recursive. This feature existed for some time in omni.graph.core, but it was unavailable to access through the omni.graph.nodes until 1.59.0 release.

Backwards compatibility

To support backward compatibility, Read Prim and Read Prim into Bundle remain as they were, but have been deprecated and hidden. Old scenes should work as they were, but it’s strongly advised to update the scenes to use the new workflow.

Inspecting recursive bundles

Unfortunately, there aren’t robust tools to inspect the recursive content of a bundle yet. Bundle Inspector node has an ability to inspect number of children in a bundle, but nothing more for now. Plans to make Bundle Inspector print the hierarchy of the bundles exist. Deprecated nodes will produce a warning when instantiated in the graph.

Primitive in a Bundle

There is no existing definition of a primitive in a bundle. A bundle is considered to carry a primitive if sourcePrimPath and sourcePrimType attributes are present in it. Because of this ambiguity, the following terms are used interchangeably:

• Single Primitive in a Bundle(SPiB), Single Bundle in a Bundle(SBiB) or Primitive in a Bundle.

• Multiple Primitives in a Bundle(MPiB) and Multiple Bundles in a Bundle(MBiB)

Single Primitive in a Bundle

A Single Primitive in a Bundle is considered when attributes of the UsdPrim are saved directly in the bundle. There are no children or other levels of indirection in that bundle:

Multiple Primitives in a Bundle - the bundle hierarchy

Multiple Primitives in a Bundle is considered where there is a hierarchy of bundles. The top level bundle does not carry any primitives, but it serves a purpose of a place holder for children:

Note, the bundle interface is flexible enough to mirror the hierarchy of the UsdStage.

New nodes - Multiple Primitives in a Bundle

The new replacements for deprecated nodes are:

• Read Prims - Reads UsdPrims as multiple primitives and outputs a bundle.

• Read Prim Attributes - Reads single UsdPrim and exposes its attributes as dynamic attributes. It does not output a bundle.

Also, there are new nodes that made work with Multiple Primitives in a Bundle possible:

• Extract Prim - Extracts a child bundle as a single primitive from multiple primitives input, using primitive path(sourcePrimPath attribute).

• Get Prims - Passes to the output primitives from the input that match specific criteria.

Extract Prim - extracting a primitive

Extract Prim node takes multiple primitives as an input, then it searches for only one child with a specific sourcePrimPath attribute. It outputs the child, as a single primitive in a bundle, that was found in the input”. Extract Prim allows access to primitive’s attributes, or its children.

Get Prims - processing primitives

Get Prims allows to filter input multiple primitives. The input primitives can be filtered based on path or type. Simple wild-card expressions allow users to make expressions very flexible.

In the example below Get Prims picks only two, out of three children, and exposes them in the output. In the example Get Prims searches for primitives with a path that matches with expression /World/C*, thus only /World/Cube and /World/Cone are carried to the output. /World/Mesh is ignored.

Get Prims allows to hand over to the output only specific primitives from the input.