Ar module

Summary: The Ar (Asset Resolution) library is responsible for querying, reading, and writing asset data.

Classes:

`DefaultResolver`	Default asset resolution implementation used when no plugin implementation is provided.
`DefaultResolverContext`	Resolver context object that specifies a search path to use during asset resolution.
`Notice`
`ResolvedPath`	Represents a resolved asset path.
`Resolver`	Interface for the asset resolution system.
`ResolverContext`	An asset resolver context allows clients to provide additional data to the resolver for use during resolution.
`ResolverContextBinder`	Helper object for managing the binding and unbinding of ArResolverContext objects with the asset resolver.
`ResolverScopedCache`	Helper object for managing asset resolver cache scopes.
`Timestamp`	Represents a timestamp for an asset.

class pxr.Ar.DefaultResolver

Default asset resolution implementation used when no plugin implementation is provided.

In order to resolve assets specified by relative paths, this resolver implements a simple”search path”scheme. The resolver will anchor the relative path to a series of directories and return the first absolute path where the asset exists.

The first directory will always be the current working directory. The resolver will then examine the directories specified via the following mechanisms (in order):

The currently-bound ArDefaultResolverContext for the calling thread

ArDefaultResolver::SetDefaultSearchPath

The environment variable PXR_AR_DEFAULT_SEARCH_PATH. This is expected to be a list of directories delimited by the platform’s standard path separator.

ArDefaultResolver supports creating an ArDefaultResolverContext via ArResolver::CreateContextFromString by passing a list of directories delimited by the platform’s standard path separator.

Methods:

SetDefaultSearchPath

classmethod SetDefaultSearchPath(searchPath) -> None

static SetDefaultSearchPath()

classmethod SetDefaultSearchPath(searchPath) -> None

Set the default search path that will be used during asset resolution.

This must be called before the first call to ArGetResolver. The specified paths will be searched in addition to, and before paths specified via the environment variable PXR_AR_DEFAULT_SEARCH_PATH

Parameters: searchPath (list[str]) –

class pxr.Ar.DefaultResolverContext

Resolver context object that specifies a search path to use during asset resolution. This object is intended for use with the default ArDefaultResolver asset resolution implementation; see documentation for that class for more details on the search path resolution algorithm.

Example usage:

ArDefaultResolverContext ctx({"/Local/Models", "/Installed/Models"});
{
    // Bind the context object:
    ArResolverContextBinder binder(ctx);

   // While the context is bound, all calls to ArResolver::Resolve
   // (assuming ArDefaultResolver is the underlying implementation being
   // used) will include the specified paths during resolution.
   std::string resolvedPath = resolver.Resolve("ModelName/File.txt")
}

// Once the context is no longer bound (due to the ArResolverContextBinder
// going out of scope), its search path no longer factors into asset
// resolution.

Methods:

GetSearchPath()

Return this context's search path.

GetSearchPath() → list[str]: Return this context’s search path.

class pxr.Ar.Notice

Classes:

`ResolverChanged`
`ResolverNotice`

class ResolverChanged

Methods:

AffectsContext

AffectsContext()

class ResolverNotice

class pxr.Ar.ResolvedPath

Represents a resolved asset path.

Methods:

GetPathString()

Return the resolved path held by this object as a string.

GetPathString() → str: Return the resolved path held by this object as a string.

class pxr.Ar.Resolver

Interface for the asset resolution system. An asset resolver is responsible for resolving asset information (including the asset’s physical path) from a logical path.

See ar_implementing_resolver for information on how to customize asset resolution behavior by implementing a subclass of ArResolver. Clients may use ArGetResolver to access the configured asset resolver.

Methods:

