.. include:: rolesAndUtils.rst

.. include:: tut_setup_version_badge.rst

================== Authoring Variants

This tutorial walks through authoring a variant set on the HelloWorld layer from :doc:tut_inspect_and_author_props. We begin with the layer :filename:USD/extras/usd/tutorials/authoringVariants/HelloWorld.usda and the Python code :filename:authorVariants.py in the same directory. Please copy these files to a working directory and make them writable.

#. Open the stage and clear the :usda:Sphere's authored :usda: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 :python: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 :ref:usdglossary-livrpsstrengthordering for more details on strength order in USD.

.. code-block:: python

  from pxr import Usd, UsdGeom
  stage = Usd.Stage.Open('HelloWorld.usda')
  colorAttr = UsdGeom.Gprim.Get(stage, '/hello/world').GetDisplayColorAttr()
  colorAttr.Clear()
  print(stage.GetRootLayer().ExportToString())

The :usda:</hello/world> prim is a :usda:Sphere; a schema subclass of :usda:Gprim. So we can use the :python:UsdGeom.Gprim API to work with it. In USD, :usda:Gprim defines :usda:displayColor so all gprim subclasses have it.

.. code-block:: usd :emphasize-lines: 14

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello"
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor
          double radius = 2
      }
  }

The resulting scene description still has the declaration for the displayColor attribute; a future iteration on the :python:Usd.Attribute API may clean this up.

#. Create a shading variant on the root prim called :usda:shadingVariant

.. code-block:: python

  rootPrim = stage.GetPrimAtPath('/hello')
  vset = rootPrim.GetVariantSets().AddVariantSet('shadingVariant')
  print(stage.GetRootLayer().ExportToString())

produces

.. code-block:: usd :emphasize-lines: 7

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello" (
      prepend variantSets = "shadingVariant"
  )
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor
          double radius = 2
      }
  }

#. Create variants within 'shadingVariant' to contain the opinions we will author.

.. code-block:: python

  vset.AddVariant('red')
  vset.AddVariant('blue')
  vset.AddVariant('green')
  print(stage.GetRootLayer().ExportToString())

produces

.. code-block:: usd :emphasize-lines: 20-29

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello" (
      prepend variantSets = "shadingVariant"
  )
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor
          double radius = 2
      }

      variantSet "shadingVariant" = {
          "blue" {
          }

          "green" {
          }

          "red" {
          }
      }
  }

#. Author a red color to the sphere prim :usda:</hello/world> in the :usda:red variant.

To author opinions inside the :usda:red variant we first select the variant, then use a :python:Usd.EditContext. This directs editing into the variant.

.. code-block:: python

  vset.SetVariantSelection('red')
  with vset.GetVariantEditContext():
      colorAttr.Set([(1,0,0)])

  print(stage.GetRootLayer().ExportToString())

If we just invoked :python:colorAttr.Set() without using the variant edit context, we would write a local opinion; specifically the same opinion we cleared at the beginning.

.. code-block:: usd :emphasize-lines: 7-9, 30-35

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello" (
      variants = {
          string shadingVariant = "red"
      }
      prepend variantSets = "shadingVariant"
  )
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor
          double radius = 2
      }

      variantSet "shadingVariant" = {
          "blue" {
          }

          "green" {
          }

          "red" {
              over "world"
              {
                  color3f[] primvars:displayColor = [(1, 0, 0)]
              }
          }
      }
  }

Now :usda:hello has a :usda:shadingVariant with a default variant selection of :usda:red, and the :usda:red variant has an opinion for :usda:displayColor.

#. Author the blue and green variants similarly.

.. code-block:: python

  vset.SetVariantSelection('blue')
  with vset.GetVariantEditContext():
      colorAttr.Set([(0,0,1)])

  vset.SetVariantSelection('green')
  with vset.GetVariantEditContext():
      colorAttr.Set([(0,1,0)])

  print(stage.GetRootLayer().ExportToString())

produces

.. code-block:: usd :emphasize-lines: 24-36

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello" (
      variants = {
          string shadingVariant = "green"
      }
      prepend variantSets = "shadingVariant"
  )
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor
          double radius = 2
      }

      variantSet "shadingVariant" = {
          "blue" {
              over "world"
              {
                  color3f[] primvars:displayColor = [(0, 0, 1)]
              }
          }

          "green" {
              over "world"
              {
                  color3f[] primvars:displayColor = [(0, 1, 0)]
              }
          }

          "red" {
              over "world"
              {
                  color3f[] primvars:displayColor = [(1, 0, 0)]
              }
          }
      }
  }

As mentioned at the beginning, it was important to first :code:Clear() the local opinion for :usda:primvars:displayColor because local opinions are strongest. Had we not cleared the local opinion, the sphere would remain blue regardless of the selected :usda:shadingVariant for this reason.

.. admonition:: Opinion Strength Order

  :ref:`Strength order <usdglossary-livrpsstrengthordering>` is a fundamental
  part of USD.

#. Examine the composed result.

.. code-block:: python

  print(stage.ExportToString(addSourceFileComment=False))

shows

.. code-block:: usd

  #usda 1.0
  (
      defaultPrim = "hello"
  )

  def Xform "hello"
  {
      custom double3 xformOp:translate = (4, 5, 6)
      uniform token[] xformOpOrder = ["xformOp:translate"]

      def Sphere "world"
      {
          float3[] extent = [(-2, -2, -2), (2, 2, 2)]
          color3f[] primvars:displayColor = [(0, 1, 0)]
          double radius = 2
      }

  }

What happened to the variants? :usdcpp:Exporting a UsdStage <UsdStage::Export> writes the composed scene description with all the composition operators (like variants) fully evaluated. We call this :ref:flattening <glossary:Flatten>. :ref:Flattening <glossary:Flatten> the composition applies the opinions from the currently selected variants so we only get the green color due to the last call to :usdcpp:SetVariantSelection() <UsdVariantSet::SetVariantSelection>.

#. Save the edited authoring layer to a new file, :filename:HelloWorldWithVariants.usda

In contrast to exporting a :usdcpp:UsdStage, :usdcpp:exporting an individual layer <SdfLayer::Export> writes its contents as-is to a different file. There is no flattening.

.. code-block:: python

  stage.GetRootLayer().Export('HelloWorldWithVariants.usda')

We could also call :code:Save() to update the original file with the new content.

#. Run :ref:toolset:usdview on :filename:HelloWorldWithVariants.usda.

.. image:: http://openusd.org/images/tut_authoring_variants_helloworld1.png

Click the :usda:hello prim in the tree view on the left. Then click the :guilabel: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.

.. image:: http://openusd.org/images/tut_authoring_variants_helloworld2.png

#. In the interpreter you can see the variant selections that usdview authors to the :ref:session layer <usdglossary-sessionlayer>. 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.

.. code-block:: python

  print(usdviewApi.stage.GetSessionLayer().ExportToString())

shows

.. code-block:: python

  #usda 1.0

  over "hello" (
      variants = {
          string shadingVariant = "red"
      }
  )
  {
  }