## Envelope

Object Hierarchy | Related C++ Class: Envelope

### Inheritance

###

SIObject

ProjectItem

Operator

Envelope

### Description

The Envelope object represents an Envelope Operator on an object. For example an envelope can be used to deform a mesh surface according to changes in the positions of ChainBones.
It is possible to add an envelope operator to a point Cluster using SceneItem.ApplyEnvelope. It is also possible to call ApplyEnvelope on an X3DObject, in which case a complete point cluster is automatically created.
A ClusterProperty is used to store the influence that each deformer has on each point. This data can be read and updated from the Object Model via the Envelope.Weights property.
The Envelope Operators on an object can be accessed via the Primitive.ConstructionHistory property (see X3DObject.ActivePrimitive). Alternatively an envelope can be accessed via the SceneItem.Envelopes property on the Cluster.

### Methods

AddCustomOp | AddICEAttribute | AddScriptedOp | AddScriptedOpFromFile
AnimatedParameters2 | BelongsTo | Connect | ConnectToGroup
Copy | Disconnect | DisconnectGroup | EvaluateAt
GetDeformerColor | GetDeformerWeights | GetICEAttributeFromName | GetInputValue
GetNumInstancesInGroup | GetNumPortGroups | GetNumPortsInGroup | GetPort2
GetPort3 | GetPortAt | GetWeights2 | IsA
IsAnimated2 | IsClassOf | IsEqualTo | IsKindOf
IsLocked | IsSelected | LockOwners | PortAt
RemoveICEAttribute | SetAsSelected | SetCapabilityFlag | SetDeformerColor
SetDeformerWeights | SetDeformerWeights2 | SetLock | SupportsBranchGroup
TaggedParameters | UnSetLock |  |

### Properties

Application | BranchFlag | Capabilities | Categories
Deformers | Elements | EvaluationID | Families
FullName | Help | HierarchicalEvaluationID | ICEAttributes
InputPorts | IsConnected | LockLevel | LockMasters
LockType | Model | Mute | Name
NestedObjects | ObjectID | Origin | OriginPath
OutputPorts | Owners | PPGLayout | Parameters
Parent | Parent3DObject | Port | PortGroups
Selected | Type | Weights |

### Examples

#### 1. VBScript Example

    'vbscript example how to access and change the weights of an envelope

    newscene , false

    set oRoot = Application.ActiveProject.ActiveScene.Root

    set oSphere = oRoot.AddGeometry( "Sphere", "MeshSurface")

    set oChainRoot = oRoot.Add3DChain

    ' apply envelope to geometry

    set oEnvelope = oSphere.ApplyEnvelope( oChainRoot, siBranch )

    ' Here is another way to get this new envelope:

    set oEnvelope = oSphere.Envelopes(0)

    ' get 2D array of element/deformer weights

    aWeights = oEnvelope.Weights.Array

    ' change the weights so each deformer has equal influence

    equalWeight = 100 / oEnvelope.Deformers.Count

    for iElement=lbound(aWeights,2) to ubound(aWeights,2)

    	for iDeformer=lbound(aWeights,1) to ubound(aWeights,1)

    		aWeights(iDeformer,iElement) = equalWeight

    	next

    next

    ' after manipulating the weights set the updated

    ' weights back on the envelope

    oEnvelope.Weights.Array = aWeights

#### 2. JScript Example

    //jscript example how to access and change the weights of an envelope

    var dft

    newscene(dft, false ) ;

    var oRoot = Application.ActiveProject.ActiveScene.Root

    var oSphere = oRoot.AddGeometry( "Sphere", "MeshSurface") ;

    var oChainRoot = oRoot.Add3DChain() ;

    //apply envelope to geometry

    var oEnvelope = oSphere.ApplyEnvelope( oChainRoot, siBranch ) ;

    //Here is another way to get this new envelope:

    var oEnvelope = oSphere.Envelopes(0) ;

    //get 2D array of element/deformer weights

    var aVBWeights = new VBArray( oEnvelope.Weights.Array ) ;

    //convert to a jscript (1D) array object

    var aWeights = aVBWeights.toArray() ;

    //change the weights so each deformer has equal influence

    equalWeight = 100 / oEnvelope.Deformers.Count ;

    for ( iElement = 0 ; iElement < aWeights.length ; iElement++ )

    {

    	aWeights[iElement] = equalWeight ;

    }

    //after manipulating the weights set the updated

    //weights back on the envelope

    oEnvelope.Weights.Array = aWeights

#### 3. VBScript Example

    'vbscript example that demonstrates how to apply an envelope to

    'a cluster.

    'It demonstrates how the index in the weights array are based on the

    'cluster index, but how this can easily be translated to the

    'true vertex index

    newscene ,false

    set oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" )

    'Create a cluster that only contains some of the points.

    'These are the only points that will be inflenced by the skeleton

    set oCluster = oSphere.ActivePrimitive.Geometry.AddCluster( _

    				siVertexCluster, "MyFrontPoints", Array( 18,19,20,25,26,27) )

    'Create the skeleton

    set oChainRoot = ActiveSceneRoot.Add3DChain

    set oEffPos = XSIMath.CreateVector3

    oEffPos.Set 3,3,3

    set oBone1 = oChainRoot.AddBone(oEffPos)

    set oEnvelope = oCluster.ApplyEnvelope( oChainRoot, siBranch )

    aWeights = oEnvelope.Weights.Array

    for iElement=lbound(aWeights,2) to ubound(aWeights,2)

    	'Build a string with all the deformer weights

    	strElementWeights=""

    	for iDeformer=lbound(aWeights,1) to ubound(aWeights,1)

    		strElementWeights = strElementWeights & Round( aWeights(iDeformer,iElement), 2) & ","

    	next

    	'Calculate the index of the point that corresponds to this

    	'index in the cluster

    	iVertex = oEnvelope.Elements.Item( iElement )

    	'an equivalent way to calculate this same result is as follows:

    	'iVertex = oCluster.Elements.Item( iElement )

    	logmessage "Cluster element " & iElement & _

    		     " (pnt " & iVertex & ") has weights " & strElementWeights

    next

    'Output of this script is:

    'INFO : "Cluster element 0 (pnt 18) has weights 0,50.26,49.74,0,"

    'INFO : "Cluster element 1 (pnt 19) has weights 0,37.73,62.27,0,"

    'INFO : "Cluster element 2 (pnt 20) has weights 0,21.99,78.01,0,"

    'INFO : "Cluster element 3 (pnt 25) has weights 0,41.27,58.73,0,"

    'INFO : "Cluster element 4 (pnt 26) has weights 0,14.34,85.66,0,"

    'INFO : "Cluster element 5 (pnt 27) has weights 0,0.29,99.71,0,"

### See Also

ChainRoot SceneItem.ApplyEnvelope Envelope.Weights Cluster ClusterProperty