---

The Problem: Manual Rigging is a Bottleneck

In interactive 3D web platforms (metaverses, configurators, UGC gaming), empowering users to upload custom avatars usually requires a massive compromise:

1. Force manual rigging: Users spend days in Blender placing bones and painting weights.
2. Server-side pipelines: Send meshes to a cloud service running Mixamo or Maya scripts (slow, expensive, high latency).

The Solution

auto-rig-web shifts the entire pipeline to the client. Using a lightweight, browser-local ONNX vision model, it analyzes mesh topology, predicts joint locations, constructs a skeletal hierarchy, and computes biharmonic skin weights procedurally using Three.js—all within milliseconds.

---

Architecture

┌────────────────────────────────────────────────────────────┐
│                    auto-rig-web                            │
│                                                            │
│  1. Ingestion        2. AI Inference       3. Topology     │
│  ┌────────────┐      ┌─────────────┐       ┌────────────┐  │
│  │ Static     │      │ ONNX Runtime│       │ Procedural │  │
│  │ THREE.Mesh │─────>│ (WebGPU)    │──────>│ Skinning   │  │
│  └────────────┘      │ Joint Predict│      │ (Weights)  │  │
│                      └─────────────┘       └──────┬─────┘  │
│                                                   │        │
│  4. Output           5. Animation                 │        │
│  ┌────────────┐      ┌─────────────┐              │        │
│  │ SkinnedMesh│<─────│ CCDIK Solver│<─────────────┘        │
│  │ (Ready)    │      │ (Real-Time) │                       │
│  └────────────┘      └─────────────┘                       │
└────────────────────────────────────────────────────────────┘

1. Voxelization & Tensor Prep: The input geometry's vertices are mapped to a 3D occupancy grid tensor.
2. ONNX Inference: A quantized spatial CNN runs via onnxruntime-web (WebGPU accelerated) to predict 3D coordinates for a standard 19-joint bipedal hierarchy.
3. Procedural Skinning: Bones are instantiated. Skin indices and skin weights are computed per-vertex using inverse distance weighting with exponential falloff (approximating heat-diffusion/geodesic distance).
4. IK Constraints: A built-in Cyclic Coordinate Descent (CCDIK) solver allows instant dynamic posing by pulling end-effectors (e.g., wrists, ankles).

---

Tech Stack

This library is engineered for performance at the edge:

• AI Inference: onnxruntime-web leveraging the WebGPU execution provider. This allows complex spatial CNNs to run directly on the client's GPU without WebGL overhead or CPU blocking.
• 3D Pipeline: Three.js is used for matrix math, hierarchy construction, and upgrading standard BufferGeometry to skinning-ready buffers (skinIndex, skinWeight).
• Procedural Algorithms:
  • Weight Calculation: Custom multi-threaded fallback algorithms for distance-based bone influence mapping.
  • Kinematics: Integrated CCDIK solver to handle complex joint rotations avoiding gimbal lock via Quaternion slerp chains.

---

API Usage

1. Installation

npm install auto-rig-web three onnxruntime-web

2. Auto-Rigging a Mesh

import * as THREE from 'three';
import { RiggingEngine, JointType } from 'auto-rig-web';

// 1. Initialize the engine (loads the ONNX model via WebGPU)
const engine = new RiggingEngine({
  modelPath: '/models/joint_estimator_quantized.onnx',
  skinningFalloff: 2.5
});
await engine.init();

// 2. Load your static mesh (e.g., via GLTFLoader)
const staticMesh = myLoadedGltf.scene.children[0] as THREE.Mesh;

// 3. Boom. Rigged.
const skinnedMesh = await engine.autoRig(staticMesh);
scene.add(skinnedMesh);

3. Applying Inverse Kinematics (IK)

Once rigged, easily pose the character by moving targets.

// Create a visual target (e.g., a red sphere to control the hand)
const handTarget = new THREE.Vector3(1, 1, 0);

// Assign the target to the IK Solver
engine.setIKTarget({
  joint: JointType.RightHand,
  position: handTarget,
  influence: 1.0 // 0.0 to 1.0 interpolation
});

// Update the solver in your render loop
function animate() {
  requestAnimationFrame(animate);
  
  // Solve IK chains for the current frame
  engine.updateIK(skinnedMesh.skeleton);
  
  renderer.render(scene, camera);
}
animate();

---

License

MIT — iKi / Frozen Flame

---

📜 Open Source & Commercial Use (MIT)

This project is 100% open-source software under the MIT License.

💼 Commercial Use & Free Redistribution

You are explicitly permitted to use, modify, fork, integrate, package, and sell commercial products or SaaS built using this engine with one visible attribution requirement:

Attribution Requirement: You must include a visible credit to nff747 in your application (e.g., Powered by nff747 linking to https://github.com/nff747 in your application UI, footer, about modal, or documentation).

<!-- Example visible footer attribution -->
<p>Powered by <a href="https://github.com/nff747" target="_blank">nff747</a></p>