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 the mappingPairs. The regex match found by the AR_ENV_SEARCH_REGEX_EXPRESSION environment variable will be replaced by the content of the AR_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 the AR_CACHEDRESOLVER_ENV_EXPOSE_ABSOLUTE_PATH_IDENTIFIERS environment variable to 1 or by calling pxr.Ar.GetUnderlyingResolver().SetExposeAbsolutePathIdentifierState(True). This then forwards any path to be run through our mapped pairs mapping, regardless of how the identifier is formatted.

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