Skip to content

api.md

Latest commit

 

History

History
815 lines (661 loc) · 22.2 KB

api.md

File metadata and controls

815 lines (661 loc) · 22.2 KB
Raw

Vivid Animation Library - API Documentation

Overview

Vivid is a modern web-based animation library for mathematical visualizations, similar to Manim but designed to run live in the browser. This comprehensive API documentation covers all classes, interfaces, and utilities.

Core Types & Interfaces

Point2D

interface Point2D {
  x: number
  y: number
}

Point3D

interface Point3D extends Point2D {
  z: number
}

Color

interface Color {
  r: number  // Red component (0-1)
  g: number  // Green component (0-1)
  b: number  // Blue component (0-1)
  a?: number // Alpha component (0-1, optional)
}

Scale2D

interface Scale2D {
  x: number  // X-axis scale factor
  y: number  // Y-axis scale factor
}

Transform2D

interface Transform2D {
  translate: Point2D  // Translation offset
  scale: Point2D      // Scale factors
  rotate: number      // Rotation angle in radians
}

VividObject Interface

All renderable objects implement this interface:

interface VividObject {
  id: string
  transform: Transform2D
  color: Color
  visible: boolean
  coordinateSystem?: VividObject
  
  update(deltaTime: number): void
  render(ctx: CanvasRenderingContext2D): void
  getBounds(): { min: Point2D; max: Point2D }
  
  // Coordinate system association
  setCoordinateSystem?(axes: VividObject): this
  getWorldTransform?(): Transform2D
}

2D Objects

Circle

Creates circular shapes with customizable appearance.

class Circle implements VividObject

Constructor

constructor(options: CircleOptions = {})

interface CircleOptions {
  radius?: number
  color?: Color | string
  fillOpacity?: number
  strokeWidth?: number
  strokeColor?: Color | string
}

Properties

  • radius: number - Circle radius
  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)
  • setCoordinateSystem(axes: VividObject): this - Associate with coordinate system
  • getBounds(): { min: Point2D; max: Point2D } - Get bounding box

Text

Renders text with customizable fonts and alignment.

class Text implements VividObject

Constructor

constructor(text: string = '', options: TextOptions = {})

interface TextOptions {
  text?: string
  fontSize?: number
  fontFamily?: string
  color?: Color | string
  align?: 'left' | 'center' | 'right'
  baseline?: 'top' | 'middle' | 'bottom' | 'alphabetic'
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setText(newText: string): this - Update text content
  • getText(): string - Get current text
  • setFontSize(size: number): this - Change font size
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Static Properties

  • MathSymbols - Collection of Unicode math symbols (α, β, π, ∞, etc.)

MathText

Advanced text rendering with LaTeX support via KaTeX.

class MathText implements VividObject

Constructor

constructor(mathExpression: string, options: MathTextOptions = {})

interface MathTextOptions {
  fontSize?: number
  color?: Color | string
  backgroundColor?: Color | string
  fontFamily?: string
  padding?: number
  renderMode?: 'katex' | 'unicode'
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setExpression(expression: string): this - Update LaTeX expression
  • setText(text: string): this - Alias for setExpression
  • getExpression(): string - Get current expression
  • setFontSize(size: number): this - Change font size
  • setColor(color: Color | string): this - Change text color
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Line

Creates line segments between two points.

class Line implements VividObject

Constructor

constructor(start: Point2D = { x: -1, y: 0 }, end: Point2D = { x: 1, y: 0 }, options: LineOptions = {})

interface LineOptions {
  start?: Point2D
  end?: Point2D
  color?: Color | string
  strokeWidth?: number
  lineCap?: 'butt' | 'round' | 'square'
  lineDash?: number[]
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setStart(point: Point2D): this - Set start point
  • setEnd(point: Point2D): this - Set end point
  • setPoints(start: Point2D, end: Point2D): this - Set both points
  • getStart(): Point2D - Get start point
  • getEnd(): Point2D - Get end point
  • getLength(): number - Calculate line length
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Rectangle

Creates rectangular shapes with optional rounded corners.

class Rectangle implements VividObject

Constructor

constructor(options: RectangleOptions = {})

interface RectangleOptions {
  width?: number
  height?: number
  color?: Color | string
  fillOpacity?: number
  strokeWidth?: number
  strokeColor?: Color | string
  cornerRadius?: number
}

Properties

