Go to: Synopsis. Return value. Keywords. Related. Flags. MEL examples.

Synopsis

deformerWeights [-attribute string] [-defaultValue float] [-deformer string] [-export] [-format string] [-ignoreName] [-import] [-method string] [-path string] [-positionTolerance float] [-remap string] [-shape string] [-skip string] [-vertexConnections] [-weightPrecision uint] [-weightTolerance float] [-worldSpace]

deformerWeights is undoable, queryable, and editable.

Command to import and export deformer weights to and from a simple XML file. The weight data is stored in a per-vertex fashion along with a "point cloud" corresponding to the vertices from the geometry input to the deformer. For example a cluster deformer would have the following information: On import the weights are then mapped back to a specified deformer based on the specified mapping method. Note that the geometry used to perform the mapping association is not the visible shape but rather the incoming geometry to the deformer. For example, in the case of a skin cluster this would be the bind pose geometry.

Return value

STRINGpath to the file imported/exported, if successful

In query mode, return type is based on queried flag.

Keywords

deformer, export

Related

blendShape, skinCluster, skinPercent

Flags

attribute, defaultValue, deformer, export, format, ignoreName, import, method, path, positionTolerance, remap, shape, skip, vertexConnections, weightPrecision, weightTolerance, worldSpace
Long name (short name) Argument types Properties
-attribute(-at) string createqueryeditmultiuse
Specify the long name of deformer attribute that should be imported/exported along with the deformerWeights. i.e. -at "envelope" -at "skinningMethod" etc.. No warning or error is given if a specified attribute does not exist on a particular deformer, making it possible to use this command with multiple deformers without aborting or slowing down the import/export process. Currently supports numeric attributes and matrix attributes
-defaultValue(-dv) float createqueryedit
Manually set the default value. Default values are values that are not written to file. For example, for blendShapes the default value is automatically set to 1.0 and these values are not written to disk. For skinClusters the value is 0.0. If all weights should be forced to be written to disk, set a defaultValue = -1.0.
-deformer(-df) string createqueryeditmultiuse
Specify the deformer whose weights should be exported or imported. If a pattern is supplied for the deformer name (i.e: cluster*), only the first deformer that matches the pattern will be imported/exported unless used in conjunction with the -skip option
-export(-ex) createqueryedit
Export the given deformer
-format(-fm) string createqueryedit
Specify either "XML" or "JSON" as the file extension to save as.
-ignoreName(-ig) createqueryedit
Ignore the names of the layers on import, just use the order of the layers instead. This can be used when joint names have been changed. Leaving it on only name that match on import will be write to the deformer.
-import(-im) createqueryedit
Import weights to the specified deformer. See the method flag for details on how the weights will be mapped to the destination deformer.
-method(-m) string createqueryedit
Specify the method used to map the weight during import. Valid values are: "index", "nearest", "barycentric", "bilinear" and "over". The "index" method uses the vertex index to map the weights onto the object. This is most useful when the destination object shares the same topology as the exported data. The "nearest" method finds the nearest vertex in the imported data set and sets the weight value to that value. This is best used when mapping a higher resolution mesh to a lower resolution. The "barycentric" and "bilinear" methods are only supported with polygon mesh exported with -vc/vertexConnections flag. The "barycentric" method finds the nearest triangle of the input geometry and rescales the weights at the triangle vertices according to the barycentric weights to each vertex of the nearest triangle. The "bilinear" method finds the nearest convex quad of the input geometry and rescales the weights at the quad vertices according to the bilinear weights to each vertex of the nearest convex quad. For non-quad polygon, the "bilinear" method will fall back to "barycentric" method. The "over" method is similar to the "index" method but the weights on the destination mesh are not cleared prior to mapping, so that unmatched indices keep their weights intact.
-path(-p) string createqueryedit
The path to the given file. Default to the current project.
-positionTolerance(-pt) float createqueryedit
The position tolerance is used to determine the radius of search for the nearest method. This flag is only used with import. Defaults to a huge number.
-remap(-r) string createqueryeditmultiuse
Remap maps source regular expression to destination format. It maps any name that matches the regular expression (before the semi-colon) to the expression format (after the semi-colon). For example, -remap "test:(.*);$1" will rename all items in the test namespace to the global namespace. Accepts $1, $2, .., $9 as pattern holders in the expression format. Remap flag must be used together with import or export. When working with import, the name of the object from the xml file matching the regular expression is remapped to object in scene. When working with export, the name of the object from the scene matching the regular expression is remapped to object in xml file.
-shape(-sh) string createqueryeditmultiuse
Specify the source shape. Export will write out all the deformers on the shape node into one file. If a pattern is supplied for the shape name (i.e: pCylinder*), only the first shape that matches the pattern will be imported/exported unless used in conjunction with the -skip option.
-skip(-sk) string createqueryeditmultiuse
Skip any deformer, shape, or layer that whose name matches the given regular expression string
-vertexConnections(-vc) createqueryedit
Export vertex connection information, which is required for -m/-method "barycentric" and "bilinear". The flag is only used with -ex/-export flag. The vertex connection information is automatically loaded during import if available in xml file.
-weightPrecision(-wp) uint createqueryedit
Sets the output decimal precision for exported weights. The default value is 3.
-weightTolerance(-wt) float createqueryedit
The weight tolerance is used to decide if a given weight value is close enough to the default value that it does not need to be included. This flag is only used with export. The default value is .001.
-worldSpace(-ws) createqueryedit
For spatially based association methods (nearest), the position should be based on the world space position rather then the local object space.

Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can be used more than once in a command.

