USD allows storing multiple named variants of a primitive on the primitive. Each variant can have different attributes, relationships, and children. You can switch the primitive between different variants in different layers. Each primitive can store multiple groups of variants in named variant sets.

The following are some common use cases for variants:

• A family of different geometry (for example, a primitive that can switch between different types of trees).

• Levels of detail (storing progressively lower resolution versions of the same geometry as variants, and switching based on distance to the camera).

  Houdini includes the Create LOD and Auto Select LOD nodes for automating this workflow.

• Material assignments (storing variants with different materials assigned to them to allow switching the look of the primitive easily).

Here is an example of a layer which contains a variant set called owner, where each variant’s color corresponds to which character in the story owns that ball:

#usda 1.0
()

def Sphere "toyBall" (
    variants = {
        string owner = "blake"
    }
    append variantSets = "owner"
)
{
    double radius = 1
    variantSet "owner" = {
        "andy" (
        ) {
            color3f[] primvars:displayColor = [(1, 0, 0)] (
                interpolation = "constant"
            )


        }
        "blake" (
        ) {
            color3f[] primvars:displayColor = [(0, 0, 1)] (
                interpolation = "constant"
            )


        }
        "sally" (
        ) {
            color3f[] primvars:displayColor = [(0, 1, 0)] (
                interpolation = "constant"
            )


        }
    }
}

See Variant Set in Pixar USD glossary

1. Connect the “main” stage line to the node’s first input.

2. Set the Primitive path to the path of the primitive you want to add the variant to, and the name of the Variant set to add the variant to on the primitive.

   This node will create a primitive at the given path(s) and any parent prims if they don’t exist. The Primitive kind and Parent primitive type parameters control what type of primitives to create in this case.

   Optionally, you can supply an explicit list of space separated primitive paths to Primitive path, or a prim pattern pointing to existing prims on the stage, to add the variant to multiple primitives.

3. Connect a stage containing the variant primitive you want to add to the second multi-input.

   Often, this “variant” input will not be a “full” stage, but just the result of importing geometry from a SOP network or from disk into USD.

   If the primitive branch you want to use as a variant already exists on the “main” stage, you can connect the “main” stage line to both the first and second inputs.

4. Set the Variant path to the path to the primitive that defines the variant you will add. (This path is in the scene graph tree of the second input.)

5. In the table at the bottom of the parameter editor, double-click the right column next to the input node to and enter the name for this variant in the variant set.

   (If you don’t specify a name, one is computed automatically using the expression in the Variant name default parameter.)

   The variant copied from the second input into the variant set includes the primitive you point to in Variant path and all its descendants.

• The node sets the context option VARIANT to the name of the variant being defined as it cooks each input. This allows the input nodes to respond to the variant name set on this node, or to have the same input node connected to this node multiple times, and produce unique output for each variant name.

  The node also sets the context option VARIANTINPUT to the input number of each variant as each is cooked. This allows per-variant responses which don’t depend on the variant name directly.

  The node also sets the context option VARIANTPRIM to the primpath of the prim to which the variant is currently being added. This allows per-variant responses to the primpath the variant is being added to when adding the variant to multiple prims at once.

  These context options are also available to the parameters of the Add Variant node, allowing the selection of Variant Source Primitive or Source Primitive based on variant name or the primpath the variant is being added to, etc.

• The layers of the stage connected to the second input are always “flattened” into a single layer to allow copying all the information defining the variant into the active layer.

• The contents of the flattened layer are completely unchanged by the copy operation, so defined primitives will be defined inside the variant, and over primitives will be over primitives inside the variant.

• USD imposes no restrictions on the contents of variants. If further opinions are going to be expressed on the primitive specified in Primitive path or its children, you may want to provide a consistent structure to the data of each variant (so the later opinions “fit” correctly no matter which variant is currently selected), but that is completely optional.

• If you want to use variants for level of detail, check out the Create LOD and Auto Select LOD nodes.

• If you are using variants to switch between different material assignments, the content of each variant should be very similar. When authoring these material assignment overrides, you will want to be able to see the effect of these assignments in context before using them to create the variants.

  Typically, this means all the variants will be branches off the same input LOP node, likely the same LOP node connected to the first input of this Add Variant node.

  Use a Layer Break node before each set of material assignments to strip out all information above the Layer Break during flattening, resulting in each variant input copying only the material assignment overrides to the variant definition.

• If the given name in the given variant set on the given primitive already exists, the node copies the primitives from the variant input without any attention to the existing variant. If the existing variant was defined in the active layer, some or all of the existing primitives may be overwritten. If the existing variant was in a layer other than the active layer, the information from the new variant will be composed as a stronger layer over the existing primitives.

• If you don’t add any variants using the second multi-input, this node passes through the stage from the first input unchanged.

• To select a variant on a USD primitive, use the Set Variant LOP.

• Opinions expressed in variants are weaker than opinions expressed in the local layer stack. This strength ordering can make it appear that the variant is having no effect on the primitive. The option to Warn of weak variant opinions will add a warning to this node if this situation is detected. In this case, the simplest solution is to enable the use of a separate Source primitive. Set the Source primitive to the current value of the Primitive path, and set the Primitive path to a new path where the variants will be created, using a reference to the Source primitive. Opinions expressed in variants are stronger than opinions expressed in references, so the opinions in the variant will be composed onto the stage as expected.

  If you want to reference a Source primitive onto multiple Primitive paths at once, then you must supply a space separated list of explicit primitive paths that do not currently exist on the stage. A primitive pattern will not work in this case, since it would only find existing primitives.

  Additionally, you can make use of the VARIANTPATH context option to vary the Source primitive per primitive when specifying multiple Primitive paths.