UsdUtils module

Summary: The UsdUtils module contains utility classes and functions for managing, inspecting, editing, and creating USD Assets.


Classes:

CoalescingDiagnosticDelegate

A class which collects warnings and statuses from the Tf diagnostic manager system in a thread safe manner.

CoalescingDiagnosticDelegateItem

An item used in coalesced results, containing a shared component: the file/function/line number, and a set of unshared components: the call context and commentary.

CoalescingDiagnosticDelegateSharedItem

The shared component in a coalesced result This type can be thought of as the key by which we coalesce our diagnostics.

CoalescingDiagnosticDelegateUnsharedItem

The unshared component in a coalesced result.

ConditionalAbortDiagnosticDelegate

A class that allows client application to instantiate a diagnostic delegate that can be used to abort operations for a non fatal USD error or warning based on immutable include exclude rules defined for this instance.

ConditionalAbortDiagnosticDelegateErrorFilters

A class which represents the inclusion exclusion filters on which errors will be matched stringFilters: matching and filtering will be done on explicit string of the error/warning codePathFilters: matching and filtering will be done on errors/warnings coming from a specific usd code path.

RegisteredVariantSet

Info for registered variant set

SparseAttrValueWriter

A utility class for authoring time-varying attribute values with simple run-length encoding, by skipping any redundant time-samples.

SparseValueWriter

Utility class that manages sparse authoring of a set of UsdAttributes.

StageCache

The UsdUtilsStageCache class provides a simple interface for handling a singleton usd stage cache for use by all USD clients.

TimeCodeRange

Represents a range of UsdTimeCode values as start and end time codes and a stride value.

UsdStageStatsKeys

class pxr.UsdUtils.CoalescingDiagnosticDelegate

A class which collects warnings and statuses from the Tf diagnostic manager system in a thread safe manner.

This class allows clients to get both the unfiltered results, as well as a compressed view which deduplicates diagnostic events by their source line number, function and file from which they occurred.

Methods:

DumpCoalescedDiagnosticsToStderr

DumpCoalescedDiagnosticsToStdout

DumpUncoalescedDiagnostics(ostr)

Print all pending diagnostics without any coalescing to ostr .

TakeCoalescedDiagnostics()

Get all pending diagnostics in a coalesced form.

TakeUncoalescedDiagnostics()

Get all pending diagnostics without any coalescing.

DumpCoalescedDiagnosticsToStderr()
DumpCoalescedDiagnosticsToStdout()
DumpUncoalescedDiagnostics(ostr) None

Print all pending diagnostics without any coalescing to ostr .

This method clears the pending diagnostics.

Parameters

ostr (ostream) –

TakeCoalescedDiagnostics() list[CoalescingDiagnosticDelegate]

Get all pending diagnostics in a coalesced form.

This method clears the pending diagnostics.

TakeUncoalescedDiagnostics() list[TfDiagnosticBase]

Get all pending diagnostics without any coalescing.

This method clears the pending diagnostics.

class pxr.UsdUtils.CoalescingDiagnosticDelegateItem

An item used in coalesced results, containing a shared component: the file/function/line number, and a set of unshared components: the call context and commentary.

Attributes:

sharedItem

unsharedItems

property sharedItem
property unsharedItems
class pxr.UsdUtils.CoalescingDiagnosticDelegateSharedItem

The shared component in a coalesced result This type can be thought of as the key by which we coalesce our diagnostics.

Attributes:

sourceFileName

sourceFunction

sourceLineNumber

property sourceFileName
property sourceFunction
property sourceLineNumber
class pxr.UsdUtils.CoalescingDiagnosticDelegateUnsharedItem

The unshared component in a coalesced result.

Attributes:

commentary

context

property commentary
property context
class pxr.UsdUtils.ConditionalAbortDiagnosticDelegate

A class that allows client application to instantiate a diagnostic delegate that can be used to abort operations for a non fatal USD error or warning based on immutable include exclude rules defined for this instance.

These rules are regex strings where case sensitive matching is done on error/warning text or the location of the code path where the error/warning occured. Note that these rules will be respected only during the lifetime of the delegate. Include Rules determine what errors or warnings will cause a fatal abort. Exclude Rules determine what errors or warnings matched from the Include Rules should not cause the fatal abort. Example: to abort on all errors and warnings coming from”*pxr*”codepath but not from”*ConditionalAbortDiagnosticDelegate*”, a client can create the following delegate:

