ShapeKey

Object Hierarchy | Related C++ Class: ShapeKey

Inheritance

SIObject

ProjectItem

Property

ClusterProperty

ShapeKey

Introduced

v4.0

Description

The ShapeKey object represents a special ClusterProperty which is used to store a specific geometry. ShapeKeys provide information about how the shape of a cluster changes by either storing its absolute value, an offset based on the object referential or values base on the local reference frame of vertices.

You can find out the key's reference mode by getting the value of the KeyType Parameter. To convert from one reference mode to the other, use the ConvertShapeReferenceMode command.

Warning: The KeyType parameter uses a different set of values from the siShapeReferenceMode enum. For more information, see Shape Animation.

Because a ShapeKey modifies scene content when instantiated, it is an AnimationSource and as such can be accessed by using the AnimationSourceItem.Source method.

Methods

AddCustomOp AddScriptedOp AddScriptedOpFromFile AnimatedParameters2
BelongsTo operator EvaluateAt GetICEAttributeFromName IsA
IsAnimated2 IsClassOf operator IsEqualTo operator IsKindOf
IsLocked operator IsSelected operator LockOwners SetAsSelected operator
SetCapabilityFlag operator SetLock TaggedParameters UnSetLock

Properties

Application Branch operator BranchFlag operator Capabilities operator
Categories Elements operator EvaluationID Families operator
FullName operator Help HierarchicalEvaluationID ICEAttributes
LockLevel operator LockMasters operator LockType operator Model
Name operator NestedObjects ObjectID Origin
OriginPath Owners PPGLayout operator Parameters operator
Parent Parent3DObject Selected operator ShapeGroupName
Singleton operator Type operator    
       

Examples

1. JScript Example

