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 AddScriptedOp AddScriptedOpFromFile AnimatedParameters2
BelongsTo operator Connect ConnectToGroup Copy
Disconnect DisconnectGroup EvaluateAt GetDeformerColor
GetDeformerWeights GetICEAttributeFromName GetInputValue GetNumInstancesInGroup operator
GetNumPortGroups operator GetNumPortsInGroup operator GetPort2 operator GetWeights2
IsA IsAnimated2 IsClassOf operator IsEqualTo operator
IsKindOf IsLocked operator IsSelected operator LockOwners
PortAt operator SetAsSelected operator SetCapabilityFlag operator SetDeformerColor
SetDeformerWeights SetDeformerWeights2 SetLock SupportsBranchGroup operator
TaggedParameters UnSetLock    
       

Properties

Application BranchFlag operator Capabilities operator Categories
Deformers Elements EvaluationID Families operator
FullName operator Help HierarchicalEvaluationID ICEAttributes
InputPorts operator IsConnected operator LockLevel operator LockMasters operator
LockType operator Model Mute operator Name operator
NestedObjects ObjectID Origin OriginPath
OutputPorts operator Owners PPGLayout operator Parameters operator
Parent Parent3DObject Port operator PortGroups operator
Selected operator Type operator 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