usdex.core

usdex.core provides higher-level convenience functions top of lower-level OpenUSD concepts, so developers can quickly adopt OpenUSD best practices when mapping their native data sources to OpenUSD-legible data models.

Functions:

version()	Verify the expected usdex modules are being loaded at runtime.
deprecated(version, message)	Decorator used to deprecate public functions
isDiagnosticsDelegateActive()	Test whether the Delegate is currently active.
activateDiagnosticsDelegate()	Activates the Delegate to specialize TfDiagnostics handling.
deactivateDiagnosticsDelegate()	Deactivates the Delegate to restore default TfDiagnostics handling.
setDiagnosticsLevel(value)	Set the DiagnosticsLevel for the Delegate to filter TfDiagnostics by severity.
getDiagnosticsLevel()	Get the current DiagnosticsLevel for the Delegate.
setDiagnosticsOutputStream(value)	Set the DiagnosticsOutputStream for the Delegate to redirect Tf.Diagnostics to different streams.
getDiagnosticsOutputStream()	Get the current DiagnosticsOutputStream for the Delegate.
hasLayerAuthoringMetadata(layer)	Check if the Sdf.Layer has metadata indicating the provenance of the data.
setLayerAuthoringMetadata(layer, value)	Set metadata on the Sdf.Layer indicating the provenance of the data.
saveLayer(layer[, authoringMetadata, comment])	Save the given Sdf.Layer with an optional comment
exportLayer(layer, identifier, authoringMetadata)	Export the given Sdf.Layer to an identifier with an optional comment.
createStage(identifier, defaultPrimName, ...)	Create and configure a Usd.Stage so that the defining metadata is explicitly authored.
configureStage(stage, defaultPrimName, ...)	Configure a stage so that the defining metadata is explicitly authored.
saveStage(stage[, authoringMetadata, comment])	Save the given Usd.Stage with metadata applied to all dirty layers.
isEditablePrimLocation(*args, **kwargs)	Overloaded function.
getValidPrimName(name)	Produce a valid prim name from the input name
getValidPrimNames(names[, reservedNames])	Take a vector of the preferred names and return a matching vector of valid and unique names.
getValidChildName(prim, name)	Take a prim and a preferred name.
getValidChildNames(prim, names)	Take a prim and a vector of the preferred names.
getValidPropertyName(name)	Produce a valid property name using the Bootstring algorithm.
getValidPropertyNames(names[, reservedNames])	Take a vector of the preferred names and return a matching vector of valid and unique names.
getDisplayName(prim)	Return this prim's display name (metadata).
setDisplayName(prim, name)	Sets this prim's display name (metadata)
clearDisplayName(prim)	Clears this prim's display name (metadata) in the current EditTarget (only)
blockDisplayName(prim)	Block this prim's display name (metadata)
computeEffectiveDisplayName(prim)	Calculate the effective display name of this prim
defineXform(*args, **kwargs)	Overloaded function.
getLocalTransform(prim[, time])	Get the local transform of a prim at a given time.
getLocalTransformMatrix(prim[, time])	Get the local transform of a prim at a given time in the form of a 4x4 matrix.
getLocalTransformComponents(prim[, time])	Get the local transform of a prim at a given time in the form of common transform components.
setLocalTransform(*args, **kwargs)	Overloaded function.
definePointCloud(*args, **kwargs)	Overloaded function.
definePolyMesh(*args, **kwargs)	Overloaded function.
defineLinearBasisCurves(*args, **kwargs)	Overloaded function.
defineCubicBasisCurves(*args, **kwargs)	Overloaded function.
defineCamera(*args, **kwargs)	Overloaded function.
isLight(prim)	Determines if a UsdPrim has a UsdLux.LightAPI schema applied
getLightAttr(defaultAttr)	Get the "correct" light attribute for a light that could have any combination of authored old and new UsdLux schema attributes
defineDomeLight(*args, **kwargs)	Overloaded function.
defineRectLight(*args, **kwargs)	Overloaded function.
createMaterial(parent, name)	Create a UsdShade.Material as the child of the Prim parent
bindMaterial(prim, material)	Authors a direct binding to the given material on this prim.
computeEffectivePreviewSurfaceShader(material)	Get the effective surface Shader of a Material for the universal render context.
definePreviewMaterial(*args, **kwargs)	Overloaded function.
addDiffuseTextureToPreviewMaterial(material, ...)	Adds a diffuse texture to a preview material
addNormalTextureToPreviewMaterial(material, ...)	Adds a normals texture to a preview material
addOrmTextureToPreviewMaterial(material, ...)	Adds an ORM (occlusion, roughness, metallic) texture to a preview material
addRoughnessTextureToPreviewMaterial(...)	Adds a single channel roughness texture to a preview material
addMetallicTextureToPreviewMaterial(...)	Adds a single channel metallic texture to a preview material
addOpacityTextureToPreviewMaterial(material, ...)	Adds a single channel opacity texture to a preview material
addPreviewMaterialInterface(material)	Adds UsdShade.Inputs to the material prim to create an "interface" to the underlying Preview Shader network.
removeMaterialInterface(material[, bakeValues])	Removes any UsdShade.Inputs found on the material prim.
getColorSpaceToken(value)	Get the str matching a given ColorSpace
sRgbToLinear(color)	Translate an sRGB color value to linear color space
linearToSrgb(color)	Translate a linear color value to sRGB color space

Classes:

DiagnosticsLevel	Controls the diagnostics that will be emitted when the Delegate is active.
DiagnosticsOutputStream	Control the output stream to which diagnostics are logged.
ValidChildNameCache	A caching mechanism for valid and unique child prim names.
RotationOrder	Enumerates the rotation order of the 3-angle Euler rotation.
FloatPrimvarData	PrimvarData that holds Vt.FloatArray values (e.g widths or scale factors).
IntPrimvarData	PrimvarData that holds Vt.IntArray values (e.g simple switch values or booleans consumable by shaders).
Int64PrimvarData	PrimvarData that holds Vt.Int64Array values (e.g ids that might be very large).
Vec3fPrimvarData	PrimvarData that holds Vt.Vec3fArray values (e.g normals, colors, or other vectors).
Vec2fPrimvarData	PrimvarData that holds Vt.Vec2fArray values (e.g texture coordinates).
StringPrimvarData	PrimvarData that holds Vt.StringArray values (e.g human readable descriptors).
TokenPrimvarData	PrimvarData that holds Vt.TokenArray values (e.g more efficient human readable descriptors).
ColorSpace	Texture color space (encoding) types

usdex.core.version() → str

Verify the expected usdex modules are being loaded at runtime.

Returns:

A human-readable version string for the usdex modules.

usdex.core.deprecated(version: str, message: str)

Decorator used to deprecate public functions

Example:

@deprecated("0.5", "Use `baz` instead")
def foo(bar: str) -> str:
    return baz(bar)

Parameters:

• version – The major.minor version in which the function was first deprecated

• message – A user facing message about the deprecation, ideally with a suggested alternative function. Do not include the version in this message, it will be prefixed automatically.

class usdex.core.DiagnosticsLevel

Controls the diagnostics that will be emitted when the Delegate is active.

Members:

eFatal : Only Tf.Fatal are emitted.

