Skip to content

getting-started.md

Latest commit

 

History

History
371 lines (278 loc) · 7.66 KB

getting-started.md

File metadata and controls

371 lines (278 loc) · 7.66 KB

Getting Started with Vivid

This guide will help you get up and running with Vivid for creating mathematical visualizations.

Installation

Using npm

npm install vivid-animations

Using yarn

yarn add vivid-animations

Using CDN (for quick prototyping)

<script type="module">
  import { Scene, Circle, Create } from 'https://unpkg.com/vivid-animations/dist/index.js'
  // Your code here
</script>

Your First Animation

Let's create a simple animation with a circle:

1. Set Up HTML

<!DOCTYPE html>
<html>
<head>
    <title>My First Vivid Animation</title>
    <style>
        canvas {
            border: 1px solid #ccc;
            display: block;
            margin: 20px auto;
        }
    </style>
</head>
<body>
    <canvas id="canvas" width="800" height="600"></canvas>
    <script type="module" src="main.js"></script>
</body>
</html>

2. Create the Animation

// main.js
import { Scene, Circle, Create } from 'vivid-animations'

// Get the canvas element
const canvas = document.getElementById('canvas') as HTMLCanvasElement
const scene = new Scene(canvas)

// Create a circle
const circle = new Circle({
  radius: 1,
  color: { r: 0.2, g: 0.6, b: 1, a: 1 }
})

// Animate the circle appearing
scene.play(new Create(circle))

3. Run Your Animation

Open the HTML file in a web browser and you'll see a blue circle animate into view!

Core Concepts

Scene

The Scene is the main container that manages all objects and handles rendering:

const scene = new Scene(canvas)

// Add objects to the scene
scene.add(circle)

// Play animations
scene.play(animation)

// Play multiple animations
scene.play([animation1, animation2])

Objects

Objects are things that can be drawn on screen. All objects implement the VividObject interface:

// Basic shapes
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 } })

// Text
const text = new Text('Hello Vivid!')

// Mathematical objects
const axes = new Axes({ xRange: [-5, 5], yRange: [-3, 3] })
const func = new FunctionPlot({ func: x => x * x })

Animations

Animations modify objects over time:

// Basic animations
new Create(object)         // Scale from 0 to full size
new FadeIn(object)         // Fade in opacity
new FadeOut(object)        // Fade out opacity

// Transform animations
new Transform(object, {
  transform: {
    translate: { x: 2, y: 1 },
    scale: { x: 1.5, y: 1.5 },
    rotate: Math.PI / 4
  }
})

// Text animations
new DrawText(text)         // Draw text character by character
new EraseText(text)        // Erase text character by character

Positioning Objects

Objects can be positioned using several methods:

// Absolute positioning
circle.moveTo({ x: 2, y: 1 })

// Relative positioning
circle.shift({ x: 1, y: 0 })  // Move right by 1 unit

// Chaining transformations
circle.moveTo({ x: 0, y: 0 }).scale(1.5).rotate(Math.PI / 4)

Mathematical Visualizations

Coordinate Systems

// 2D axes
const axes = new Axes({
  xRange: [-5, 5],
  yRange: [-3, 3],
  showGrid: true,
  gridColor: { r: 0.8, g: 0.8, b: 0.8, a: 0.5 }
})

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

Function Plotting

// Basic function
const parabola = new FunctionPlot({
  func: x => x * x,
  xRange: [-3, 3],
  color: { r: 1, g: 0.5, b: 0, a: 1 }
})

// Trigonometric function
const sine = new FunctionPlot({
  func: Math.sin,
  xRange: [-2 * Math.PI, 2 * Math.PI],
  resolution: 100
})

// Custom function
const custom = new FunctionPlot({
  func: x => Math.exp(-x*x) * Math.cos(5*x),
  xRange: [-3, 3]
})

Mathematical Text

// Basic math notation
const formula = new MathText('f(x) = x^2 + 2x + 1')

// Greek letters and symbols
const equation = new MathText('\\alpha + \\beta = \\gamma')

// Fractions and complex expressions
const complex = new MathText('\\frac{d}{dx} \\int_0^x f(t) dt = f(x)')

3D Visualizations

Basic 3D Objects

// 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],
  resolution: 50
})

Camera Controls

// Enable interactive controls (mouse/touch)
scene.camera3D.enableControls(true)

// Programmatic camera control
scene.camera3D.setPosition(5, 5, 5)
scene.camera3D.lookAt(0, 0, 0)

// Animate camera
scene.play(new Transform(scene.camera3D, {
  position: { x: 10, y: 10, z: 10 }
}))

Animation Timing

Sequential Animations

import { Sequence } from 'vivid-animations'

scene.play(new Sequence([
  new Create(circle),      // First: create circle
  new FadeIn(text),        // Then: fade in text
  new Transform(circle, {  // Finally: move circle
    transform: { translate: { x: 2, y: 0 } }
  })
]))

Parallel Animations

import { AnimationGroup } from 'vivid-animations'

scene.play(new AnimationGroup([
  new Create(circle),      // All animations
  new FadeIn(text),        // happen at the
  new Create(axes)         // same time
]))

Custom Timing

// Set custom duration
new Create(circle, { duration: 2 })  // 2 seconds

// Set custom easing
new FadeIn(text, { 
  duration: 1.5,
  easing: t => t * t  // Quadratic ease-in
})

Interactive Features

Updater System

Create objects that update continuously:

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

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

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

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

Event Handling

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect()
  const x = (event.clientX - rect.left - canvas.width / 2) / 80
  const y = -(event.clientY - rect.top - canvas.height / 2) / 80
  
  const dot = new Circle({ radius: 0.1 })
  dot.moveTo({ x, y })
  scene.play(new Create(dot))
})

Performance Tips

Optimizing Animations

  1. Limit object count: Keep the number of objects reasonable
  2. Use object pooling: Reuse objects instead of creating new ones
  3. Optimize update loops: Avoid expensive calculations in update methods
  4. Use appropriate resolution: Don't use more detail than necessary

Memory Management

// Clean up when done
scene.clear()  // Remove all objects
scene.stop()   // Stop animation loop

Next Steps

Common Issues

Canvas Not Found

// Make sure canvas exists before creating scene
const canvas = document.getElementById('canvas') as HTMLCanvasElement
if (!canvas) {
  console.error('Canvas element not found!')
  return
}

Import Errors

// Use exact import names
import { Scene, Circle, Create } from 'vivid-animations'
// Not: import Scene from 'vivid-animations'

Animation Not Starting

// Make sure to call scene.play()
scene.add(circle)           // Adds object to scene
scene.play(new Create(circle))  // Starts animation

Ready to create amazing mathematical visualizations? Let's dive in!