A modular, lightweight, and native Three.js library for generating, customizing, and animating all 59 stellations of the icosahedron (as enumerated by Coxeter et al. in The Fifty-Nine Icosahedra).

See demo here!

🌟 Features

Native Three.js Integration: IcosahedronStellationGeometry extends THREE.BufferGeometry, fully compatible with materials, standard modifiers, shadow maps, and raycasting.
59 Pre-defined Stellations: Instant access to all Coxeter/Miller icosahedron stellations (e.g. Great Icosahedron, Small Stellated Icosahedron, Echidna, and the Final Stellation).
Exploded View Animations: StellationGroup allows physical radial separation of individual cells and facelets for exploded-view animations.
Multi-Material Styling: Grouping modes (groupMode: 'facelet-type' or 'plane') for multi-material mesh assignment via geometry.groups.
Pre-computed Geometry Engine: Blazing fast runtime instantiation (< 2ms) powered by pre-transformed topological facelet lookup tables.

📦 Installation

pnpm add three-echidna three
# or
npm install three-echidna three

🚀 Quick Start

1. Basic Mesh Usage

import * as THREE from 'three';
import { IcosahedronStellationGeometry } from 'three-echidna';

// Create Great Icosahedron (preset 7)
const geometry = new IcosahedronStellationGeometry({ index: 7, radius: 2.0 });
const material = new THREE.MeshStandardMaterial({
  color: 0xff0055,
  side: THREE.DoubleSide,
  roughness: 0.3
});

const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);

// Dynamically change stellation to Echidna (preset 58)
geometry.updateStellation('echidna');

2. Animated Exploded View

import { StellationGroup } from 'three-echidna';

// Create an exploded view node for the Final Stellation
const stellationGroup = new StellationGroup({ index: 'final-stellation', radius: 1.5 });
scene.add(stellationGroup);

function animate() {
  requestAnimationFrame(animate);
  const factor = (Math.sin(Date.now() * 0.002) + 1) / 2; // 0.0 to 1.0
  stellationGroup.setExplosionFactor(factor);
}

3. Registry & Metadata Querying

import { StellationRegistry } from 'three-echidna';

// Fetch metadata by index or name
const info = StellationRegistry.get('echidna');
console.log(info?.name); // "Echidna (Complete Stellation)"
console.log(info?.index); // 58
console.log(info?.faceletIds); // ['a', 'b', 'c', 'd', 'e1', 'e2', 'f1', 'g1', 'h']

// List all 59 stellations
const allStellations = StellationRegistry.listAll();

✅ Completed Progress

Project Tooling & Environment Setup: Configured Node 24 (via .nvmrc), pnpm, TypeScript, tsup, and vitest.
Offline Data Pre-builder (tools/generate-facelets.ts): Generates 60 icosahedral symmetry group transformations (I_h), 11 facelet region geometries (a, b, c, d, e_1, e_2, f_1, f_1', g_1, g_2, h), and preset bitmasks for all 59 stellations into facelets-data.json.
Core Geometry Engine (IcosahedronStellationGeometry): Instant Float32Array attribute construction, dynamic updates, and multi-material groups.
Exploded View Class (StellationGroup): Individual cell sub-mesh management and radial explosion factor animation.
Stellation Metadata Registry (StellationRegistry): Querying and listing metadata and facelet masks.
Unit Testing & Verification: 100% test coverage passing via vitest.
Production Bundle: Bundled ESM, CommonJS, and TypeScript type declarations via tsup.
Interactive Showcase Demo App: Full Vite + Three.js OrbitControls web application demonstrating all 3 core features.

🛠️ Development Scripts

# Start interactive showcase demo app in dev server
pnpm dev

# Build static demo site for deployment (outputs to dist-demo/)
pnpm build:demo

# Generate precomputed geometry data asset (src/data/facelets-data.json)
pnpm generate-data

# Build production library bundle (outputs to dist/)
pnpm build

# Run unit tests
pnpm test

📄 License

MIT