eError : Emit Tf.Error and Tf.Fatal, but suppress Tf.Warn and Tf.Status diagnostics.

eWarning : Emit Tf.Warn, Tf.Error, and Tf.Fatal, but suppress Tf.Status diagnostics.

eStatus : All diagnostics are emitted.

Attributes:

name

property name

class usdex.core.DiagnosticsOutputStream

Control the output stream to which diagnostics are logged.

Members:

eNone : All diagnostics are suppressed.

eStdout : All diagnostics print to the stdout stream.

eStderr : All diagnostics print to the stderr stream.

Attributes:

name

property name

usdex.core.isDiagnosticsDelegateActive() → bool

Test whether the Delegate is currently active.

When active, the Delegate replaces the default TfDiagnosticMgr printing with a more customized result. See activateDiagnosticsDelegate() for more details.

Returns:

Whether the Delegate is active

usdex.core.activateDiagnosticsDelegate() → None

Activates the Delegate to specialize TfDiagnostics handling.

The Tf module from OpenUSD provides various diagnostic logging abilities, including the ability to override the default message handler (which prints to stderr) with one or more custom handlers.

This function can be used to activate a specialized TfDiagnosticMgr::Delegate provided by OpenUSD Exchange. The primary advantages of this Delegate are:

• Diagnostics can be filtered by DiagnosticsLevel.

• Diagnostics can be redirected to stdout, stderr, or muted entirely using DiagnosticsOutputStream.

• The message formatting is friendlier to end-users.

Note

Use of this Delegate is entirely optional and it is not activated by default when loading this module. To active it, client code must explicitly call activateDiagnosticsDelegate(). This is to allow clients to opt-in and to prevent double printing for clients that already have their own TfDiagnosticMgr::Delegate implementation.

usdex.core.deactivateDiagnosticsDelegate() → None

Deactivates the Delegate to restore default TfDiagnostics handling.

When deactivated, the default TfDiagnosticMgr printing is restored, unless some other Delegate is still active.

usdex.core.setDiagnosticsLevel(

value: usdex.core._usdex_core.DiagnosticsLevel,

) → None

Set the DiagnosticsLevel for the Delegate to filter TfDiagnostics by severity.

This can be called at any time, but the filtering will only take affect after calling activateDiagnosticsDelegate().

Parameters:

value – The highest severity DiagnosticsLevel that should be emitted.

usdex.core.getDiagnosticsLevel() → usdex.core._usdex_core.DiagnosticsLevel

Get the current DiagnosticsLevel for the Delegate.

This can be called at any time, but the filtering will only take affect after calling activateDiagnosticsDelegate().

Returns:

The current DiagnosticsLevel for the Delegate.

usdex.core.setDiagnosticsOutputStream(

value: usdex.core._usdex_core.DiagnosticsOutputStream,

) → None

Set the DiagnosticsOutputStream for the Delegate to redirect Tf.Diagnostics to different streams.

This can be called at any time, but will only take affect after calling activateDiagnosticsDelegate().

Parameters:

value – The stream to which all diagnostics should be emitted.

usdex.core.getDiagnosticsOutputStream() → usdex.core._usdex_core.DiagnosticsOutputStream

Get the current DiagnosticsOutputStream for the Delegate.

This can be called at any time, but will only take affect after calling activateDiagnosticsDelegate().

Returns:

The current DiagnosticsOutputStream for the Delegate.

usdex.core.hasLayerAuthoringMetadata(layer: pxr.Sdf.Layer) → bool

Check if the Sdf.Layer has metadata indicating the provenance of the data.

Note

This metadata is strictly informational, it is not advisable to drive runtime behavior from this metadata. In the future, the “creator” key may change, or a more formal specification for data provenance may emerge.

Checks the CustomLayerData for a “creator” key.

Parameters:

layer – The layer to check

Returns:

A bool indicating if the metadata exists

usdex.core.setLayerAuthoringMetadata(layer: pxr.Sdf.Layer, value: str) → None

Set metadata on the Sdf.Layer indicating the provenance of the data.

It is desirable to capture data provenance information into the metadata of SdfLayers, in order to keep track of what tools & versions were used throughout content creation pipelines, and to capture notes from the content author. While OpenUSD does not currently have a formal specification for this authoring metadata, some conventions have emerged throughout the OpenUSD Ecosystem.

The most common convention for tool tracking is to include a “creator” string in the Sdf.Layer.customLayerData. Similarly, notes from the content author should be captured via Sdf.Layer.SetComment. While these are trivial using Sdf.Layer public methods, they are also easy to forget, and difficult to discover.

This function assists authoring applications in settings authoring metadata, so that each application can produce consistant provenance information. The metadata should only add information which can be used to track the data back to its origin. It should not be used to store sensitive information about the content, nor about the end user (i.e. do not use it to store Personal Identifier Information).

Example

layer = Sdf.Layer.CreateAnonymous()
authoring_metadata = "My Content Editor® 2024 SP 2, USD Exporter Plugin v1.1.23.11"
usdex.core.exportLayer(layer, file_name, authoring_metadata, user_comment);

Note

This metadata is strictly informational, it is not advisable to drive runtime behavior from this metadata. In the future, the “creator” key may change, or a more formal specification for data provenance may emerge.

Parameters:

• layer – The layer to modify

• value – The provenance information for this layer

usdex.core.saveLayer(

layer: pxr.Sdf.Layer,

authoringMetadata: str | None = None,

comment: str | None = None,

) → bool

Save the given Sdf.Layer with an optional comment

Note

This does not impact sublayers or any stages that this layer may be contributing to. See setLayerAuthoringMetadata for details. This is to preserve authoring metadata on referenced layers that came from other applications.

Parameters:

• layer – The stage to be saved.

• authoringMetadata – The provenance information from the host application. See setLayerAuthoringMetadata for details.

• comment –

  The comment will be authored in the layer as the Sdf.Layer comment.

  Returns:

  A bool indicating if the save was successful.

usdex.core.exportLayer(

layer: pxr.Sdf.Layer,

identifier: str,

authoringMetadata: str,

comment: str | None = None,

fileFormatArgs: Dict[str, str] = {},

) → bool

Export the given Sdf.Layer to an identifier with an optional comment.

Note

This does not impact sublayers or any stages that this layer may be contributing to. See setLayerAuthoringMetadata for details. This is to preserve authoring metadata on referenced layers that came from other applications.

Parameters:

• layer – The layer to be exported.

• identifier – The identifier to be used for the new layer.

• authoringMetadata – The provenance information from the host application. See setLayerAuthoringMetadata for details. If the “creator” key already exists, it will not be overwritten & this data will be ignored.

• comment – The comment will be authored in the layer as the Sdf.Layer comment.

• fileFormatArgs – Additional file format-specific arguments to be supplied during layer export.

Returns:

A bool indicating if the export was successful.

usdex.core.createStage(

identifier: str,

defaultPrimName: str,

upAxis: str,

linearUnits: float,

authoringMetadata: str,

fileFormatArgs: dict | None = None,

) → Stage | None

Create and configure a Usd.Stage so that the defining metadata is explicitly authored.

See configureStage for more details.

Note

