THREE.IK

Inverse kinematics for three.js.

A work in progress, THREE.IK supports multiple chains with multiple effectors, solved via FABRIK iterative solver, and a ball-joint constraint. Best way to see how this works for now is to check out the demo, examples, and the docs.

:warning: work in progress/request for feedback :warning:

There are many open issues regarding axis alignment, new constraints, alternative solvers, and an API overhaul. Discussion and solutions are welcome! There will be breaking changes between versions as an API is settled on.

Installation

$ npm install --save three three-ik

or include the build at build/three-ik.js:

<script src="https://github.com/jsantell/THREE.IK/raw/master/build/three-ik.js"></script>

Usage

You can use ES6 importing like so:

import { IK, IKChain, IKJoint, IKBallConstraint, IKHelper } from 'three-ik';

And here's a full example if included via script tag, with THREE.IK classes defined on THREE.

// Set up scene, camera, renderer
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.01, 100);
camera.position.z = 5;
const renderer = new THREE.WebGLRenderer();
renderer.setPixelRatio(window.devicePixelRatio);
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

const ik = new THREE.IK();

const chain = new THREE.IKChain();
const constraints = [new THREE.IKBallConstraint(90)];
const bones = [];

// Create a target that the IK's effector will reach
// for.
const movingTarget = new THREE.Mesh(new THREE.SphereGeometry(0.1), new THREE.MeshBasicMaterial({ color: 0xff0000 }));
movingTarget.position.z = 2;
const pivot = new THREE.Object3D();
pivot.add(movingTarget);
scene.add(pivot);

// Create a chain of THREE.Bone's, each wrapped as an IKJoint
// and added to the IKChain
for (let i = 0; i < 10; i++) {
  const bone = new THREE.Bone();
  bone.position.y = i === 0 ? 0 : 0.5;

  if (bones[i - 1]) { bones[i - 1].add(bone); }
  bones.push(bone);

  // The last IKJoint must be added with a `target` as an end effector.
  const target = i === 9 ? movingTarget : null;
  chain.add(new THREE.IKJoint(bone, { constraints }), { target });
}

// Add the chain to the IK system
ik.add(chain);

// Ensure the root bone is added somewhere in the scene
scene.add(ik.getRootBone());

// Create a helper and add to the scene so we can visualize
// the bones
const helper = new THREE.IKHelper(ik);
scene.add(helper);

function animate() {
  pivot.rotation.x += 0.01;
  pivot.rotation.y += 0.01;
  pivot.rotation.z += 0.01;

  ik.solve();

  renderer.render(scene, camera);

  requestAnimationFrame(animate);
}

animate()

Documentation

Full API documentation can be found at https://jsantell.github.io/THREE.IK/docs.

Build

$ npm run build

Logo

The logo and artwork was created by Caitlyn Crites.

jsantell / THREE.IK

readme