Update AYON USD Docs and Add AYON USD Resolver Docs #238
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| --- | ||
| id: addon_usd_resolver_admin | ||
| title: AYON USD Resolver | ||
| sidebar_label: USD Resolver | ||
| description: AYON USD Resolver documentation for admins. | ||
| toc_max_heading_level: 5 | ||
| --- | ||
|
|
||
| import ReactMarkdown from "react-markdown"; | ||
| import versions from '@site/docs/assets/json/Ayon_addons_version.json' | ||
|
There was a problem hiding this comment. This sounds like you need to configure every application while we bring a few defaults. Maybe we should say, "Set up the LakeFs settings (currently because of the alpha version, etc.), and if you have a custom software version, add an alias to the "Main" Version." Also, I just want to note that adding a new version is probably never needed, as we already bring all software packages that we have on lakeFs as defaults, so only an alias should be added. |
||
|
|
||
| <ReactMarkdown> | ||
| {versions.USD_Badge} | ||
| </ReactMarkdown> | ||
|
|
||
BigRoy marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Using the AYON USD Resolver requires some small steps to enable the full | ||
| usage of the AYON Entity URI in USD throughout AYON and have the resolver | ||
| downloaded and configured. | ||
|
|
||
| ## Enabling the AYON USD Resolver | ||
|
|
||
| 1. Install the `ayon-usd` addon, and enable it in your bundle. | ||
| 2. Configure the LakeFS settings to use the right AYON USD resolver for your applications. | ||
|
|
||
| :::tip Want to learn more about what the AYON USD Resolver is? | ||
|
|
||
| The AYON USD Resolver artist documentation provides more details on what it is and how it works (from a simplified perspective). | ||
|
|
||
| ::: | ||
|
|
||
| ### AYON USD LakeFS Settings | ||
|
|
||
| The `ayon-usd` addon is able to download and activate a matching AYON USD | ||
| Resolver automatically for an application. These are distributed from compiled binaries that we provide for multiple recent versions of major DCCs, like Houdini and Maya. | ||
|
|
||
| This configuration requires access to the server with an access key and a | ||
| configuration to the server. | ||
|
|
||
|  | ||
|
|
||
| :::note Access Keys and URIs | ||
|
|
||
| These are currently not public, however they are provided upon request. | ||
|
|
||
| ::: | ||
|
|
||
| :::tip Application aliases | ||
|
|
||
| You can configure additional application aliases for which the resolver matches | ||
| and should be downloaded and activated for. | ||
|
|
||
|  | ||
|
|
||
| This allows you to manage a single entry for multiple application variants. | ||
|
|
||
| ::: | ||
|
|
||
| ## Enabling AYON Entity URIs | ||
|
|
||
| To enable publishing and loading of AYON Entity URIs in your project you need to enable: | ||
|
|
||
| #### core | ||
| ``` | ||
| ayon+settings://core/publish/ExtractUSDAssetContribution/use_ayon_entity_uri | ||
| ayon+settings://core/publish/ExtractUSDLayerContribution/use_ayon_entity_uri | ||
| ``` | ||
|
|
||
| #### houdini | ||
| ``` | ||
| ayon+settings://houdini/load/LOPLoadAssetLoader/use_ayon_entity_uri | ||
| ayon+settings://houdini/load/LOPLoadShotLoader/use_ayon_entity_uri | ||
| ayon+settings://houdini/load/USDSublayerLoader/use_ayon_entity_uri | ||
| ayon+settings://houdini/load/USDReferenceLoader/use_ayon_entity_uri | ||
| ayon+settings://houdini/load/SopUsdImportLoader/use_ayon_entity_uri | ||
| ``` | ||
|
|
||
| #### maya | ||
| ``` | ||
| ayon+settings://maya/load/MayaUsdLoader/use_ayon_entity_uri | ||
| ``` | ||
|
|
||
|
There was a problem hiding this comment. Maybe we should add where you need to add the LakeFs keys? |
||
| :::tip Want to enable for only some projects? | ||
|
|
||
| The setting URLs shared above link to the Studio Setting, but these same | ||
| toggles are available in project settings to enable/disable the usage of | ||
| AYON Entity URIs only in a specific project. | ||
|
|
||
| ::: | ||
|
|
||
| ## Pinning | ||
|
|
||
| The AYON USD Resolver supports **pinning**, mapping an entity URI to a | ||
| resulting path without requiring a server connection. This is crucial for | ||
| (large) renderfarms to avoid the many resolves and server queries degrading | ||
| the server's performance. | ||
|
|
||
| **TODO** Explain how the pinning works technically and what env vars will be set to | ||
|
There was a problem hiding this comment. @antirotor This I suppose would be in your hands. These are the admin facing docs. |
||
| enable pinning in the resolver. | ||
|
|
||
| ## API and Technical References | ||
|
|
||
| Looking for more technical documentation? The [AYON-USD Resolver repository](https://github.com/ynput/ayon-usd-resolver) contains more details about the resolver itself and provides a link to the [AYON USD Resolver API documentation](https://ynput.github.io/ayon-usd-resolver/index.html). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| id: addon_usd_resolver_artist | ||
| title: AYON USD Resolver | ||
| sidebar_label: USD Resolver | ||
| description: AYON USD Resolver documentations for artists. | ||
| toc_max_heading_level: 5 | ||
| --- | ||
|
|
||
| import ReactMarkdown from "react-markdown"; | ||
| import versions from '@site/docs/assets/json/Ayon_addons_version.json' | ||
|
|
||
| <ReactMarkdown> | ||
| {versions.USD_Badge} | ||
| </ReactMarkdown> | ||
|
|
||
| ## What is the AYON USD Resolver? | ||
|
|
||
BigRoy marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| The AYON USD Resolver allows to load files in USD using an AYON Entity URI like `ayon+entity://demo_Big_Feature/assets/environments/01_pfueghtiaoft?product=layoutMain&version=v004&representation=ma` by resolving it at runtime to the correct filepath on your machine. | ||
|
|
||
| ## Pinning | ||
|
|
||
| The AYON USD Resolver supports **pinning**. Pinning allows to retarget an entity URI or path to a 'pinned' output filepath. | ||
|
|
||
| This is heavily used on the farm, because loading a single USD file may itself require resolving many other files resulting in potentially 1000s of resolves, requiring 1000s of AYON server queries - for each worker in your farm. Pinning avoids this completely by predefining the mapping of an AYON Entity URI to a filepath, resulting in no AYON server connection even being required at all. | ||
|
|
||
| :::tip Pinning files are heavily recommend for the farm | ||
|
|
||
| The amount of resolves a USD resolver may do can be detrimental to the performance of your server. The AYON USD Resolver does have a good local caching system, but if 100s of machines start resolving 1000s of unique URIs simultaneously there's little optimization that can be done because USD will resolve URIs one by one. | ||
|
|
||
| ::: | ||
|
|
||
| :::note What is the `.json` file next to my USD file? | ||
|
|
||
| If you see a `.json` file next to a USD file, especially when the USD file is to be rendered on the farm, there's a good chance that it is an AYON USD Resolver pinning file. | ||
|
|
||
| This can easily be confirmed by checking whether it contains a big list of files and text like `ayon_resolver_pinning_data` inside of it. | ||
|
|
||
| ::: | ||
|
|
||
| ## Caching | ||
|
There was a problem hiding this comment. There might be a point to mention that we don't do this for Deduplicaiont (Usd already does this internally) and also that the Cache is not bound to the Resolver class instance (If not explicitly requested via API) but lives as an instance shared cache. I mention this because I talked about just that on the Usd forums, and it caused a bit of confusion before I explained it. |
||
|
|
||
| The AYON USD Resolver has a local caching mechanism to optimize its performance in | ||
| daily use. Entity URIs traditionally resolve to static paths, so caching them in your local sessions is the best way to improve performance. | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -1540,7 +1540,7 @@ | |
| "@docusaurus/theme-search-algolia" "2.4.0" | ||
| "@docusaurus/types" "2.4.0" | ||
|
|
||
| "@docusaurus/[email protected]": | ||
| version "5.5.2" | ||
| resolved "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-5.5.2.tgz" | ||
| integrity sha512-A3dYjdBGuy0IGT+wyLIGIKLRE+sAk1iNk0f1HjNDysO7u8lhL4N3VEm+FAubmJbAztn94F7MxBTPmnixbiyFdQ== | ||
|
|
@@ -4829,7 +4829,7 @@ [email protected]: | |
|
|
||
| docusaurus@^1.14.7: | ||
| version "1.14.7" | ||
| resolved "https://registry.yarnpkg.com/docusaurus/-/docusaurus-1.14.7.tgz#f51858ab643b29ec52264d6dd85e0d629e5b3a4a" | ||
| integrity sha512-UWqar4ZX0lEcpLc5Tg+MwZ2jhF/1n1toCQRSeoxDON/D+E9ToLr+vTRFVMP/Tk84NXSVjZFRlrjWwM2pXzvLsQ== | ||
| dependencies: | ||
| "@babel/core" "^7.12.3" | ||
|
|
@@ -10660,6 +10660,14 @@ react-loadable-ssr-addon-v5-slorber@^1.0.1: | |
| dependencies: | ||
| "@babel/runtime" "^7.10.3" | ||
|
|
||
| "react-loadable@npm:@docusaurus/[email protected]": | ||
| version "5.5.2" | ||
| resolved "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-5.5.2.tgz" | ||
| integrity sha512-A3dYjdBGuy0IGT+wyLIGIKLRE+sAk1iNk0f1HjNDysO7u8lhL4N3VEm+FAubmJbAztn94F7MxBTPmnixbiyFdQ== | ||
| dependencies: | ||
| "@types/react" "*" | ||
| prop-types "^15.6.2" | ||
|
|
||
| react-markdown@^8.0.7: | ||
| version "8.0.7" | ||
| resolved "https://registry.npmjs.org/react-markdown/-/react-markdown-8.0.7.tgz" | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should rather say that the Ayon contribution workflow was introduced around this time or its version, not this pr.
Reason:
many commits Created the Contribution workflow.
It might be confusing if you look at this one PR and don't see all the parts that made the contribution workflow.