The extension of the identifier must be associated with a file format that supports editing.

Parameters:

• identifier – The identifier to be used for the root layer of this stage.

• defaultPrimName – Name of the root prim root prim.

• upAxis – The up axis for all the geometry contained in the stage.

• linearUnits – The meters per unit for all linear measurements in the stage.

• authoringMetadata – The provenance information from the host application. See setLayerAuthoringMetadata for details.

• fileFormatArgs – Additional file format-specific arguments to be supplied during Stage creation.

Returns:

The newly created stage or None

usdex.core.configureStage(

stage: pxr.Usd.Stage,

defaultPrimName: str,

upAxis: str,

linearUnits: float,

authoringMetadata: str | None = None,

) → bool

Configure a stage so that the defining metadata is explicitly authored.

The default prim will be used as the target of a Reference or Payload to this layer when no explicit prim path is specified. A root prim with the given defaultPrimName will be defined on the stage. If a new prim is defined then the type name will be set to Scope.

The stage metrics of Up Axis and Linear Units will be authored.

The root layer will be annotated with authoring metadata, unless previously annotated. This is to preserve authoring metadata on referenced layers that came from other applications. See setLayerAuthoringMetadata for more details.

Parameters:

• stage – The stage to be configured.

• defaultPrimName – Name of the default root prim.

• upAxis – The up axis for all the geometry contained in the stage.

• linearUnits – The meters per unit for all linear measurements in the stage.

• authoringMetadata – The provenance information from the host application. See setLayerAuthoringMetadata for details.

Returns:

A bool indicating if the metadata was successfully authored.

usdex.core.saveStage(

stage: pxr.Usd.Stage,

authoringMetadata: str | None = None,

comment: str | None = None,

) → None

Save the given Usd.Stage with metadata applied to all dirty layers.

Save all dirty layers and sublayers contributing to this stage.

All dirty layers will be annotated with authoring metadata, unless previously annotated. This is to preserve authoring metadata on referenced layers that came from other applications.

The comment will be authored in all layers as the SdfLayer comment.

Parameters:

• stage – The stage to be saved.

• authoringMetadata – The provenance information from the host application. See setLayerAuthoringMetadata for details. If the “creator” key already exists on a given layer, it will not be overwritten & this data will be ignored.

• comment – The comment will be authored in all dirty layers as the Sdf.Layer comment.

usdex.core.isEditablePrimLocation(*args, **kwargs)

Overloaded function.

1. isEditablePrimLocation(stage: pxr.Usd.Stage, path: pxr.Sdf.Path) -> tuple

   Validate that prim opinions could be authored at this path on the stage

   This validates that the stage and path are valid, and that the path is absolute. If a prim already exists at the given path it must not be an instance proxy.

   If the location is invalid and reason is non-null, an error message describing the validation error will be set.

   Parameters:

   • stage - The stage to consider.

   • path - The absolute to consider.

   Returns:

   Tuple[bool, str] with a bool indicating if the location is valid, and the string is a non-empty reason if the location is invalid.

2. isEditablePrimLocation(prim: pxr.Usd.Prim, name: str) -> tuple

   Validate that prim opinions could be authored for a child prim with the given name

   This validates that the prim is valid, and that the name is a valid identifier. If a prim already exists at the given path it must not be an instance proxy.

   If the location is invalid and reason is non-null, an error message describing the validation error will be set.

   Parameters:

   • parent - The UsdPrim which would be the parent of the proposed location.

   • name - The name which would be used for the UsdPrim at the proposed location.

   Returns:

   Tuple[bool, str] with a bool indicating if the location is valid, and the string is a non-empty reason if the location is invalid.

usdex.core.getValidPrimName(name: str) → str

Produce a valid prim name from the input name

Parameters:

name – The input name

Returns:

A string that is considered valid for use as a prim name.

usdex.core.getValidPrimNames(

names: List[str],

reservedNames: list(str) = [],

)

Take a vector of the preferred names and return a matching vector of valid and unique names.

Parameters:

• names – A vector of preferred prim names.

• reservedNames – A vector of reserved prim names. Names in the vector will not be included in the returns.

Returns:

A vector of valid and unique names.

usdex.core.getValidChildName(prim: pxr.Usd.Prim, name: str) → str

Take a prim and a preferred name. Return a valid and unique name as the child name of the given prim.

Parameters:

• prim – The USD prim where the given prim name should live under.

• names – A preferred prim name.

Returns:

A valid and unique name.

usdex.core.getValidChildNames(prim: pxr.Usd.Prim, names: List[str])

Take a prim and a vector of the preferred names. Return a matching vector of valid and unique names as the child names of the given prim.

Parameters:

• prim – The USD prim where the given prim names should live under.

• names – A vector of preferred prim names.

Returns:

A vector of valid and unique names.

class usdex.core.ValidChildNameCache

A caching mechanism for valid and unique child prim names.

For best performance, this object should be reused for multiple name requests.

It is not valid to request child names from prims from multiple stages as only the prim path is used as the cache key.

Warning

This class does not automatically invalidate cached values based on changes to the stage from which values were cached. Additionally, a separate instance of this class should be used per-thread, calling methods from multiple threads is not safe.

Methods:

clear(self, clear)	Clear the name cache for a Prim.
getValidChildName(self, prim, name)	Take a prim and a preferred name.
getValidChildNames(self, prim, names)	Take a prim and a vector of the preferred names.
update(self, prim)	Update the name cache for a Prim to include all existing children.

clear(

self: usdex.core._usdex_core.ValidChildNameCache,

clear: pxr.Usd.Prim,

) → None

Clear the name cache for a Prim.

Parameters:

prim – The prim that child names should be cleared for.

getValidChildName(

self: usdex.core._usdex_core.ValidChildNameCache,

prim: pxr.Usd.Prim,

name: str,

) → str

Take a prim and a preferred name. Return a valid and unique name for use as the child name of the given prim.

Parameters:

• prim – The prim that the child name should be valid for.

• names – Preferred prim name.

Returns:

Valid and unique name.

getValidChildNames(

self: usdex.core._usdex_core.ValidChildNameCache,

prim: pxr.Usd.Prim,

names: List[str],

)

Take a prim and a vector of the preferred names. Return a matching vector of valid and unique names as the child names of the given prim.

Parameters:

• prim – The USD prim where the given prim names should live under.

• names – A vector of preferred prim names.

Returns:

A vector of valid and unique names.

update(

self: usdex.core._usdex_core.ValidChildNameCache,

prim: pxr.Usd.Prim,

) → None

Update the name cache for a Prim to include all existing children.

This does not clear the cache, so any names that have been previously returned will still be reserved.

Parameters:

prim – The prim that child names should be updated for.

usdex.core.getValidPropertyName(name: str) → str

Produce a valid property name using the Bootstring algorithm.

Parameters:

name – The input name

Returns:

A string that is considered valid for use as a property name.

usdex.core.getValidPropertyNames(

names: List[str],

reservedNames: list(str) = [],

)

Take a vector of the preferred names and return a matching vector of valid and unique names.

Parameters:

• names – A vector of preferred property names.

• reservedNames – A vector of reserved prim names. Names in the vector will not be included in the return.

Returns:

A vector of valid and unique names.

