Scene Organization via USD Model Hierarchy#

Model hierarchy provides a simplified view of the full prim hierarchy for enhanced navigability.
The model hierarchy is broken down into the important points of interest, “component models” and “assembly models”, as well as their containing “groups”.
“Component models” are the leaves of the model hierarchy. They form a “component model boundary” under which no other models may be specified.
Model hierarchies are intended to be “shallow” compared to the full prim hierarchy.
Model hierarchy is both optional and forgiving, so don’t get blocked maintaining it.

What is model hierarchy?#

Consider a very large factory scene, with thousands of entities of different types - robots, architectural structures, actors, etc. Each of these may contain hundreds or thousands of descendant prims (meshes, shaders, etc). It can be helpful for users to be able to quickly navigate to “important” prims in the hierarchy. These prims of interest are often not the root prim of the stage nor the leaf meshes at the bottom of the hierarchy but rather the roots of the individual models the scene is constructed from.

The model hierarchy is identified through a single piece of prim metadata, Kind.

../../_images/model_hierarchy_unlabeled.png — Unnanotated full prim hierarchy#

../../_images/model_hierarchy_labeled.png — Prim hierarchy annotated with model Kinds#

The language of model hierarchy#

Model hierarchy simplifies the Prim hierarchy into two key Kinds: assembly models and component models.

Warning

Be mindful that the usage of “assembly” and “component” in the context of OpenUSD model hierarchy does not often map to the concepts of “assembly” and “component” used in many industrial and manufacturing contexts.

In OpenUSD, the concept of a “component model” aligns with complete, end-consumer-facing products. Products can vary in complexity and scale– buildings and pens are both products, whereas an individual screw typically is not.

Note

A “component model” is not a “component of a model”.

“Component models” are conventionally structured to be operational for simulation and rendering, with fully specified and organized geometry, materials, or physics data (if needed).

OpenUSD requires that all ancestors of “component models” are “groups”. This “group” Kind makes it easy for OpenUSD to identify during traversal whether or not a prim may have “component model” descendants.

Note

A prim with kind=component that has any non-”group” ancestors is not considered a valid model hierarchy element.

Some “groups” are important points of interest. A factory that references other architecture models, equipment models, and actor models can be tagged as an “assembly model”. While “component models” are strictly leaf elements of model hierarchies, “assembly models” can be nested (“assembly models” are “groups”). For example, an industrial park “assembly model” can reference multiple distinct factory “assembly models” that are being maintained and organized in parallel.

Note

“Assembly models” may contain their own geometry or materials outside of a “component model”, but that is an uncommon structure and can lead to confusion when collaborating with others in scene assembly / data aggregation workflows.

Model hierarchy correctness is “group” correctness#

A correct model hierarchy has two characteristics:

There are no “component model”, “assembly model”, or “group” descendants of “component models”
All ancestors of “component models”, “assembly models”, or “groups” must be a “group” (or “assembly model”)

Due to their importance, users often take special care with maintenance of “assembly” or “component” tagging. Failing to tag intermediate organizational scopes with kind=group commonly leads to an incorrect model hierarchy.

Many connectors generate either “assembly models” or “component models”. A user assembling a stage will likely create new organizational scopes to place the generated results of a connector. When model hierarchy is used, the user will need to tag the organizational scopes as “group” (or “assembly”) to preserve the model hierarchy correctness.

Model hierarchy is more than a tag#

OpenUSD scales by reading only the essential fields during composition. It may be surprising that Kind is conditionally one of those fields. Kind will be read on all root prims and direct descendants of “group” prims in the model hierarchy. Kind reads aren’t more expensive than any other field but their cost is re-incurred during any recomposition.

A “shallow” model hierarchy avoids this cost, amortizing the extra field read from the first few levels of the full prim hierarchy. The shallowness of the model hierarchy is measured by the placement of the “component model boundary”. The remainder of the prim hierarchy can be structured as deep as needed to organize each “component model”.

Due to the similarity of names, it’s not uncommon to see manufacturing and industrial tooling try to align kind=component with parts instead of products, generating “deep” model hierarchies. It’s worth being mindful of the small performance and navigability costs, but a scene should still be operational even with “deep” model hierarchies.

../../_images/model_hierarchy_full.png — Full prim hierarchy#

../../_images/model_hierarchy_simple.png — Shallow model hierarchy#

Subcomponents aren’t models#

The model hierarchy ends at the “component model boundary”. Prims beneath this boundary are no longer part of the model hierarchy. OpenUSD allows important prims beneath the “component model boundary” to still participate in Kind tagging. An example of an important descendant might be the root Xform of a door on a building. Important descendants of “component models” are tagged with kind=subcomponent. Filtering a building by its subcomponents lets users quickly locate a door intended to be opened or closed, without dealing with the clutter of all the other static meshes of the building. Many “component models” don’t have any “subcomponent” hierarchies; don’t assume they are needed.

../../_images/model_hierarchy_subcomponent.png

Model hierarchy is optional#

While model hierarchy is a core feature of OpenUSD that improves navigability of the stage, it is optional. Scenes and workflows that do not benefit from the additional organizational tooling do not have to utilize it. Scenes with incorrect model hierarchies (ie. nested components or incorrect group specification) are expected to render and simulate the same regardless of the presence or absence of a correctly specified model hierarchy.

There is a tax to correct maintenance of model hierarchy. Users assembling scenes need to be aware of where the “component model boundary” has been placed to ensure that all ancestors are properly tagged as “group” prims and that no descendants are tagged with kind=group, kind=assembly, or kind=component.

Be aware of the rules of model hierarchy and how it can enhance a scene’s navigability, but don’t get blocked by it.