AniTop-Web

Interactive web-based rigid body physics simulator implementing three classical spinning top systems: Euler, Lagrange, and Kovalevskaya tops.

🌐 Live Demo: danielhou315.github.io/AniTop-Web

Features

• Three Simulator Types:

  • Euler Top: Free rigid body with no external torques (demonstrates intermediate axis theorem)
  • Lagrange Top: Symmetric top with gravity (precession and nutation)
  • Kovalevskaya Top: Integrable heavy top with special constraints

• Real-time 3D Visualization:

  • Interactive three.js scene with camera controls
  • Inertia ellipsoid rendering with metallic shaders
  • Body and world axes visualization
  • Angular momentum vector display
  • Motion trail tracking

• Live Data Plots:

  • Angular velocity components (ωₓ, ωᵧ, ω_z)
  • Energy tracking (total, kinetic, potential)

• Configuration System:

  • 10 preset scenarios across all top types
  • Real-time parameter adjustment with automatic reset
  • Import/export configuration as JSON
  • MATLAB-compliant validation and constraints

• Physics Engine:

  • SO(3) integration using Rodrigues exponential
  • RK4 and midpoint integration methods
  • Energy-conserving algorithms (<0.001% drift)
  • Web Worker architecture for 60 FPS performance

Quick Start

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Running Tests

# Install Python test dependencies
cd tests
uv sync

# Run validation tests
uv run pytest

Deployment

This project is automatically deployed to GitHub Pages at anitop.danielhou.me via GitHub Actions.

Custom Domain Setup

1. DNS Configuration: Add a CNAME record pointing to your GitHub Pages domain:

   anitop.danielhou.me  →  yourusername.github.io
   

2. GitHub Repository Settings:

   • Go to Settings → Pages
   • Source: Deploy from a branch → gh-pages branch
   • Custom domain: anitop.danielhou.me
   • Enforce HTTPS: ✓

3. Automatic Deployment: Every push to main triggers the GitHub Actions workflow at .github/workflows/deploy.yml

Project Structure

src/
├── sim/              # Physics simulation core
│   ├── euler_top.ts
│   ├── lagrange_top.ts
│   ├── kovalevskaya_top.ts
│   ├── integrators.ts
│   ├── linalg.ts
│   └── worker.ts     # Web Worker for background simulation
├── viz/              # 3D visualization and plotting
│   ├── scene.ts      # three.js scene setup
│   └── plot.ts       # Plotly.js charts
├── ui/               # User interface
│   ├── controls.ts   # Configuration panel
│   └── presets.ts    # Preset configurations
└── main.ts           # Application coordinator

tests/                # Python validation tests
├── test_csv_format.py
└── test_numerical_accuracy.py

Physics Implementation

Euler Top

Free rigid body governed by Euler's equations:

I₁ω̇₁ = (I₂ - I₃)ω₂ω₃
I₂ω̇₂ = (I₃ - I₁)ω₃ω₁
I₃ω̇₃ = (I₁ - I₂)ω₁ω₂

Lagrange Top

Symmetric top with gravity (I₁ = I₂):

τ = r_com × (Rᵀ · g_world)
I₁ω̇₁ = (I₂ - I₃)ω₂ω₃ + τ₁
...

Kovalevskaya Top

Integrable case with I₁ = I₂ = 2I₃ and COM on x-axis.

Technology Stack

• Frontend: TypeScript, Vite
• 3D Graphics: three.js
• Plotting: Plotly.js
• Testing: Python, pytest, numpy, pandas
• Build: Vite with code splitting
• Deployment: GitHub Actions → GitHub Pages

Credits

Based on the MATLAB implementation AniTop-MATLAB by the University of Michigan LoG(M) 2024WN Tops Team.

License

MIT License - see LICENSE file for details.