Geometry.SaveShapeKey
Saves a shape key for this Geometry
and creates a new ShapeClip object in
the mixer to represent this shape. Shape keys have two parts:
sources (a shape that you have stored) and clips (an instance of a
shape key (source) at a particular position along a track in the
animation mixer).
There are two possible workflows for using this method: the first
is to change the actual shape of the primitive and then call this
method (which is similar to the SaveShapeKey command); the
second is to specify the shape using the PositionArray argument.
The example below illustrates these two approaches.
The actual data for the shape is stored as a ClusterProperty. It is possible to store
a shape key that defines positions for only a subset of the points,
by using the IndexArray argument. This can save memory on a large
object. Each subset of points with a shape key is represented by a
separate Cluster.
ShapeClip Geometry.SaveShapeKey( Double in_time, Double in_clipDuration, siShapeReferenceMode in_refMode, siShapeInstanceMode in_instMode, String in_name, Object in_indexArray, Object in_positionArray, Object in_normalArray ); |
oReturn = Geometry.SaveShapeKey( Time, [ClipDuration], [RefMode], [InstMode], [Name], [IndexArray], [PositionArray], [NormalArray] ); |
| Parameter | Type | Description |
|---|---|---|
| Time | Double | Time in seconds. The shape of the object is evaluated at this time, unless the shape is explicitly defined by the PositionArray argument. The time argument is also used when adding the ShapeClip to the Mixer. For example, if siShapeMixedWeightMode is specified as the InstMode argument, then the new shape will account for 100% of the shape at the specified time. Only a single shape key can be specified at any particular time. |
| ClipDuration | Double | Clip duration in seconds. Specify -1.0 to have the default
behavior, which depends on the InstMode argument. For example if
siShapeMixedWeightMode is specified then the ClipDuration is the
entire scene duration, but if siShapeTransitionMode is specified
then clip will last 1 second.
Default Value: -1.0 |
| RefMode | siShapeReferenceMode | Shape reference mode. This specifies how the shape is stored
and how the shape will change if the underlying reference shape
changes. The reference mode is ignored when more than one shape is
saved on the same cluster, the reference mode of the first shape
key is used instead.
Default Value: siShapeLocalReferenceMode |
| InstMode | siShapeInstanceMode | Shape instantiation mode. This controls the way the new
ShapeClip is added to the Mixer. With
siShapeMixedWeightMode a new track is created, the new clip added
to this track, and the fcurves controlling the weighting are
adjusted. With siShapeInstanceOnlyMode the clips are added to
separate tracks, but no fcurves are used to weight between the
shapes. With siShapeTransitionMode all clips are added to the same
track, with transition effects applied between them.
Default Value: siShapeMixedWeightMode |
| Name | String | Name to use for the new ShapeClip.
The ClusterProperty associated
with this shape is not affected by this argument.
Default Value: "Point_AUTO_ShapeAction_Clip" |
| IndexArray | Array | A 1-dimensional array of geometry point indices. Only these
points will be included in the shape definition. If no other shapes
use this subset of points then a new Cluster will be created.
Default Value: If not specified the shape key is saved for every point on the geometry |
| PositionArray | Array | A 1- or 2- dimensional array of key position points used for
computing the offsets of the geometry points referred by the array
of indices. The points must be specified in absolute coordinates. A
1-dimensional array must be formatted as a sequence of x,y,z
values: {Xo,Yo,Zo,...X(n-1),Y(n-1),Z(n-1)}. A 2 dimensional array
must be formatted as a Nx3 array of x,y,z values. This argument is
only considered if the IndexArray argument is specified, and must
specify the same number of points as the IndexArray.
Default Value: Shape key is based on the current positions of the geometry points |
| NormalArray | Array | A 1 or 2 dimensional array of normal points. Normals are not yet supported. |
'
' This example shows how it is possible to create shape animations from the object model.
' Two techniques are used to create the same animation on two polygons
'
dim oGrid1, oGrid2
' Technique one is similar to the process used when interactively
' saving shape keys - we change the shape of the object and then save a
' shape key
' Create a polygon
set oGrid1 = CreatePrim( "Grid", "MeshSurface" )
SetValue oGrid1 & ".polymsh.geom.subdivu", 1
SetValue oGrid1 & ".polymsh.geom.subdivv", 1
Scale oGrid1, 0.25, 0.25, 0.25, siAbsolute, siParent, siObj, siXYZ
Translate oGrid1, -2, 0, 0, siRelative, siParent, siObj, siXYZ
' Our animation will start with the initial shape at frame 1 and
' morph to the second shape until frame 30
dim frameRate, frame1Seconds, frame30Seconds
frameRate = GetValue( "PlayControl.Rate" )
frame1Seconds = 1 / frameRate
frame30Seconds = 30 / frameRate
' Save the current shape as the reference
' This remembers the locations of each vertex. This information will
' be all zeros because we haven't moved any vertices and use siShapeLocalReferenceMode
call oGrid1.ActivePrimitive.Geometry.SaveShapeKey( frame1Seconds, -1.0, _
siShapeLocalReferenceMode, siShapeMixedWeightMode )
' Move some of the points
Translate oGrid1 & ".pnt[0]" , 0, 0, -1, siRelative, siGlobal, siObj, siXYZ
Translate oGrid1 & ".pnt[2]" , 0, 0, 1, siRelative, siGlobal, siObj, siXYZ
Translate oGrid1 & ".pnt[3]" , 0, 0, -1, siRelative, siGlobal, siObj, siXYZ
' Take a second snap shot of the object
call oGrid1.ActivePrimitive.Geometry.SaveShapeKey( frame30Seconds, -1.0, _
siShapeLocalReferenceMode, siShapeMixedWeightMode )
' Technique two is direct. We describe the actual positions
' of the vertices for each shape.
set oGrid2 = CreatePrim( "Grid", "MeshSurface" )
SetValue oGrid2 & ".polymsh.geom.subdivu", 1
SetValue oGrid2 & ".polymsh.geom.subdivv", 1
Scale oGrid2, 0.25, 0.25, 0.25, siAbsolute, siParent, siObj, siXYZ
Translate oGrid2, +2, 0, 0, siRelative, siParent, siObj, siXYZ
' We only specify the vertices that actually move. In the case of
' a large object this could save a lot of memory
call oGrid2.ActivePrimitive.Geometry.SaveShapeKey( frame1Seconds, -1.0, _
siShapeLocalReferenceMode, siShapeMixedWeightMode, ,_
Array( 0,2,3 ), Array( -4,0,-4, 4,0,-4, 4,0,4) )
call oGrid2.ActivePrimitive.Geometry.SaveShapeKey( frame30Seconds, -1.0, _
siShapeLocalReferenceMode, siShapeMixedWeightMode, ,_
Array( 0,2,3 ), Array( -4,0,-8, 4,0,0, 4,0,0) )
|
'
' Three cones are created with identical animation
' although they use different Reference Modes to record the shape
'
set root = Application.ActiveProject.ActiveScene.Root
set obj = root.AddGeometry( "Cone", "MeshSurface" )
ApplyOp "bend", obj
obj.posz.Value = -3
set geometry = obj.ActivePrimitive.Geometry
' Move the point to 1,1,0 in local mode
set clip = geometry.SaveShapeKey( 1, 1, siShapeLocalReferenceMode, _
siShapeInstanceOnlyMode, "MyShapeKey", Array(1), Array(1.,1.,0) )
set obj = root.AddGeometry( "Cone", "MeshSurface" )
ApplyOp "bend", obj
set geometry = obj.ActivePrimitive.Geometry
' Move the point to 1,1,0 in absolute mode
set clip = geometry.SaveShapeKey( 1, 1, siShapeAbsoluteReferenceMode, _
siShapeInstanceOnlyMode, "MyShapeKey", Array(1), Array(1.,1.,0) )
set obj = root.AddGeometry( "Cone", "MeshSurface" )
ApplyOp "bend", obj
obj.posz.value = 3
set geometry = obj.ActivePrimitive.Geometry
' Move the point to 1,1,0 in object mode
set clip = geometry.SaveShapeKey( 1, 1, siShapeObjectReferenceMode, _
siShapeInstanceOnlyMode, "MyShapeKey", Array(1), Array(1.,1.,0) )
|
'
' This example demonstrates how you access the shape information for a particular shape key by looking
' at the cluster properties which store this data
'
option explicit
' Set up a little scene
dim oCircle
set oCircle = CreatePrim( "Sphere", "MeshSurface" )
' Move the top and bottom point of the sphere outwards
oCircle.ActivePrimitive.Geometry.SaveShapeKey 0.5, 3.0, _
siShapeAbsoluteReferenceMode, siShapeInstanceOnlyMode, ,_
Array( 1, 0 ), Array( 0,6,0, 0,-6,0 )
' 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.
oCircle.ActivePrimitive.Geometry.SaveShapeKey 0.8, 1.0, _
siShapeLocalReferenceMode, siShapeInstanceOnlyMode,, _
Array( 5, 33 ), Array( -2,0,0, 2,0,0 )
ShowShapeInformation( oCircle )
sub ShowShapeInformation( in_obj )
dim oClusters, oCluster, oProperties, oProperty, cntFoundShapes
on error resume next
set oClusters = in_obj.ShapeAnimatedClusters
if ( err <> 0 ) then
Application.LogMessage "Please select a 3D Object"
exit sub
end if
on error goto 0
Application.LogMessage "Dump of shape key data on object " & in_obj.Fullname
cntFoundShapes = 0
' Go through the various clusters on the object
' (In practice only the Point clusters will have shape keys)
for each 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:
dim oClusterElementsCollection, aElements
set oClusterElementsCollection = oCluster.Elements
aElements = oClusterElementsCollection.Array
' Only search for the shape keys, which have type "clskey"
set oProperties = oCluster.LocalProperties.filter( "clskey" )
for each oProperty in oProperties
' Found a shape key
dim i, XYZArray
cntFoundShapes = cntFoundShapes + 1
if InstrRev( oProperty, ".ResultClusterKey" ) <> 0 then
' There may also be an internal cluster property
' called "ResultClusterKey" which stores the
' result of blending the various shapes at the
' current time
Application.LogMessage "Blended shape at this time: " & oProperty
else
Application.LogMessage "Shape key: " & oProperty
end if
' The reference mode is available from the KeyType parameter
dim ReferenceType
ReferenceType = oProperty.Parameters("KeyType").Value
if ( ReferenceType = 0 ) then
Logmessage " Uses: Absolute Reference Mode"
elseif ( ReferenceType = 1 ) then
Logmessage " Uses: Local Reference Mode"
elseif ( ReferenceType = 2 ) then
Logmessage " Uses: Object Reference Mode"
end if
' The contents of the cluster can be found in this safearray
XYZArray = oProperty.Elements.Array
For i=0 to UBound(oProperty.Elements.Array,2)
' Print out the x,y,z values
LogMessage " pnt["& aElements( i ) & "] has position (" _
& Round(XYZArray(0,i),3) & "," & Round(XYZArray(1,i),3) & ","_
& Round(XYZArray(2,i),3) & ")"
Next
next
next
if ( cntFoundShapes = 0 ) then
LogMessage "There are no shapes on this object"
end if
end sub
|