Standardize handedness transform to match other file format (FTV-299)

package/com.unity.formats.usd/Runtime/Scripts/Behaviors/UsdAsset.cs

@@ -264,6 +264,7 @@ private void OnDestroy() {
     private string GetPrefabAssetPath(GameObject root) {
       string assetPath = null;
 #if UNITY_EDITOR
+// TODO: According to Yamato we don't support version of Unity earlier to this one. Is this really necessary?
 #if !UNITY_2018_3_OR_NEWER
       assetPath = UnityEditor.AssetDatabase.GetAssetPath(
               UnityEditor.PrefabUtility.GetPrefabObject(root));
@@ -272,7 +273,11 @@ private string GetPrefabAssetPath(GameObject root) {
         var prefabStage = UnityEditor.Experimental.SceneManagement.PrefabStageUtility.GetPrefabStage(root);
         if (prefabStage != null) {
           if (!UnityEditor.PrefabUtility.IsPartOfPrefabInstance(root)) {
+#if UNITY_2020_1_OR_NEWER
+            assetPath = prefabStage.assetPath;
+#else
             assetPath = prefabStage.prefabAssetPath;
+#endif
             // This is a great resource for determining object type, but only covers new APIs:
             // https://github.com/Unity-Technologies/UniteLA2018Examples/blob/master/Assets/Scripts/GameObjectTypeLogging.cs
           }

package/com.unity.formats.usd/Runtime/Scripts/IO/Scene/SceneImportOptions.cs

@@ -36,6 +36,15 @@ public enum BasisTransformation {
     /// </summary>
     SlowAndSafe,
 
+    /// <summary>
+    /// Transform to left-handed basis by processing all positions, triangles, transforms, and
+    /// primvar data. It transforms to match the basis transformation of FBX which is from (X,Y,Z) to (-X,Y,Z)
+    /// instead of the standard (SlowAndSafe option) (X,Y,Z) to (X,Y,-Z).
+    /// This is not a conventional behavior and this option is here only to allow consistency between
+    /// geometry importers.
+    /// </summary>
+    SlowAndSafeAsFBX,
+
     /// <summary>
     /// Preform no transformation; should only be used when the USD file is known to contain
     /// data which was (non-portably) stored in a left-handed basis.

package/com.unity.formats.usd/Runtime/Scripts/IO/Scene/SceneImporter.cs

@@ -252,6 +252,23 @@ public static void ImportUsd(GameObject goRoot,
         throw new ImportException("Null USD Scene");
       }
 
+      // The matrix to convert USD (right-handed) to Unity (left-handed) is different for the legacy FBX importer
+      // and incorrectly swaps the X-axis rather than the Z-axis. This changes the basisChange matrix to match the
+      // user options. <see cref="Unity.Formats.USD.SceneImportOptions.BasisTransformation"/> for additional details.
+      // Note that in those specific cases, the inverse matrix are identical to the original one, in general,
+      // UnityTypeConverter.inverseBasisChange should be equal to UnityTypeConverter.basisChange.inverse.
+      if (importOptions.changeHandedness == BasisTransformation.SlowAndSafeAsFBX) {
+        // To be consistent with FBX basis change, ensure it's the X axis that is inverted.
+        Vector3 matrixDiagonal = new Vector3(-1, 1, 1);
+        UnityTypeConverter.basisChange = Matrix4x4.Scale(matrixDiagonal);
+        UnityTypeConverter.inverseBasisChange = Matrix4x4.Scale(matrixDiagonal);
+      } else {
+        // Ensure it's the Z axis that is inverted.
+        Vector3 matrixDiagonal = new Vector3(1, 1, -1);
+        UnityTypeConverter.basisChange = Matrix4x4.Scale(matrixDiagonal);
+        UnityTypeConverter.inverseBasisChange = Matrix4x4.Scale(matrixDiagonal);
+      }
+
       scene.SetInterpolation(importOptions.interpolate ?
                              Scene.InterpolationMode.Linear :
                              Scene.InterpolationMode.Held);

src/USD.NET.Unity/UnityTypeConverter.cs

@@ -18,33 +18,33 @@
 using pxr;
 
 namespace USD.NET.Unity {
+
   public class UnityTypeConverter : IntrinsicTypeConverter {
 
+    /// <summary>
+    /// Configurable matrix used for change of basis from USD to Unity and vice versa (change handedness).
+    /// </summary>
+    /// <remarks>
+    /// Allows global configuration of the change of basis matrix, which e.g. is used to make the USD importer conform
+    /// to the legacy FBX import convention in Unity, swapping the X-axis instead of the Z-axis.
+    /// By default this matrix is set to change handedness by swapping the Z-axis.
+    /// </remarks>
+    public static UnityEngine.Matrix4x4 basisChange = UnityEngine.Matrix4x4.Scale(new UnityEngine.Vector3(1, 1, -1));
+    public static UnityEngine.Matrix4x4 inverseBasisChange = UnityEngine.Matrix4x4.Scale(new UnityEngine.Vector3(1, 1, -1));
+
     /// <summary>
     /// Converts to and from the USD transform space.
     /// This method should be applied to all Unity matrices before being written and all USD
     /// matrices after being read, unless the USD file is stored in the Unity transform space
     /// (though doing so will result in a non-standard USD file).
     /// </summary>
     static public UnityEngine.Matrix4x4 ChangeBasis(UnityEngine.Matrix4x4 input) {
-      // TODO(jcowles): the change of basis matrix should probably be cached.
-      var basisChange = UnityEngine.Matrix4x4.identity;
-      // Invert the forward vector.
-      basisChange[2, 2] = -1;
-
-      // Note that the fully general solution is basisChange * m * basisChange.inverse, however
-      // basisChange and basisChange.inverse are identical. Just aliasing here so the math below
-      // reads correctly.
-      var basisChangeInverse = basisChange;
-
       // Furthermore, this could be simplified to multiplying -1 by input elements [2,6,8,9,11,14].
-      return basisChange * input * basisChangeInverse;
+      return UnityTypeConverter.basisChange * input * UnityTypeConverter.inverseBasisChange;
     }
 
     public static UnityEngine.Vector3 ChangeBasis(UnityEngine.Vector3 point) {
-      UnityEngine.Matrix4x4 mat = UnityEngine.Matrix4x4.identity;
-      mat[2, 2] = -1;
-      return mat.MultiplyPoint3x4(point);
+      return UnityTypeConverter.basisChange.MultiplyPoint3x4(point);
     }
 
     /// <summary>