chinedufn/skeletal-animation-system chinedufn/skeletal-animation-system

  • Stars
    star
    250
  • Rank 161,785 (Top 4 %)
  • Language
    JavaScript
  • Created about 8 years ago
  • Updated almost 6 years ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
chinedufn/skeletal-animation-system
github

chinedufn

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A standalone, stateless, dual quaternion based skeletal animation system built with interactive applications in mind

skeletal-animation-system npm version Build Status

A standalone, stateless, dual quaternion based skeletal animation system built with interactive applications in mind

View live demo

TODO: Create a demo site instead of just a demo. Embed a demo inside of the demo site

Tutorials

WebGL Skeletal Animation Sound Effects Tutorial

Attaching objects to bones

WebGL Skeletal Animation Tutorial

Background / Initial Motivation

skeletal-animation-system aims to give the user a flexible module for managing skeletal animations across different 3d models and bone groups.

skeletal-animation-system aims to provide a sane API for starting, stopping and interpolating skeletal animations.

It supports blending between your previous and current animation when you switch animations. It also supports splitting your model into different bone groups such as the upper and lower body, allowing you to, for example, play a walking animation for your legs while playing a punch animation for your upper body.

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

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.

So we switched to dual quaternions and completely dropped support for matrices.

However, if you use matrices you can still make use of skeletal-animation-system.

  1. Convert your matrices into dual quaternions once when you first load your model.
  2. Use skeletal-animation-system to determine your pose dual quaternions
  3. Convert your pose dual quaternions back into matrices before each render
  4. Use your newly created matrices for skinning

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 based skinning.

TODO: Example code demonstrating how to incorporate skeletal-animation-system into matrix based skinning application

This API is still experimental and will evolve as we use it and realize the kinks.

To Install

$ npm install --save skeletal-animation-system

Demo

To run the demo locally:

$ git clone https://github.com/chinedufn/skeletal-animation-system
$ cd skeletal-animation-system
$ npm install
$ npm run demo

Changes to the demo and src files will now live reload in your browser.

View live demo

Usage

var animationSystem = require('skeletal-animation-system')
// Parsed using collada-dae-parser or some other parser
var parsedColladaModel = require('./parsed-collada-model.json')

// Keyframe data for all joints.
// @see `github.com/chinedufn/blender-actions-to-json` for an example format
var lowerBodyKeyframes = {...}
var upperBodyKey = {...}

// Convert our joint names into their associated joint index number
// This number comes from collada-dae-parser
// (or your parser of choice)
var upperBodyJointNums = [0, 1, 5, 6, 8]
var lowerBodyJointNums = [2, 3, 4, 7, 9]

// Our options for animating our model's upper body
var upperBodyOptions = {
  currentTime: 28.24,
  jointNums: upperBodyJointsNums,
  blendFunction: function (dt) {
    // Blend animations linearly over 2.5 seconds
    return 1 / 2.5 * dt
  },
  currentAnimation: {
    keyframes: currentAnimKeyframes,
    startTime: 25
  },
  previousAnimation: {
    keyframes: previousAnimKeyframes,
    startTime: 24.5
  }
}

// Our options for animating our model's lower body
var lowerBodyOptions = {
  currentTime: 28.24,
  jointNums: lowerBodyJointNums,
  currentAnimation: {
    keyframes: currentAnimKeyframes,
    startTime: 24.3,
    noLoop: true
  }
}

var interpolatedUpperBodyJoints = animationSystem
.interpolateJoints(upperBodyOptions).joints

var lowerBodyData = animationSystem
.interpolateJoints(lowerBodyOptions)
var interpolatedLowerBodyJoints = lowerBodyData.joints

console.log(lowerBodyData.currentAnimationInfo)
// => {lowerKeyframeNumber: 5, upperKeyframeNumber: 6}

// You now have your interpolated upper and lower body dual quaternions (joints).
// You can pass these into any vertex shader that
// works with dual quaternions

// If you're just getting started and you still need matrices you
// can convert these into matrices using dual-quat-to-mat4
//  @see https://github.com/chinedufn/dual-quat-to-mat4

Expected JSON model format

TODO: Link to collada-dae-parser README

Benchmark

npm run bench

TODO:

  • Handle rotation quaternion lerp when dot product is < 0
  • Implement more from the papers linked in References section below (whenever we need them)
  • Add documentation about how to approach playing a sound effect on a keyframe in your game / simulation / program
  • Benchmark
  • Allow consumer to provide the sampling function between keyframes. Currently we sample linearly between all keyframes. Could make use of chromakode/fcurve here
  • Create a new demo site and demo(s)

