EMSUSD-946 axis in import UI and command

README_DOC.md

@@ -8,6 +8,7 @@
 + [Managing Translation (Import/Export) Options](lib/mayaUsd/fileio/doc/Managing_export_options_via_JobContext_in_Python.md)
 + [Example Import and Export Plugin in Python](tutorials/import-export-plugin/README.md)
 + [Example Import and Export Plugin in C++](tutorials/import-export-plugin-c++/README.md)
++ [Adding new import or export option](lib/mayaUsd/fileio/doc/How-to-add-new-option.md)
 + [SchemaAPI Translators](lib/mayaUsd/fileio/doc/SchemaAPI_Import_Export_in_Python.md)
 + [UFE Transform](lib/usdUfe/ufe/trf/UsdTransform3d.md)
 + [Undo/Redo Support](lib/mayaUsd/undo/README.md)

lib/mayaUsd/commands/Readme.md

@@ -53,6 +53,8 @@ Each base command class is documented in the following sections.
 | `-importUSDZTextures`         | `-itx`     | bool           | false                             | Imports textures from USDZ archives during import to disk. Can be used in conjuction with `-importUSDZTexturesFilePath` to specify an explicit directory to write imported textures to. If not specified, requires a Maya project to be set in the current context.  |
 | `-importUSDZTexturesFilePath` | `-itf`     | string         | none                              | Specifies an explicit directory to write imported textures to from a USDZ archive. Has no effect if `-importUSDZTextures` is not specified. |
 | `-importRelativeTextures`     | `-rtx`     | string         | none                              | Selects how textures filenames are generated: absolute, relative, automatic or none. When automatic, the filename is relative if the source filename of the texture being imported is relative. When none, the file path is left alone, for backward compatible behavior. |
+| `-upAxis`                     | `-upa`     | bool           | true                              | Enable changing axis on import. |
+| `-axisAndUnitMethod`          | `-aum`     | string         | rotateScale                       | Selects how the unit and axis are handled during import. |
 
 ### Return Value
 

lib/mayaUsd/commands/baseImportCommand.cpp

@@ -68,6 +68,12 @@ MSyntax MayaUSDImportCommand::createSyntax()
         kImportRelativeTexturesFlag,
         UsdMayaJobImportArgsTokens->importRelativeTextures.GetText(),
         MSyntax::kString);
+    syntax.addFlag(
+        kImportUpAxisFlag, UsdMayaJobImportArgsTokens->upAxis.GetText(), MSyntax::kBoolean);
+    syntax.addFlag(
+        kImportAxisAndUnitMethodFlag,
+        UsdMayaJobImportArgsTokens->axisAndUnitMethod.GetText(),
+        MSyntax::kString);
     syntax.addFlag(kMetadataFlag, UsdMayaJobImportArgsTokens->metadata.GetText(), MSyntax::kString);
     syntax.makeFlagMultiUse(kMetadataFlag);
     syntax.addFlag(

lib/mayaUsd/commands/baseImportCommand.h

@@ -46,6 +46,8 @@ class MAYAUSD_CORE_PUBLIC MayaUSDImportCommand : public MPxCommand
     static constexpr auto kImportUSDZTexturesFlag = "itx";
     static constexpr auto kImportUSDZTexturesFilePathFlag = "itf";
     static constexpr auto kImportRelativeTexturesFlag = "rtx";
+    static constexpr auto kImportUpAxisFlag = "upa";
+    static constexpr auto kImportAxisAndUnitMethodFlag = "aum";
     static constexpr auto kMetadataFlag = "md";
     static constexpr auto kApiSchemaFlag = "api";
     static constexpr auto kJobContextFlag = "jc";

lib/mayaUsd/fileio/doc/How-to-add-new-option.md

@@ -0,0 +1,46 @@
+# How to add a new option to import or export
+
+Search for an existing option in the code and do the same for the new option
+everywhere you find the old existing option. Use an existing option with a
+very unique name to avoid false matches.
+
+## Adding the option UI, command flag and import/export argument
+
+Usually, you will need to modify these places:
+
+- baseImportCommand.h: (or baseExportCommand.h)
+	- Add the short flag
+
+- baseImportCommand.cpp: (or baseExportCommand.cpp)
+	- Add the flag to the syntax
+
+- lib/mayaUsd/commands/Readme.md:
+	- Document the new flag
+
+- lib/mayaUsd/fileio/jobs/jobArgs.h:
+	- Add the token to the import or export tokens
+	- Add data item to the import or export struct
+
+- lib/mayaUsd/fileio/jobs/jobArgs.cpp:
+	- Handle parsing the flag in the constructor
+	- Add default value to GetDefaultDictionary
+	- Add the type to GetGuideDictionary
+	- Add writing the value to the operator<<
+
+- wrapPrimReader.cpp:
+	- Expose the option to Python
+
+- mayaUSDRegisterStrings.mel:
+	Add the new UI labels
+
+- mayaUsdTranslatorImport.mel: (or mayaUsdTranslatorExport.mel)
+	- Add new UI elements in mayaUsdTranslatorImport "post"
+	- Read the UI values in mayaUsdTranslatorImport "query"
+	- Add the UI in EnableAllControls
+	- Add filling the UI with data in SetFromOptions
+	- Maybe add some callback when UI valeu change when UI affect other UI.
+
+## Handling the option in code
+
+Afterward, modify the import/export code itself to handle the new option and
+add new behavior during the actual import or export.

lib/mayaUsd/fileio/jobs/jobArgs.cpp

@@ -1344,6 +1344,14 @@ UsdMayaJobImportArgs::UsdMayaJobImportArgs(
             UsdMayaJobImportArgsTokens->absolute,
             UsdMayaJobImportArgsTokens->relative,
             UsdMayaJobImportArgsTokens->none }))
