File Resolver
Overview
This resolver is a file system based resolver similar to the default resolver with support for custom mapping pairs.
- A simple mapping pair look up in a provided mapping pair Usd file. The mapping data has to be stored in the Usd layer metadata in an key called
mappingPairs
as an array with the syntax["sourcePathA.usd", "targetPathA.usd", "sourcePathB.usd", "targetPathB.usd"]
. (This is quite similar to Rodeo's asset resolver that can be found here using the AR 1.0 specification.) - The search path environment variable by default is
AR_SEARCH_PATHS
. It can be customized in the CMakeLists.txt file. - You can use the
AR_ENV_SEARCH_REGEX_EXPRESSION
/AR_ENV_SEARCH_REGEX_FORMAT
environment variables to preformat any asset paths before they looked up in themappingPairs
. The regex match found by theAR_ENV_SEARCH_REGEX_EXPRESSION
environment variable will be replaced by the content of theAR_ENV_SEARCH_REGEX_FORMAT
environment variable. The environment variable names can be customized in the CMakeLists.txt file. - The resolver contexts are cached globally, so that DCCs, that try to spawn a new context based on the same mapping file using the
Resolver.CreateDefaultContextForAsset
, will re-use the same cached resolver context. The resolver context cache key is currently the mapping file path. This may be subject to change, as a hash might be a good alternative, as it could also cover non file based edits via the exposed Python resolver API. Resolver.CreateContextFromString
/Resolver.CreateContextFromStrings
is not implemented due to many DCCs not making use of it yet. As we expose the ability to edit the context at runtime, this is also often not necessary. If needed please create a request by submitting an issue here: Create New Issue- You can adjust the resolver context content during runtime via exposed Python methods (More info here). Refreshing the stage is also supported, although it might be required to trigger additional reloads in certain DCCs.
- We optionally also support exposing alle path identifiers to our
ResolverContext.ResolveAndCache
Python method. This can be enabled by setting theAR_EXPOSE_ABSOLUTE_PATH_IDENTIFIERS
environment variable to1
or by callingpxr.Ar.GetUnderlyingResolver().SetExposeAbsolutePathIdentifierState(True)
. This then forwards any path to be run through our mapped pairs mapping, regardless of how the identifier is formatted.
Optionally you can opt-in into also exposing absolute identifiers (so all (absolute/relative/identifiers that don't start with "/","./","../") identifiers) to our mapping pair mechanism by setting the AR_FILERESOLVER_ENV_EXPOSE_ABSOLUTE_PATH_IDENTIFIERS
environment variable to 1
or by calling pxr.Ar.GetUnderlyingResolver().SetExposeAbsolutePathIdentifierState(True)
. This enforces all identifiers to run through our mapped pairs mapping. The mapped result can also be a search path based path, which then uses the search paths to resolve itself. (So mapping from an absolute to search path based path via the mapping pairs is possible.)
Resolver Environment Configuration
AR_SEARCH_PATHS
: The search path for non absolute asset paths.AR_SEARCH_REGEX_EXPRESSION
: The regex to preformat asset paths before mapping them via the mapping pairs.AR_SEARCH_REGEX_FORMAT
: The string to replace with what was found by the regex expression.
The resolver uses these env vars to resolve non absolute asset paths relative to the directories specified by AR_SEARCH_PATHS
. For example the following substitutes any occurrence of v<3digits>
with v000
and then looks up that asset path in the mapping pairs.
```bash
export AR_SEARCH_PATHS="/workspace/shots:/workspace/assets"
export AR_SEARCH_REGEX_EXPRESSION="(v\d\d\d)"
export AR_SEARCH_REGEX_FORMAT="v000"
```
Debug Codes
Adding following tokens to the TF_DEBUG
env variable will log resolver information about resolution/the context respectively.
FILERESOLVER_RESOLVER
FILERESOLVER_RESOLVER_CONTEXT
For example to enable it on Linux run the following before executing your program:
export TF_DEBUG=FILERESOLVER_RESOLVER_CONTEXT