Technical Breakdown of Data Structure

The data structure is organized as follows /World/dataStructure. Besides the Root DataStructure, that holds the currently active category, there are 3 types of data prims in this structure:

  • Category - Top level categorization. Many categories can exist under the data structure root. A category may also contain a category behavior that triggers when the category is clicked. Only one behavior is needed for any given category.

  • Option - A category can contain many options and each option can contain many behaviors.

  • Behavior - These prims exists under option and are tied to the graph logic.

The panel recognizes categories and option prims by their names starting with category_ and option_.

Category

Categories contains options and the selected option gets set on the category prim via a property. Setting this property will trigger a variant being set via the action graph. All relevant attribute names, as well as the path to the data structure are defined in the mapping.py file via static variables. If you want to change anything, you can do so there.

The following category properties are currently in use:

STATIC

Property Name

Description

CATEGORY_SCOPE_PREFIX

category

Prefix naming convention for category prims. Thanks to this it is possible to put other prims for whatever purpose in the structure and the UI will happily ignore them unless they have the prefix naming.

CATEGORY_LABEL_ATTR

UI_label

String attribute for the label that will be shown in the UI.

CATEGORY_ID

id

String attribute that represents the category when the active category is set on the data structure prim. Internally used by the system.

CATEGORY_CURRENT_OPTION

currentOption

String id attribute of the currently selected option from the option prims that are organized below this category.

CATEGORY_ICON

icon

Asset path to the icon that will be shown in the UI for this category.

Option

Options contain behaviors. Behaviors can be seen as a playlist of actions that gets executed when an option is selected so that you can for example, set a variant, load an environment and do other custom behaviors. Like previously mentioned, the selected option get set on the parent category. The id of the option gets set on the currentOption attribute.

The following option properties are currently in use:

STATIC

Property Name

Description

OPTION_LABEL_ATTR

UI_label

String attribute storing the label for this option to be shown in the UI.

OPTION_ID

id

String representation that is set on the currentOption attribute on the parent category when the option is selected. Internally used by the system.

OPTION_ICON

icon

Asset path to the icon that will be shown for this option.

In mapping.py, the various attributes and paths are mapped and referred to throughout the code so that it is easy to edit:

STRUCTURE_ROOT_PATH = '/World/dataStructure' # Path to the data structure in the stage
STRUCTURE_CURRENT_CATEGORY = 'currentCategory' # Current active category
CATEGORY_SCOPE_PREFIX = 'category' # Category naming prefix - only folders with this prefix are considered
CATEGORY_LABEL_ATTR = 'UI_label' # Category UI label allowing for descriptive labels
CATEGORY_ID = 'id' # Category code, can be anything you want and is the attribute that will be set on the `STRUCTURE_CURRENT_CATEGORY`
CATEGORY_CURRENT_OPTION = 'currentOption' # The current option (`OPTION_ID`) set on this category
CATEGORY_ICON = 'icon' # Icon asset path for the category icon
CATEGORY_ICON_DEFAULT = 'category_default.png' # Default icon when the user has no icon slotted.

OPTION_SCOPE_PREFIX = 'option' # Option naming prefix - only folders with this prefix are considered
OPTION_LABEL_ATTR = 'UI_label' # Option UI label allowing for descriptive labels
OPTION_ID = 'id' # Option code, can be anything you want and is the attribute that will be set on the `CATEGORY_CURRENT_OPTION`
OPTION_ICON = 'icon' # Icon asset path for the option icon
OPTION_ICON_DEFAULT = 'option_default.png' # Default icon when the user has no icon slotted.

Graphs

There are two main actionGraphs that drive the configurator behavior itself. Additionally you will find other graphs in the file to control the camera behavior, and to control the prepping of the stage. All graphs have in-line documentation explaining how they work in case you need to open them.

  • variantController.usd - One for each category.

  • categoryBehaviorController.usd - One for the entire data structure.

variantController.usd

This graph pays attention to the options chosen by the user. A copy of this graph must be made for each category of your dataStructure. The graph has logic to read through a category, collect all it’s options, then run all the necessary behaviors when those options are clicked.

When selecting the variantController the following properties are used to customize the graph

Variable

Description

categoryPath

This is the USD path to the category prim from the dataStructure. You must set this manually. If you are using the configuration utilities, this will be set for you when a new variantController is added to your stage.

setVariant Composer 2023.2+

In Composer 2023.2 a performance optimization was added to bypass USD recomposition when setting variants. This avoids any hitches from stage recomposition that comes with actually setting a variant, and instead directly writes the attributes described within the variant. Defaults to OFF.

In situations where a variant requires a stage recomposition, you would set this to true and force setting the variant on the prim. This could introduce hitches depending on how complex your asset is, or how the variants were authored on it.

Situations where a recomposition is required are variants that change prim relationships (such as material binding or reference paths) or variants that use prim defs to toggle prims on/off in the stage.

availableIDs availableOptions behaviorsToProcess optionLookup

These are all variables used internally by the graph and do not need to be changed.

categoryBehaviorController.usd

A single copy of this graph for your entire dataStructure is all that is needed. Instead of tracking the options, this graph processes the categories chosen by the user. Each category has an optional “categoryBehavior” scope folder to store behaviors that you wish to be triggered when a category is selected.

For example: Plate Style category is selected, and a behavior that triggers an alternate camera is called so the user gets a zoomed in view of the plates while browsing the plate options.

When selecting the categoryBehaviorController the following properties are used to customize the graph

Variable

Description

dataStructurePath

This is the USD path to the top level dataStructure prim. You must set this manually. If you are using the configuration utilities to build your dataStructure, this will be set for you when a new dataStructure is built in your stage.

setVariant Composer 2023.2+

In Composer 2023.2 a performance optimization was added to bypass USD recomposition when setting variants. This avoids any hitches from stage recomposition that comes with actually setting a variant, and instead directly writes the attributes described within the variant. Defaults to OFF.

In situations where a variant requires a stage recomposition, you would set this to true and force setting the variant on the prim. This could introduce hitches depending on how complex your asset is, or how the variants were authored on it.

Situations where a recomposition is required are variants that change prim relationships (such as material binding or reference paths) or variants that use prim defs to toggle prims on/off in the stage.

availableIDs availableCategories behaviorsToProcess optionLookup

These are all variables used internally by the graph and do not need to be changed.

Note

The set variant variable for variantController and categoryBehaviorController is only available in Composer 2023.2+

Hierarchy & Files

  • World - defaultPrim
    • dataStructure - databaseStructurePrims/dataStructure.usd
      • category - databaseStructurePrims/category.usd

        • categoryBehavior - Graphs/categoryBehaviorController.usd

        • option - databaseStructurePrims/option.usd

          • behavior - databaseStructurePrims/behavior.usd

    • Graphs

      • variantController - Graphs/variantController.usd

You can find all the graphs in - omniverse://localhost/NVIDIA/Assets/Configurator/2023_1/DataStructure/Graphs/
You can find data structure prims - omniverse://localhost/NVIDIA/Assets/Configurator/2023_1/DataStructure/Prims/