MEL examples


proc createRig(string $nsp, int $res)
{

    // Create a plane with two clusters in a namespace.
    //
    string $shpName = $nsp+":myShape";
    print $shpName;
    polyPlane -w 10 -h 10 -sx $res -sy $res -ax 0 1 0 -ch 1 -n $shpName;
    cluster -n ($nsp+":clusterA") $shpName;
    cluster -n ($nsp+":clusterB") $shpName;
}


//--------------------------------------------------------------------
// Create the setup.
//--------------------------------------------------------------------

// Clear file.
file -f -new;

// Create plane and two clusters.
createRig("nsp1", 5);

// Modify some weights on clusterA
select nsp1:myShape.vtx[6:11];
percent -v 0.5 nsp1:clusterA;

// Modify some weights on clusterB
select nsp1:myShape.vtx[0:2] nsp1:myShape.vtx[6:8] nsp1:myShape.vtx[12:14];
percent -v 0.3 nsp1:clusterB;


//--------------------------------------------------------------------
// Export the weights in a variety of different ways
//--------------------------------------------------------------------

// Write cluster A weights.
//
deformerWeights -export -deformer "nsp1:clusterA" "clusterA.xml";

// Write cluster B weights, but do not write values of 1.0.
//
deformerWeights -export -deformer "nsp1:clusterB" -dv 1.0 "clusterB.xml";

// Write cluster A and B weights at the same time.
//
deformerWeights -export -deformer "nsp1:clusterA" -deformer "nsp1:clusterB" "clusterAB.xml";

// Export weights for all deformers on the shape, including vertex connections.
//
deformerWeights -export -vc -sh "nsp1:myShape" "shape_all.xml";

// Same as above skipping deformers matching "*B".
//
deformerWeights -export -vc -sh "nsp1:myShape" -sk "*B" "shape_NotB.xml";

// Export weights and attributes.
//
deformerWeights -export -vc -attribute "envelope" -attribute "percentResolution" -attribute "usePartialResolution" -sh "nsp1:myShape" "shape_all_attr.xml";

// Export name space nsp1: in scene to nsp2: in xml.
deformerWeights -export -vc -sh "nsp1:myShape" -remap "nsp1:(.*);nsp2:$1" "shape_all_nsp2.xml";



//--------------------------------------------------------------------
// Import the weights
//--------------------------------------------------------------------

// Read both cluster's weight files separately.
deformerWeights -import -sh "nsp1:myShape" -deformer "nsp1:clusterA" "clusterA.xml";
deformerWeights -import -sh "nsp1:myShape" -deformer "nsp1:clusterB" "clusterB.xml";

// Read both deformers from the single file.
deformerWeights -import -sh "nsp1:myShape" -deformer "nsp1:clusterA" -deformer "nsp1:clusterB" "shape_all.xml";

// Alternative way of reading both deformers.
deformerWeights -import -deformer "nsp1:clusterA" -deformer "nsp1:clusterB" "shape_all.xml";

// Read clusterA from the file containing both clusters.
deformerWeights -import -deformer "nsp1:clusterA" "shape_all.xml";


//
// Create the same rig in a different namespace.
//
createRig("nsp2", 5);

// Import weights from file that remapped the namespace on export.
deformerWeights -import -sh "nsp2:myShape" -deformer "nsp2:clusterA" -deformer "nsp2:clusterB" "shape_all_nsp2.xml";

// Import weights from file containing a different namespace, and remap the namespace on import.
deformerWeights -import -sh "nsp2:myShape" -deformer "nsp2:clusterA" -deformer "nsp2:clusterB" -remap "nsp1:(.*);nsp2:$1" "shape_all.xml" ;

//
// Create similar rig with different resolution (topology) in a different namespace.
//
createRig("nsp3", 8);

// Import weights from file, remap the namespace on import, and use the barycentric method to remap the weight values.
deformerWeights -import -sh "nsp3:myShape" -deformer "nsp3:clusterA" -deformer "nsp3:clusterB" -remap "nsp1:(.*);nsp3:$1" -method "barycentric" "shape_all.xml";