UsdUtilsConditionalAbortDiagnosticDelegateErrorFilters includeFilters;
UsdUtilsConditionalAbortDiagnosticDelegateErrorFilters excludeFilters;
includeFilters.SetCodePathFilters({"\*pxr\*"});
excludeFilters.SetCodePathFilters({"\*ConditionalAbortDiagnosticDelegate\*"});
UsdUtilsConditionalAbortDiagnosticDelegate delegate =
    UsdUtilsConditionalAbortDiagnosticDelegate(includeFilters,
        excludeFilters);
class pxr.UsdUtils.ConditionalAbortDiagnosticDelegateErrorFilters

A class which represents the inclusion exclusion filters on which errors will be matched stringFilters: matching and filtering will be done on explicit string of the error/warning codePathFilters: matching and filtering will be done on errors/warnings coming from a specific usd code path.

Methods:

GetCodePathFilters()

GetStringFilters()

SetCodePathFilters(codePathFilters)

param codePathFilters

SetStringFilters(stringFilters)

param stringFilters

GetCodePathFilters() list[str]
GetStringFilters() list[str]
SetCodePathFilters(codePathFilters) None
Parameters

codePathFilters (list[str]) –

SetStringFilters(stringFilters) None
Parameters

stringFilters (list[str]) –

class pxr.UsdUtils.RegisteredVariantSet

Info for registered variant set

Classes:

SelectionExportPolicy

This specifies how the variantSet should be treated during export.

Attributes:

name

selectionExportPolicy

class SelectionExportPolicy

This specifies how the variantSet should be treated during export.

Note, in the plugInfo.json, the values for these enum’s are lowerCamelCase.

Attributes:

Always

IfAuthored

Never

names

values

Always = pxr.UsdUtils.SelectionExportPolicy.Always
IfAuthored = pxr.UsdUtils.SelectionExportPolicy.IfAuthored
Never = pxr.UsdUtils.SelectionExportPolicy.Never
names = {'Always': pxr.UsdUtils.SelectionExportPolicy.Always, 'IfAuthored': pxr.UsdUtils.SelectionExportPolicy.IfAuthored, 'Never': pxr.UsdUtils.SelectionExportPolicy.Never}
values = {0: pxr.UsdUtils.SelectionExportPolicy.Never, 1: pxr.UsdUtils.SelectionExportPolicy.IfAuthored, 2: pxr.UsdUtils.SelectionExportPolicy.Always}
property name
property selectionExportPolicy
class pxr.UsdUtils.SparseAttrValueWriter

A utility class for authoring time-varying attribute values with simple run-length encoding, by skipping any redundant time-samples. Time-samples that are close enough to each other, with relative difference smaller than a fixed epsilon value are considered to be equivalent. This is to avoid unnecessary authoring of time-samples caused by numerical fuzz in certain computations.

For vectors, matrices, and other composite types (like quaternions and arrays), each component is compared with the corresponding component for closeness. The chosen epsilon value for double precision floating point numbers is 1e-12. For single-precision, it is 1e-6 and for half- precision, it is 1e-2.

Example c++ usage:

