# Simplygon command

# Description

The Simplygon command is responsible for executing Simplygon based on the provided settings, as well as scene import and export and various overrides.

# Syntax

    # Flags and args

    Short flag Long flag Argument(s) Description
    mb LockMaterialBoundaryVertices string materialName Locks vertices along the specified material's borders. These vertices will not be modified when generating the MeshLOD.
    lsv LockSetVertices string setName Locks vertices in the named set. These vertices will not be modified when generating the MeshLOD.
    lse LockSetEdges string setName Preserves edges depending on the Edge Set importance parameter when generating the MeshLOD.
    mc MaterialColor string materialName
    string channelName
    float r
    float g
    float b
    float a
    Overrides or creates the color on the specified channel of the material.
    mt MaterialTexture string materialName
    string channelName
    string texturePath
    Overrides or sets the texture on the specified channel of the material.
    mlt MaterialLayeredTexture string materialName
    string channelName
    string texturePath
    int layer
    string blendType
    Overrides or sets the texture on the specified texture layer of the material. Blend type can be add, multiply, subtract or none.
    mtn MaterialTextureNormals string materialName
    string texturePath
    bool isTangentSpace
    Overrides the normals texture of the material. Set the third parameter isTangentSpace to true if the normal map is in tangent space.
    tcn MaterialTextureChannelName string materialName
    string channelName
    string uvSetName
    Overrides the UV-set for the material.
    tod TextureOutputDirectory string outputPath Overrides the texture output folder for all processed textures to this absolute path. This flag is not compatible with imp, exp and cte.
    cpb UseCurrentPoseAsBindPose <none> Specifies that the skinning data will be extracted from the current pose rather than the bind pose. Please do not use this flag when in bind pose as synchronization issues might appear!
    swp SkipBlendShapeWeightPostfix <none> If set, the default prefix in blend shape attribute names (__, as in Mouth_1) will be removed.
    Note: If set, all generated target meshes will be left in the scene!
    sf SettingsFile string settingsPath Sets the path to the settings-file (pipeline-file) which will be used when processing.
    so SettingsObject int pipelineId Specifies which settings-object (pipeline-object) to use when processing.
    isf InputSceneFile string filepath If the input scene file is set the optimization will be based on the content of the specified file instead of the selection. Must be used in combination with osf.
    osf OutputSceneFile string filepath If the output scene file is set the resulting scene will be saved to the specified location. Must be used in combination with isf.
    cgm ClearGlobalMapping <none> Clears global mapping stored by previous exports.
    exp Export string filepath Exports selected Maya objects to a Simplygon scene file. This flag is not compatible with any kind of processing and is intended for exporting selected objects in Maya to an external Simplygon scene.
    imp Import string filepath Imports a Simplygon scene from the given file path. This flag is not compatible with any kind of processing and is intended for importing processed objects back into Maya.
    lma LinkMaterials <none> If set, try to re-use materials from existing scene. Only compatible with imp.
    lme LinkMeshes <none> If set, try to find original mesh in scene for copying of extra properties. Only compatible with imp.
    cte CopyTextures <none> If set in combination with export: exports textures to textures-subdirectory. If set in combination with import: imports textures to Maya's texture directory. If not set, use original file paths. Only compatible with exp and imp.
    mnf MeshNameFormat string formatString Specifies the format string that will be used when importing meshes. {MeshName} and {LODIndex} are reserved and will be replaced with the correct values during import. Use ili to manually adjust the value of LODIndex.
    bnf BlendShapeNameFormat string formatString Specifies the format string that will be used when importing blend shapes. {Name} and {LODIndex} are reserved and will be replaced with the correct values during import. Use ili to manually adjust the value of LODIndex.
    ili InitialLODIndex int lodIndex Sets the initial lod index that will be used at import (if specified in fmn and/or bnf).
    asm AddShaderMaterial string materialNames Specifies which materials to override with shading networks at export. Material names are separated by "|". Ex: "redMaterial | blueMaterial".
    ixf ImportShaderXML string materialName
    string channelName
    string importFilePath
    Imports shading network from file into the specified material channel.
    dgm DoNotGenerateMaterial <none> If set, the plug-in will not generate a phong material for each baked material during import. Use SimplygonQuery command to query the plug-in for baked material details and set up a material of your own choice.
    qm QuadMode <none> If set, enables export and import of quads. This mode is required for preserving quads through the QuadReducer.

    # Examples

    This section contains various examples written in MEL and Python. We've left out some parts of the scripts to keep things as simple as possible.

    • import maya.cmds as cmds must be declared at the top of each Python script.
    • reductionPipeline settings-path must be declared for both MEL and Python scripts where it makes sense.
    • a scene-selection is made before each Simplygon-command.

    # Run Simplygon

    To run Simplygon, simply execute the Simplygon-command along with a Pipeline settings-path or Pipeline settings-object. A Pipeline contains the settings that Simplygon will use during optimization, much like SPL (8.x) and INI (7.x). The optimized result will be returned to Maya as soon as the processing has completed.

    # Execute Simplygon using a Pipeline file-path

      # Execute Simplygon using a Pipeline-object

        # Mapping data for Import and Export

        Some data is incompatible with Simplygon's scene format, such as animation, key frames and blind data. To tackle this during manual export and import we are storing some mapping data that makes it possible to preserve this information, this data will reside in memory until manually cleared. Clearing global mapping before an import will result in meshes and materials getting imported solely based on the data in the file. Clear the global mapping manually, preferably before each export.

        Clear global mapping data:

          Take the example below where we first export a scene to file, then import it back into Maya. During export we store mapping data for meshes and materials (guid mapped). At import we do a lookup in the mapping data and if we find a match we can copy blind data, rendering properties and link bones more accurately.

            To gain more control of Import we have exposed two flags, -lma (LinkMaterials) and -lme (LinkMeshes). If LinkMaterials is set we will try to do a lookup in the global mapping, if any, if there is no hit we will do a name based search. If a match is found we will link the existing material(s) to the imported mesh(es). If LinkMaterials is set to false then new materials will be generated and applied to the mesh(es).

            Allow (re)use of original materials:

              If LinkMeshes (lme) is set we will try to do a global lookup, and if that is not working then we will do a named based search. Non-existing mapping may result in loss of data, for example blind data, rendering properties and skinning / key frames. If LinkMeshes is set to false the imported meshes will be considered new meshes, Reductions will not be able to map back to the original hierarchy as an example.

              Allow Import to access data on original mesh(es):

                # Export selected Maya assets to file

                To export selected Maya assets to file, use the Export (exp) flag followed by the output file path. Export is compatible with flags that modifies the output scene in any manner, such as example shading networks and material overrides. The exported file will be saved as Simplygon's proprietary file format.

                  Export selected Maya assets along with its textures to file using the CopyTextures (cte) flag. Textures will be exported to a sub-directory named "Textures" located in the same directory as the output scene file, in this specific case "D:/Exports/Textures".

                    # Import saved scene into Maya

                    To import a previously saved file into Maya, use the Import (imp) flag followed by the file path.

                    Note: The importer is part of the standard Simplygon pipeline (export -> process -> import) and can not create complex materials. New materials will get imported as Phong with one (the first) texture available for the given material channel. For complex (node-based) material import we recommend a manual approach.

                      To specify wether the textures should be copied to a local directory, use the CopyTextures (cte) flag. Keep in mind that LinkMaterials may override this setting, if the imported asset is reusing existing scene materials it will also use the original textures. If CopyTextures is set the textures will get imported from it's source destination to Maya's texture directory. If CopyTextures is not set the imported (generated) material's texture paths will point to the imported scene's destination textures.

                        # Specify name of processed / imported meshes

                        Renaming of processed / imported meshes can now be done by using the FormatMeshName (fmn) flag. {MeshName} and {LODIndex} will be replaced internally if present. If meshes with the given name already exists they will get assigned a new indexed name, usually the original name appended by a unique number.

                        As scenes can be exported and imported in an unordered manner we've also added the InitialLODIndex (ili) flag which specifies the starting index for LODIndex. So if you want to import a scene from disk and want to use LODIndex = 5 for all meshes found in the scene, that is now possible.

                          # Process scene from file

                          We've extended the Simplygon command to be able to process scenes from file. The InputSceneFile (isf) flag specifies which file to optimize while OutputSceneFile (osf) specifies the target file path of the optimized scene.

                          If the pipeline is cascaded the output scene names will be appended with "_LOD" prefix and then indexed from 1 to *, where the index increments for each cascaded level. The output texture folder for each cascaded scene will be "Textures/LOD1" for LOD1, "Textures/LOD2" for LOD2 and so on. The output file names can be fetched with GetProcessedOutputPaths (gpp) which can then be used at import.

                            # Calculate switch-distance

                            Simplygon writes down custom attributes for each mesh transform that can be used to calculate the recommended LOD-Switch distance. The attributes are MaxDeviation which indicates the pixel deviation compared to the original asset, and then SceneRadius which is the total radius of the scene that was sent for processing. All meshes processed at the same time will have the same attribute values, thus also switch distance. MaxDeviation is currently available for Reduction and Remeshing. Aggregation do not have a switch distance as all it does is to merges geometry (and possibly materials), in this example the MaxDeviation gets set to 0 where the attribute does not exists.

                            Attributes:

                            LOD-switch attributes

                            To calculate the switch distance you also need to take a few other parameters into account, such as resolution and field-of-view (FOV). See the formula below (there is a more detailed description in the API documentation). A complete LOD-switch example can be found in the examples section.

                              A complete UI example can be found here.

                              # Material color override

                              To override a color of a material channel, enter the material name, the name of the channel and the RGBA values for a specific color. In the example below we choose to set the diffuse channel of "MyMaterial" to blue. If the material channel does not exist it will be created.

                                # Material texture override

                                To override a texture of a material channel, enter the name of the material, the name of the channel and at last the path to the target texture. In the example below we choose to set a diffuse texture to the diffuse channel of the material. If the material channel does not exist it will be created.

                                  # Selection sets

                                  Object selection sets are (as of 9.0) exported from Maya's selection sets automatically. There is no need to script the creation of selection sets but it is still required to assign which selection set to use for features such as Bone Lock and Clipping Geometry.

                                  Vertex Locks and Edge Locks does not require Pipeline settings but needs to be specified with -lsv "setName" and -lse "setName" at export.

                                  Please see the Pipeline documentation for more information on how to set specific settings parameters.