  • width: number - Rectangle width
  • height: number - Rectangle height
  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setSize(width: number, height: number): this - Change dimensions
  • setCornerRadius(radius: number): this - Set corner rounding
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

FunctionPlot

Plots mathematical functions (y = f(x)) or parametric curves.

class FunctionPlot implements VividObject

Constructor

constructor(funcOrParametric: FunctionType | ParametricFunction, options: FunctionPlotOptions = {})

type FunctionType = (x: number) => number
type ParametricFunction = (t: number) => { x: number; y: number }

interface FunctionPlotOptions {
  func?: FunctionType
  parametric?: ParametricFunction
  tMin?: number
  tMax?: number
  xMin?: number
  xMax?: number
  samples?: number
  color?: Color | string
  strokeWidth?: number
  lineDash?: number[]
  smooth?: boolean
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • updateFunction(func: FunctionType, xMin?: number, xMax?: number): this - Update function
  • updateParametric(parametric: ParametricFunction, tMin?: number, tMax?: number): this - Update parametric function
  • setSamples(samples: number): this - Change resolution
  • setColor(color: Color | string): this - Change line color
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Static Helper Functions

MathFunctions = {
  // Basic functions
  linear: (m: number, b?: number) => (x: number) => number
  quadratic: (a: number, b?: number, c?: number) => (x: number) => number
  
  // Trigonometric
  sin: (amplitude?: number, frequency?: number, phase?: number) => (x: number) => number
  cos: (amplitude?: number, frequency?: number, phase?: number) => (x: number) => number
  
  // Parametric curves
  circle: (radius?: number, centerX?: number, centerY?: number) => (t: number) => {x: number, y: number}
  ellipse: (a?: number, b?: number, centerX?: number, centerY?: number) => (t: number) => {x: number, y: number}
  spiral: (a?: number, b?: number) => (t: number) => {x: number, y: number}
}

PolygonFromPoints

Creates polygons and polylines from arrays of points.

class PolygonFromPoints implements VividObject

Constructor

constructor(points: Point2D[] = [], options: PolygonFromPointsOptions = {})

interface PolygonFromPointsOptions {
  points?: Point2D[]
  color?: Color | string
  fillOpacity?: number
  strokeWidth?: number
  strokeColor?: Color | string
  closed?: boolean
  smooth?: boolean
  showPoints?: boolean
  pointSize?: number
  pointColor?: Color | string
}

Properties

  • points: Point2D[] - Array of polygon vertices
  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setPoints(points: Point2D[]): this - Replace all points
  • addPoint(point: Point2D): this - Add point to end
  • insertPoint(index: number, point: Point2D): this - Insert point at index
  • removePoint(index: number): this - Remove point at index
  • updatePoint(index: number, point: Point2D): this - Update specific point
  • getPoints(): Point2D[] - Get copy of all points
  • getPointCount(): number - Get number of points
  • setClosed(closed: boolean): this - Set whether shape is closed
  • setSmooth(smooth: boolean): this - Enable/disable smooth curves
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Static Factory Methods

