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

Simplygon -<short/long flag> <arg0> <arg1> ... <argN>;

import maya.cmds as cmds
cmds.Simplygon(<short/long flag>=<arg>)
cmds.Simplygon(<short/long flag>=[<arg0>, <arg1>, ..., <argN>])

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.

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 with the given pipeline (settings-file)
Simplygon -sf "D:/Pipelines/reductionPipeline.json";

# execute Simplygon with the given pipeline (settings-file)
cmds.Simplygon(sf = 'D:/Pipelines/reductionPipeline.json')

Execute Simplygon using a Pipeline-object

// create a reduction pipeline-object
$reductionPipeline = `SimplygonPipeline -c "ReductionPipeline"`;
...

// execute Simplygon with the given pipeline-object
Simplygon -so $reductionPipeline;

// clear all pipelines
SimplygonPipeline -cl;

# create a reduction pipeline-object
reductionPipeline = cmds.SimplygonPipeline(c = 'ReductionPipeline')
...

# execute Simplygon with the given pipeline-object
cmds.Simplygon(so = reductionPipeline)

# clear all pipelines
cmds.SimplygonPipeline(cl = True)

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:

// clear global mapping
Simplygon -cgm;

# clear global mapping
cmds.Simplygon(cgm = True)

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.

// export the selected Maya assets to file
$bResult = `Simplygon -exp "D:/Exports/scene.sb"`;

// import the specified Simplygon scene into Maya
$bResult = `Simplygon -imp "D:/Exports/scene.sb"`;

# export the selected Maya assets to file
bResult = cmds.Simplygon(exp = 'D:/Exports/scene.sb')

# import the specified Simplygon scene into Maya
bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb')

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:

// import the specified Simplygon scene into Maya, try to reuse existing materials
$bResult = `Simplygon -imp "D:/Exports/scene.sb" -lma`;

# import the specified Simplygon scene into Maya, try to reuse existing materials
bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb', lma = True)

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):

// import the specified Simplygon scene into Maya, try to access existing mesh data
$bResult = `Simplygon -imp "D:/Exports/scene.sb" -lme`;

# import the specified Simplygon scene into Maya, try to access existing mesh data
bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb', lme = True)

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 the selected Maya assets to file
$bResult = `Simplygon -exp "D:/Exports/scene.sb"`;

# export the selected Maya scene to file
bResult = cmds.Simplygon(exp = 'D:/Exports/scene.sb')

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".

// export the selected Maya assets to file (bundle textures)
$bResult = `Simplygon -exp "D:/Exports/scene.sb" -cte`;

# export the selected Maya assets to file (bundle textures)
bResult = cmds.Simplygon(exp = 'D:/Exports/scene.sb', cte = True)

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.

// import the specified Simplygon scene into Maya
$bResult = `Simplygon -imp "D:/Exports/scene.sb"`;

# import the specified Simplygon scene into Maya
bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb')

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.

// export the selected Maya assets to file (copy textures into Maya's texture directory)
$bResult = `Simplygon -imp "D:/Exports/scene.sb" -cte`;

# export the selected Maya assets to file (copy textures into Maya's texture directory)
bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb', cte = True)

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.

$bResult = `Simplygon -imp "D:/Exports/scene.sb" -mnf "My_{MeshName}_LOD{LODIndex}" -ili 0`;

bResult = cmds.Simplygon(imp = 'D:/Exports/scene.sb', mnf = 'My_{MeshName}_LOD{LODIndex}', ili = 0)

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.

// process input file and save optimized result to output file.
$bResult = `Simplygon -so $pipeline -isf "D:/Exports/scene.sb" -osf "D:/Exports/scene_processed.sb"`;

string $processedOutputFiles[] = `SimplygonQuery -gpp`;

int $lodIndex = 1;
for($path in $processedOutputFiles)
{
    $bResult = `Simplygon -imp $path -lme -fmn "{MeshName}_LOD{LODIndex}" -ili $lodindex`;
    lodIndex += 1;
}

# process input file and save optimized result to output file.
bResult = cmds.Simplygon(so = pipeline, isf = 'D:/Exports/scene.sb', osf = 'D:/Exports/scene_processed.sb')

# get processed output file paths
processedOutputFiles = cmds.SimplygonQuery(gpp = True)

# import scene(s)
lodIndex = 1
for path in processedOutputFiles:
    bResult = cmds.Simplygon(imp = path, cte = False, lme = True, lma = False, mnf = '{MeshName}_LOD{LODIndex}', ili = lodIndex)
    lodIndex += 1

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:

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.

    # Object is the mesh transform
    def calculateLODSwitchDistance(object):
        # Reads the .SceneRadius attribute
        radius = SimplygonWrapper.getSceneRadius(object)

        # Reads the MaxDeviation attribute
        deviation = SimplygonWrapper.getMaxDeviation(object)

        # Calculates the pixel size (OnScreenSize)
        pixelsize = (radius*2)/deviation

        # Screen resolution and FOV
        curView = OpenMayaUI.M3dView.active3dView()
        screenheight = curView.portHeight()
        screenwidth = curView.portWidth()
        curCamPath = OpenMaya.MDagPath()
        curView.getCamera(curCamPath)
        curCam = Camera(curCamPath.node())
        [fov_x, fov_y] = curCam.getPortFieldOfView(screenwidth, screenheight)

        # Calculates screen ratio
        screen_ratio = float(pixelsize) / float(screenheight)
        normalized_distance = 1.0 / (math.tan(fov_y / 2))

        # The view-angle of the bounding sphere rendered on-screen.
        bsphere_angle = math.atan(screen_ratio / normalized_distance)

        # The distance in real world units from the camera to the center of the
        # bounding sphere. Not to be confused with normalized distance.
        distance = radius / math.sin(bsphere_angle)
        return distance

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.

// execute Simplygon with settings file
// and material color override
Simplygon
 -sf $reductionPipeline
 -mc "MyMaterial" "Ambient" 0.0 0.0 1.0 1.0
 -mc "MyMaterial" "Diffuse" 0.0 0.0 1.0 1.0;

# execute Simplygon with settings file
# and material color override
cmds.Simplygon(
    sf = reductionPipeline,
    mc = [
            ['MyMaterial', 'Ambient', 0.0, 0.0, 1.0, 1.0],
            ['MyMaterial', 'Diffuse', 0.0, 0.0, 1.0, 1.0]
         ])

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.

// execute Simplygon with settings file
// and material texture override
Simplygon
 -sf $reductionPipeline
 -mt "MyMaterial" "Ambient" "c:/MyTexture.jpg"
 -mt "MyMaterial" "Diffuse" "c:/MyTexture.jpg";

# execute Simplygon with settings file
# and material texture override
cmds.Simplygon(
    sf = reductionPipeline,
    mt = [
            ['MyMaterial', 'Ambient', 'c:/MyTexture.jpg'],
            ['MyMaterial', 'Diffuse', 'c:/MyTexture.jpg']
         ])

Selection sets

Object selection sets are now (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.