Migrate from Simplygon 8 to Simplygon 9

The Simplygon Maya plug-in exports various commands and flags that exposes Simplygon functionality through Maya. Since Simplygon 8 there's been breaking changes to core features as well as the Simplygon API in general. While developing Simplygon 9 we decided to strip away layers that we felt were no longer necessary and that required lots of maintenance, such as the standalone Simplygon UI and the fundamentals it was built upon, as well as Simplygon Processing Language (SPL) and the Simplygon Scene Format (SSF). These changes resulted in us rebuilding the Simplygon Maya plug-in to work directly against the API instead of another layers. While trying to keep compatibility with previous versions of the plug-in there are some fundamental things that has changed, as well as some improvements.

This guide will focus on how to migrate from Simplygon 8 to Simplygon 9.

Installation

Pre-9 install scripts will no longer work with Simplygon 9. Simplygon 9 relies on environment variables to find certain components compared to previous solution of registry and configuration files, most Simplygon files have also been renamed. We recommend the Simplygon installer as it not only sets everything up correctly, but also installs all necessary prerequisites. We also provide a Simplygon 9 archive for manual installation. See the Simplygon 9 plug-in installation for further instructions.

Simplygon UI

The standalone Simplygon UI has been replaced by a lightweight UI in the form of a Maya plug-in. The UI plug-in is bundled with the installer and will show up in the plug-in manager after installation. See the Simplygon 9 plug-in installation for further instructions on how to enable plug-ins in Maya.

Settings system

The settings system has been completely revamped which means that old settings of the SPL- and Preset format is no longer compatible with Simplygon 9. The successor of SPL is Pipeline objects. Pipelines are made to make the life easier for users by encapsulating functionality in Pipeline objects. At the time of release we will have four Pipelines available: Reduction, Aggregation, Remeshing and LegacyRemeshing, which will reflect functionality offered in previous versions of Simplygon. These initial Pipelines will have a 1-to-1 mapping to the Simplygon API and should feel quite familiar to existing users. Pipelines are saved as text-based files with JSON extension. The job distribution system (that was previously part of Simplygon Grid) is now part of Pipelines.

Note that some settings have been added, removed, renamed and / or moved to a different settings group, see the SPL-to-Pipeline documentation for information of how to migrate SPL to Pipelines.

New Remesher

A new Remesher gets introduced in Simplygon 9 and takes the name of the old remesher. The old (legacy) remesher is still accessible but through a new "Legacy" name. The new remesher introduces features such as intelligent hole-filling, cavity removal as well as some performance increases when generating large OnScreenSize meshes.

The old remesher becomes the legacy remesher:

• RemeshingPipeline -> RemeshingLegacyPipeline
• RemeshingProcessor -> RemeshingLegacyProcessor
• RemeshingSettings -> RemeshingLegacySettings

New remesher:

• RemeshingPipeline
• RemeshingProcessor
• RemeshingSettings

For more information, see the Remeshing Pipeline example and Remeshing Pipeline API documentation.

Script migration

The following sections contain details of how to migrate specific parts from Simplygon 8 to Simplygon 9.

Simplygon command

Command
Simplygon

Previously short	Previously long	Status	Replacement short	Replacement long	Note
b	BatchMode	Removed			BatchMode is the only mode.
rb	RemoveBone	Removed			Moved to Pipeline-settings.
lb	LockBone	Removed			Moved to Pipeline-settings.
sf	SettingsFile	Repurposed	sf	SettingsFile	SPL-file replaced by Pipeline-file.
spl	SPL	Replaced	so	SettingsObject	SPL-object replaced by Pipeline-object.
ss	SelectionSet	Removed			Plug-in reads Maya's built-in sets.
caw	UseColorSetAsWeights	Removed			Moved to Pipeline-settings.
wm	SetWeightsMultiplier	Removed			Moved to Pipeline-settings.
wi	SetWeightsInterpreter	Removed			Moved to Pipeline-settings.

See Simplygon command reference for more details.

SPL- to SimplygonPipeline command

Previous command	New command
SPL	SimplygonPipeline

