MAYA-128599 fixing pivot command

In order to be able to apply some Maya more sophisticated transformations on USD prim that already use the USD common xform stack, we need to be able to use the Maya xform stack UFE Transformer3d. But that only accepted to be use if the existing USD form stack matched the Maya one. Unfortunately, the USD common API pivot ws not found in teh Maya stack.

Adding the common pivot to the Maya stack allows using the Maya transferm 3d on the USD common stack, allowing more complex operations on the pivot.

The real problem is that the chain of responsibility design pattern locks which xform-editor is used and thus what can be applied on the xform based on what opinions are already authored. Once chosen, the xform editor cannot be changed. This means some Maya operations cannot ever be applied on that prim.

The real solution would be to allow conversions between differnt xform representations. These conversions would be triggered when an operation not supported by the current xform representation need to be applied.

Concretely, instead of having multiple classes dereived from UFE Transform3d and which is used chosen at the time the Transform3d is created, we would have a single Transform3d class which would contain multiple implementations of the API and which implementation is used could change dynamically, with the USD xform representation converted from one to the other. It would be more of a hierarchy of more and more complex and complete representation of xform, with conversion from simpler forms to more complex forms.

Also:
- Remove spurious error generated by MayaSessionState.
- Add a unit test for center pivot command
- Fix unit test that expect that Maya stack cannot handle a custom xform stack: make the xform names really unique. The new change was able to handle the stack unit by the test.
- Add documentations about transforms

doc/USD Transforms Stack.md

@@ -0,0 +1,74 @@
+# USD Transforms Stack
+
+## Take Aways
+
+- Understand the USD transform stack (xformOp)
+- Know the available USD transform ops
+- Know the structure of the USD transform stack
+- Know how it maps to UFE
+- Know the various implementations of xformOp in MayaUSD
+
+## What is a USD Transform stack
+
+- Control the 3D position of a USD prim
+- It is  an ordered list of transform operations (xformOp):
+  translation, rotation, scale, 4x4 matrix
+- USD supports any number of xformOp, in any order
+- An individual xformOp is kept in a USD attribute
+- All transform-related attributes begin with the "xformOp:" prefix
+- An xformOp attribute name has two or three parts:
+    - "xformOp:"
+    - the transform type
+    - optional suffix
+- For example: "xformOp:translate:pivot"
+- The xformOp order is kept in a special attribute: "xformOpOrder"
+
+## Quick Recap on Pivot
+
+Pivots...
+
+- ... are generally neutral: they don't move the prim
+- ... come as a pair of opposite translations, sandwhiching other transforms
+- ... are used in DCC to position the center of rotation and center of scaling
+
+## Quick Recap on Transform Maths
+
+- A single matrix is equivalent to any number of chained transforms
+- The inverse is not true
+- Some matrices cannot be expressed with translation, rotation and scaling...
+- ... but they are generally considered degenerate and are rarely seen
+- On the other hand, matrix cannot express pivot pairs, since they are neutral
+- In general, except for pivots, all transform representations are equivalent
+
+## USD Common Transform Stack
+
+- USD provides a recommended, simple transform stack it calls the "common API"
+- The goal is to have a baseline transform stack that all DCC should support
+- The USD common stack structure is: translate, pivot, rotate, scale
+- In particular, the pivot wraps both the rotation and scaling, unlike Maya
+
+## UFE Transforms
+
+UFE Transform3d ...
+
+- ... allows modifying a UFE scene item transforms
+- ... is created by the registered UFE Transform3dHandler
+- ... creates commands that when executed changes the transform
+- ... does *not* prescribe how the various transforms interact
+- ... is implicitly tied to Maya's view of how transforms are ordered
+
+## MayaUSD XformOp Implementations
+
+- MayaUSD provides multiple UFE Transform3d implementations
+- The implementations are: point instance, Maya stack, USD common API, 4x4 matrix and no comprendo + Maya stack
+- For the rest of the presentation, we will ignore point instance and no comprendo
+
+## MayaUSD XformOp Details
+
+- Only the Maya stack supports all the UFE commands. In particular, pivot commands
+- Which one is used is decided at the time of the creation of the Transform3d
+- Once decided, there is no turning back, we cannot switch dynamically
+- The decision is based on what is already authored on the prim
+- In case multiple implementations could be used, the priority order is: Maya stack, common API, matrix
+- The main goal was that we would privilege the Maya stack, but still support the others representations
+- One design decision is to *not* convert between representations

