Scripting: LockEnvelopeWeights

LockEnvelopeWeights

Introduced

v5.0

Description

Prevents modifying the envelope weights for point deformer pairs.

The effect of an envelope deformation is controlled by a weight mapping. You can modify these envelope weights with painting, smoothing, or numerical edition tools. This command allows you to block weights for some deformers to be modified either directly or indirectly through normalization.

Note that this command requires two arrays. These two arrays together define the (point,deformer) pairs to lock. For example, if the point array (2,62,93) and the deformer array (1,12,16) are passed this means that the weight between the second point of and the first deformer will be locked, the weight between the 62nd point and 12th deformer will be locked, and the weight between the 93rd point and 16th deformer will be locked. Hence, the size of these two arrays must be equal. The deformer indices are as connected to the envelope property.

Scripting Syntax

oReturn = LockEnvelopeWeights( PropObj, Points, Deformers, [Locked] );

Return Value

Returns an XSICollection that contains the new operator that applies the locking.

Parameters

Parameter	Type	Description
PropObj	String	Envelope weights property for which we want to lock the weights.
Points	XSICollection	Array of points indices to be locked.
Deformers	String	Array of point deformers to be locked.
Locked	Boolean	Should these deformers be locked (otherwise unlocked). Default Value: True

Examples

JScript Example

/*
        This example illustrates how you can control the normalization process
        when setting envelope weights by using weight locking. Normalization
        automatically enforces that the sum of the weights for a given point
        is always maintained to 100% when modifying weights numerically,
        by painting or through any of the other weight editing commands.
*/
// We start with a simple cylinder enveloped to a 6 bone chain
NewScene( null, false );
var oCyl = CreatePrim( "Cylinder", "MeshSurface" );
SetValue( "cylinder.cylinder.height", 10 );
SetValue( "cylinder.polymsh.geom.subdivv", 20 );
SetValue( "cylinder.polymsh.geom.subdivu", 16 );
Create2DSkeleton( 1.97818728045807E-02, 5.04656031338284, 0, 0.81105678498785, 3.66123003127775, 0, 0, 0, 0, 4 );
AppendBone( "eff", 0.890184276206176, 1.91967196234563, 0 );
AppendBone( "eff", 0.969311767424504, 0.257275623819517, 0 );
AppendBone( "eff", 1.00887551303367, -1.76134850153362, 0 );
AppendBone( "eff", 0.969311767424504, -3.18625964884171, 0 );
AppendBone( "eff", 1.97818728045807E-02, -4.96739858297683, 0 );
SelectObj( "cylinder", null, true );
ApplyFlexEnv( "cylinder;bone,bone1,bone2,bone3,bone4,bone5,eff", false, 0 );
// Say that for a given set of points you want to set the
// envelope weight assignment so that the points are weighted
// 50% to "bone1", 25% to "bone" and 25% to "bone2"
// You can first set the weight for these points to 50% to "bone1"
SIModifyFlexEnvWght( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", "bone1", 
        "cylinder.pnt[18,19,41,42,64,65,87,88,110,111,133,134,156,157,179,180,202,203,225,226,248,249,271,272,294,295,317,318,340,341,363,364]", 0, 50 );
// Get the list of deformers to use as input to the LockEnvelopeDeformerWeights command
var oDefs = new ActiveXObject( "XSI.Collection" );
oDefs.SetAsText( "bone1" );
// Tip - Alternatively, you could use "oDefs.Add oCyl.Envelopes(0).Deformers(0)" to populate the Deformers collection
// Now to avoid that normalization affects the new 50%
// assignment, we can lock the weights for deformer "bone1" as follows:
LockEnvelopeDeformerWeights( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", oDefs, true );
// Now we can assign the two other bones to 25% without having normalization
// affect the "bone1" values.
SIModifyFlexEnvWght( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", "bone", 
        "cylinder.pnt[18,19,41,42,64,65,87,88,110,111,133,134,156,157,179,180,202,203,225,226,248,249,271,272,294,295,317,318,340,341,363,364]", 0, 25 );
SIModifyFlexEnvWght( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", "bone2", 
        "cylinder.pnt[18,19,41,42,64,65,87,88,110,111,133,134,156,157,179,180,202,203,225,226,248,249,271,272,294,295,317,318,340,341,363,364]", 0, 25 );
// Now once we're done we can unlock the weights for that
// deformer in the same way:
LockEnvelopeDeformerWeights( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", oDefs, false );
// We could have also simply cleared all weight locks as follows:
ClearEnvelopeWeightLocks( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights" );
// Now weights don't need to be locked on a per deformer basis.
// One could have locked individual point/deformer weight pairs as follows:
LockEnvelopeWeights( "cylinder.polymsh.cls.EnvelopWeightCls.Envelope_Weights", new Array(41,42,64,65), new Array(1,1,2,2), true );
// This last command locks the weight for points 41 and 42 for deformer 1 (the
// second deformer since indices start at zero) and points 64 and 65 for deformer 2.