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

attr (Attribute) –
value (VtValue) –
time (TimeCode) –

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

attr (Attribute) –
value (VtValue) –
time (TimeCode) –

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

attr (Attribute) –
value (T) –
time (TimeCode) –

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'