usdex.core.getDisplayName(prim: pxr.Usd.Prim) → str

Return this prim’s display name (metadata).

Parameters:

prim – The prim to get the display name from

Returns:

Authored value, or an empty string if no display name has been set.

usdex.core.setDisplayName(prim: pxr.Usd.Prim, name: str) → bool

Sets this prim’s display name (metadata)

DisplayName is meant to be a descriptive label, not necessarily an alternate identifier; therefore there is no restriction on which characters can appear in it

Parameters:

• prim – The prim to set the display name for

• name – The value to set

Returns:

True on success, otherwise false

usdex.core.clearDisplayName(prim: pxr.Usd.Prim) → bool

Clears this prim’s display name (metadata) in the current EditTarget (only)

Parameters:

prim – The prim to clear the display name for

Returns:

True on success, otherwise false

usdex.core.blockDisplayName(prim: pxr.Usd.Prim) → bool

Block this prim’s display name (metadata)

The fallback value will be explicitly authored to cause the value to resolve as if there were no authored value opinions in weaker layers

Parameters:

prim – The prim to block the display name for

Returns:

True on success, otherwise false

usdex.core.computeEffectiveDisplayName(prim: pxr.Usd.Prim) → str

Calculate the effective display name of this prim

If the display name is un-authored or empty then the prim’s name is returned

Parameters:

prim – The prim to compute the display name for

Returns:

The effective display name

usdex.core.defineXform(*args, **kwargs)

Overloaded function.

1. defineXform(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, transform: Optional[pxr.Gf.Transform] = None) -> pxr.UsdGeom.Xform

   Defines an xform on the stage.

   Parameters:

   • stage - The stage on which to define the xform

   • path - The absolute prim path at which to define the xform

   • transform - Optional local transform to set

   Returns:

   UsdGeom.Xform schema wrapping the defined Usd.Prim. Returns an invalid schema on error.

2. defineXform(parent: pxr.Usd.Prim, name: str, transform: Optional[pxr.Gf.Transform] = None) -> pxr.UsdGeom.Xform

   Defines an xform on the stage.

   Parameters:

   • parent - Prim below which to define the xform

   • name - Name of the xform

   • transform - Optional local transform to set

   Returns:

   UsdGeom.Xform schema wrapping the defined Usd.Prim. Returns an invalid schema on error.

class usdex.core.RotationOrder

Enumerates the rotation order of the 3-angle Euler rotation.

Members:

eXyz

eXzy

eYxz

eYzx

eZxy

eZyx

Attributes:

name

property name

usdex.core.getLocalTransform(

prim: pxr.Usd.Prim,

time: pxr.Usd.TimeCode = nan,

) → pxr.Gf.Transform

Get the local transform of a prim at a given time.

Parameters:

• prim – The prim to get local transform from.

• time – Time at which to query the value.

Returns:

Transform value as a transform.

usdex.core.getLocalTransformMatrix(

prim: pxr.Usd.Prim,

time: pxr.Usd.TimeCode = nan,

) → pxr.Gf.Matrix4d

Get the local transform of a prim at a given time in the form of a 4x4 matrix.

Parameters:

• prim – The prim to get local transform from.

• time – Time at which to query the value.

Returns:

Transform value as a 4x4 matrix.

usdex.core.getLocalTransformComponents(

prim: pxr.Usd.Prim,

time: pxr.Usd.TimeCode = nan,

) → tuple

Get the local transform of a prim at a given time in the form of common transform components.

Parameters:

• prim – The prim to get local transform from.

• time – Time at which to query the value.

Returns:

Transform value as a tuple of translation, pivot, rotation, rotation order, scale.

usdex.core.setLocalTransform(*args, **kwargs)

Overloaded function.

1. setLocalTransform(prim: pxr.Usd.Prim, transform: pxr.Gf.Transform, time: pxr.Usd.TimeCode = nan) -> bool

   Set the local transform of a prim.

   Parameters:

   • prim - The prim to set local transform on.

   • transform - The transform value to set.

   • time - Time at which to write the value.

   Returns:

   A bool indicating if the local transform was set.

2. setLocalTransform(prim: pxr.Usd.Prim, matrix: pxr.Gf.Matrix4d, time: pxr.Usd.TimeCode = nan) -> bool

   Set the local transform of a prim from a 4x4 matrix.

   Parameters:

   • prim - The prim to set local transform on.

   • matrix - The matrix value to set.

   • time - Time at which to write the value.

   Returns:

   A bool indicating if the local transform was set.

3. setLocalTransform(prim: pxr.Usd.Prim, translation: pxr.Gf.Vec3d, pivot: pxr.Gf.Vec3d, rotation: pxr.Gf.Vec3f, rotationOrder: usdex.core._usdex_core.RotationOrder, scale: pxr.Gf.Vec3f, time: pxr.Usd.TimeCode = nan) -> bool

   Set the local transform of a prim from common transform components.

   Parameters:

   • prim - The prim to set local transform on.

   • translation - The translation value to set.

   • pivot - The pivot position value to set.

   • rotation - The rotation value to set in degrees.

   • rotationOrder - The rotation order of the rotation value.

   • scale - The scale value to set.

   • time - Time at which to write the value.

   Returns:

   A bool indicating if the local transform was set.

usdex.core.definePointCloud(*args, **kwargs)

Overloaded function.