  • PolygonFromPoints.fromDataPoints(xValues: number[], yValues: number[]): PolygonFromPoints - Create from data arrays
  • PolygonFromPoints.fromFunction(func: (x: number) => number, xMin: number, xMax: number, samples?: number): PolygonFromPoints - Create from function
  • PolygonFromPoints.regularPolygon(sides: number, radius?: number, center?: Point2D): PolygonFromPoints - Create regular polygon
  • PolygonFromPoints.star(outerRadius?: number, innerRadius?: number, points?: number, center?: Point2D): PolygonFromPoints - Create star shape

Coordinate Systems

Axes

Creates 2D coordinate axes with grid, labels, and scaling.

class Axes implements VividObject

Constructor

constructor(options: AxesOptions = {})

interface AxesOptions {
  xMin?: number
  xMax?: number
  yMin?: number
  yMax?: number
  xStep?: number
  yStep?: number
  axisColor?: Color | string
  tickColor?: Color | string
  labelColor?: Color | string
  gridColor?: Color | string
  showGrid?: boolean
  showTickMarks?: boolean
  showLabels?: boolean
  tickSize?: number
  labelSize?: number
  strokeWidth?: number
  gridOpacity?: number
  width?: number                    // Physical width in pixels
  height?: number                   // Physical height in pixels
  pixelsPerUnit?: number            // Scale factor (default: 80)
  maintainAspectRatio?: boolean     // Whether to maintain aspect ratio (default: true)
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setRange(xMin: number, xMax: number, yMin: number, yMax: number): this - Set axis ranges
  • setXRange(min: number, max: number): this - Set X axis range
  • setYRange(min: number, max: number): this - Set Y axis range
  • setStep(xStep: number, yStep?: number): this - Set tick spacing
  • setDimensions(width: number, height: number): this - Set physical dimensions
  • setPixelsPerUnit(pixelsPerUnit: number): this - Set scale factor
  • setSize(pixelsPerUnit: number): this - Alias for setPixelsPerUnit
  • coordsToPoint(x: number, y: number): Point2D - Convert coordinates to canvas position
  • pointToCoords(point: Point2D): Point2D - Convert canvas position to coordinates
  • move_to(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Data Visualization

Matrix

Displays matrices and tables with customizable styling.

class Matrix implements VividObject

Constructor

constructor(data: (string | number)[][], options: MatrixOptions = {})

interface MatrixOptions {
  fontSize?: number
  color?: Color | string
  bracketStyle?: 'square' | 'round' | 'curly' | 'angle' | 'pipe' | 'none'
  cellPadding?: number
  rowSpacing?: number
  colSpacing?: number
  showGrid?: boolean
  gridColor?: Color | string
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setData(data: (string | number)[][]): this - Replace all data
  • getData(): (string | number)[][] - Get copy of data
  • setElement(row: number, col: number, value: string | number): this - Update single cell
  • getElement(row: number, col: number): string | number | undefined - Get single cell
  • getDimensions(): { rows: number; cols: number } - Get matrix dimensions
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Subclasses

class Table extends Matrix  // Matrix with grid enabled and no brackets

Graph

Creates graph visualizations with nodes and edges.

class Graph implements VividObject

Constructor

constructor(options: GraphOptions = {})

interface GraphOptions {
  nodeRadius?: number
  nodeColor?: Color | string
  edgeColor?: Color | string
  edgeWidth?: number
  labelSize?: number
  labelColor?: Color | string
  showLabels?: boolean
  showWeights?: boolean
  layout?: 'manual' | 'circle' | 'grid' | 'force'
  spacing?: number
}

interface GraphNode {
  id: string
  label?: string
  position?: Point2D
  color?: Color | string
  size?: number
  data?: any
}

interface GraphEdge {
  from: string
  to: string
  label?: string
  weight?: number
  color?: Color | string
  width?: number
  directed?: boolean
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • addNode(node: GraphNode): this - Add node to graph
  • removeNode(nodeId: string): this - Remove node and connected edges
  • addEdge(edge: GraphEdge): this - Add edge between nodes
  • removeEdge(from: string, to: string): this - Remove specific edge
  • getNode(nodeId: string): GraphNode | undefined - Get node by ID
  • getEdges(): GraphEdge[] - Get all edges
  • setLayout(layout: string): this - Change layout algorithm
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Subclasses

class Tree extends Graph
  • buildFromData(data: any, nodeId?: string, position?: Point2D, level?: number): this - Build tree from hierarchical data

NumberLine

Creates number lines with markers and labels.

class NumberLine implements VividObject

Constructor

constructor(options: NumberLineOptions = {})

interface NumberLineOptions {
  xMin?: number
  xMax?: number
  step?: number
  length?: number
  color?: Color | string
  tickColor?: Color | string
  labelColor?: Color | string
  showLabels?: boolean
  showTicks?: boolean
  tickSize?: number
  labelSize?: number
  strokeWidth?: number
  includeArrow?: boolean
  unitLength?: number
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • pointFromNumber(value: number): Point2D - Convert number to canvas position
  • numberFromPoint(point: Point2D): number - Convert canvas position to number
  • addNumber(value: number, color?: Color | string): NumberLineMarker - Add marker at value
  • setRange(xMin: number, xMax: number): this - Set number range
  • getRange(): { min: number; max: number } - Get current range
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

NumberLineMarker

Markers that can be placed on number lines.

class NumberLineMarker implements VividObject

Constructor

constructor(numberLine: NumberLine, value: number, options: NumberLineMarkerOptions = {})

interface NumberLineMarkerOptions {
  color?: Color | string
  size?: number
  style?: 'dot' | 'arrow' | 'line'
  label?: string
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setValue(value: number): this - Change marker position
  • getValue(): number - Get current value
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Utility Objects

HighlightBox

Creates highlighting boxes around other objects.

class HighlightBox implements VividObject

Constructor

constructor(target: VividObject, options: HighlightBoxOptions = {})

interface HighlightBoxOptions {
  padding?: number
  color?: Color | string
  strokeWidth?: number
  fillOpacity?: number
  cornerRadius?: number
  dashPattern?: number[]
}

Properties

  • visible: boolean - Visibility flag
  • transform: Transform2D - Position, scale, rotation

Methods

  • setTarget(target: VividObject): this - Change highlighted object
  • setPadding(padding: number): this - Adjust padding around target
  • setColor(color: Color | string): this - Change highlight color
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Subclasses

class UnderlineBox extends HighlightBox  // Creates underline instead of box

NumericValue

Invisible object for tracking numeric values with smooth transitions.

class NumericValue implements VividObject

Constructor

constructor(startValue: number = 0)

Properties

  • visible: boolean - Always false (invisible)
  • transform: Transform2D - Position, scale, rotation

Methods

  • get(): number - Get current value
  • set(value: number): this - Set value directly
  • transitionTo(targetValue: number, duration?: number): Promise<void> - Smooth transition
  • reset(): this - Reset to starting value
  • setStart(value: number): this - Update starting value
  • increment(amount: number): this - Add to current value
  • moveTo(point: Point2D): this - Move to absolute position
  • shift(delta: Point2D): this - Move by relative offset
  • scale(factor: number): this - Scale uniformly
  • rotate(angle: number): this - Rotate by angle (radians)

Utility Functions

ID Generation

function generateId(): string  // Generates unique object IDs

Constants

const ORIGIN = { x: 0, y: 0 }
const UP = { x: 0, y: 1 }
const DOWN = { x: 0, y: -1 }
const LEFT = { x: -1, y: 0 }
const RIGHT = { x: 1, y: 0 }

const PI = Math.PI
const TAU = Math.PI * 2
const DEGREES = Math.PI / 180

Easing Functions

const ease = {
  linear: (t: number) => number
  easeInOut: (t: number) => number
  easeIn: (t: number) => number
  easeOut: (t: number) => number
  bounce: (t: number) => number
}

Interpolation

function lerp(start: number, end: number, t: number): number
function lerpPoint(start: Point2D, end: Point2D, t: number): Point2D

Coordinate System Architecture

Scale2D Support

All VividObject classes support non-uniform scaling through the Scale2D system:

  • Independent X/Y scaling: Objects can be stretched horizontally or vertically
  • Aspect ratio control: The maintainAspectRatio option in Axes controls whether scaling preserves proportions
  • Coordinate system integration: Objects automatically inherit scaling from their coordinate system

Coordinate System Association

Objects can be associated with coordinate systems (typically Axes) using:

object.setCoordinateSystem(axes)

This enables:

  • Automatic coordinate transformations
  • Consistent scaling across related objects
  • Mathematical coordinate space mapping

Transform Hierarchy

Each object has its own transform that combines with its coordinate system:

  1. Object's local transform (object.transform)
  2. Coordinate system transform (if set)
  3. Final world transform (computed automatically)

Common Usage Patterns

Creating a Basic Scene

// Create coordinate system
const axes = new Axes({
  xMin: -5, xMax: 5,
  yMin: -3, yMax: 3,
  showGrid: true
})

// Create and position objects
const circle = new Circle({ radius: 1, color: '#ff6b6b' })
  .setCoordinateSystem(axes)
  .move_to({ x: 2, y: 1 })

const func = new FunctionPlot(x => Math.sin(x), {
  xMin: -5, xMax: 5,
  color: '#4ecdc4'
}).setCoordinateSystem(axes)

Animation Pattern

// Using the animate property (framework integration required)
circle.animate.move_to({ x: -2, y: 1 })
circle.animate.scale(1.5)

Mathematical Visualization

// Plot a function with custom styling
const parabola = new FunctionPlot(
  x => x * x,
  { 
    xMin: -3, 
    xMax: 3, 
    color: '#9b59b6',
    strokeWidth: 3 
  }
).setCoordinateSystem(axes)

// Add LaTeX labels
const label = new MathText('f(x) = x^2', {
  fontSize: 20,
  color: '#9b59b6'
}).setCoordinateSystem(axes)
 .move_to({ x: 1, y: 2 })

This comprehensive API documentation covers all the classes, methods, and patterns available in the Vivid animation library.