Overview

This module provides schemas for encoding information on USD prims for client graphical user interface tools to use in deciding how to organize and present the prims in UI layouts. This information does not guide the 3D rendering of data contained in a scene, rather it's about how to visualize the nodes in the graph that comprises a UsdStage.

The primary classes are:

UsdUINodeGraphNodeAPI - Encodes layout information for prims that participate in an interconnected (via relationships) graph, as would prims in a shading network.
UsdUIObjectHints - Provides API for reading and writing fields in UsdObject's uiHints metadata dictionary.
UsdUIPrimHints - Provides API for reading and writing fields in UsdPrim's uiHints metadata dictionary.
UsdUIPropertyHints - Provides API for reading and writing fields in UsdProperty's uiHints metadata dictionary.
UsdUIAttributeHints - Provides API for reading and writing fields in UsdAttribute's uiHints metadata dictionary.

UsdUI additionally has schemas that describe accessibility information used in assistive UI, and UI hints that provide hints on how prims and properties should be presented in a UI.

Accessibility Information

The AccessibilityAPI schema describes accessibility information on a prim that may be surfaced to a given runtime's accessibility frameworks. This information may be used by assistive features in tools, such as voice controls or screen readers.

Accessibility information is provided as a standard triplet of label, description, and priority. This is a multiple-apply schema, and so may have multiple namespaced accessibility triplets, where an instance name may reflect a given purpose for that triplet. For example, you may desire to express different information for different aspects of the prim, such as size or color.

UI Hints

UI hints are, broadly speaking, metadata fields that pertain to presentation of scene data in a UI. Most such fields in USD are held in the uiHints metadata dictionary belonging to prims and properties. UsdUI provides API for reading and writing these values in the form of "hints" objects corresponding to the relevant core object types: UsdUIObjectHints, UsdUIPrimHints, UsdUIPropertyHints, and UsdUIAttributeHints. No unique hints apply only to UsdRelationship, so there is no UsdUIRelationshipHints.

These objects provide access to the following hint fields:

displayName (UsdUIObjectHints) - The user-facing name of a prim or property
hidden (UsdUIObjectHints) - Flag indicating whether an object should be hidden from the UI
displayGroup (UsdUIPropertyHints) - The name of the display group to which a property belongs
shownIf (UsdUIPropertyHints) - An expression for determining whether to hide or show a property in the UI
valueLabels (UsdUIAttributeHints) - A dictionary associating display labels with attribute values
valueLabelsOrder (UsdUIAttributeHints) - User-facing order that valueLabels should appear in (typically in a combo box)
displayGroupsExpanded (UsdUIPrimHints) - Flag dictionary indicating which of a prim's display groups should be expanded by default
displayGroupsShownIf (UsdUIPrimHints) - Dictionary associating shownIf expressions with a prim's display groups

Other UI-relevant metadata fields that are, for various reasons, not part of the uiHints dictionary include:

userDoc and userDocBrief (provided by UsdPrimDefinition) - User-facing documentation and tooltip strings
allowedTokens (UsdAttribute) - Valid values for token-valued attributes
propertyOrder (UsdPrim) - The user-facing order a prim's properties should appear in
displayGroupOrder (UsdPrim) - The user-facing order a prim's display groups should appear in (note: this field is now considered deprecated – display group order should be determined by property order)
limits (UsdAttribute) - Minimum and maximum values for an attribute
arraySizeConstraint (UsdAttribute) - Array size and encoding information