Previously short	Previously long	Status	Replacement short	Replacement long	Note
sf	SaveFile	Replaced	s	Save	Saves Pipeline-object to file.
lf	LoadFile	Replaced	l	Load	Loads Pipeline-object from file.
co	CreateObject	Replaced	c	Create	Use to create Pipeline-object.
sv	SetValue	Replaced	ss and v	SetSetting and Value	Use ss to specify setting path, v for setting the value. Must be used in combination of each other.
ss	SetString	Replaced	ss and v	SetSetting and Value	Use ss to specify setting path, v for setting the value. Must be used in combination of each other.
gv	GetValue	Replaced	gs	GetSetting	Use gs to specify setting path from where to fetch the setting value.
ao	AddObject	Removed
ro	RemoveObject	Removed
gc	GetChild	Removed
cl	ClearList	Removed
gp	GetParameter	Removed
c	Clear	Replaced	cl	Clear	Clears all Pipelines that resides in memory (created and loaded).

See SimplygonPipeline command reference for more details.

Load and save settings

Loading a SPL-file was previously done using the SPL command in combination with the lf (LoadFile) flag followed by the file path and name of the handle the SPL object will be accessed from. The sf (SaveFile) flag takes the file path and the SPL object handle.

SPL -lf "D:/Pipelines/Reduction.spl" reductionObject;
SPL -sf "D:/Pipelines/Reduction.spl" reductionObject;

For Pipelines the loading of files translates to the SimplygonPipeline command in combination with the l (Load) flag followed by the file path. The command returns the Pipeline handle as soon as the load has completed. Saving works in a similar fashion; the flag s (Save) followed by the file path and the Pipeline handle.

$reductionPipeline = `SimplygonPipeline -l "D:/Pipelines/Reduction.json"`;
$bResult = `SimplygonPipeline -s "D:/Pipelines/Reduction.json" $reductionPipeline`;

Get and set settings

The SPL settings system in Simplygon 8 has been replaced by the Pipeline settings system which are focusing more on ease-of-use. To set a setting in a Pipeline, simply specify the setting path and value, or just setting path for queries. There is no longer any need to manually traverse the SPL graph to be able to set and get settings, no more containers or write nodes are necessary.

Note that some settings have been added, removed, renamed and / or moved to a different settings group, see the SPL-to-Pipeline documentation for information of how to migrate SPL to Pipelines.

Previously these lines were required to create a "simple" 50% reduction:

// create SPL object
SPL -CreateObject SPL reductionObject;

// create reduction settings
SPL -CreateObject ReductionSettings reductionSettings;
SPL -SetValue reductionSettings TriangleRatio 0.5
    -SetValue reductionSettings Enabled true;

// create reduction processor and assign the reduction settings
SPL -CreateObject ReductionProcessor reductionProcessor;
SPL -SetValue reductionProcessor ReductionSettings reductionSettings;;

// create process node and assign reduction processor
SPL -CreateObject ProcessNode processNode;
SPL -SetString processNode Name processNode
    -SetValue processNode Processor reductionProcessor;

// create write node and add it to the process node
SPL -CreateObject WriteNode writeNode;
SPL -SetString writeNode Format ssf
    -SetString writeNode Name outputlod_0
    -AddObject processNode Children writeNode;

// create container node,
// add process node to container node
SPL -CreateObject ContainerNode containerNode;
SPL -SetString containerNode Name containerNode
    -AddObject containerNode Children processNode;

// assign container node to spl node
SPL -SetValue reductionObject ProcessGraph containerNode;

// execute Simplygon in batch mode with the provided SPL object
Simplygon -b -spl "reductionObject";

The new Pipeline settings system reduces the lines above to:

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

// set the triangle ratio to 50%
$bResult = `SimplygonPipeline -ss "ReductionProcessor/ReductionSettings/ReductionTargetTriangleRatio" -v 0.5 $reductionPipeline`;

// execute Simplygon with the provided Pipeline object
Simplygon -so $reductionPipeline;

// clear all pipelines that resides in memory
SimplygonPipeline -cl;

As you can see there is no direct translation for the get and set flags as Pipeline settings can be set through a settings path and does not require the individual objects.

Here's how to get and set the triangle ratio for a reduction processor:

// set the triangle ratio to 50%
$bResult = `SimplygonPipeline -ss "ReductionProcessor/ReductionSettings/ReductionTargetTriangleRatio" -v 0.5 $reductionPipeline`;

// get the triangle ratio
$reductionTargetTriangleRatio = `SimplygonPipeline -gs "ReductionProcessor/ReductionSettings/ReductionTargetTriangleRatio" $reductionPipeline`;

// print the triangle ratio
print ("ReductionTargetTriangleRatio: " + $reductionTargetTriangleRatio + "\n");

How to setup material baking settings for a reduction Pipeline:

// mapping image is required for material baking
$bResult = `SimplygonPipeline -ss "ReductionProcessor/MappingImageSettings/GenerateMappingImage" -v true $reductionPipeline`;

