UsdUI module

Summary: The UsdUI module provides schemas for encoding information on USD prims for client GUI tools to use in organizing/presenting prims in GUI layouts.

Classes:

`Backdrop`	Provides a'group-box'for the purpose of node graph organization.
`NodeGraphNodeAPI`	This api helps storing information about nodes in node graphs.
`SceneGraphPrimAPI`	Utility schema for display properties of a prim
`Tokens`

class pxr.UsdUI.Backdrop

Provides a’group-box’for the purpose of node graph organization.

Unlike containers, backdrops do not store the Shader nodes inside of them. Backdrops are an organizational tool that allows Shader nodes to be visually grouped together in a node-graph UI, but there is no direct relationship between a Shader node and a Backdrop.

The guideline for a node-graph UI is that a Shader node is considered part of a Backdrop when the Backdrop is the smallest Backdrop a Shader node’s bounding-box fits inside.

Backdrop objects are contained inside a NodeGraph, similar to how Shader objects are contained inside a NodeGraph.

Backdrops have no shading inputs or outputs that influence the rendered results of a NodeGraph. Therefore they can be safely ignored during import.

Like Shaders and NodeGraphs, Backdrops subscribe to the NodeGraphNodeAPI to specify position and size.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdUITokens. So to set an attribute to the value”rightHanded”, use UsdUITokens->rightHanded as the value.

Methods:

