Variant Sets Basics#

What Are Variant Sets?#

Variant sets let you define alternative representations for a prim and switch between them without duplicating data. Typical uses include model shapes, materials or looks, and LODs. When you select a variant, USD composes the opinions authored for that variant at the prim where the variant set is defined.

How Does It Work?#

A prim can have one or more named variant sets. Each variant set contains variants (choices). A variant selection can be authored on the same layer that defines the set or in a different layer that references the prim, so each reference can pick a different option. You author data “inside a variant” by selecting it and opening a variant edit context; opinions authored in that context apply only when that variant is active. Standard strength ordering rules still apply; we will dive deeper into LIVRPS later.

Working With Python#

The essential APIs live on UsdPrim, UsdVariantSets, and UsdVariantSet:

 1# On a prim:
 2prim.GetVariantSets() # -> UsdVariantSets
 3vsets = prim.GetVariantSets()
 4vset  = vsets.AddVariantSet("name")  # -> UsdVariantSet (create or get)
 5vset.AddVariant("ChoiceA")  # add a variant
 6vset.SetVariantSelection("ChoiceA") # select a variant
 7
 8# Author opinions inside a variant:
 9with vset.GetVariantEditContext():
10    # All specs authored in this 'with' go inside the selected variant
11    ...
12
13# Other useful calls:
14vset.GetVariantNames()  # ["ChoiceA", "ChoiceB", ...]
15vset.GetVariantSelection()  # currently selected name or ""
16vset.ClearVariantSelection()  # remove selection at edit target

Key Takeaways#

  • A variant set provides named choices for a prim. A variant is one choice. Selecting a variant composes the opinions authored for that choice at that prim.

  • Author data inside a variant by selecting it and using GetVariantEditContext(). Those opinions only apply when that variant is active.

  • Variant selections can be authored in different layers, letting each reference pick a different option. Overall results still follow USD strength ordering; covered in more depth in a later lesson.