Use "mtl" as default scope name on export

lib/mayaUsd/commands/Readme.md

@@ -255,9 +255,16 @@ primitive. The original name will be preserved in custom data for roundtripping.
 
 #### Material Scopes
 
-The default material scope when exporting materials is named `mtl`. Users can
-change this default material scope name by setting the environment variable
-named `MAYAUSD_MATERIALS_SCOPE_NAME`.
+The recommended way of selecting a global scope name for materials is to use the
+materialsScopeName argument of MayaUSDExportCommand.
+
+If that argument is not specified, we will use "mtl" as a globally defined default.
+This follows the [Guidelines for Structuring USD Assets](https://wiki.aswf.io/display/WGUSD/Guidelines+for+Structuring+USD+Assets)
+as defined by the USD Assets WG.
+
+The `MAYAUSD_MATERIALS_SCOPE_NAME` environment variable can be used to change
+that default on a global level. The value defined in that env var will take
+precedence over any value passed in the materialsScopeName argument.
 
 This environment variable was added in part to support legacy user of mayaUSD:
 in past versions of the plugin, the material scope was named `Looks`. The change

lib/mayaUsd/fileio/jobs/jobArgs.cpp

@@ -26,6 +26,7 @@
 #include <pxr/base/tf/diagnostic.h>
 #include <pxr/base/tf/envSetting.h>
 #include <pxr/base/tf/fileUtils.h>
+#include <pxr/base/tf/getenv.h>
 #include <pxr/base/tf/staticTokens.h>
 #include <pxr/base/tf/token.h>
 #include <pxr/base/vt/array.h>
@@ -78,6 +79,10 @@ TF_DEFINE_PRIVATE_TOKENS(
 
 namespace {
 
+// Default material scope name as defined by USD Assets working group.
+// See https://wiki.aswf.io/display/WGUSD/Guidelines+for+Structuring+USD+Assets
+static constexpr auto kDefaultMaterialScopeName = "mtl";
+
 using namespace MayaUsd::DictUtils;
 
 // The chaser args are stored as vectors of vectors (since this is how you
@@ -176,6 +181,12 @@ TfToken _GetMaterialsScopeName(const std::string& materialsScopeName)
         // If the env setting is set, make sure we don't allow the materials
         // scope name to be overridden by a parameter value.
         return defaultMaterialsScopeName;
+    } else {
+        const std::string mayaUsdDefaultMaterialsScopeName
+            = TfGetenv("MAYAUSD_MATERIALS_SCOPE_NAME");
+        if (!mayaUsdDefaultMaterialsScopeName.empty()) {
+            return TfToken(mayaUsdDefaultMaterialsScopeName);
+        }
     }
 
     if (SdfPath::IsValidIdentifier(materialsScopeName)) {
@@ -826,8 +837,7 @@ const VtDictionary& UsdMayaJobExportArgs::GetDefaultDictionary()
         d[UsdMayaJobExportArgsTokens->kind] = std::string();
         d[UsdMayaJobExportArgsTokens->disableModelKindProcessor] = false;
         d[UsdMayaJobExportArgsTokens->materialCollectionsPath] = std::string();
-        d[UsdMayaJobExportArgsTokens->materialsScopeName]
-            = UsdUtilsGetMaterialsScopeName().GetString();
+        d[UsdMayaJobExportArgsTokens->materialsScopeName] = kDefaultMaterialScopeName;
         d[UsdMayaJobExportArgsTokens->melPerFrameCallback] = std::string();
         d[UsdMayaJobExportArgsTokens->melPostCallback] = std::string();
         d[UsdMayaJobExportArgsTokens->mergeTransformAndShape] = true;
@@ -940,6 +950,11 @@ const VtDictionary& UsdMayaJobExportArgs::GetGuideDictionary()
     return d;
 }
 
+const std::string UsdMayaJobExportArgs::GetDefaultMaterialsScopeName()
+{
+    return _GetMaterialsScopeName(kDefaultMaterialScopeName);
+}
+
 std::string UsdMayaJobExportArgs::GetResolvedFileName() const
 {
     MFileObject fileObj;

lib/mayaUsd/fileio/jobs/jobArgs.h

@@ -124,7 +124,7 @@ TF_DECLARE_PUBLIC_TOKENS(
     /* geomSidedness values */ \
     (derived)                             \
     (single)                              \
-    ((double_, "double"))                                          \
+    ((double_, "double"))
 // clang-format on
 
 TF_DECLARE_PUBLIC_TOKENS(
@@ -294,6 +294,12 @@ struct UsdMayaJobExportArgs
     MAYAUSD_CORE_PUBLIC
     static const VtDictionary& GetGuideDictionary();
 
+    /// Gets the resolved default material scope name.
+    ///
+    /// Accounts for all env vars that can affect the scope name.
+    MAYAUSD_CORE_PUBLIC
+    static const std::string GetDefaultMaterialsScopeName();
+
     /// Returns the resolved file name of the final export location
     MAYAUSD_CORE_PUBLIC
     std::string GetResolvedFileName() const;

lib/mayaUsd/python/wrapPrimWriter.cpp

@@ -592,7 +592,9 @@ void wrapJobExportArgs()
                 &UsdMayaJobExportArgs::usdModelRootOverridePath,
                 return_value_policy<return_by_value>()))
         .def_readonly("verbose", &UsdMayaJobExportArgs::verbose)
-        .def("GetResolvedFileName", &UsdMayaJobExportArgs::GetResolvedFileName);
+        .def("GetResolvedFileName", &UsdMayaJobExportArgs::GetResolvedFileName)
+        .def("GetDefaultMaterialsScopeName", &UsdMayaJobExportArgs::GetDefaultMaterialsScopeName)
+        .staticmethod("GetDefaultMaterialsScopeName");
 }
 
 void wrapPrimWriter()

lib/mayaUsd/ufe/UsdUndoMaterialCommands.cpp

@@ -15,10 +15,9 @@
 //
 #include "UsdUndoMaterialCommands.h"
 
+#include <mayaUsd/fileio/jobs/jobArgs.h>
 #include <mayaUsd/ufe/Utils.h>
 
-#include <pxr/base/tf/envSetting.h>
-#include <pxr/base/tf/getenv.h>
 #include <pxr/usd/sdr/registry.h>
 #include <pxr/usd/sdr/shaderProperty.h>
 #include <pxr/usd/usd/prim.h>
@@ -286,17 +285,7 @@ Ufe::SceneItem::Ptr UsdUndoAssignNewMaterialCommand::insertedChild() const
 
 std::string UsdUndoAssignNewMaterialCommand::resolvedMaterialScopeName()
 {
-    std::string materialsScopeName = kDefaultMaterialScopeName;
-    if (TfGetEnvSetting(USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME)) {
-        materialsScopeName = UsdUtilsGetMaterialsScopeName().GetString();
-    } else {
-        const std::string mayaUsdDefaultMaterialsScopeName
-            = TfGetenv("MAYAUSD_MATERIALS_SCOPE_NAME");
-        if (!mayaUsdDefaultMaterialsScopeName.empty()) {
-            materialsScopeName = mayaUsdDefaultMaterialsScopeName;
-        }
-    }
-    return materialsScopeName;
+    return UsdMayaJobExportArgs::GetDefaultMaterialsScopeName();
 }
 
 void UsdUndoAssignNewMaterialCommand::execute()

plugin/adsk/scripts/mayaUsdTranslatorExport.mel

@@ -219,14 +219,6 @@ proc string mayaUsdTranslatorExport_AppendFromTextField(string $currentOptions,
     return $currentOptions + ";" + $arg + "=" + $value;
 }
 
-proc string mayaUsdTranslatorExport_AppendFromEnvElseDefault(string $currentOptions, string $arg, string $envVarName, string $defaultValue) {
-    string $value = `getenv $envVarName`;
-    if ($value == "") {
-        $value = $defaultValue;
-    }
-    return $currentOptions + ";" + $arg + "=" + $value;
-}
-
 global proc mayaUsdTranslatorExport_AnimationCB() {
     if (`checkBoxGrp -exists animationCheckBox` == 0)
         return;
@@ -797,8 +789,6 @@ global proc int mayaUsdTranslatorExport (string $parent,
             $currentOptions = mayaUsdTranslatorExport_AppendJobContexts($currentOptions, "jobContext");
         }
 
-        $currentOptions = mayaUsdTranslatorExport_AppendFromEnvElseDefault($currentOptions, "materialsScopeName", "MAYAUSD_MATERIALS_SCOPE_NAME", `getMayaUsdString("kExportMaterialsDefaultScopeName")`);
-
         eval($resultCallback+" \""+$currentOptions+"\"");
         $bResult = 1;
 

test/lib/CMakeLists.txt

@@ -17,7 +17,6 @@ endif()
 # Interactive Unit test scripts.
 set(INTERACTIVE_TEST_SCRIPT_FILES
     testMayaUsdInteractiveLayerEditorCommands.py
-    testMayaUsdInteractiveMaterialsScopeName.py
 )
 
 foreach(script ${TEST_SCRIPT_FILES})

test/lib/mayaUsd/fileio/CMakeLists.txt

@@ -49,6 +49,7 @@ foreach(script ${TEST_SCRIPT_FILES})
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         ENV
             "UFE_PREVIEW_VERSION_NUM=${UFE_PREVIEW_VERSION_NUM}"
+            "USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME=1"
     )
 
     # Add a ctest label to these tests for easy filtering.

test/lib/usd/pxrUsdPreviewSurface/CMakeLists.txt

@@ -17,6 +17,8 @@ foreach(script ${TEST_SCRIPT_FILES})
     mayaUsd_add_test(${target}
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
         PYTHON_MODULE ${target}
+        ENV
+            "USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME=1"
     )
     set_property(TEST ${target} APPEND PROPERTY LABELS usdPreviewSurface)
 endforeach()

test/lib/usd/translators/CMakeLists.txt

@@ -6,7 +6,6 @@ set(TEST_SCRIPT_FILES
     testUsdExportCamera.py
     testUsdExportColorSets.py
     testUsdExportConnected.py
-    testUsdExportDisplacement.py
     testUsdExportDisplayColor.py
     testUsdExportEulerFilter.py
     testUsdExportFileFormat.py
@@ -39,8 +38,6 @@ set(TEST_SCRIPT_FILES
     testUsdExportRootsAndParentScope.py
     testUsdExportSelection.py
     testUsdExportSelectionHierarchy.py
-    testUsdExportShadingInstanced.py
-    testUsdExportShadingModePxrRis.py
     testUsdExportSkeleton.py
     testUsdExportStripNamespaces.py
     testUsdExportStroke.py
@@ -76,7 +73,6 @@ set(TEST_SCRIPT_FILES
     testUsdImportUVSetMappings.py
     testUsdImportUSDZTextures.py
     testUsdExportImportRoundtripPreviewSurface.py
-    testUsdExportImportUDIM.py
     testUsdImportSkeleton.py
     testUsdImportXforms.py
     testUsdImportXformAnim.py
@@ -104,12 +100,40 @@ endif()
 
 if (BUILD_RFM_TRANSLATORS)
     list(APPEND TEST_SCRIPT_FILES
-        testUsdExportRfMShaders.py
         testUsdImportRfMShaders.py
     )
 endif()
 
 foreach(script ${TEST_SCRIPT_FILES})
+    mayaUsd_get_unittest_target(target ${script})
+    mayaUsd_add_test(${target}
+        PYTHON_MODULE ${target}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        ENV
+            "USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME=1"
+    )
+
+    # Add a ctest label to these tests for easy filtering.
+    set_property(TEST ${target} APPEND PROPERTY LABELS translators)
+endforeach()
+
+# These tests use custom material scope names and must not use
+# the USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME env var because
+# it takes precedence over the provided material scope name.
+set(TEST_SCRIPT_FILES_WITH_MATERIAL_SCOPE
+    testUsdExportDisplacement.py
+    testUsdExportShadingInstanced.py
+    testUsdExportShadingModePxrRis.py
+    testUsdExportImportUDIM.py
+)
+
+if (BUILD_RFM_TRANSLATORS)
+    list(APPEND TEST_SCRIPT_FILES_WITH_MATERIAL_SCOPE
+        testUsdExportRfMShaders.py
+    )
+endif()
+
+foreach(script ${TEST_SCRIPT_FILES_WITH_MATERIAL_SCOPE})
     mayaUsd_get_unittest_target(target ${script})
     mayaUsd_add_test(${target}
         PYTHON_MODULE ${target}
@@ -202,7 +226,8 @@ if (MAYA_APP_VERSION VERSION_GREATER_EQUAL 2020)
                     "${PXR_OVERRIDE_PLUGINPATH_NAME}=${CMAKE_CURRENT_BINARY_DIR}/../plugin/${plugin_type}"
                     "INPUT_PATH=${CMAKE_CURRENT_SOURCE_DIR}"
                     "PYTHONPATH=${CMAKE_CURRENT_BINARY_DIR}"
-            )
+                    "USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME=1"
+                    )
             set_property(TEST ${target} APPEND PROPERTY LABELS translators)
         endforeach()
     endforeach()

test/lib/usd/translators/testUsdExportMultiMaterial.py

@@ -70,6 +70,21 @@ def testStageOpens(self):
         '''
         self.assertTrue(self._stage)
 
+    def testMaterialScopeResolution(self):
+        # New default value as per USD Asset WG:
+        self.assertEqual(mayaUsdLib.JobExportArgs.GetDefaultMaterialsScopeName(), "mtl")
+
+        # This override is low-priority
+        os.environ["MAYAUSD_MATERIALS_SCOPE_NAME"] = "MyMaterialScope"
+        self.assertEqual(mayaUsdLib.JobExportArgs.GetDefaultMaterialsScopeName(), "MyMaterialScope")
+
+        # The USD_FORCE_DEFAULT_MATERIALS_SCOPE_NAME override has higher priority, but is read
+        # at startup and can not be turned on/off for this test. It was used on all tests that
+        # relied on "Looks" being the default name instead of "mtl"
+
+        os.environ.pop("MAYAUSD_MATERIALS_SCOPE_NAME")
+        self.assertEqual(mayaUsdLib.JobExportArgs.GetDefaultMaterialsScopeName(), "mtl")
+
     def testExportedUsdShadeNodeTypes(self):
         '''
         Tests that all node ids are what we expect:
@@ -154,7 +169,8 @@ def testVarnameMerging(self):
         cmds.usdExport(mergeTransformAndShape=True,
             file=usd_path,
             shadingMode='useRegistry',
-            convertMaterialsTo=['MaterialX', 'UsdPreviewSurface'])
+            convertMaterialsTo=['MaterialX', 'UsdPreviewSurface'],
+            materialsScopeName='Looks')
 
         # We expect 2 primvar readers, and 2 st transforms:
         stage = Usd.Stage.Open(usd_path)