`CanWriteAssetToPath`(resolvedPath, whyNot)	Returns true if an asset may be written to the given `resolvedPath` , false otherwise.
`CreateContextFromString`(contextStr)	Return an ArResolverContext created from the primary ArResolver implementation using the given `contextStr` .
`CreateContextFromStrings`(contextStrs)	Return an ArResolverContext created by combining the ArResolverContext objects created from the given `contextStrs` .
`CreateDefaultContext`()	Return an ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.
`CreateDefaultContextForAsset`(assetPath)	Return an ArResolverContext that may be bound to this resolver to resolve the asset located at `assetPath` or referenced by that asset when no other context is explicitly specified.
`CreateIdentifier`(assetPath, anchorAssetPath)	Returns an identifier for the asset specified by `assetPath` .
`CreateIdentifierForNewAsset`(assetPath, ...)	Returns an identifier for a new asset specified by `assetPath` .
`GetAssetInfo`(assetPath, resolvedPath)	Returns an ArAssetInfo populated with additional metadata (if any) about the asset at the given `assetPath` .
`GetCurrentContext`()	Returns the asset resolver context currently bound in this thread.
`GetExtension`(assetPath)	Returns the file extension for the given `assetPath` .
`GetModificationTimestamp`(assetPath, resolvedPath)	Returns an ArTimestamp representing the last time the asset at `assetPath` was modified.
`IsContextDependentPath`(assetPath)	Returns true if `assetPath` is a context-dependent path, false otherwise.
`RefreshContext`(context)	Refresh any caches associated with the given context.
`Resolve`(assetPath)	Returns the resolved path for the asset identified by the given `assetPath` if it exists.
`ResolveForNewAsset`(assetPath)	Returns the resolved path for the given `assetPath` that may be used to create a new asset.

CanWriteAssetToPath(resolvedPath, whyNot) → bool

Returns true if an asset may be written to the given resolvedPath , false otherwise.

If this function returns false and whyNot is not nullptr , it may be filled with an explanation.

Parameters

resolvedPath (ResolvedPath) –
whyNot (str) –

CreateContextFromString(contextStr) → ResolverContext

Return an ArResolverContext created from the primary ArResolver implementation using the given contextStr .

Parameters: contextStr (str) –

CreateContextFromString(uriScheme, contextStr) -> ResolverContext

Return an ArResolverContext created from the ArResolver registered for the given uriScheme using the given contextStr .

An empty uriScheme indicates the primary resolver and is equivalent to CreateContextFromString(string).

If no resolver is registered for uriScheme , returns an empty ArResolverContext.

Parameters

uriScheme (str) –
contextStr (str) –

CreateContextFromStrings(contextStrs) → ResolverContext

Return an ArResolverContext created by combining the ArResolverContext objects created from the given contextStrs .

contextStrs is a list of pairs of strings. The first element in the pair is the URI scheme for the ArResolver that will be used to create the ArResolverContext from the second element in the pair. An empty URI scheme indicates the primary resolver.

For example:

ArResolverContext ctx = ArGetResolver().CreateContextFromStrings(
   { {"", "context str 1"},
     {"my_scheme", "context str 2"} });

This will use the primary resolver to create an ArResolverContext using the string”context str 1”and use the resolver registered for the”my_scheme”URI scheme to create an ArResolverContext using”context str 2”. These contexts will be combined into a single ArResolverContext and returned.

If no resolver is registered for a URI scheme in an entry in contextStrs , that entry will be ignored.

Parameters: contextStrs (list[tuple[str, str]]) –

CreateDefaultContext() → ResolverContext

Return an ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.

The returned ArResolverContext will contain the default context returned by the primary resolver and all URI resolvers.

CreateDefaultContextForAsset(assetPath) → ResolverContext

Return an ArResolverContext that may be bound to this resolver to resolve the asset located at assetPath or referenced by that asset when no other context is explicitly specified.

The returned ArResolverContext will contain the default context for assetPath returned by the primary resolver and all URI resolvers.

Parameters: assetPath (str) –

CreateIdentifier(assetPath, anchorAssetPath) → str

Returns an identifier for the asset specified by assetPath .

If anchorAssetPath is not empty, it is the resolved asset path that assetPath should be anchored to if it is a relative path.

Parameters

assetPath (str) –
anchorAssetPath (ResolvedPath) –

CreateIdentifierForNewAsset(assetPath, anchorAssetPath) → str

Returns an identifier for a new asset specified by assetPath .

If anchorAssetPath is not empty, it is the resolved asset path that assetPath should be anchored to if it is a relative path.

Parameters

assetPath (str) –
anchorAssetPath (ResolvedPath) –

GetAssetInfo(assetPath, resolvedPath) → ArAssetInfo

Returns an ArAssetInfo populated with additional metadata (if any) about the asset at the given assetPath .

resolvedPath is the resolved path computed for the given assetPath .

Parameters

assetPath (str) –
resolvedPath (ResolvedPath) –

GetCurrentContext() → ResolverContext

Returns the asset resolver context currently bound in this thread.

