51 | 70 | 71 | 72 |
Introduction
73 | 74 | 75 |skeletal-animation-system aims to give the user a flexible module for managing skeletal animations across different 3d models and bone groups.
76 | 77 |skeletal-animation-system aims to provide a sane API for starting, stopping and interpolating skeletal animations.
It supports blending between 80 | your previous and current animation when you switch animations. It also supports splitting your model into different bone groups such as the upper 81 | and lower body, allowing you to, for example, play a walking animation for your legs while playing a punch animation for your upper body.
82 | 83 |skeletal-animation-system does not maintain an internal state, but instead lets the modules consumer track things such as the current animation and the current clock time.
I use matrices and not dual quaternions
86 | 87 |The first versions of skeletal-animation-system uses matrices instead of dual quaternions.
The issue there was that blending matrices can lead to unexpected artifacts.
90 | 91 |So we switched to dual quaternions and completely dropped support for matrices.
92 | 93 |However, if you use matrices you can still make use of skeletal-animation-system.
-
96 |
- Convert your matrices into dual quaternions once when you first load your model. 97 |
- Use
skeletal-animation-systemto determine your pose dual quaternions
98 | - Convert your pose dual quaternions back into matrices before each render 99 |
- Use your newly created matrices for skinning 100 |
The 3rd step here means that you're doing some extra work on the CPU, but this hopefully bridges the gap for you until you can move to dual quaternion 103 | based skinning.
104 | 105 |This API is still experimental and will evolve as we use it and realize the kinks.
106 | 107 |To Install
108 | 109 |$ npm install --save skeletal-animation-systemUsage
112 | 113 |var animationSystem = require('skeletal-animation-system')
114 | // Parsed using collada-dae-parser or some other parser
115 | var parsedColladaModel = require('./parsed-collada-model.json')
116 |
117 | // Keyframe data for all joints.
118 | // @see `github.com/chinedufn/blender-actions-to-json` for an example format
119 | var lowerBodyKeyframes = {...}
120 | var upperBodyKey = {...}
121 |
122 | // Convert our joint names into their associated joint index number
123 | // This number comes from collada-dae-parser
124 | // (or your parser of choice)
125 | var upperBodyJointNums = [0, 1, 5, 6, 8]
126 | var lowerBodyJointNums = [2, 3, 4, 7, 9]
127 |
128 | // Our options for animating our model's upper body
129 | var upperBodyOptions = {
130 | currentTime: 28.24,
131 | jointNums: upperBodyJointsNums,
132 | blendFunction: function (dt) {
133 | // Blend animations linearly over 2.5 seconds
134 | return 1 / 2.5 * dt
135 | },
136 | currentAnimation: {
137 | keyframes: currentAnimKeyframes,
138 | startTime: 25
139 | },
140 | previousAnimation: {
141 | keyframes: previousAnimKeyframes,
142 | startTime: 24.5
143 | }
144 | }
145 |
146 | // Our options for animating our model's lower body
147 | var lowerBodyOptions = {
148 | currentTime: 28.24,
149 | jointNums: lowerBodyJointNums,
150 | currentAnimation: {
151 | keyframes: currentAnimKeyframes,
152 | startTime: 24.3,
153 | noLoop: true
154 | }
155 | }
156 |
157 | var interpolatedUpperBodyJoints = animationSystem
158 | .interpolateJoints(upperBodyOptions).joints
159 |
160 | var lowerBodyData = animationSystem
161 | .interpolateJoints(lowerBodyOptions)
162 | var interpolatedLowerBodyJoints = lowerBodyData.joints
163 |
164 | console.log(lowerBodyData.currentAnimationInfo)
165 | // => {lowerKeyframeNumber: 5, upperKeyframeNumber: 6}
166 |
167 | // You now have your interpolated upper and lower body dual quaternions (joints).
168 | // You can pass these into any vertex shader that
169 | // works with dual quaternions
170 |
171 | // If you're just getting started and you still need matrices you
172 | // can convert these into matrices using dual-quat-to-mat4
173 | // @see https://github.com/chinedufn/dual-quat-to-mat4Tutorials
177 | 178 |WebGL Skeletal Animation Sound Effects Tutorial
179 | 180 | 181 | 182 |WebGL Skeletal Animation Tutorial
183 | 184 | 185 |API
186 | 187 |animationSystem.interpolateJoints( options ) -> Object
188 |
189 | options
190 | 191 |Optional
192 | 193 |Type: object
// Example overrides
196 | var myOptions = {
197 | // TODO:
198 | }
199 | interpolatedJoints = animationSystem.interpolateJoints(myOptions)currentTime
202 | 203 |Type: Number
Default: 0
The current number of seconds elapsed. If you have an animation an loop, 208 | this will typically be the sum of all of your loops time deltas
209 | 210 |// Example of tracking current time
211 | var currentTime = 0
212 | function animationLoop (dt) {
213 | currentTime += dt
214 | }keyframes
217 | 218 |Type: Object
Default: {}
jointNums
223 | 224 |Type: Array
An array of joint indices that you would like to interpolate.
227 | 228 |Say your model has 4 joints. To interpolate the entire model you would pass in [0, 1, 2, 3]. 229 | To only interpolate two of the joints you might pass in [0, 2], or any desired combination.
230 | 231 |These joint indices are based on the order of the joints in your keyframes
blendFunction
234 | 235 |Type: Function
Default: Blend linearly over 0.2 seconds
A function that accepts a time elapsed in seconds
240 | and returns a value between 0 and 1.
This returned value represents the weight of the new animation.
243 | 244 |function myBlendFunction (dt) {
245 | // Blend the old animation into the new one linearly over 5 seconds
246 | return 0.2 * dt)
247 | }currentAnimation
250 | 251 |Type: Object
An object containing parameters for the current animation
254 | 255 |If you supply a previous animation your current animation will be
256 | blended in using your blendFunction
var currentAnimation = {
259 | keyframes: {0: [..], 1.66666: [...]}
260 | startTime: 10
261 | }currentAnimation.keyframes
264 | 265 |Type: Array
{
268 | "0": [
269 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
270 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
271 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
272 | ],
273 | "1.33333": [
274 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
275 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
276 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 5, 1]
277 | ]
278 | }Pose matrices for each joint in the model, organized by the animation time (0 and 1.33333 are seconds)
currentAnimation.startTime
283 | 284 |Type: Number
The time in seconds that your current animation was initiated. This gets compared with
287 | the currentTime in order to interpolate your joint data appropriately.
currentAnimation.noLoop
290 | 291 |Type: Boolean
Whether or not your animation should loop. For example, let's say you are 13 seconds into a 4 second animation.
294 | 295 |If noLoop === true then you will be playing the frame at the 4th second.
If noLoop === false then you will be playing the frame at the 1st second.
previousAnimation
300 | 301 |An object containing parameters for the previous animations.
302 | Your previous animation gets blended out using your blendFunction
303 | while your current animation gets blended in.
Type: Object
previousAnimation.keyframes
308 | 309 |Type: Array
{
312 | "0": [
313 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
314 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
315 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
316 | ],
317 | "1.33333": [
318 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
319 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
320 | [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 5, 1]
321 | ]
322 | }Pose matrices for each joint in the model, organized by the animation time (0 and 1.33333 are seconds)
previousAnimation.startTime
327 | 328 |Type: Number
The time in seconds that your previous animation was initiated. 331 | This is used in order to blend in the current animation.
332 | 333 |Returned data
334 | 335 |// Example
336 | {
337 | joints: [...],
338 | currentAnimationInfo: {
339 | lowerKeyframeNumber: 0,
340 | upperKeyframeNumber:: 1
341 | }
342 | }See Also
345 | 346 |-
347 |
- collada-dae-parser 348 |
- blender-iks-to-fks 349 |
- blender-actions-to-json 350 |
References
353 | 354 |-
355 |
- Anatomy of a skeletal animation system part 1, part 2 and part 3 356 |
- Dual-Quaternions - From Classical Mechanics to Computer Graphics and Beyond 357 |
License
360 | 361 |MIT
362 |363 |
364 |