Animation utilities

Interpolation, spring physics, and animation functions

Animation utilities for creating smooth transitions and physics-based motion.

interpolate()

Maps an input value within a range to an output value.

const value = interpolate(input, inputRange, outputRange, options);

input · number · required

The value to interpolate

inputRange · number[] · required

Array of input values (must be strictly monotonically increasing, at least 2 elements)

outputRange · number[] · required

Array of output values (must match length of inputRange)

options · InterpolateOptions

Configuration options

Show properties

extrapolateLeft · 'extend' | 'clamp' | 'identity' · default: "'extend'"

Behavior when input is less than inputRange[0]

• extend: Continue the trend
• clamp: Return outputRange[0]
• identity: Return input

extrapolateRight · 'extend' | 'clamp' | 'identity' · default: "'extend'"

Behavior when input is greater than inputRange[last]

• extend: Continue the trend
• clamp: Return outputRange[last]
• identity: Return input

easing · (t: number) => number

Easing function to apply to the interpolation

value · number

The interpolated output value

Example

import { interpolate, Easing } from '@heliosvideo/core';

// Linear interpolation
const opacity = interpolate(
  frame,
  [0, 30],
  [0, 1]
);

// With easing
const scale = interpolate(
  frame,
  [0, 60],
  [0.5, 1.5],
  { easing: Easing.cubic.out }
);

// Multi-segment animation
const y = interpolate(
  frame,
  [0, 30, 60, 90],
  [0, 100, 100, 200]
);

// Clamping
const clamped = interpolate(
  frame,
  [0, 100],
  [0, 1],
  {
    extrapolateLeft: 'clamp',
    extrapolateRight: 'clamp'
  }
);

spring()

Calculates the value of a spring physics simulation at a specific frame.

const value = spring(options);

options · SpringOptions · required

Spring configuration

Show properties

frame · number · required

Current frame number

fps · number · required

Frame rate in frames per second

from · number · default: "0"

Starting value

to · number · default: "1"

Target value

config · SpringConfig

Physics configuration

Show properties

mass · number · default: "1"

Mass of the spring (must be > 0)

stiffness · number · default: "100"

Stiffness of the spring (must be > 0)

damping · number · default: "10"

Damping coefficient

overshootClamping · boolean · default: "false"

Prevent the spring from overshooting the target value

durationInFrames · number

Duration hint (currently ignored by spring function)

value · number

The calculated spring value at the given frame

Example

import { spring } from '@heliosvideo/core';

// Basic spring animation
const scale = spring({
  frame: currentFrame,
  fps: 30,
  from: 0,
  to: 1,
});

// Bouncy spring
const y = spring({
  frame: currentFrame,
  fps: 30,
  from: 0,
  to: 100,
  config: {
    mass: 1,
    stiffness: 200,
    damping: 5,
  },
});

// Stiff spring with no overshoot
const opacity = spring({
  frame: currentFrame,
  fps: 30,
  from: 0,
  to: 1,
  config: {
    stiffness: 300,
    damping: 30,
    overshootClamping: true,
  },
});

calculateSpringDuration()

Calculates the number of frames required for a spring to settle.

const duration = calculateSpringDuration(options, threshold);

options · Omit<SpringOptions, 'frame'> · required

Spring configuration (same as spring() but without frame)

threshold · number · default: "0.001"

Distance from target to consider settled

duration · number

Estimated duration in frames

Example

import { calculateSpringDuration } from '@heliosvideo/core';

const duration = calculateSpringDuration({
  fps: 30,
  from: 0,
  to: 1,
  config: {
    stiffness: 100,
    damping: 10,
  },
});

console.log(`Spring will settle in ${duration} frames`);

DEFAULT_SPRING_CONFIG

Default spring configuration values.

const DEFAULT_SPRING_CONFIG: Required<SpringConfig> = {
  mass: 1,
  stiffness: 100,
  damping: 10,
  overshootClamping: false,
};