API

animationSystem.interpolateJoints(options) -> Object

options

Optional

Type: object

// Example overrides
var myOptions = {
  // TODO:
}
interpolatedJoints = animationSystem.interpolateJoints(myOptions)
currentTime

Type: Number

Default: 0

The current number of seconds elapsed. If you have an animation an loop, this will typically be the sum of all of your loops time deltas

// Example of tracking current time
var currentTime = 0
function animationLoop (dt) {
 currentTime += dt
}
keyframes

Type: Object

Default: {}

TODO: Link to collada-dae-parser README on keyframes for more info, but also put an example here

jointNums

Type: Array

An array of joint indices that you would like to interpolate.

Say your model has 4 joints. To interpolate the entire model you would pass in [0, 1, 2, 3]. To only interpolate two of the joints you might pass in [0, 2], or any desired combination.

These joint indices are based on the order of the joints in your keyframes

blendFunction

Type: Function

Default: Blend linearly over 0.2 seconds

A function that accepts a time elapsed in seconds and returns a value between 0 and 1.

This returned value represents the weight of the new animation.

function myBlendFunction (dt) {
  // Blend the old animation into the new one linearly over 5 seconds
  return 0.2 * dt)
}
currentAnimation

Type: Object

An object containing parameters for the current animation

If you supply a previous animation your current animation will be blended in using your blendFunction

var currentAnimation = {
  keyframes: {0: [..], 1.66666: [...]}
  startTime: 10
}
currentAnimation.keyframes

Type: Array

{
  "0": [
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
  ],
  "1.33333": [
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 5, 1]
  ]
}

Pose matrices for each joint in the model, organized by the animation time (0 and 1.33333 are seconds)

currentAnimation.startTime

Type: Number

The time in seconds that your current animation was initiated. This gets compared with the currentTime in order to interpolate your joint data appropriately.

currentAnimation.noLoop

Type: Boolean

Whether or not your animation should loop. For example, let's say you are 13 seconds into a 4 second animation.

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

An object containing parameters for the previous animations. Your previous animation gets blended out using your blendFunction while your current animation gets blended in.

Type: Object

previousAnimation.keyframes

Type: Array

{
  "0": [
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
  ],
  "1.33333": [
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 2, 1],
    [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 5, 1]
  ]
}

Pose matrices for each joint in the model, organized by the animation time (0 and 1.33333 are seconds)

previousAnimation.startTime

Type: Number

The time in seconds that your previous animation was initiated. This is used in order to blend in the current animation.

Returned data

// Example
{
  joints: [...],
  currentAnimationInfo: {
    lowerKeyframeNumber: 0,
    upperKeyframeNumber:: 1
  }
}

currentAnimationInfo is the lower and upper keyframe time bounds of the current animation. If you have three keyframes at 1 8 and 19 seconds and you are currently 12 seconds into your animation then your lower keyframe is 1 (8) and your upper keyframe is 2 (19).

See Also

References

License

MIT

More Repositories

1

percy

Build frontend browser apps with Rust + WebAssembly. Supports server side rendering.
Rust
2,260
star
2

swift-bridge

swift-bridge facilitates Rust and Swift interop.
Rust
800
star
3

webgl-water-tutorial

The source code for a tutorial on rendering water using WebGL + Rust + WebAssembly
Rust
477
star
4

psd

A Rust API for parsing and working with PSD files.
Rust
265
star
5

dipa

dipa makes it easy to efficiently delta encode large Rust data structures.
Rust
264
star
6

landon

A collection of tools, data structures and methods for exporting Blender data (such as meshes and armatures) and preparing it for your rendering pipeline.
Rust
147
star
7

collada-dae-parser

Parse collada .dae 3d animation files into a WebGL friendly JSON format
JavaScript
103
star
8

cross-compile-rust-from-mac-to-linux

An example of how to cross compile Rust from `macOS` to Linux `x86_64-unknown-linux-gnu`
Shell
95
star
9

rectangle-pack

A general purpose, deterministic bin packer designed to conform to any two or three dimensional use case.
Rust
72
star
10

blender-iks-to-fks

A Blender script that takes a mesh and armature that use IKs and other non-deformation bones and creates a new mesh and armature that uses only FK bones.
Python
44
star
11

hot-app-replacement

Like hot module replacement but... yeah you'll see
JavaScript
26
star
12

blender-webgl-hot-reload-experiment

An experiment in hot reloading 3d models from Blender into a WebGL scene
JavaScript
23
star
13

blender-actions-to-json

Write the joint data for all of a `.blend` file's actions to a JSON file
Python
17
star
14