1. definePointCloud(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, points: pxr.Vt.Vec3fArray, ids: Optional[pxr.Vt.Int64Array] = None, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.Points

   Defines a UsdGeom.Points prim on the stage.

   Attribute values will be validated and in the case of invalid data the Points will not be defined. An invalid UsdGeom.Points object will be returned in this case.

   Values will be authored for all attributes required to completely describe the Points, even if weaker matching opinions already exist.

   • Point Count

   • Points

   • Extent

   The “extent” of the Points will be computed and authored based on the points and widths provided.

   The following common primvars can optionally be authored at the same time using a PrimvarData to specify interpolation, data, and optionally indices or elementSize.

   • Ids

   • Widths

   • Normals

   • Display Color

   • Display Opacity

   For both widths and normals, if they are provided, they are authored as primvars:widths and primvars:normals, so that indexing is possible and to ensure that the value takes precedence in cases where both the non-primvar and primvar attributes are authored.

   Parameters:

   • stage The stage on which to define the points.

   • path The absolute prim path at which to define the points.

   • points Vertex/CV positions for the points described in local space.

   • ids Values for the id specification for the points.

   • widths Values for the width specification for the points.

   • normals Values for the normals primvar for the points. Only Vertex normals are considered valid.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.Points schema wrapping the defined Usd.Prim

2. definePointCloud(prim: pxr.Usd.Prim, name: str, points: pxr.Vt.Vec3fArray, ids: Optional[pxr.Vt.Int64Array] = None, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.Points

   Defines a UsdGeom.Points prim on the stage.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • prim The stage on which to define the points.

   • name The absolute prim path at which to define the points.

   • points Vertex/CV positions for the points described in local space.

   • ids Values for the id specification for the points.

   • widths Values for the width specification for the points.

   • normals Values for the normals primvar for the points. Only Vertex normals are considered valid.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.Points schema wrapping the defined Usd.Prim

usdex.core.definePolyMesh(*args, **kwargs)

Overloaded function.

1. definePolyMesh(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, faceVertexCounts: pxr.Vt.IntArray, faceVertexIndices: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, uvs: Optional[usdex.core._usdex_core.Vec2fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.Mesh

   Defines a basic polygon mesh on the stage.

   All interrelated attribute values will be authored, even if weaker matching opinions already exist.

   The following common primvars can optionally be authored at the same time.

   • Normals

   • Primary UV Set

   • Display Color

   • Display Opacity

   Parameters:

   • stage - The stage on which to define the mesh

   • path - The absolute prim path at which to define the mesh

   • faceVertexCounts - The number of vertices in each face of the mesh

   • faceVertexIndices - Indices of the positions from the points to use for each face vertex

   • points - Vertex positions for the mesh described points in local space

   • normals - Values to be authored for the normals primvar

   • uvs - Values to be authored for the uv primvar

   • displayColor - Value to be authored for the display color primvar

   • displayOpacity - Value to be authored for the display opacity primvar

   Returns:

   UsdGeom.Mesh schema wrapping the defined Usd.Prim.

2. definePolyMesh(parent: pxr.Usd.Prim, name: str, faceVertexCounts: pxr.Vt.IntArray, faceVertexIndices: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, uvs: Optional[usdex.core._usdex_core.Vec2fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.Mesh

   Defines a basic polygon mesh on the stage.

   All interrelated attribute values will be authored, even if weaker matching opinions already exist.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • parent - Prim below which to define the mesh

   • name - Name of the mesh

   • faceVertexCounts - The number of vertices in each face of the mesh

   • faceVertexIndices - Indices of the positions from the points to use for each face vertex

   • points - Vertex positions for the mesh described points in local space

   • normals - Values to be authored for the normals primvar

   • uvs - Values to be authored for the uv primvar

   • displayColor - Value to be authored for the display color primvar

   • displayOpacity - Value to be authored for the display opacity primvar

   Returns:

   UsdGeom.Mesh schema wrapping the defined Usd.Prim.

usdex.core.defineLinearBasisCurves(*args, **kwargs)

Overloaded function.

1. defineLinearBasisCurves(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, curveVertexCounts: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, wrap: str = ‘nonperiodic’, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.BasisCurves

   Defines a batched Linear UsdGeom.BasisCurves prim on the stage.

   Attribute values will be validated and in the case of invalid data the Curves will not be defined. An invalid UsdGeom.BasisCurves object will be returned in this case.

   Values will be authored for all attributes required to completely describe the Curves, even if weaker matching opinions already exist.

   • Curve Vertex Counts

   • Points

   • Type

   • Wrap

   • Extent

   The “extent” of the Curves will be computed and authored based on the points and widths provided.

   The following common primvars can optionally be authored at the same time using a PrimvarData to specify interpolation, data, and optionally indices or elementSize.

   • Widths

   • Normals

   • Display Color

   • Display Opacity

   For both widths and normals, if they are provided, they are authored as primvars:widths and primvars:normals, so that indexing is possible and to ensure that the value takes precedence in cases where both the non-primvar and primvar attributes are authored.

   Parameters:

   • stage The stage on which to define the curves.

   • path The absolute prim path at which to define the curves.

   • curveVertexCounts The number of vertices in each independent curve. The length of this array determines the number of curves.

   • points Vertex/CV positions for the curves described in local space.

   • wrap Determines how the start and end points of the curve behave. Accepted values for linear curves are

     UsdGeom.Tokens.nonperiodic and UsdGeom.Tokens.periodic.

   • widths Values for the width specification for the curves.

   • normals Values for the normals primvar for the curves. If authored, the curves are considered oriented ribbons rather than tubes.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.BasisCurves schema wrapping the defined Usd.Prim

2. defineLinearBasisCurves(prim: pxr.Usd.Prim, name: str, curveVertexCounts: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, wrap: str = ‘nonperiodic’, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.BasisCurves

   Defines a batched Linear UsdGeom.BasisCurves prim on the stage.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • prim The stage on which to define the curves.

   • name The absolute prim path at which to define the curves.

   • curveVertexCounts The number of vertices in each independent curve. The length of this array determines the number of curves.

   • points Vertex/CV positions for the curves described in local space.

   • wrap Determines how the start and end points of the curve behave. Accepted values for linear curves are

     UsdGeom.Tokens.nonperiodic and UsdGeom.Tokens.periodic.

   • widths Values for the width specification for the curves.

   • normals Values for the normals primvar for the curves. If authored, the curves are considered oriented ribbons rather than tubes.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.BasisCurves schema wrapping the defined Usd.Prim

usdex.core.defineCubicBasisCurves(*args, **kwargs)

Overloaded function.

1. defineCubicBasisCurves(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, curveVertexCounts: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, basis: str = ‘bezier’, wrap: str = ‘nonperiodic’, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.BasisCurves

   Defines a batched Cubic UsdGeom.BasisCurves prim on the stage.

   Attribute values will be validated and in the case of invalid data the Curves will not be defined. An invalid UsdGeom.BasisCurves object will be returned in this case.

   Values will be authored for all attributes required to completely describe the Curves, even if weaker matching opinions already exist.

   • Curve Vertex Counts

   • Points

   • Type

   • Basis

   • Wrap

   • Extent

   The “extent” of the Curves will be computed and authored based on the points and widths provided.

   The following common primvars can optionally be authored at the same time using a PrimvarData to specify interpolation, data, and optionally indices or elementSize.

   • Widths

   • Normals

   • Display Color

   • Display Opacity

   For both widths and normals, if they are provided, they are authored as primvars:widths and primvars:normals, so that indexing is possible and to ensure that the value takes precedence in cases where both the non-primvar and primvar attributes are authored.

   Parameters:

   • stage The stage on which to define the curves.

   • path The absolute prim path at which to define the curves.

   • curveVertexCounts The number of vertices in each independent curve. The length of this array determines the number of curves.

   • points Vertex/CV positions for the curves described in local space.

   • basis The basis specifies the vstep and matrix used for cubic interpolation. Accepted values for cubic curves are

     UsdGeom.Tokens.bezier, UsdGeom.Tokens.bspline, or UsdGeom.Tokens.catmullRom.

   • wrap Determines how the start and end points of the curve behave. Accepted values are UsdGeom.Tokens.nonperiodic,

     UsdGeom.Tokens.periodic, and UsdGeom.Tokens.pinned (bspline and catmullRom only).

   • widths Values for the width specification for the curves.

   • normals Values for the normals primvar for the curves. If authored, the curves are considered oriented ribbons rather than tubes.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.BasisCurves schema wrapping the defined Usd.Prim

2. defineCubicBasisCurves(prim: pxr.Usd.Prim, name: str, curveVertexCounts: pxr.Vt.IntArray, points: pxr.Vt.Vec3fArray, basis: str = ‘bezier’, wrap: str = ‘nonperiodic’, widths: Optional[usdex.core._usdex_core.FloatPrimvarData] = None, normals: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayColor: Optional[usdex.core._usdex_core.Vec3fPrimvarData] = None, displayOpacity: Optional[usdex.core._usdex_core.FloatPrimvarData] = None) -> pxr.UsdGeom.BasisCurves

   Defines a batched Cubic UsdGeom.BasisCurves prim on the stage.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • prim The stage on which to define the curves.

   • name The absolute prim path at which to define the curves.

   • curveVertexCounts The number of vertices in each independent curve. The length of this array determines the number of curves.

   • points Vertex/CV positions for the curves described in local space.

   • basis The basis specifies the vstep and matrix used for cubic interpolation. Accepted values for cubic curves are

     UsdGeom.Tokens.bezier, UsdGeom.Tokens.bspline, or UsdGeom.Tokens.catmullRom.

   • wrap Determines how the start and end points of the curve behave. Accepted values are UsdGeom.Tokens.nonperiodic,

     UsdGeom.Tokens.periodic, and UsdGeom.Tokens.pinned (bspline and catmullRom only).

   • widths Values for the width specification for the curves.

   • normals Values for the normals primvar for the curves. If authored, the curves are considered oriented ribbons rather than tubes.

   • displayColor Values to be authored for the display color primvar.

   • displayOpacity Values to be authored for the display opacity primvar.

   Returns

   UsdGeom.BasisCurves schema wrapping the defined Usd.Prim

usdex.core.defineCamera(*args, **kwargs)

Overloaded function.

1. defineCamera(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, cameraData: pxr.Gf.Camera) -> pxr.UsdGeom.Camera

   Defines a basic 3d camera on the stage.

   Note that Gf.Camera is a simplified form of 3d camera data that does not account for time-sampled data, shutter window, stereo role, or exposure. If you need to author those properties, do so after defining the UsdGeom.Camera.

   An invalid UsdGeomCamera will be returned if camera attributes could not be authored successfully.

   Parameters:

   • stage - The stage on which to define the camera

   • path - The absolute prim path at which to define the camera

   • cameraData - The camera data to set, including the world space transform matrix

   Returns:

   A UsdGeom.Camera schema wrapping the defined Usd.Prim.

2. defineCamera(parent: pxr.Usd.Prim, name: str, cameraData: pxr.Gf.Camera) -> pxr.UsdGeom.Camera

   Defines a basic 3d camera on the stage.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • parent - Prim below which to define the camera

   • name - Name of the camera

   • cameraData - The camera data to set, including the world space transform matrix

   Returns:

   A UsdGeom.Camera schema wrapping the defined Usd.Prim.

class usdex.core.FloatPrimvarData

PrimvarData that holds Vt.FloatArray values (e.g widths or scale factors).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.FloatPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.FloatPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.FloatPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.FloatPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.FloatPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.FloatPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.FloatPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.FloatPrimvarData,

other: usdex.core._usdex_core.FloatPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.FloatPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.FloatPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.FloatPrimvarData,

) → pxr.Vt.FloatArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.IntPrimvarData

PrimvarData that holds Vt.IntArray values (e.g simple switch values or booleans consumable by shaders).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.IntPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.IntPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.IntPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.IntPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.IntPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.IntPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.IntPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.IntPrimvarData,

other: usdex.core._usdex_core.IntPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.IntPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.IntPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.IntPrimvarData,

) → pxr.Vt.IntArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.Int64PrimvarData

PrimvarData that holds Vt.Int64Array values (e.g ids that might be very large).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.Int64PrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.Int64PrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.Int64PrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.Int64PrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.Int64PrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.Int64PrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.Int64PrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.Int64PrimvarData,

other: usdex.core._usdex_core.Int64PrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.Int64PrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.Int64PrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.Int64PrimvarData,

) → pxr.Vt.Int64Array

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.Vec3fPrimvarData

PrimvarData that holds Vt.Vec3fArray values (e.g normals, colors, or other vectors).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.Vec3fPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.Vec3fPrimvarData,

other: usdex.core._usdex_core.Vec3fPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.Vec3fPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.Vec3fPrimvarData,

) → pxr.Vt.Vec3fArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.Vec2fPrimvarData

PrimvarData that holds Vt.Vec2fArray values (e.g texture coordinates).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.Vec2fPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.Vec2fPrimvarData,

other: usdex.core._usdex_core.Vec2fPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.Vec2fPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.Vec2fPrimvarData,

) → pxr.Vt.Vec2fArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.StringPrimvarData

PrimvarData that holds Vt.StringArray values (e.g human readable descriptors).

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.StringPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.StringPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.StringPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.StringPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.StringPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.StringPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.StringPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.StringPrimvarData,

other: usdex.core._usdex_core.StringPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.StringPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.StringPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.StringPrimvarData,

) → pxr.Vt.StringArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

class usdex.core.TokenPrimvarData

PrimvarData that holds Vt.TokenArray values (e.g more efficient human readable descriptors).

This is a more efficient format than raw strings if you have many repeated values across different prims.

Note

TfToken lifetime lasts the entire process. Too many tokens in memory may consume resources somewhat unexpectedly.

This is a read-only class to manage all UsdGeom.Primvar data as a single object without risk of detaching (copying) arrays.

UsdGeom.Primvars are often used when authoring UsdGeom.PointBased prims (e.g meshes, curves, and point clouds) to describe surface varying properties that can affect how a prim is rendered, or to drive a surface deformation.

However, UsdGeom.Primvar data can be quite intricate to use, especially with respect to indexed vs non-indexed primvars, element size, the complexities of Vt.Array detach (copy-on-write) semantics, and the ambiguity of “native” attributes vs primvar attributes (e.g. mesh normals).

This class aims to provide simpler entry points to avoid common mistakes with respect to UsdGeom.Primvar data handling.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Methods:

effectiveSize(self)	The effective size of the data, having accounted for values, indices, and element size.
elementSize(self)	The element size.
getPrimvarData(primvar[, time])	Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.
hasIndices(self)	Whether this is indexed or non-indexed PrimvarData
index(self)	Update the values and indices of this PrimvarData object to avoid duplicate values.
indices(self)	Access to the indices array.
interpolation(self)	The geometric interpolation.
isIdentical(self, other)	Check that all data between two PrimvarData objects is identical.
isValid(self)	Whether the data is valid or invalid.
setPrimvar(self, primvar[, time])	Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.
values(self)	Access to the values array.

effectiveSize(

self: usdex.core._usdex_core.TokenPrimvarData,

) → int

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

elementSize(

self: usdex.core._usdex_core.TokenPrimvarData,

) → int

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeom.Primvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See UsdGeom.Primvar.GetElementSize() for more details.

Returns:

The primvar element size.

static getPrimvarData(

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → usdex.core._usdex_core.TokenPrimvarData

Construct a PrimvarData from a UsdGeom.Primvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.

hasIndices(

self: usdex.core._usdex_core.TokenPrimvarData,

) → bool

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

index(

self: usdex.core._usdex_core.TokenPrimvarData,

) → bool

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

indices(

self: usdex.core._usdex_core.TokenPrimvarData,

) → pxr.Vt.IntArray

Access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData.isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices

interpolation(

self: usdex.core._usdex_core.TokenPrimvarData,

) → str

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData.isValid() or UsdGeom.Primvar.IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

isIdentical(

self: usdex.core._usdex_core.TokenPrimvarData,

other: usdex.core._usdex_core.TokenPrimvarData,

) → bool

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the Vt.Array values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

isValid(

self: usdex.core._usdex_core.TokenPrimvarData,

) → bool

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeom.Prim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeom.PointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeom.Primvar.IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a Vt.FloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

setPrimvar(

self: usdex.core._usdex_core.TokenPrimvarData,

primvar: pxr.UsdGeom.Primvar,

time: pxr.Usd.TimeCode = nan,

) → bool

Set data on an existing UsdGeom.Primvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeom.Primvar to another, use data: PrimvarData = PrimvarData.get(primvar: UsdGeom.Primvar) to gather the data, then use setPrimvar(primvar: UsdGeom.Primvar) to author it.

Parameters:

• primvar – The previously authored UsdGeom.Primvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeom.Primvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

values(

self: usdex.core._usdex_core.TokenPrimvarData,

) → pxr.Vt.TokenArray

Access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

usdex.core.isLight(prim: pxr.Usd.Prim) → bool

Determines if a UsdPrim has a UsdLux.LightAPI schema applied

Parameters:

prim – The prim to check for an applied UsdLux.LightAPI schema

Returns:

True if the prim has a UsdLux.LightAPI schema applied

usdex.core.getLightAttr(defaultAttr: pxr.Usd.Attribute) → pxr.Usd.Attribute

Get the “correct” light attribute for a light that could have any combination of authored old and new UsdLux schema attributes

The new attribute names have “inputs:” prepended to the names to make them connectable.

• Light has only “intensity” authored: return “intensity” attribute

• Light has only “inputs:intensity” authored: return “inputs:intensity” attribute

• Light has both “inputs:intensity” and “intensity” authored: return “inputs:intensity”

Parameters:

defaultAttr – The attribute to read from the light schema: eg. UsdLux.RectLight.GetHeightAttr()

Returns:

The attribute from which the light value should be read

usdex.core.defineDomeLight(*args, **kwargs)

Overloaded function.

1. defineDomeLight(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, intensity: float = 1.0, texturePath: Optional[str] = None, textureFormat: str = ‘automatic’) -> pxr.UsdLux.DomeLight

   Creates a dome light with an optional texture.

   A dome light represents light emitted inward from a distant external environment, such as a sky or IBL light probe.

   Texture Format values:

   • automatic - Tries to determine the layout from the file itself.

   • latlong - Latitude as X, longitude as Y.

   • mirroredBall - An image of the environment reflected in a sphere, using an implicitly orthogonal projection.

   • angular - Similar to mirroredBall but the radial dimension is mapped linearly to the angle, for better sampling at the edges.

   • cubeMapVerticalCross - Set to “automatic” by default.

   Note:

   The DomeLight schema requires the dome’s top pole to be aligned with the world’s +Y axis. In USD 23.11 a new UsdLuxDomeLight_1 schema was added which gives control over the pole axis. However, it is not widely supported yet, so we still prefer to author the original DomeLight schema and expect consuming application and renderers to account for the +Y pole axis.

   Parameters:

   • stage - The stage in which the light should be authored

   • path - The path which the light prim should be written to

   • intensity - The intensity value of the dome light

   • texturePath - The path to the texture file to use on the dome light.

   • textureFormat - How the texture should be mapped on the dome light.

   Returns:

   The dome light if created successfully.

2. defineDomeLight(parent: pxr.Usd.Prim, name: str, intensity: float = 1.0, texturePath: Optional[str] = None, textureFormat: str = ‘automatic’) -> pxr.UsdLux.DomeLight

   Creates a dome light with an optional texture.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • parent - Prim below which to define the light

   • name - Name of the light

   • intensity - The intensity value of the dome light

   • texturePath - The path to the texture file to use on the dome light.

   • textureFormat - How the texture should be mapped on the dome light.

   Returns:

   The dome light if created successfully.

usdex.core.defineRectLight(*args, **kwargs)

Overloaded function.

1. defineRectLight(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, width: float, height: float, intensity: float = 1.0, texturePath: Optional[str] = None) -> pxr.UsdLux.RectLight

   Creates a rectangular (rect) light with an optional texture.

   A rect light represents light emitted from one side of a rectangle.

   Parameters:

   • stage - The stage in which the light should be authored

   • path - The path which the light prim should be written to

   • width - The width of the rectangular light, in the local X axis.

   • height - The height of the rectangular light, in the local Y axis.

   • intensity - The intensity value of the rectangular light

   • texturePath - Optional - The path to the texture file to use on the rectangular light.

   Returns:

   The rect light if created successfully.

2. defineRectLight(parent: pxr.Usd.Prim, name: str, width: float, height: float, intensity: float = 1.0, texturePath: Optional[str] = None) -> pxr.UsdLux.RectLight

   Creates a rectangular (rect) light with an optional texture.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • parent - Prim below which to define the light

   • name - Name of the light

   • width - The width of the rectangular light, in the local X axis.

   • height - The height of the rectangular light, in the local Y axis.

   • intensity - The intensity value of the rectangular light

   • texturePath - Optional - The path to the texture file to use on the rectangular light.

   Returns:

   The rect light if created successfully.

usdex.core.createMaterial(

parent: pxr.Usd.Prim,

name: str,

) → pxr.UsdShade.Material

Create a UsdShade.Material as the child of the Prim parent

Parameters:

• parent – Parent prim of the material

• name – Name of the material to be created

Returns:

The newly created UsdShade.Material. Returns an invalid material object on error.

usdex.core.bindMaterial(

prim: pxr.Usd.Prim,

material: pxr.UsdShade.Material,

) → bool

Authors a direct binding to the given material on this prim.

Validates both the prim and the material, applies the UsdShade.MaterialBindingAPI to the target prim, and binds the material to the target prim.

Note

The material is bound with the default “all purpose” used for both full and preview rendering, and with the default “fallback strength” meaning descendant prims can override with a different material. If alternate behavior is desired, use the UsdShade.MaterialBindingAPI directly.

Parameters:

• prim – The prim that the material will affect

• material – The material to bind to the prim

Returns:

Whether the material was successfully bound to the target prim.

usdex.core.computeEffectivePreviewSurfaceShader(

material: pxr.UsdShade.Material,

) → pxr.UsdShade.Shader

Get the effective surface Shader of a Material for the universal render context.

Parameters:

material – The Material to consider

Returns:

The connected Shader. Returns an invalid shader object on error.

usdex.core.definePreviewMaterial(*args, **kwargs)

Overloaded function.

1. definePreviewMaterial(stage: pxr.Usd.Stage, path: pxr.Sdf.Path, color: pxr.Gf.Vec3f, opacity: float = 1.0, roughness: float = 0.5, metallic: float = 0.0) -> pxr.UsdShade.Material

   Defines a PBR UsdShade.Material driven by a UsdPreviewSurface shader network for the universal render context.

   The input parameters reflect a subset of the UsdPreviewSurface specification commonly used when authoring materials using the metallic/metalness workflow (as opposed to the specular workflow). Many other inputs are available and can be authored after calling this function (including switching to the specular workflow).

   Parameters:

   • stage - The stage on which to define the Material

   • path - The absolute prim path at which to define the Material

   • color - The diffuse color of the Material

   • opacity - The Opacity Amount to set, 0.0-1.0 range where 1.0 = opaque and 0.0 = invisible

   • roughness - The Roughness Amount to set, 0.0-1.0 range where 1.0 = flat and 0.0 = glossy

   • metallic - The Metallic Amount to set, 0.0-1.0 range where 1.0 = max metallic and 0.0 = no metallic

   Returns:

   The newly defined UsdShade.Material. Returns an Invalid prim on error

2. definePreviewMaterial(parent: pxr.Usd.Prim, name: str, color: pxr.Gf.Vec3f, opacity: float = 1.0, roughness: float = 0.5, metallic: float = 0.0) -> pxr.UsdShade.Material

   Defines a PBR UsdShade.Material driven by a UsdPreviewSurface shader network for the universal render context.

   This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

   Parameters:

   • parent - Prim below which to define the Material

   • name - Name of the Material

   • color - The diffuse color of the Material

   • opacity - The Opacity Amount to set, 0.0-1.0 range where 1.0 = opaque and 0.0 = invisible

   • roughness - The Roughness Amount to set, 0.0-1.0 range where 1.0 = flat and 0.0 = glossy

   • metallic - The Metallic Amount to set, 0.0-1.0 range where 1.0 = max metallic and 0.0 = no metallic

   Returns:

   The newly defined UsdShade.Material. Returns an Invalid prim on error

usdex.core.addDiffuseTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds a diffuse texture to a preview material

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addNormalTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds a normals texture to a preview material

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

The UsdPreviewSurface specification requires the texture reader to provide data that is properly scaled and ready to be consumed as a tangent space normal. Textures stored in 8-bit file formats require scale and bias adjustment to transform the normals into tangent space.

This module cannot read the provided texturePath to inspect the channel data (the file may not resolve locally, or even exist yet). To account for this, it performs the scale and bias adjustment when the texturePath extension matches a list of known 8-bit formats: ["bmp", "tga", "jpg", "jpeg", "png", "tif"]. Similarly, it assumes that the raw normals data was written into the file, regardless of any file format specific color space metadata. If either of these assumptions is incorrect for your source data, you will need to adjust the scale, bias, and sourceColorSpace settings after calling this function.

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addOrmTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds an ORM (occlusion, roughness, metallic) texture to a preview material

An ORM texture is a normal 3-channel image asset, where the R channel represents occlusion, the G channel represents roughness, and the B channel represents metallic/metallness.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addRoughnessTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds a single channel roughness texture to a preview material

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addMetallicTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds a single channel metallic texture to a preview material

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addOpacityTextureToPreviewMaterial(

material: pxr.UsdShade.Material,

texturePath: pxr.Sdf.AssetPath,

) → bool

Adds a single channel opacity texture to a preview material

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Parameters:

• material – The material prim

• texturePath – The Sdf.AssetPath for the texture

Returns:

Whether or not the texture was added to the material

usdex.core.addPreviewMaterialInterface(material: pxr.UsdShade.Material) → bool

Adds UsdShade.Inputs to the material prim to create an “interface” to the underlying Preview Shader network.

All non-default-value UsdShade.Inputs on the effective surface shader for the universal render context will be “promoted” to the UsdShade.Material as new UsdShade.Inputs. They will be connected to the original source inputs on the shaders, to drive those values, and they will be authored with a value matching what had been set on the shader inputs at the time this function was called.

Additionally, UsdUVTexture.file inputs on connected shaders will be promoted to the material, following the same logic as direct surface inputs.

Note

It is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface().

Warning

This function will fail if there is any other render context driving the material surface. It is only suitable for use on Preview Shader networks, such as the network generated by definePreviewMaterial() and its associated add*Texture functions. If you require multiple contexts, you should instead construct a Material Interface directly, or with targetted end-user interaction.

Parameters:

material – The material prim

Returns:

Whether or not the Material inputs were added successfully

usdex.core.removeMaterialInterface(

material: pxr.UsdShade.Material,

bakeValues: bool = True,

) → bool

Removes any UsdShade.Inputs found on the material prim.

All UsdShade.Inputs on the UsdShade.Material will be disconnected from any underlying shader inputs, then removed from the material. The current values may be optionally “baked down” onto the shader inputs in order to retain the current material behavior, or may be discarded in order to revert to a default appearance based on the shader definitions.

Note

While addPreviewMaterialInterface is specific to Preview Material shader networks, removeMaterialInterface affects all render contexts and will remove all UsdShade.Inputs returned via UsdShade.Material.GetInterfaceInputs(), baking down the values onto all consumer shaders, regardless of render context.

Parameters:

• material – The material prim

• bakeValues – Whether or not the current Material inputs values are set on the underlying Shader inputs

Returns:

Whether or not the Material inputs were removed successfully

class usdex.core.ColorSpace

Texture color space (encoding) types

Members:

eAuto : Check for gamma or metadata in the texture itself

eRaw : Use linear sampling (typically used for Normal, Roughness, Metallic, Opacity textures, or when using high dynamic range file formats like EXR)

eSrgb : Use sRGB sampling (typically used for Diffuse textures when using PNG files)

Attributes:

name

property name

usdex.core.getColorSpaceToken(value: usdex.core._usdex_core.ColorSpace) → str

Get the str matching a given ColorSpace

The string representation is typically used when setting shader inputs, such as inputs:sourceColorSpace on UsdUVTexture.

Parameters:

value – The ColorSpace

Returns:

The str for the given ColorSpace value

usdex.core.sRgbToLinear(color: pxr.Gf.Vec3f) → pxr.Gf.Vec3f

Translate an sRGB color value to linear color space

Many 3D modeling applications define colors in sRGB (0-1) color space. Many others use a linear color space that aligns with how light and color behave in the natural world. When authoring UsdShade.Shader color input data, including external texture assets, you may need to translate between color spaces.

Note

Color is a complex topic in 3D rendering and providing utilities covering the full breadth of color science is beyond the scope of this module. See this [MathWorks article](https://www.mathworks.com/help/images/understanding-color-spaces-and-color-space-conversion.html) for a relatively brief introduction. If you need more specific color handling please use a dedicated color science library like [OpenColorIO](https://opencolorio.org).

Parameters:

color – sRGB representation of a color to be translated to linear color space

Returns:

The translated color in linear color space

usdex.core.linearToSrgb(color: pxr.Gf.Vec3f) → pxr.Gf.Vec3f

Translate a linear color value to sRGB color space

Many 3D modeling applications define colors in sRGB (0-1) color space. Many others use a linear color space that aligns with how light and color behave in the natural world. When authoring UsdShade.Shader color input data, including external texture assets, you may need to translate between color spaces.

Note

Color is a complex topic in 3D rendering and providing utilities covering the full breadth of color science is beyond the scope of this module. See this [MathWorks article](https://www.mathworks.com/help/images/understanding-color-spaces-and-color-space-conversion.html) for a relatively brief introduction. If you need more specific color handling please use a dedicated color science library like [OpenColorIO](https://opencolorio.org).

Parameters:

color – linear representation of a color to be translated to sRGB color space

Returns:

The translated color in sRGB color space