+    , axisAndUnitMethod(extractToken(
+          userArgs,
+          UsdMayaJobImportArgsTokens->axisAndUnitMethod,
+          UsdMayaJobImportArgsTokens->rotateScale,
+          { UsdMayaJobImportArgsTokens->rotateScale,
+            UsdMayaJobImportArgsTokens->addTransform,
+            UsdMayaJobImportArgsTokens->overwritePrefs }))
+    , upAxis(extractBoolean(userArgs, UsdMayaJobImportArgsTokens->upAxis))
     , importInstances(extractBoolean(userArgs, UsdMayaJobImportArgsTokens->importInstances))
     , useAsAnimationCache(extractBoolean(userArgs, UsdMayaJobImportArgsTokens->useAsAnimationCache))
     , importWithProxyShapes(importWithProxyShapes)
@@ -1432,6 +1440,9 @@ const VtDictionary& UsdMayaJobImportArgs::GetDefaultDictionary()
         d[UsdMayaJobImportArgsTokens->importUSDZTexturesFilePath] = "";
         d[UsdMayaJobImportArgsTokens->importRelativeTextures]
             = UsdMayaJobImportArgsTokens->none.GetString();
+        d[UsdMayaJobImportArgsTokens->axisAndUnitMethod]
+            = UsdMayaJobImportArgsTokens->rotateScale.GetString();
+        d[UsdMayaJobImportArgsTokens->upAxis] = true;
         d[UsdMayaJobImportArgsTokens->pullImportStage] = UsdStageRefPtr();
         d[UsdMayaJobImportArgsTokens->useAsAnimationCache] = false;
         d[UsdMayaJobImportArgsTokens->preserveTimeline] = false;
@@ -1514,6 +1525,8 @@ const VtDictionary& UsdMayaJobImportArgs::GetGuideDictionary()
         d[UsdMayaJobImportArgsTokens->importUSDZTextures] = _boolean;
         d[UsdMayaJobImportArgsTokens->importUSDZTexturesFilePath] = _string;
         d[UsdMayaJobImportArgsTokens->importRelativeTextures] = _string;
+        d[UsdMayaJobImportArgsTokens->axisAndUnitMethod] = _string;
+        d[UsdMayaJobImportArgsTokens->upAxis] = _boolean;
         d[UsdMayaJobImportArgsTokens->pullImportStage] = _usdStageRefPtr;
         d[UsdMayaJobImportArgsTokens->useAsAnimationCache] = _boolean;
         d[UsdMayaJobImportArgsTokens->preserveTimeline] = _boolean;
@@ -1604,6 +1617,8 @@ std::ostream& operator<<(std::ostream& out, const UsdMayaJobImportArgs& importAr
         << "importUSDZTextures: " << TfStringify(importArgs.importUSDZTextures) << std::endl
         << "importUSDZTexturesFilePath: " << TfStringify(importArgs.importUSDZTexturesFilePath)
         << "importRelativeTextures: " << TfStringify(importArgs.importRelativeTextures) << std::endl
+        << "axisAndUnitMethod: " << TfStringify(importArgs.axisAndUnitMethod) << std::endl
+        << "upAxis: " << TfStringify(importArgs.upAxis) << std::endl
         << "pullImportStage: " << TfStringify(importArgs.pullImportStage) << std::endl
         << std::endl
         << "timeInterval: " << importArgs.timeInterval << std::endl

lib/mayaUsd/fileio/jobs/jobArgs.h

@@ -174,6 +174,12 @@ TF_DECLARE_PUBLIC_TOKENS(
     (pullImportStage) \
     (preserveTimeline) \
     (remapUVSetsTo) \
+    (upAxis) \
+    (axisAndUnitMethod) \
+    /* values for axis and unit method */ \
+    (rotateScale) \
+    (addTransform) \
+    (overwritePrefs) \
     /* values for import relative textures */ \
     (automatic) \
     (absolute) \
@@ -403,6 +409,8 @@ struct UsdMayaJobImportArgs
     const std::string    importUSDZTexturesFilePath;
     const bool           importUSDZTextures;
     const std::string    importRelativeTextures;
+    const std::string    axisAndUnitMethod;
+    const bool           upAxis;
     const bool           importInstances;
     const bool           useAsAnimationCache;
     const bool           importWithProxyShapes;