Softimage SDK Programmer's Guide > Plug-in Development > Animation >

# Shape Animation

With shape animation you can change the shape of an object over time. To do this, you store shape keys for each pose based on the geometrical shape (deformation) of an object's clusters of points (clusters made of polygons or edges are not supported).

Shape animation stores shape data on point clusters relative to the reference shape in ShapeKeys or ShapeKeys. Shape animation is a specialized kind of Source or Source object called an ActionSource or ActionSource object.

Shape Key Reference Modes

The ShapeKey or ShapeKey object represents a special ClusterProperty or ClusterProperty which is used to store a specific geometry. Shape keys 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 based on the local reference frame of vertices. You can find out the key's reference mode by getting the value of the KeyType parameter, which uses these values:

- 0 = Absolute (shape is absolute)

- 1 = Local (shape is relative to the reference frame of the control vertices)

- 2 = Object (shape is relative to the primitive reference frame)

- 3 = Result Object (blended shape is relative to the primitive reference frame)

- 4 = Reference

- 5 = Result Local (blended shape is relative to the reference frame of the control vertices)

- 6 = Result Absolute (blended shape is absolute)

- 7 = Result Absolute Null

- 8 = Unknown

Important

It is important to recognize that the values used by the KeyType parameter do not correspond to the values represented by the siShapeReferenceMode enum, which is used for many functions such as the Geometry.SaveShapeKey method, the CClusterPropertyBuilder::AddShapeKey member function, the ConvertShapeReferenceMode command, etc.

Tip

To convert from one shape key reference mode to the other, use the ConvertShapeReferenceMode command.

Creating Shape Animation

There are a number of scripting commands that can create shape keys from point clusters:

- ApplyDeformKey: Saves a pose-based deformation key

- SaveDeformKey: Saves a key on a pose-based deformation

- SelectShapeKey: Selects a list of objects as shape keys for another object

Shape keys can also be assigned to shape groups (used to semantically organize shape keys within a given cluster). You can create shape groups with the CreateShapeGroup command and use the SetShapeGroup command to assign shape keys to the groups.

Shape Animation and the Mixer

A Shape key can also be bundled into an ActionSource or ActionSource which is stored under the Mixer and instantiated as a ShapeClip or ShapeClip. A ShapeClip object is an instance of a shape key (source) at a particular position along a shape track in the animation mixer. You can create shape clips using the Geometry.SaveShapeKey method in the object model (there is no equivalent function in the C++ API) or one of the following scripting commands:

- SaveShapeKey: Creates a shape key for the current shape and adds it to the model's list of shape sources in the model's Mixer > Sources > Shape folder

- StoreShapeKey: Stores a shape key in the model's Mixer > Sources > Shape folder but it does not create a shape clip in the mixer

- ApplyShapeKey: Applies the specified shape key to an object at the current frame and creates a ShapeClip in the animation mixer

Like other clips based on ActionSources, ShapeClips can be simple (siClipShapeType) or compound (siClipShapeCompoundType) which you can test on the Clip object with the SIObject.Type or SIObject::GetType property.

Exporting Shape Keys

You can export shape keys to .obj files without touching the animation by soloing the shapes on the geometry. Soloing consists of two actions:

1. Set the ShowResult parameter of the clustershapecombiner to false.

2. Set the SoloIndex parameter to the shape you want to export.

For example, this snippet demonstrates how to solo and then export a shape key using scripting commands:

Python Example: Soloing and Exporting Shape Keys

This example uses scripting commands to perform most of the actions.

    # Setup a few Python-specific things
    from win32com.client import constants as c# so we can use Softimage constants
    app = Application			# use pointer since we are using so many commands

    # Start by making a cone and deforming the topmost point
    app.NewScene( "", 0 )
    obj = app.CreatePrim( "Cone", "MeshSurface" )
    app.SetValue( "Context.ConstructionMode", 1 )
    app.ActivateVertexSelTool()
    app.AddToSelection( "cone.pnt[1]", "ASITIS", 1 )
    app.Translate( "cone.pnt[1]", -4.03443654541759, 4.44089209850063E-16, -3.46944695195361E-17,
    	c.siRelative, c.siView, c.siObj, c.siXYZ )

    # Now save a shape key on the cone
    app.SaveShapeKey( "cone.pnt[1]", "", "", 1, "", "", "", "", c.siShapeObjectReferenceMode )
    app.SelectFilter( "object" )
    app.SelectObj( "Mixer.Mixer_Shape_Track.Shape_ClusterClip" )
    app.SetValue( "Mixer.Mixer_Shape_Track.Shape_ClusterClip.Mixer_Shape_Track1.ShapeKey_Clip.actionclip.weight", 0.52 )
    app.SetKey( "Mixer.Mixer_Shape_Track.Shape_ClusterClip.Mixer_Shape_Track1.ShapeKey_Clip.actionclip.weight", 1, 0.52 )

    # Solo the shape key
    app.Selection.SetAsText( obj.Name )
    stack = obj.ActivePrimitive.ConstructionHistory
    for op in stack :
    	if op.Type == "clustershapecombiner" :
    		op.Parameters("ShowResult").Value = 1 #true
    		op.Parameters("SoloIndex").Value = 1  #solo shape key

    # This is the equivalent using scripting commands:
    #app.SelectObj( "cone.polymsh.clustershapecombiner" )
    #app.SetValue( "cone.polymsh.clustershapecombiner.ShowResult", 0 )
    #app.SetValue( "cone.polymsh.clustershapecombiner.SoloIndex", 1 )

    # Export the soloed geometry in an OBJ file
    sPath = XSIUtils.BuildPath( app.InstallationPath(c.siUserPath), "Data", "SoloExportDemo.obj" )
    app.ObjExport( sPath )