Understanding UsdUtils.StageCache and mayaUsd.lib.StageCache

[eddiehoyle]

Starting from a simple stage:

from pxr import Usd, UsdGeom

# Export a simple stage
stage = Usd.Stage.CreateInMemory()
UsdGeom.Cube.Define(stage, "/cube")
stage.Export("/tmp/cube.usda")

Consider this example:

import mayaUsd
from maya import cmds
from pxr import UsdUtils

cmds.file(new=True, force=True)
cmds.loadPlugin("mayaUsdPlugin")

# Clear caches
maya_cache = mayaUsd.lib.StageCache.Get(loadAll=True)
usd_cache = UsdUtils.StageCache.Get()
maya_cache.Clear()
usd_cache.Clear()
assert not maya_cache.GetAllStages()
assert not usd_cache.GetAllStages()

# Import stage
shape = cmds.ls(cmds.createNode("mayaUsdProxyShape"), long=True)[0]
cmds.setAttr("{}.filePath".format(shape), "/tmp/cube.usda", type="string")

# Query by stage 
assert maya_cache.GetId(mayaUsd.ufe.getStage(shape)).IsValid()
#assert usd_cache.GetId(mayaUsd.ufe.getStage(shape)).IsValid() # False

# Query by id
cache_id = cmds.getAttr("{}.outStageCacheId".format(shape))
#assert maya_cache.Find(Usd.StageCache.Id.FromLongInt(cache_id)) # None
assert usd_cache.Find(Usd.StageCache.Id.FromLongInt(cache_id))

In the above snippet the Maya cache is queryable by stage, and the UsdUtils cache is queryable by cache id (populated on attribute get). Is this behaviour intended? Which cache (and strategy) should I prefer for fetching stages within a Maya session?

[kxl-adsk]

Can you tell me more about how you are intending to use the stage after? Is it something you want to pass to another DG node? Pass the stages across different libraries? Will you mutate the data in the stage or it's for reading only? Any expectations about the lifetime of this stage?

[eddiehoyle]

We initialise UIs from stages found on proxies with both read/write access, and consider the stages lifetime coupled to the proxy importing it. For stages who's lifetimes need to persist between scenes, I would expect their cache ids be found in UsdUtils.StageCache and that they would be valid for the length of the Maya application, or unless explicitly cleared/removed. I believe this is the current behaviour.

From a user perspective, I thought the the outStageCacheId was associated with mayaUsd cache instead of UsdUtils.StageCache and I had to dig through the source code to find which cache the id belonged to. Either cache works fine for our tools, I'm mostly curious about how we're using them and if there are guidelines for which cache should be used within/around Maya sessions.

From a few rounds of testing, it looks like I should...

• Prefer mayaUsd.lib.StageCache for stages within Maya's scene lifetime. Query by stage.
• Prefer UsdUtils.StageCache for stages within Maya's application lifetime. Query by outStageCacheId attribute on proxy.

Does that sound right?

[kxl-adsk]

Thank you for the additional context.

In short, I would recommend relying more on Maya's data model and not on stage caches. This is exactly what we do for UFE workflows (see stage map) and in Layer Editor (see maya session state). What it means is that you will build tools that work with proxy shapes and query the stage from the proxy. FWIW. you can query stage directly from proxy using python - two possible ways are described in this discussion post.

Now, a little about the stage caches. MayaUsd stage cache (mayaUsd.lib.StageCache) should really be considered as an implementation detail. For some time we were forced to include all proxy shape stages into the stage cache because data stored in data block wasn't holding strong references to stages. We fixed it (pr) and now we no longer need to put all stages in the cache and in fact duplicated stages won't be in the stage cache IIRC. We will revisit at one point stages with anonymous root layers, since they don't bring much value of being stored in the stage cache and keep on taking memory if you add/remove them often in the same scene.

For USD global stage cache (UsdUtils.StageCache), we use it when exchanging data with other DG nodes that couldn't be built with dependency on MayaUSD library. The fact that we don't flush it on file new is potentially an oversight because this cache can hold onto potentially big stages. So the lifetime of stages can change.

[eddiehoyle]

Awesome, thanks for the detailed response! As our tools (in Maya) are coupled to stages imported by proxies, I'll prefer the Maya data model approach like your UFE and layer editor examples.