ArResolver::BindContext, ArResolver::UnbindContext

GetExtension(assetPath) → str

Returns the file extension for the given assetPath .

The returned extension does not include a”.”at the beginning.

Parameters: assetPath (str) –

GetModificationTimestamp(assetPath, resolvedPath) → Timestamp

Returns an ArTimestamp representing the last time the asset at assetPath was modified.

resolvedPath is the resolved path computed for the given assetPath . If a timestamp cannot be retrieved, return an invalid ArTimestamp.

Parameters

assetPath (str) –
resolvedPath (ResolvedPath) –

IsContextDependentPath(assetPath) → bool

Returns true if assetPath is a context-dependent path, false otherwise.

A context-dependent path may result in different resolved paths depending on what asset resolver context is bound when Resolve is called. Assets located at the same context-dependent path may not be the same since those assets may have been loaded from different resolved paths. In this case, the assets’resolved paths must be consulted to determine if they are the same.

Parameters: assetPath (str) –

RefreshContext(context) → None

Refresh any caches associated with the given context.

If doing so would invalidate asset paths that had previously been resolved, an ArNotice::ResolverChanged notice will be sent to inform clients of this.

Parameters: context (ResolverContext) –

Resolve(assetPath) → ResolvedPath

Returns the resolved path for the asset identified by the given assetPath if it exists.

If the asset does not exist, returns an empty ArResolvedPath.

Parameters: assetPath (str) –

ResolveForNewAsset(assetPath) → ResolvedPath

Returns the resolved path for the given assetPath that may be used to create a new asset.

If such a path cannot be computed for assetPath , returns an empty ArResolvedPath.

Note that an asset might or might not already exist at the returned resolved path.

Parameters: assetPath (str) –

class pxr.Ar.ResolverContext

An asset resolver context allows clients to provide additional data to the resolver for use during resolution. Clients may provide this data via context objects of their own (subject to restrictions below). An ArResolverContext is simply a wrapper around these objects that allows it to be treated as a single type. Note that an ArResolverContext may not hold multiple context objects with the same type.

A client-defined context object must provide the following:

Default and copy constructors

operator<

operator==

An overload for size_t hash_value(const T&)

Note that the user may define a free function:

std::string ArGetDebugString(const Context & ctx); (Where Context is the type of the user’s path resolver context.)

This is optional; a default generic implementation has been predefined. This function should return a string representation of the context to be utilized for debugging purposes(such as in TF_DEBUG statements).

The ArIsContextObject template must also be specialized for this object to declare that it can be used as a context object. This is to avoid accidental use of an unexpected object as a context object. The AR_DECLARE_RESOLVER_CONTEXT macro can be used to do this as a convenience.

AR_DECLARE_RESOLVER_CONTEXT

ArResolver::BindContext

ArResolver::UnbindContext

ArResolverContextBinder

Methods:

`Get`()	Returns pointer to the context object of the given type held in this resolver context.
`GetDebugString`()	Returns a debug string representing the contained context objects.
`IsEmpty`()	Returns whether this resolver context is empty.

Get() → ContextObj

Returns pointer to the context object of the given type held in this resolver context.

Returns None if this resolver context is not holding an object of the requested type.

GetDebugString() → str: Returns a debug string representing the contained context objects.

IsEmpty() → bool: Returns whether this resolver context is empty.

class pxr.Ar.ResolverContextBinder

Helper object for managing the binding and unbinding of ArResolverContext objects with the asset resolver.

Asset Resolver Context Operations

class pxr.Ar.ResolverScopedCache

Helper object for managing asset resolver cache scopes.

A scoped resolution cache indicates to the resolver that results of calls to Resolve should be cached for a certain scope. This is important for performance and also for consistency it ensures that repeated calls to Resolve with the same parameters will return the same result.

Scoped Resolution Cache

class pxr.Ar.Timestamp

Represents a timestamp for an asset. Timestamps are represented by Unix time, the number of seconds elapsed since 00:00:00 UTC 1/1/1970.

Methods:

`GetTime`()	Return the time represented by this timestamp as a double.
`IsValid`()	Return true if this timestamp is valid, false otherwise.

GetTime() → float

Return the time represented by this timestamp as a double.

If this timestamp is invalid, issue a coding error and return a quiet NaN value.

IsValid() → bool: Return true if this timestamp is valid, false otherwise.