Cache

Generating a UJITSO cache for the asset to accelerate load times and enhance performance may accelerate any kit-app-template app configured to utilize cache.

UJITSO cache files are data blobs (binary large objects) that house all data for all options in your configurator. To write all data initially for reuse, you need to run through all options in the configurator when the UJITSO client is loaded and write the cache as the options are set.

Automated cache generation utilizes Action Graph to set scene elements. The Caching Graph from the previous section runs through all options embedded in the Concept Car configured file. The Action Graph may be triggered using a keyboard shortcut or event message.

The cache may be generated manually, or via the Configurator Publisher extension.

Manual Cache Generation

Manually generating the cache involves two main steps:

Launching USD Viewer via the command line with a series of flags.
Manually triggering the action graph.

To manually generate the cache, run the USD Viewer app with the following flags via command line:

--enable omni.ujitso.client
--/UJITSO/enabled=true
--/UJITSO/textures=true
--/UJITSO/geometry=true
--/UJITSO/materials=true
--/UJITSO/datastore/localCachePath="{package_root}/cache"

# If the cache is to be used on GDN
--/UJITSO/writeCacheWithAssetRoot="{package_root}"

To run USD Viewer with these flags, you must first pass in the path to the built kit.exe file, as well as the built .kit file for your USD Viewer app. These files may be found at _build/{platform}/release/kit/kit.exe and _build/{platform}/release/apps/{app_name}.kit.

Here is an example of the entire command to run from the command line if we have built a USD Viewer app called my_company.my_usd_viewer for Windows:

{kit-app-template_root}/_build/windows-x86_64/release/kit/kit.exe {kit-app-template_root}/_build/windows-x86_64/release/apps/my_company.my_usd_viewer.kit
--enable omni.ujitso.client
--/UJITSO/enabled=true
--/UJITSO/textures=true
--/UJITSO/geometry=true
--/UJITSO/materials=true
--/UJITSO/datastore/localCachePath="{package_root}/cache"
--/UJITSO/writeCacheWithAssetRoot="{package_root}"
--/app/auto_load_usd={concept_car_usd_path}

Note

We also added a --/app/auto_load_usd="{concept_car_usd_path}" flag to the previous command block, which ensures the Concept Car is loaded when USD Viewer launches. This ensures we can also manually trigger the Action Graph that runs through and caches the configured options. Make sure you replace the path with your local path to the Concept Car stage prior to executing this command.

After loading the USD Viewer template application and stage, the assets begin caching to the specified local cache path. All the configurator options must next be systematically cycled through to cache. In the configured car USD sample, this graph has been setup to trigger when Control+Shift+J is pressed, but any hotkey combination could be used. You must also enable this functionality by checking the allowManualCache checkbox in the /World/Graphs/CacheGeneration prim.

Alternatively, the process below automates this process.

Automated Cache Generation

The Configurator Publisher automates cache generation by extracting the kit file path from the .bat file set in the Kit Application Path, then running the USD Viewer template application with the flags mentioned above. The application runs this headlessly and provides the arguments in addition to a Python file that emits the GenerateCache message when the asset is loaded, which triggers the caching graph execution. To see the cache files being generated:

Make sure you have run USD Viewer at least once normally. Running USD Viewer headlessly requires some data files to be in place since these files are created on the first run.
Open the collected folder generated in the Collecting section.
In the Configurator Publisher extension, set the Kit Application Path by browsing to the built USD Viewer .bat file. This is located at _build/{platform}/release/{application_name}.kit.bat.
Enable only the Cache option.
Select Run Process.
A cache folder is created in the root directory. Verify UJITSO cache files have been created in the directory.

Note

If you are caching very large textures files, like the .exr files mentioned in the optimization section, the UJITSO caching system may not have enough time to cache the file before the next file gets loaded by the graph setting the next variant. You will notice this is the case if the caching function does not complete or if the local testing described below prints UJITSO: FAILED to load build dependency. Processor: 'UJITSO-v2-OvTextureProcessor-v2' in the log and console. To fix this, you can increase the delayTime value on the /World/Graphs/CacheGeneration prim.

Those files may be used when the asset is loaded on GDN by providing the following flags for the USD Viewer app that runs on GDN. Read more about passing in custom flags for your application here. Application settings may be used on GDN, using the Technical Metadata sections when your title is onboarded.

--enable omni.ujitso.client
--/UJITSO/enabled=true
--/UJITSO/textures=true
--/UJITSO/geometry=true
--/UJITSO/materials=true
--/UJITSO/datastore/localCachePath="{package_root}/cache"
--/UJITSO/readCacheWithAssetRoot="{gdn_asset_path}"

Validating Cache Locally

Run USD Viewer with an added flag: --/UJITSO/failedDepLoadingLogging=true.

This flag adds log entries to any missing cache elements encountered when loading and running the configurator.

The log file location can also be specified by supplying the flag: --/log/file={package_root}/configurator.log.

{kit-app-template_root}/_build/windows-x86_64/release/kit/kit.exe {kit-app-template_root}/_build/windows-x86_64/release/apps/my_company.my_usd_viewer.kit --enable omni.ujitso.client --/UJITSO/enabled=true --/UJITSO/textures=true --/UJITSO/geometry=true --/UJITSO/materials=true --/UJITSO/failedDepLoadingLogging=true --/log/file={package_root}/configurator.log --/UJITSO/datastore/localCachePath="{package_root}/cache" --/UJITSO/writeCacheWithAssetRoot="{package_root}" --/app/auto_load_usd={concept_car_usd_path}

You may also test copying your configurator to another location and provide the flag: --/UJITSO/readCacheWithAssetRoot={new_asset_path}.

{kit-app-template_root}/_build/windows-x86_64/release/kit/kit.exe {kit-app-template_root}/_build/windows-x86_64/release/apps/my_company.my_usd_viewer.kit --enable omni.ujitso.client --/UJITSO/enabled=true --/UJITSO/textures=true --/UJITSO/geometry=true --/UJITSO/materials=true --/UJITSO/failedDepLoadingLogging=true --/log/file={new_asset_path}/configurator.log --/UJITSO/datastore/localCachePath="{new_asset_path}/cache" --/UJITSO/readCacheWithAssetRoot="{new_asset_path}" --/app/auto_load_usd={concept_car_usd_path}

Note

You will see a few UJITSO: FAILED to load build dependency. Processor: ‘UJITSO-v2-MdlToHlslProcessor-v0’ in the log and console - this mdl to Hlsl processor log output is expected at this time and can be ignored.