/*
        The following example illustrates how to access the position
        information stored in a shape key. Adding a shape key using
        local reference mode will store the positions as deltas to
        the local referential of each point. To calculate the
        absolute position for each point you need the local
        referential for the point and the original position before
        the shape was applied.
*/
// Create the scene with an object with a shape clip
NewScene( null, false );
var root = Application.ActiveSceneRoot;
var c1 = root.AddGeometry( "Cube", "MeshSurface" );
var c2 = Duplicate( c1, 1, 2, 1, 1, 0, 0, 1, 0, 1 )(0);
Translate( c2, 10, 0, -2, siRelative, siView, siObj, siXYZ );
Translate( c2 + ".pnt[2,3,6,LAST]", -6, -4, 4, siRelative, siView, siObj, siXYZ );
// Add a shapeclip where the position data is stored as deltas to
// the point's local referential. You can also store the shape in
// absolute mode in which case the cluster property contains
// for the shape the actual point data or you can store it in
// object mode in which case deltas are stored in the object
// referential (i.e. the pose of the object).
var key = SelectShapeKey( c1, c2, siShapeLocalReferenceMode );
var mix = ( root.HasMixer() ) ? root.Mixer : root.AddMixer();
var shapetrack = AddTrack( root, mix, 1 );
AddClip( root, key, "", shapetrack, 1, null, "", "", false );
//
// Get the shapeclip
//
var clip;
var c = new Enumerator( mix.Clips );
for ( ; !c.atEnd(); c.moveNext() ) {
        if ( c.item().Type == siClipShapeType ) {
                clip = c.item();
        }
}
// We need to mute the shape combiner and all the operators above it
// in order to get the local reference frame and position of each
// point before the shape animation was applied to the geometry.
// (This gives the position values before the shape that was stored
// and does not include the result of deformations applied afterwards.)
var geom = null;
for ( var idx=0; idx<clip.MappedItems.Count; idx++ ) {
        var mi = clip.MappedItems(idx);
        Application.LogMessage( Application.ClassName(mi) );
        Application.LogMessage( Application.ClassName(mi.Source2) );
        // Get the cluster property/shape key stored in the shapeclip
        var clsprop = mi.Source2;
        // Since the geometry for each mappeditem will be
        // the same we'll only need to get it once.
        if ( !geom ) {
                // Get the primitive and geometry from the cluster property
                geom = clsprop.Parent.Parent;
                var prim = geom.Parent;
                // Deactivate all operators above and including the shape combiner
                DeactivateAbove( prim.FullName + ".clustershapecombiner", true );
                // Get the position array from the geometry
                var aPosition = geom.Points.PositionArray;
                // Get the old Geometry0D object to access
                // the local reference frame for each point
                var geomv1 = geom.Parent.Obj;
                var o0DGeometry = geomv1.Geometry0D;
        }
        // Assume that the number of cluster property elements
        // matches the geometry and that they are same order i.e.
        // point0 == clusterelement0
        // Get the delta position array from the clusterproperty
        var vbaDelta = clsprop.Elements.Array;
        // Figure out the absolute position value using the deltas,
        // the original point position and the local referential
        // of each point
        for ( var i=vbaDelta.lbound(2); i<=vbaDelta.ubound(2); i++ ) {
                // Set a vector3 with the delta for the position
                var oDelta = XSIMath.CreateVector3(
                        vbaDelta.getItem(0,i),
                        vbaDelta.getItem(1,i),
                        vbaDelta.getItem(2,i)
                );
                // Get the local reference frame for the point
                var oXAxis = XSIMath.CreateVector3();
                var oYAxis = XSIMath.CreateVector3();
                var oZAxis = XSIMath.CreateVector3();
                var oXAxisValid, oYAxisValid, oZAxisValid;
                var rtn = o0DGeometry.LocalReferenceFrame( i, oXAxis, oXAxisValid, oYAxis, oYAxisValid, oZAxis, oZAxisValid );
                // Get the transformation matrix to go from point
                // local reference frame to object referential
                var oMatrix33 = XSIMath.CreateMatrix3(
                        oXAxis.X , oXAxis.Y, oXAxis.Z,
                        oYAxis.X , oYAxis.Y, oYAxis.Z,
                        oZAxis.X , oZAxis.Y, oZAxis.Z
                );
                oDelta.MulByMatrix3( oDelta, oMatrix33 );
                // Set a vector3 with the point position
                var oPosition = XSIMath.CreateVector3(
                        aPosition.getItem(0,i),
                        aPosition.getItem(1,i),
                        aPosition.getItem(2,i)
                );
                // Compute the absolute position by adding the delta
                oPosition.AddInPlace( oDelta );
                // Log the absolute position values for the point
                Application.LogMessage( oPosition.X + "," + oPosition.Y + "," + oPosition.Z     );
        }
}
// Reactivate shapecombiner and all operators above it
if ( !prim ) {
        DeactivateAbove( prim.FullName + ".clustershapecombiner", false );
}
// Enumerate the shapeclips under the mixer shape track.
var t = new Enumerator( ActiveSceneRoot.Mixer.Tracks );
for ( ; !t.atEnd(); t.moveNext() ) {
        if ( t.item().Type == siTrackShapeType ) {
                var shapetrack = t.item();
                break;
        }
}
for ( var s=0; s<shapetrack.Clips.Count; s++ ) {
        var shapeclip = shapetrack.Clips(s);
        Application.LogMessage( shapeclip );
}
// Expected results:
// INFO : MappedItem
// INFO : ShapeKey
// INFO : -4,-4,-4
// INFO : 4,-4,-4
// INFO : -10,-8.881784197001252e-16,8.881784197001252e-16
// INFO : -2.000000000000001,-8.881784197001252e-16,8.881784197001252e-16
// INFO : -4,-4,4
// INFO : 4,-4,4
// INFO : -10.000000000000001,-8.881784197001252e-16,8.000000000000001
// INFO : -2.0000000000000017,-1.7763568394002505e-15,8
// INFO : Mixer.Mixer_Shape_Track.cube1_ShapeKey_Clip

2. Python Example

# 
# Three cones are created with identical animation although 
# they use different Reference Modes to record the shape 
# 
from win32com.client import constants as c
app = Application
app.NewScene( "", 0 )
root = app.ActiveSceneRoot
# Local mode
obj1 = root.AddGeometry( "Cone", "MeshSurface" )
app.ApplyOp( "bend", obj1 )
obj1.posz.Value = -3
geom1 = obj1.ActivePrimitive.Geometry
clip1 = geom1.SaveShapeKey( 1, 1, c.siShapeLocalReferenceMode, c.siShapeInstanceOnlyMode, "MyShapeKey1", [1], [1,1,0] )
# Absolute mode
obj2 = root.AddGeometry( "Cone", "MeshSurface" )
app.ApplyOp( "bend", obj2 )
geom2 = obj2.ActivePrimitive.Geometry
clip2 = geom2.SaveShapeKey( 1, 1, c.siShapeAbsoluteReferenceMode, c.siShapeInstanceOnlyMode, "MyShapeKey2", [1], [1,1,0] )
# Object mode
obj3 = root.AddGeometry( "Cone", "MeshSurface" )
app.ApplyOp( "bend", obj3 )
obj3.posz.Value = 3
geom3 = obj3.ActivePrimitive.Geometry
clip3 = geom3.SaveShapeKey( 1, 1, c.siShapeObjectReferenceMode, c.siShapeInstanceOnlyMode, "MyShapeKey3", [1], [1,1,0] )

