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.

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:

property name#

class usdex.core.DiagnosticsOutputStream#

Control the output stream to which diagnostics are logged.

Members:

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, 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. 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.

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, ) → 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. If the “creator” key already exists, it will not be overwritten & this data will be ignored.

Returns:

A bool indicating if the metadata was successfully authored.

usdex.core.saveStage( stage: pxr.Usd.Stage, authoringMetadata: str, 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, 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.

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.
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.

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.

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.
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:

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.

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.
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.
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.

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
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.

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.
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.

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
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.

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
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.

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.
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.

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:

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.

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:

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.

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:

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.

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:

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.

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:

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.

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:

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.

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:

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.

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.

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.
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.

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.
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.

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
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:

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