UsdGeomSphere sphere = UsdGeomSphere::Define(stage, SdfPath("/Sphere"));
UsdAttribute radius = sphere.CreateRadiusAttr();
UsdUtilsSparseAttrValueWriter attrValueWriter(radius,
        /\*defaultValue\*/ VtValue(1.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(1.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(2.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(3.0));
attrValueWriter.SetTimeSample(VtValue(20.0), UsdTimeCode(4.0));

Equivalent python example:

sphere = UsdGeom.Sphere.Define(stage, Sdf.Path("/Sphere"))
radius = sphere.CreateRadiusAttr()
attrValueWriter = UsdUtils.SparseAttrValueWriter(radius, defaultValue=1.0)
attrValueWriter.SetTimeSample(10.0, 1.0)
attrValueWriter.SetTimeSample(10.0, 2.0)
attrValueWriter.SetTimeSample(10.0, 3.0)
attrValueWriter.SetTimeSample(20.0, 4.0)

In the above examples, the specified default value of radius (1.0) will not be authored into scene description since it matches the fallback value. Additionally, the time-sample authored at time=2.0 will be skipped since it is redundant. Also note that for correct behavior, the calls to SetTimeSample() must be made with sequentially increasing time values. If not, a coding error is issued and the authored animation may be incorrect.

Methods:

SetTimeSample(value, time)

Sets a new time-sample on the attribute with given value at the given time .

SetTimeSample(value, time) bool

Sets a new time-sample on the attribute with given value at the given time .

The time-sample is only authored if it’s different from the previously set time-sample, in which case the previous time-sample is also authored, in order to to end the previous run of contiguous identical values and start a new run.

This incurs a copy of value . Also, the value will be held in memory at least until the next time-sample is written or until the SparseAttrValueWriter instance is destroyed.

Parameters
  • value (VtValue) –

  • time (TimeCode) –


SetTimeSample(value, time) -> bool

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

For efficiency, this function swaps out the given value , leaving it empty.

The value will be held in memory at least until the next time-sample is written or until the SparseAttrValueWriter instance is destroyed.

Parameters
  • value (VtValue) –

  • time (TimeCode) –

class pxr.UsdUtils.SparseValueWriter

Utility class that manages sparse authoring of a set of UsdAttributes. It does this by maintaining a map of UsdAttributes to their corresponding UsdUtilsSparseAttrValueWriter objects.

To use this class, simply instantiate an instance of it and invoke the SetAttribute() method with various attributes and their associated time-samples.

If the attribute has a default value, SetAttribute() must be called with time=Default first (multiple times, if necessary), followed by calls to author time-samples in sequentially increasing time order.

This class is not threadsafe. In general, authoring to a single USD layer from multiple threads isn’t threadsafe. Hence, there is little value in making this class threadsafe. Example c++ usage:

UsdGeomCylinder cylinder = UsdGeomCylinder::Define(stage, SdfPath("/Cylinder"));
UsdAttribute radius = cylinder.CreateRadiusAttr();
UsdAttribute height = cylinder.CreateHeightAttr();
UsdUtilsSparseValueWriter valueWriter;
valueWriter.SetAttribute(radius, 2.0, UsdTimeCode::Default());
valueWriter.SetAttribute(height, 2.0, UsdTimeCode::Default());

valueWriter.SetAttribute(radius, 10.0, UsdTimeCode(1.0));
valueWriter.SetAttribute(radius, 20.0, UsdTimeCode(2.0));
valueWriter.SetAttribute(radius, 20.0, UsdTimeCode(3.0));
valueWriter.SetAttribute(radius, 20.0, UsdTimeCode(4.0));

valueWriter.SetAttribute(height, 2.0, UsdTimeCode(1.0));
valueWriter.SetAttribute(height, 2.0, UsdTimeCode(2.0));
valueWriter.SetAttribute(height, 3.0, UsdTimeCode(3.0));
valueWriter.SetAttribute(height, 3.0, UsdTimeCode(4.0));

Equivalent python code:

cylinder = UsdGeom.Cylinder.Define(stage, Sdf.Path("/Cylinder"))
radius = cylinder.CreateRadiusAttr()
height = cylinder.CreateHeightAttr()
valueWriter = UsdUtils.SparseValueWriter()
valueWriter.SetAttribute(radius, 2.0, Usd.TimeCode.Default())
valueWriter.SetAttribute(height, 2.0, Usd.TimeCode.Default())

valueWriter.SetAttribute(radius, 10.0, 1.0)
valueWriter.SetAttribute(radius, 20.0, 2.0)
valueWriter.SetAttribute(radius, 20.0, 3.0)
valueWriter.SetAttribute(radius, 20.0, 4.0)

valueWriter.SetAttribute(height, 2.0, 1.0)
valueWriter.SetAttribute(height, 2.0, 2.0)
valueWriter.SetAttribute(height, 3.0, 3.0)
valueWriter.SetAttribute(height, 3.0, 4.0)

In the above example,

  • The default value of the”height”attribute is not authored into scene description since it matches the fallback value.

  • Time-samples at time=3.0 and time=4.0 will be skipped for the radius attribute.

  • For the”height”attribute, the first timesample at time=1.0 will be skipped since it matches the default value.

  • The last time-sample at time=4.0 will also be skipped for”height”since it matches the previously written value at time=3.0.

Methods:

GetSparseAttrValueWriters()

Returns a new vector of UsdUtilsSparseAttrValueWriter populated from the attrValueWriter map.

SetAttribute(attr, value, time)

Sets the value of attr to value at time time .

GetSparseAttrValueWriters() list[SparseAttrValueWriter]

Returns a new vector of UsdUtilsSparseAttrValueWriter populated from the attrValueWriter map.

SetAttribute(attr, value, time) bool

Sets the value of attr to value at time time .

The value is written sparsely, i.e., the default value is authored only if it is different from the fallback value or the existing default value, and any redundant time-samples are skipped when the attribute value does not change significantly between consecutive time-samples.

Parameters

SetAttribute(attr, value, time) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. For efficiency, this function swaps out the given value , leaving it empty.

The value will be held in memory at least until the next time-sample is written or until the SparseAttrValueWriter instance is destroyed.

Parameters

SetAttribute(attr, value, time) -> bool

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

Parameters
class pxr.UsdUtils.StageCache

The UsdUtilsStageCache class provides a simple interface for handling a singleton usd stage cache for use by all USD clients. This way code from any location can make use of the same cache to maximize stage reuse.

Methods:

Get

classmethod Get() -> StageCache

GetSessionLayerForVariantSelections

classmethod GetSessionLayerForVariantSelections(modelName, variantSelections) -> Layer

static Get()

classmethod Get() -> StageCache

Returns the singleton stage cache.

static GetSessionLayerForVariantSelections()

classmethod GetSessionLayerForVariantSelections(modelName, variantSelections) -> Layer

Given variant selections as a vector of pairs (vector in case order matters to the client), constructs a session layer with overs on the given root modelName with the variant selections, or returns a cached session layer with those opinions.

Parameters
  • modelName (str) –

  • variantSelections (list[tuple[str, str]]) –

class pxr.UsdUtils.TimeCodeRange

Represents a range of UsdTimeCode values as start and end time codes and a stride value.

A UsdUtilsTimeCodeRange can be iterated to retrieve all time code values in the range. The range may be empty, it may contain a single time code, or it may represent multiple time codes from start to end. The interval defined by the start and end time codes is closed on both ends.

Note that when constructing a UsdUtilsTimeCodeRange, UsdTimeCode::EarliestTime() and UsdTimeCode::Default() cannot be used as the start or end time codes. Also, the end time code cannot be less than the start time code for positive stride values, and the end time code cannot be greater than the start time code for negative stride values. Finally, the stride value cannot be zero. If any of these conditions are not satisfied, then an invalid empty range will be returned.

Classes:

Tokens

Methods:

CreateFromFrameSpec

classmethod CreateFromFrameSpec(frameSpec) -> TimeCodeRange

IsValid()

Return true if this range contains one or more time codes, or false otherwise.

empty()

Return true if this range contains no time codes, or false otherwise.

Attributes:

endTimeCode

TimeCode

frameSpec

startTimeCode

TimeCode

stride

float

class Tokens

Attributes:

EmptyTimeCodeRange

RangeSeparator

StrideSeparator

EmptyTimeCodeRange = 'NONE'
RangeSeparator = ':'
StrideSeparator = 'x'
static CreateFromFrameSpec()

classmethod CreateFromFrameSpec(frameSpec) -> TimeCodeRange

Create a time code range from frameSpec .

A FrameSpec is a compact string representation of a time code range. A FrameSpec may contain up to three floating point values for the start time code, end time code, and stride values of a time code range.

A FrameSpec containing just a single floating point value represents a time code range containing only that time code.

A FrameSpec containing two floating point values separated by the range separator (‘:’) represents a time code range from the first value as the start time code to the second values as the end time code.

A FrameSpec that specifies both a start and end time code value may also optionally specify a third floating point value as the stride, separating it from the first two values using the stride separator (‘x’).

The following are examples of valid FrameSpecs: 123 101:105 105:101 101:109x2 101:110x2 101:104x0.5

An empty string corresponds to an invalid empty time code range.

A coding error will be issued if the given string is malformed.

Parameters

frameSpec (str) –

IsValid() bool

Return true if this range contains one or more time codes, or false otherwise.

empty() bool

Return true if this range contains no time codes, or false otherwise.

property endTimeCode

TimeCode

Return the end time code of this range.

Type

type

property frameSpec
property startTimeCode

TimeCode

Return the start time code of this range.

Type

type

property stride

float

Return the stride value of this range.

Type

type

class pxr.UsdUtils.UsdStageStatsKeys

Attributes:

activePrimCount

approxMemoryInMb

assetCount

inactivePrimCount

instanceCount

instancedModelCount

modelCount

primCounts

primCountsByType

primary

prototypeCount

prototypes

pureOverCount

totalInstanceCount

totalPrimCount

untyped

usedLayerCount

activePrimCount = 'activePrimCount'
approxMemoryInMb = 'approxMemoryInMb'
assetCount = 'assetCount'
inactivePrimCount = 'inactivePrimCount'
instanceCount = 'instanceCount'
instancedModelCount = 'instancedModelCount'
modelCount = 'modelCount'
primCounts = 'primCounts'
primCountsByType = 'primCountsByType'
primary = 'primary'
prototypeCount = 'prototypeCount'
prototypes = 'prototypes'
pureOverCount = 'pureOverCount'
totalInstanceCount = 'totalInstanceCount'
totalPrimCount = 'totalPrimCount'
untyped = 'untyped'
usedLayerCount = 'usedLayerCount'