lib/mayaUsd/fileio/utils/xformStack.cpp

@@ -437,10 +437,11 @@ UsdMayaXformStack::MatchingSubstack(const std::vector<UsdGeomXformOp>& xformops)
 
         if (GetNameMatters()) {
             // First try the fast attrName lookup...
-            const auto foundTokenIdxPairIter
-                = _sharedData->m_attrNamesToIdxs.find(xformOp.GetName());
+            const TfToken& opName = xformOp.GetName();
+            const auto     foundTokenIdxPairIter = _sharedData->m_attrNamesToIdxs.find(opName);
             if (foundTokenIdxPairIter == _sharedData->m_attrNamesToIdxs.end()) {
                 // Couldn't find the xformop in our stack, abort
+                // TF_WARN("Cannot find xform op %s", opName.GetText());
                 return _NO_MATCH;
             }
 
@@ -455,13 +456,21 @@ UsdMayaXformStack::MatchingSubstack(const std::vector<UsdGeomXformOp>& xformops)
             } else {
                 // The result we found is before an earlier-found op,
                 // so it doesn't match our stack... abort.
+                // TF_WARN(
+                //     "Cannot find index of xform op %s at %ld between [%ld, %ld]",
+                //     opName.GetText(),
+                //     long(nextOpIndex),
+                //     long(foundIdxPair.first),
+                //     long(foundIdxPair.second));
                 return _NO_MATCH;
             }
 
             assert(foundOpIdx != NO_INDEX);
+            // TF_STATUS("Found xform op %s at %ld", opName.GetText(), long(foundOpIdx));
 
             // Now check that the op type matches...
             if (!GetOps()[foundOpIdx].IsCompatibleType(xformOp.GetOpType())) {
+                // TF_WARN("Incorrect type for xform op %s", opName.GetText());
                 return _NO_MATCH;
             }
         } else {
@@ -489,7 +498,10 @@ UsdMayaXformStack::MatchingSubstack(const std::vector<UsdGeomXformOp>& xformops)
     // check pivot pairs
     TF_FOR_ALL(pairIter, GetInversionTwins())
     {
-        if (opNamesFound[pairIter->first] != opNamesFound[pairIter->second]) {
+        const size_t firstIdx = pairIter->first;
+        const size_t secondIdx = pairIter->second;
+        if (opNamesFound[firstIdx] != opNamesFound[secondIdx]) {
+            // TF_WARN("Unmatched pivot pairs at [%ld, %ld]", firstIdx, secondIdx);
             return _NO_MATCH;
         }
     }
@@ -519,36 +531,45 @@ const UsdMayaXformStack& UsdMayaXformStack::MayaStack()
 {
     static UsdMayaXformStack mayaStack(
         // ops
-        { UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->translate, UsdGeomXformOp::TypeTranslate),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->rotatePivotTranslate, UsdGeomXformOp::TypeTranslate),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->rotatePivot, UsdGeomXformOp::TypeTranslate),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->rotate, UsdGeomXformOp::TypeRotateXYZ),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->rotateAxis, UsdGeomXformOp::TypeRotateXYZ),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->rotatePivot,
-              UsdGeomXformOp::TypeTranslate,
-              true /* isInvertedTwin */),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->scalePivotTranslate, UsdGeomXformOp::TypeTranslate),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->scalePivot, UsdGeomXformOp::TypeTranslate),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->shear, UsdGeomXformOp::TypeTransform),
-          UsdMayaXformOpClassification(UsdMayaXformStackTokens->scale, UsdGeomXformOp::TypeScale),
-          UsdMayaXformOpClassification(
-              UsdMayaXformStackTokens->scalePivot,
-              UsdGeomXformOp::TypeTranslate,
-              true /* isInvertedTwin */) },
+        {
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->translate, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->pivot, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->rotatePivotTranslate, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->rotatePivot, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->rotate, UsdGeomXformOp::TypeRotateXYZ),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->rotateAxis, UsdGeomXformOp::TypeRotateXYZ),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->rotatePivot,
+                UsdGeomXformOp::TypeTranslate,
+                true /* isInvertedTwin */),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->scalePivotTranslate, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->scalePivot, UsdGeomXformOp::TypeTranslate),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->shear, UsdGeomXformOp::TypeTransform),
+            UsdMayaXformOpClassification(UsdMayaXformStackTokens->scale, UsdGeomXformOp::TypeScale),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->scalePivot,
+                UsdGeomXformOp::TypeTranslate,
+                true /* isInvertedTwin */),
+            UsdMayaXformOpClassification(
+                UsdMayaXformStackTokens->pivot,
+                UsdGeomXformOp::TypeTranslate,
+                true /* isInvertedTwin */),
+        },
 
         // inversionTwins
         {
-            { 2, 5 },
-            { 7, 10 },
+            { 1, 12 },
+            { 3, 6 },
+            { 8, 11 },
         });
 
     return mayaStack;

