Instancable metadata and what usd determines as "identical"?

Community USD
1

Are there any good resources that explain the low level way which payloads and references are brought in and shared or not shared when using instancable metadata?

The general documentation I’ve seen says
… instanceable metadata informs USD that prim hierarchies with identical references (and other “composition arcs”) should be treated as identical sub-hierarchies

At what point is the “identical” sub-hierarchy applied? Imagine we have a script or tool which builds a layer and this layer contains the following prims (and marked instanceable):

/root/prop/mugA01/
/root/prop/mugA02/

Under each of these prims is a reference or payload to a dynamically generated temp file which contain the same sub-hierarchies of data but are different temp files added to each prim uniquely.

Is this something that the USD runtime engine works out behind the scenes? Or is there a price to be paid for those two reference not being identical paths on disk? Does the reference/payload anchored at the prims in the top most layer have to point to the same file to gain these benfits?

Any pointers would be greatly appreciated!

I hope this question makes sense - if not I can probably provide a python example or at least some usda snippets.

2

The answer to your specific question is that USD purposefully does not want to do any diffing of referenced layers to determine “what is the same”, because that would be hugely expensive at scale. So, yes, you would need to be referencing the exact same asset/layer for instances to be recognized as identical. That could still be temporary content, in-memory, even, because you can use the identifier of an anonymous layer in a reference/payload.

To your more general question of what goes into what we call “The instancing key”, we attempt to describe it here. Let me know if this leaves unanswered questions!

3

Hey - that makes sense and is what I expected!

I was playing around with generating variant sets with identical payloads and using instanceable = true and notice that no matter where I put instancable = true in the example below I could not get it generate a single prototype (it generates 3 - even when all variant sets are defaulted to “high”

#usda 1.0
(
   defaultPrim = "root"
)

def "root"
{
   def Xform "prop"
   {
       def Xform "mugA" (
       )
       {
           def Xform "geo" (
               instanceable = true
               variants = {
                   string usdVariantSet = "high"
               }
               prepend variantSets = "usdVariantSet"
           )
           {
               variantSet "usdVariantSet" = {
                   "high" (
                       prepend payload = @./usdcache-high.usd@
                   ) {

                   }
                   "low" (
                       prepend payload = @./usdcache-low.usd@
                   ) {

                   }
               }
           }
       }

       def Xform "mugA1" (
       )
       {
           def Xform "geo" (
               instanceable = true
               variants = {
                   string usdVariantSet = "high"
               }
               prepend variantSets = "usdVariantSet"
           )
           {
               variantSet "usdVariantSet" = {
                   "high" (
                       prepend payload = @./usdcache-high.usd@
                   ) {

                   }
                   "low" (
                       prepend payload = @./usdcache-low.usd@
                   ) {

                   }
               }
           }
       }
       def Xform "mugA2" (
       )
       {
           def Xform "geo" (
               instanceable = true
               variants = {
                   string usdVariantSet = "high"
               }
               prepend variantSets = "usdVariantSet"
           )
           {
               variantSet "usdVariantSet" = {
                   "high" (
                       prepend payload = @./usdcache-high.usd@
                   ) {

                   }
                   "low" (
                       prepend payload = @./usdcache-low.usd@
                   ) {

                   }
               }
           }
       }
   }
}

is this expected behaviour?
4

That’s what I would expect. There are three unique variant specs, authored at /root/prop/mugA/geo, /root/prop/mugA1/geo, and /root/prop/mugA2/geo, even if they have the same name and opinons.

You could make an abstract prim–

class "sources" (
    over "variantSets" (
        variants = {
            string usdVariantSet = "high"
        }
        prepend variantSets = "usdVariantSet"
    )
    {
        variantSet "usdVariantSet" = {
            "high" (
                prepend payload = @./usdcache-high.usd@
            ) {
            }
            "low" (
                prepend payload = @./usdcache-low.usd@
            ) {
            }
        }
    }
}

and then reference /sources/variantSets that to make the specs the same.

1 Like