webgl-particle-effect-tutorial

A tutorial for creating a WebGL fire particle effect using billboarded quads
JavaScript
17
star
15

wavefront-obj-parser

An api and cli for parsing wavefront .obj files into JSON
JavaScript
17
star
16

webgl-shadow-mapping-tutorial

A WebGL shadow mapping tutorial
JavaScript
16
star
17

mat4-to-dual-quat

Convert a 4x4 matrix into a dual quaternion. Useful for skeletal animation (dual quaternion linear blending)
JavaScript
14
star
18

virtual-progress-bar

virtual-dom progress bar component
JavaScript
11
star
19

virtual-loading-dots

virtual-dom loading dots component
JavaScript
9
star
20

webgl-skeletal-animation-tutorial

A quick tutorial on WebGL skeletal animation using small modules
JavaScript
9
star
21

watertight-ray-triangle-intersection

An implementation of the Watertight Ray/Triangle Intersection algorithm
JavaScript
9
star
22

solid-state

Trigger listener functions when your state changes
JavaScript
8
star
23

blender-webgl-skinned-hot-reload-experiment

An experiment in hot reloading skinned models from Blender to WebGL
JavaScript
7
star
24

dom-filenameify

Add filenames as attributes to your DOM elements to help locate them in code by inspect-elementing them in the browser
JavaScript
7
star
25

webgl-unit-test-tutorial

The source code for a tutorial on unit testing WebGL components
JavaScript
7
star
26

image-to-heightmap

Convert a JPG or PNG image into a heightmap array
JavaScript
7
star
27

webgl-wield-item-tutorial

A tutorial for positioning items on top of bones using WebGL and 3d math
JavaScript
6
star
28

create-keyframe

Create css keyframes using JSON
JavaScript
6
star
29

webgl-to-img-stream

Use a WebGL context to write the canvas's contents to a image file. Meant to be used in Node.js
JavaScript
5
star
30

load-collada-dae

Load the WebGL graphics buffer data from a collada .dae model and return a draw command that accepts options
JavaScript
5
star
31

app-world

A framework agnostic approach to managing frontend application state.
Rust
5
star
32

make-component

A code generator for virtual-dom component files
JavaScript
3
star
33

client-ketchup

A simple interface for keeping remote clients up to date with their authoritative state
JavaScript
3
star
34

neighborhood-pathfinder

An A* implementation that accepts a function to detect neighboring tiles
JavaScript
3
star
35

webgl-skeletal-animation-sound-tutorial

A tutorial for playing sound effects during skeletal animations
JavaScript
2
star
36

expand-vertex-data

Expand vertex, normal and uv indices into vertex normal and uv data that is ready for your array buffers
JavaScript
2
star
37

minimal-object-diff

Create and apply a tiny representation of diffs between two objects. Useful for sending diffs over a network
JavaScript
2
star
38

generate-keyframe-animation-tutorial

A tutorial on generating CSS keyframes during runtime
JavaScript
2
star
39

branching-dialogue

A stateless API for modeling branching dialogue in role-playing games
JavaScript
2
star
40

conformer

conformer helps you write and visualize conformance test suites.
Rust
2
star
41

create-hover-class

Turn a JSON object into :hover class to use with inline styled components
JavaScript
2
star
42

load-wavefront-obj

Load the graphics buffer data from a wavefront .obj model and return a draw command that accepts options
JavaScript
2
star
43

get-attributes-uniforms

Get the attributes and uniforms from a GLSL shader string
JavaScript
2
star
44

keyframes-to-dual-quats

Convert a set of keyframe matrices into dual quaternions
JavaScript
1
star
45

knowledge

Concepts, solutions and links that I want to remember
1
star
46

angular-video-time

AngularJS Filter for displaying a video's current time
JavaScript
1
star
47

create-shader-program

Compiles, links and returns a shader program from a give vertex and fragment shader
JavaScript
1
star
48

webgl-blend-map-tutorial

A tutorial on multitexturing a WebGL terrain using a blend map
JavaScript
1
star
49

epoch-to-timeago

Get a string representation of a time difference
JavaScript
1
star
50

create-orbit-camera

Create a camera that orbits a target
JavaScript
1
star
51

blender-rustlang-docker

Docker image with Blender 2.80 and Rust
Dockerfile
1
star
52

create-draw-function

Create a WebGL draw call based on user provided data
JavaScript
1
star
53

donutjs-skeletal-animation-slides

Skeletal Animation in Your Browser via WebGL - the accompanying slides for a talk at Portland's Donut.js meetup
JavaScript
1
star