vivid-animations/README.md

A modern web-based animation library for mathematical visualizations - like Manim but live in the browser

# Vivid Animations

A modern web-based animation library for mathematical visualizations - like Manim but live in the browser.

## Features

- **Live Canvas Rendering** - Real-time animations without video encoding
- **Mathematical Objects** - Circles, lines, text, axes, functions, 3D surfaces
- **Smooth Animations** - Create, transform, fade, morph, and custom animations  
- **2D & 3D Support** - Full 3D coordinate systems with interactive camera controls
- **Updater System** - Continuous object updates and reactive animations
- **Function Plotting** - Built-in support for mathematical function visualization
- **TypeScript First** - Full type safety and IntelliSense support

## Installation

```bash
npm install vivid-animations
```

## Quick Start

```typescript
import { Scene, Circle, Text, FadeIn, Create } from 'vivid-animations'

// Create a scene
const scene = new Scene(document.getElementById('canvas'))

// Create objects
const circle = new Circle({ radius: 1, color: { r: 0.2, g: 0.6, b: 1, a: 1 } })
const text = new Text('Hello Vivid!').moveTo({ x: 0, y: -2 })

// Add animations
scene.play([
  new Create(circle),
  new FadeIn(text)
])
```

## Core Objects

### Basic Shapes
```typescript
import { Circle, Rectangle, Line } from 'vivid-animations'

const circle = new Circle({ radius: 1 })
const rect = new Rectangle({ width: 2, height: 1 })
const line = new Line({ start: { x: -1, y: 0 }, end: { x: 1, y: 0 } })
```

### Mathematical Objects
```typescript
import { Axes, FunctionPlot, NumberLine, MathText } from 'vivid-animations'

// Coordinate axes
const axes = new Axes({
  xRange: [-5, 5],
  yRange: [-3, 3]
})

// Function plotting
const func = new FunctionPlot({
  func: (x) => x * x,
  xRange: [-2, 2],
  color: { r: 1, g: 0.5, b: 0, a: 1 }
})

// Math expressions
const formula = new MathText('f(x) = x^2 + 2x + 1')
```

### 3D Objects
```typescript
import { Axes3D, Vector3D, Surface3D } from 'vivid-animations'

// 3D coordinate system
const axes3d = new Axes3D({
  xRange: [-2, 2],
  yRange: [-2, 2], 
  zRange: [-2, 2]
})

// 3D vector
const vector = new Vector3D({ x: 1, y: 2, z: 1 })

// 3D surface
const surface = new Surface3D({
  func: (x, y) => Math.sin(x) * Math.cos(y),
  xRange: [-Math.PI, Math.PI],
  yRange: [-Math.PI, Math.PI]
})
```

## Animations

### Basic Animations
```typescript
import { Create, FadeIn, FadeOut, Transform } from 'vivid-animations'

scene.play([
  new Create(circle),           // Scale from 0 to full size
  new FadeIn(text),            // Fade in opacity
  new Transform(rect, { 
    transform: { 
      translate: { x: 2, y: 1 },
      scale: { x: 1.5, y: 1.5 }
    }
  })
])
```

### Text Animations
```typescript
import { DrawText, EraseText } from 'vivid-animations'

scene.play([
  new DrawText(text, { direction: 'forward' }),
  new EraseText(text, { duration: 1 })
])
```

### Motion Animations
```typescript
import { Spin, Orbit, FollowPath } from 'vivid-animations'

scene.play([
  new Spin(circle, 2),         // 2 full rotations
  new Orbit(text, circle),     // Orbit around circle
])
```

### Animation Groups
```typescript
import { AnimationGroup, Sequence } from 'vivid-animations'

// Play animations simultaneously
scene.play(new AnimationGroup([
  new Create(circle),
  new FadeIn(text)
]))

// Play animations in sequence
scene.play(new Sequence([
  new Create(circle),
  new FadeIn(text)
]))
```

## Updater System

Create reactive animations that update continuously:

```typescript
import { Updater, ValueTracker } from 'vivid-animations'

const tracker = new ValueTracker(0)
const circle = new Circle({ radius: 1 })

// Circle follows the tracker value
scene.addUpdater(new Updater(
  () => {
    circle.moveTo({ x: tracker.getValue(), y: 0 })
  }
))

// Animate the tracker
scene.play(new Transform(tracker, { value: 5 }))
```

## 3D Camera Controls

Interactive 3D scenes with camera controls:

```typescript
// Enable interactive controls
scene.camera3D.enableControls(true)

// Or programmatic camera movement
scene.camera3D.setPosition(5, 5, 5)
scene.camera3D.lookAt(0, 0, 0)
```

## AI Integration Example

Perfect for AI-generated visualizations:

```typescript
// AI can generate code like this:
function createVisualization(description: string) {
  const scene = new Scene(canvas)
  
  if (description.includes('sine wave')) {
    const axes = new Axes({ xRange: [-2*Math.PI, 2*Math.PI] })
    const sine = new FunctionPlot({ 
      func: Math.sin,
      color: { r: 0, g: 0.8, b: 1, a: 1 }
    })
    
    scene.add(axes)
    scene.play(new Create(sine))
  }
  
  return scene
}
```

## Advanced Examples

### Matrix Visualization
```typescript
import { Matrix, HighlightBox } from 'vivid-animations'

const matrix = new Matrix({
  data: [[1, 2], [3, 4]],
  elementSpacing: 1.5
})

const highlight = new HighlightBox(matrix.getElement(0, 0))
scene.play(new Flash(highlight))
```

### Graph Theory
```typescript
import { Graph } from 'vivid-animations'

const graph = new Graph({
  nodes: [
    { id: 'A', position: { x: -1, y: 1 } },
    { id: 'B', position: { x: 1, y: 1 } },
    { id: 'C', position: { x: 0, y: -1 } }
  ],
  edges: [
    { from: 'A', to: 'B' },
    { from: 'B', to: 'C' },
    { from: 'C', to: 'A' }
  ]
})
```

## TypeScript Support

Vivid is built with TypeScript and provides full type definitions:

```typescript
import type { VividObject, Animation, Point2D, Color } from 'vivid-animations'

// Custom animation with full type safety
class CustomAnimation implements Animation {
  id: string
  duration: number
  completed: boolean = false
  
  update(deltaTime: number): void {
    // Your animation logic
  }
}
```

## License

MIT License - see LICENSE file for details.