lib/mayaUsd/ufe/UsdTransform3dMayaXformStack.cpp

@@ -75,6 +75,8 @@ PXR_NS::UsdAttribute getUsdPrimAttribute(const UsdPrim& prim, const TfToken& att
 const std::unordered_map<TfToken, UsdTransform3dMayaXformStack::OpNdx, TfToken::HashFunctor>
     gOpNameToNdx {
         { TfToken("xformOp:translate"), UsdTransform3dMayaXformStack::NdxTranslate },
+        // Note: this matches the USD common xformOp name.
+        { TfToken("xformOp:translate:pivot"), UsdTransform3dMayaXformStack::NdxPivot },
         { TfToken("xformOp:translate:rotatePivotTranslate"),
           UsdTransform3dMayaXformStack::NdxRotatePivotTranslate },
         { TfToken("xformOp:translate:rotatePivot"), UsdTransform3dMayaXformStack::NdxRotatePivot },
@@ -97,7 +99,10 @@ const std::unordered_map<TfToken, UsdTransform3dMayaXformStack::OpNdx, TfToken::
         { TfToken("xformOp:transform:shear"), UsdTransform3dMayaXformStack::NdxShear },
         { TfToken("xformOp:scale"), UsdTransform3dMayaXformStack::NdxScale },
         { TfToken("!invert!xformOp:translate:scalePivot"),
-          UsdTransform3dMayaXformStack::NdxScalePivotInverse }
+          UsdTransform3dMayaXformStack::NdxScalePivotInverse },
+        // Note: this matches the USD common xformOp name.
+        { TfToken("!invert!xformOp:translate:pivot"),
+          UsdTransform3dMayaXformStack::NdxPivotInverse }
     };
 
 } // namespace

lib/mayaUsd/ufe/UsdTransform3dMayaXformStack.h

@@ -41,6 +41,7 @@ class MAYAUSD_CORE_PUBLIC UsdTransform3dMayaXformStack : public UsdTransform3dBa
     enum OpNdx
     {
         NdxTranslate = 0,
+        NdxPivot,
         NdxRotatePivotTranslate,
         NdxRotatePivot,
         NdxRotate,
@@ -51,6 +52,7 @@ class MAYAUSD_CORE_PUBLIC UsdTransform3dMayaXformStack : public UsdTransform3dBa
         NdxShear,
         NdxScale,
         NdxScalePivotInverse,
+        NdxPivotInverse,
         NbOpNdx
     };
 

lib/usd/ui/layerEditor/mayaSessionState.cpp

@@ -82,9 +82,11 @@ bool MayaSessionState::getStageEntry(StageEntry* out_stageEntry, const MString&
 
     MObject shapeObj;
     MStatus status = UsdMayaUtil::GetMObjectByName(shapePath, shapeObj);
-    CHECK_MSTATUS_AND_RETURN(status, false);
+    if (!status)
+        return false;
     MFnDagNode dagNode(shapeObj, &status);
-    CHECK_MSTATUS_AND_RETURN(status, false);
+    if (!status)
+        return false;
 
     if (const UsdMayaUsdPrimProvider* usdPrimProvider
         = dynamic_cast<const UsdMayaUsdPrimProvider*>(dagNode.userNode())) {
@@ -303,7 +305,7 @@ void MayaSessionState::loadSelectedStage()
 #if defined(WANT_UFE_BUILD)
     const std::string shapePath = MayaUsd::LayerManager::getSelectedStage();
     StageEntry        entry;
-    if (getStageEntry(&entry, shapePath.c_str())) {
+    if (!shapePath.empty() && getStageEntry(&entry, shapePath.c_str())) {
         setStageEntry(entry);
     }
 #endif