This tutorial walks through authoring a variant set on the HelloWorld layer from Inspecting and Authoring Properties. We begin with the layer USD/extras/usd/tutorials/authoringVariants/HelloWorld.usda and the Python code authorVariants.py in the same directory. Please copy these files to a working directory and make them writable.
Open the stage and clear the Sphere’s authored displayColor opinion. In USD local opinions are stronger than variant opinions. So if we do not clear this opinion it will win over those we author within variants below.
To see this in action, comment out the Clear() and run the tutorial. The steps below still author the same variant opinions, but the composed result shows the locally-authored blue color. That stronger local opinion overrides the opinions from variants.
See LIVRPS Strength Ordering for more details on strength order in USD.
The </hello/world> prim is a Sphere; a schema subclass of Gprim. So we can use the UsdGeom.Gprim API to work with it. In USD, Gprim defines displayColor so all gprim subclasses have it.
Create variants within ‘shadingVariant’ to contain the opinions we will author.
Author a red color to the sphere prim </hello/world> in the red variant.
To author opinions inside the red variant we first select the variant, then use a Usd.EditContext. This directs editing into the variant.
If we just invoked colorAttr.Set() without using the variant edit context, we would write a local opinion; specifically the same opinion we cleared at the beginning.
Now hello has a shadingVariant with a default variant selection of red, and the red variant has an opinion for displayColor.
As mentioned at the beginning, it was important to first Clear() the local opinion for primvars:displayColor because local opinions are strongest. Had we not cleared the local opinion, the sphere would remain blue regardless of the selected shadingVariant for this reason.
Strength order is a fundamental part of USD.
Examine the composed result.
What happened to the variants? Exporting a UsdStage writes the composed scene description with all the composition operators (like variants) fully evaluated. We call this flattening. Flattening the composition applies the opinions from the currently selected variants so we only get the green color due to the last call to SetVariantSelection().
In contrast to exporting a UsdStage, exporting an individual layer writes its contents as-is to a different file. There is no flattening.
We could also call Save() to update the original file with the new content.
Run usdview on HelloWorldWithVariants.usda.
Click the hello prim in the tree view on the left. Then click the Meta Data tab in the lower right. You will see the authored variant set with a combo box that can toggle the variant selection between red, blue, and green.
In the interpreter you can see the variant selections that usdview authors to the session layer. This is the same sparse override you would see if you referenced this layer into another one and authored the variant selection in the referencing layer.