`CreateDescriptionAttr`(defaultValue, ...)	See GetDescriptionAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Define`	classmethod Define(stage, path) -> Backdrop
`Get`	classmethod Get(stage, path) -> Backdrop
`GetDescriptionAttr`()	The text label that is displayed on the backdrop in the node graph.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]

CreateDescriptionAttr(defaultValue, writeSparsely) → Attribute

See GetDescriptionAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Define()

classmethod Define(stage, path) -> Backdrop

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters

stage (Stage) –
path (Path) –

static Get()

classmethod Get(stage, path) -> Backdrop

Return a UsdUIBackdrop holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdUIBackdrop(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetDescriptionAttr() → Attribute

The text label that is displayed on the backdrop in the node graph.

This help-description explains what the nodes in a backdrop do.

Declaration

uniform token ui:description

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

Parameters: includeInherited (bool) –

class pxr.UsdUI.NodeGraphNodeAPI

This api helps storing information about nodes in node graphs.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdUITokens. So to set an attribute to the value”rightHanded”, use UsdUITokens->rightHanded as the value.

Methods:

`Apply`	classmethod Apply(prim) -> NodeGraphNodeAPI
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`CreateDisplayColorAttr`(defaultValue, ...)	See GetDisplayColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateExpansionStateAttr`(defaultValue, ...)	See GetExpansionStateAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateIconAttr`(defaultValue, writeSparsely)	See GetIconAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreatePosAttr`(defaultValue, writeSparsely)	See GetPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateSizeAttr`(defaultValue, writeSparsely)	See GetSizeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateStackingOrderAttr`(defaultValue, ...)	See GetStackingOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Get`	classmethod Get(stage, path) -> NodeGraphNodeAPI
`GetDisplayColorAttr`()	This hint defines what tint the node should have in the node graph.
`GetExpansionStateAttr`()	The current expansionState of the node in the ui.
`GetIconAttr`()	This points to an image that should be displayed on the node.
`GetPosAttr`()	Declared relative position to the parent in a node graph.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]
`GetSizeAttr`()	Optional size hint for a node in a node graph.
`GetStackingOrderAttr`()	This optional value is a useful hint when an application cares about the visibility of a node and whether each node overlaps another.

static Apply()

classmethod Apply(prim) -> NodeGraphNodeAPI

Applies this single-apply API schema to the given prim .

This information is stored by adding”NodeGraphNodeAPI”to the token- valued, listOp metadata apiSchemas on the prim.

A valid UsdUINodeGraphNodeAPI object is returned upon success. An invalid (or empty) UsdUINodeGraphNodeAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters: prim (Prim) –

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

Returns true if this single-apply API schema can be applied to the given prim .

If this schema can not be a applied to the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters

prim (Prim) –
whyNot (str) –

CreateDisplayColorAttr(defaultValue, writeSparsely) → Attribute

See GetDisplayColorAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateExpansionStateAttr(defaultValue, writeSparsely) → Attribute

See GetExpansionStateAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateIconAttr(defaultValue, writeSparsely) → Attribute

See GetIconAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreatePosAttr(defaultValue, writeSparsely) → Attribute

See GetPosAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateSizeAttr(defaultValue, writeSparsely) → Attribute

See GetSizeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateStackingOrderAttr(defaultValue, writeSparsely) → Attribute

See GetStackingOrderAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> NodeGraphNodeAPI

Return a UsdUINodeGraphNodeAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdUINodeGraphNodeAPI(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetDisplayColorAttr() → Attribute

This hint defines what tint the node should have in the node graph.

Declaration

uniform color3f ui:nodegraph:node:displayColor

C++ Type

GfVec3f

Usd Type

SdfValueTypeNames->Color3f

Variability

SdfVariabilityUniform

GetExpansionStateAttr() → Attribute

The current expansionState of the node in the ui.

‘open’= fully expanded’closed’= fully collapsed’minimized’= should take the least space possible

Declaration

uniform token ui:nodegraph:node:expansionState

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

Allowed Values

open, closed, minimized

GetIconAttr() → Attribute

This points to an image that should be displayed on the node.

It is intended to be useful for summary visual classification of nodes, rather than a thumbnail preview of the computed result of the node in some computational system.

Declaration

uniform asset ui:nodegraph:node:icon

C++ Type

SdfAssetPath

Usd Type

SdfValueTypeNames->Asset

Variability

SdfVariabilityUniform

GetPosAttr() → Attribute

Declared relative position to the parent in a node graph.

X is the horizontal position. Y is the vertical position. Higher numbers correspond to lower positions (coordinates are Qt style, not cartesian).

These positions are not explicitly meant in pixel space, but rather assume that the size of a node is approximately 1.0x1.0. Where size-x is the node width and size-y height of the node. Depending on graph UI implementation, the size of a node may vary in each direction.

Example: If a node’s width is 300 and it is position is at 1000, we store for x-position: 1000 * (1.0/300)

Declaration

uniform float2 ui:nodegraph:node:pos

C++ Type

GfVec2f

Usd Type

SdfValueTypeNames->Float2

Variability

SdfVariabilityUniform

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

Parameters: includeInherited (bool) –

GetSizeAttr() → Attribute

Optional size hint for a node in a node graph.

X is the width. Y is the height.

This value is optional, because node size is often determined based on the number of in- and outputs of a node.

Declaration

uniform float2 ui:nodegraph:node:size

C++ Type

GfVec2f

Usd Type

SdfValueTypeNames->Float2

Variability

SdfVariabilityUniform

GetStackingOrderAttr() → Attribute

This optional value is a useful hint when an application cares about the visibility of a node and whether each node overlaps another.

Nodes with lower stacking order values are meant to be drawn below higher ones. Negative values are meant as background. Positive values are meant as foreground. Undefined values should be treated as 0.

There are no set limits in these values.

Declaration

uniform int ui:nodegraph:node:stackingOrder

C++ Type

int

Usd Type

SdfValueTypeNames->Int

Variability

SdfVariabilityUniform

class pxr.UsdUI.SceneGraphPrimAPI

Utility schema for display properties of a prim

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdUITokens. So to set an attribute to the value”rightHanded”, use UsdUITokens->rightHanded as the value.

Methods:

`Apply`	classmethod Apply(prim) -> SceneGraphPrimAPI
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`CreateDisplayGroupAttr`(defaultValue, ...)	See GetDisplayGroupAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateDisplayNameAttr`(defaultValue, ...)	See GetDisplayNameAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Get`	classmethod Get(stage, path) -> SceneGraphPrimAPI
`GetDisplayGroupAttr`()	When publishing a nodegraph or a material, it can be useful to provide an optional display group, for organizational purposes and readability.
`GetDisplayNameAttr`()	When publishing a nodegraph or a material, it can be useful to provide an optional display name, for readability.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]

static Apply()

classmethod Apply(prim) -> SceneGraphPrimAPI

Applies this single-apply API schema to the given prim .

This information is stored by adding”SceneGraphPrimAPI”to the token- valued, listOp metadata apiSchemas on the prim.

A valid UsdUISceneGraphPrimAPI object is returned upon success. An invalid (or empty) UsdUISceneGraphPrimAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters: prim (Prim) –

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

Returns true if this single-apply API schema can be applied to the given prim .

If this schema can not be a applied to the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters

prim (Prim) –
whyNot (str) –

CreateDisplayGroupAttr(defaultValue, writeSparsely) → Attribute

See GetDisplayGroupAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

CreateDisplayNameAttr(defaultValue, writeSparsely) → Attribute

See GetDisplayNameAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters

defaultValue (VtValue) –
writeSparsely (bool) –

static Get()

classmethod Get(stage, path) -> SceneGraphPrimAPI

Return a UsdUISceneGraphPrimAPI holding the prim adhering to this schema at path on stage .

If no prim exists at path on stage , or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdUISceneGraphPrimAPI(stage->GetPrimAtPath(path));

Parameters

stage (Stage) –
path (Path) –

GetDisplayGroupAttr() → Attribute

When publishing a nodegraph or a material, it can be useful to provide an optional display group, for organizational purposes and readability.

This is because often the usd shading hierarchy is rather flat while we want to display it in organized groups.

Declaration

uniform token ui:displayGroup

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

GetDisplayNameAttr() → Attribute

When publishing a nodegraph or a material, it can be useful to provide an optional display name, for readability.

Declaration

uniform token ui:displayName

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[TfToken]

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

Parameters: includeInherited (bool) –

class pxr.UsdUI.Tokens

Attributes:

`closed`
`minimized`
`open`
`uiDescription`
`uiDisplayGroup`
`uiDisplayName`
`uiNodegraphNodeDisplayColor`
`uiNodegraphNodeExpansionState`
`uiNodegraphNodeIcon`
`uiNodegraphNodePos`
`uiNodegraphNodeSize`
`uiNodegraphNodeStackingOrder`

closed = 'closed'

minimized = 'minimized'

open = 'open'

uiDescription = 'ui:description'

uiDisplayGroup = 'ui:displayGroup'

uiDisplayName = 'ui:displayName'

uiNodegraphNodeDisplayColor = 'ui:nodegraph:node:displayColor'

uiNodegraphNodeExpansionState = 'ui:nodegraph:node:expansionState'

uiNodegraphNodeIcon = 'ui:nodegraph:node:icon'

uiNodegraphNodePos = 'ui:nodegraph:node:pos'

uiNodegraphNodeSize = 'ui:nodegraph:node:size'

uiNodegraphNodeStackingOrder = 'ui:nodegraph:node:stackingOrder'