3. C# Example

/*
        This example demonstrates how you access the shape information for a particular shape key by looking
        at the cluster properties which store this data
*/
using System;
using Softimage.XSIOM; // Softimage object model
using Softimage.XSIMath;
using Softimage.XSIUtil;
using System.Text.RegularExpressions;   // for Regex class instanced in ShowShapeInformation
public class XSIPlugin
{
        public bool Load( PluginRegistrar in_reg )
        {
                in_reg.Author = "ShapeKeyDemo";
                in_reg.Name = "ShapeKeyCSexamplePlugin";
                in_reg.Major = 1;
                in_reg.Minor = 0;
                in_reg.RegisterCommand("ShapeKeyCSexample", "ShapeKeyCSexample");
                return true;
        }
}
public class ShapeKeyCSexample : XSIPlugin
{
        public bool Init( Context in_ctxt )
        {
                Command oCmd = null;
                oCmd = (Command)in_ctxt.Source;
                oCmd.Description = "ShapeKey object example written in CSharp";
                oCmd.Tooltip = "CSharp ShapeKey example";
                oCmd.ReturnValue = false;
                return true;
        }
        // --------------------------------------------------------------------------
        // Gets the shape clusters on the specified object, accesses their shape keys
        // and reports on their reference mode and position
        public bool ShowShapeInformation( X3DObject in_obj )
        {
                CXSIApplicationClass app = new CXSIApplicationClass();
                try {
                        ClusterCollection oClusters = in_obj.ShapeAnimatedClusters();
                        app.LogMessage( "Dump of shape key data on object " + in_obj.FullName, siSeverity.siInfo );
                        long cntFoundShapes = 0;
                        // Go through the various clusters on the object
                        // (in practice only the Point clusters will have shape keys)
                        foreach ( Cluster oCluster in oClusters ) {
                                // Cluster indices are not the same as the indices on the
                                // geometry, but we can easily determine the relationship with
                                // this array:
                                ClusterElementCollection oClusterElementsCollection = oCluster.Elements;
                                Array aElements = (Array)oClusterElementsCollection.Array;
                                // Only search for the shape keys, which have type "clskey"
                                PropertyCollection oLocalProps = oCluster.LocalProperties;
                                PropertyCollection oClsKeyProps = oLocalProps.Filter("clskey", null, null);
                                foreach ( ShapeKey oProperty in oClsKeyProps ) {
                                        // Found a shape key
                                        cntFoundShapes++;
                                        Regex rx = new Regex(@"ResultClusterKey$", RegexOptions.IgnoreCase);
                                        if ( rx.IsMatch(oProperty.Name) ) {
                                                // There may also be an internal cluster property
                                                // called "ResultClusterKey" which stores the
                                                // result of blending the various shapes at the
                                                // current time
                                                app.LogMessage( "Blended shape at current time: " + oProperty.FullName, siSeverity.siInfo );
                                        } else {
                                                app.LogMessage( "Shape key: " + oProperty.FullName, siSeverity.siInfo );
                                        }
                                        // The reference mode is available from the KeyType parameter
                                        Parameter oClsKeyTypeParam = oProperty.Parameters["KeyType"];
                                        Object ReferenceType =  oClsKeyTypeParam.get_Value(null);
                                        switch ( ReferenceType.ToString() ) {
                                                case "0" :
                                                case "6" :
                                                        app.LogMessage( "\tUses: Absolute Reference Mode", siSeverity.siInfo );
                                                        break;
                                                case "1" :
                                                case "5" :
                                                        app.LogMessage( "\tUses: Local Reference Mode", siSeverity.siInfo );
                                                        break;
                                                case "2" :
                                                case "3" :
                                                        app.LogMessage( "\tUses: Object Reference Mode", siSeverity.siInfo );
                                                        break;
                                                default :
                                                        app.LogMessage( "\tReference Mode = " + ReferenceType.ToString(), siSeverity.siInfo );
                                                        break;
                                        }
                                        // The contents of the cluster can be found in this safearray
                                        // (which we can read via the VBArray object)
                                        ClusterElementCollection oShapeKeyElements = oProperty.get_Elements();
                                        Array aXYZArray = (Array)oShapeKeyElements.Array;
                                        for ( int i=0; i<aXYZArray.GetLength(aXYZArray.Rank-1); i++ ) {
                                                // Print out the x,y,z values
                                                app.LogMessage( "\tpnt["+ aElements.GetValue(i).ToString() + "] has position ("
                                                        + Math.Round( (double)aXYZArray.GetValue(0,i), 3 ).ToString() + ","
                                                        + Math.Round( (double)aXYZArray.GetValue(1,i), 3 ).ToString() + ","
                                                        + Math.Round( (double)aXYZArray.GetValue(2,i), 3 ).ToString() + ")",
                                                        siSeverity.siInfo
                                                );
                                        }
                                }
                        }
                        if ( cntFoundShapes == 0 ) {
                                app.LogMessage( "There are no shapes on this object", siSeverity.siInfo );
                        }
                } catch {
                        app.LogMessage( "Please select a 3D Object", siSeverity.siInfo );
                        return false;
                }
                return true;
        }
        public bool Execute( Context in_ctxt )
        {
                // Set up a little scene
                CXSIApplicationClass app = new CXSIApplicationClass();
                Object[] args = new Object[2] { null, false };
                Object rtn = app.ExecuteCommand( "NewScene", args );
                Model root = app.ActiveSceneRoot;
                X3DObject oCircle = root.AddGeometry( "Sphere", "MeshSurface", null );
                // Move the top and bottom point of the sphere outwards
                Primitive oPrim = oCircle.ActivePrimitive;
                Geometry oGeom = oPrim.get_Geometry( null );
                Object[] aIndexArray = new Object[2] { 1, 0  };
                Object[] aPositionArray = new Object[6] { 0,6,0, 0,-6,0 };
                oGeom.SaveShapeKey( 0.5, 3.0, siShapeReferenceMode.siShapeAbsoluteReferenceMode,
                        siShapeInstanceMode.siShapeInstanceOnlyMode, "ShapeKey1", aIndexArray, aPositionArray, null );
                // Move two different points - this creates a new, independent cluster
                // We can use a different reference mode for this, but we still specify the
                // point positions in Absolute terms.
                aIndexArray = new Object[2] { 5, 33  };
                aPositionArray = new Object[6] { -2,0,0, 2,0,0 };
                oGeom.SaveShapeKey( 0.8, 1.0, siShapeReferenceMode.siShapeLocalReferenceMode,
                        siShapeInstanceMode.siShapeInstanceOnlyMode, "ShapeKey2", aIndexArray, aPositionArray, null );
                if ( ShowShapeInformation(oCircle) ) {
                        return true;
                } else {
                        app.LogMessage("ShowShapeInformation failed.", siSeverity.siInfo);
                        return false;
                }
        }
}
// --------------------------------------------------------------------------
// Expected output:
// INFO : Dump of shape key data on object sphere
// INFO : Blended shape at current time: sphere.polymsh.cls.Shape.ResultClusterKey
// INFO :       Uses: Absolute Reference Mode
// INFO :       pnt[1] has position (0,0,0)
// INFO :       pnt[0] has position (0,0,0)
// INFO : Shape key: sphere.polymsh.cls.Shape.ShapeKey
// INFO :       Uses: Absolute Reference Mode
// INFO :       pnt[1] has position (0,6,0)
// INFO :       pnt[0] has position (0,-6,0)
// INFO : Blended shape at current time: sphere.polymsh.cls.Shape1.ResultClusterKey
// INFO :       Uses: Local Reference Mode
// INFO :       pnt[5] has position (0,0,0)
// INFO :       pnt[33] has position (0,0,0)
// INFO : Shape key: sphere.polymsh.cls.Shape1.ShapeKey2
// INFO :       Uses: Local Reference Mode
// INFO :       pnt[5] has position (0,-2,0)
// INFO :       pnt[33] has position (0,-2,0)

See Also

ShapeClip ActionSource Clip.Source StoreShapeKey SelectShapeKey