// generate new texture coordinates
$bResult = `SimplygonPipeline -ss "ReductionProcessor/MappingImageSettings/GenerateTexCoords" -v true $reductionPipeline`;

// specify name for generated texture coordinates
$bResult = `SimplygonPipeline -ss "ReductionProcessor/MappingImageSettings/TexCoordName" -v "MaterialLOD" $reductionPipeline`;

// width and height of the baked textures
$bResult = `SimplygonPipeline -ss "ReductionProcessor/MappingImageSettings/Output0/TextureWidth" -v 512 $reductionPipeline`;
$bResult = `SimplygonPipeline -ss "ReductionProcessor/MappingImageSettings/Output0/TextureHeight" -v 512 $reductionPipeline`;

// add a color caster for Maya's standard material (color)
$bCasterAdded = `SimplygonPipeline -amc "ColorCaster" $reductionPipeline`;
$bResult = `SimplygonPipeline -ss "MaterialCaster/1/ColorCasterSettings/MaterialChannel" -v "color" $reductionPipeline`;

// add normal caster for Maya's standard material (normalCamera)
$bCasterAdded = `SimplygonPipeline -amc "NormalCaster" $reductionPipeline`;
$bResult = `SimplygonPipeline -ss "MaterialCaster/2/NormalCasterSettings/MaterialChannel" -v "normalCamera" $reductionPipeline`;

// set the correct tangent space type
$bResult = `SimplygonPipeline -ss "MaterialCaster/2/NormalCasterSettings/GenerateTangentSpaceNormals" -v true $reductionPipeline`;

Material channel mapping

Previously we were mapping Maya's standard materials (Blinn, Phong, Lambert etc) to Simplygon materials by redirecting material channels to a pre-defined structure (that was required by the standalone Simplygon UI). As the standalone UI is no longer a part of Simplygon 9 we decided to use Maya's material channels through and through, making it easier for users by removing extra layers of complexity.

If you wish to bake standard materials in Maya, see the updated channel names in the table below.

Previous channel	New channel
Ambient	ambientColor
Diffuse	color
Specular	specularColor
Opacity	transparency
Normals	normalCamera

Creation of selection sets

Creation of selection sets were previously scripted through the -ss (SelectionSet) flag, this functionality has been replaced by Maya's built in selection sets (Create -> Sets -> Set). The plug-in will make sure that the selection-sets are transferred to Simplygon.

Previous behavior of creating selection sets:

// create named selection-set
Simplygon -ss "MySet" "pSphere1|pSphere2";

The new way is to use Maya's built-in "sets" command:

// select objects
select -r pSphere1 pSphere2;

// create named selection-set
$createSetResult = `sets -name "MySet"`;

To assign a selection-set to a Pipeline, as a processing selection-set or clipping selection-set, see Clipping geometry example.

Vertex colors to vertex weights

The "vertex colors to vertex weights" functionality has been moved from the Simplygon command (-caw, UseColorSetAsWeights) to the SimplygonPipeline command and is now a part of the Pipeline settings. An additional setting has been added to allow users to specify which color component of the vertex colors to use as weights.

Previous method of specifying which color-set to use as vertex weights:

// creates SPL object and populates it with reduction process node, settings and write-node (excluded)
SPL -CreateObject SPL reductionObject;
...

// launch Simplygon in batch mode with provided setting object,
// pass which vertex-color-set to use as weights in combination with multiplier and interpreter
Simplygon -b -spl $reductionObject -caw "colorSet1" -wm 8 -wi 0;

New method of specifying which color-set to use as vertex weights:

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

// enables vertex weights in reducer
$bResult = `SimplygonPipeline -ss "ReductionProcessor/VertexWeightSettings/UseVertexWeightsInReducer" -v true $reductionPipeline`;

// sets which vertex-color-set to be used as weights
$bResult = `SimplygonPipeline -ss "ReductionProcessor/VertexWeightSettings/WeightsFromColorName" -v "colorSet1" $reductionPipeline`;

// sets the multiplier
$bResult = `SimplygonPipeline -ss "ReductionProcessor/VertexWeightSettings/WeightsFromColorMultiplier" -v 8 $reductionPipeline`;

// sets which interpreter to use
$bResult = `SimplygonPipeline -ss "ReductionProcessor/VertexWeightSettings/WeightsFromColorMode" -v 0 $reductionPipeline`;
...

// launch Simplygon with provided setting object
Simplygon -so $reductionPipeline;

For more information about vertex colors as vertex weights, see Colors as vertex weights.