> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
const value = interpolate(input, inputRange, outputRange, options);
```

<ParamField path="input" type="number" required>
  The value to interpolate
</ParamField>

<ParamField path="inputRange" type="number[]" required>
  Array of input values (must be strictly monotonically increasing, at least 2 elements)
</ParamField>

<ParamField path="outputRange" type="number[]" required>
  Array of output values (must match length of inputRange)
</ParamField>

<ParamField path="options" type="InterpolateOptions">
  Configuration options

  <Expandable title="properties">
    <ParamField path="extrapolateLeft" type="'extend' | 'clamp' | 'identity'" default="'extend'">
      Behavior when input is less than inputRange\[0]

      * `extend`: Continue the trend
      * `clamp`: Return outputRange\[0]
      * `identity`: Return input
    </ParamField>

    <ParamField path="extrapolateRight" type="'extend' | 'clamp' | 'identity'" default="'extend'">
      Behavior when input is greater than inputRange\[last]

      * `extend`: Continue the trend
      * `clamp`: Return outputRange\[last]
      * `identity`: Return input
    </ParamField>

    <ParamField path="easing" type="(t: number) => number">
      Easing function to apply to the interpolation
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="value" type="number">
  The interpolated output value
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const value = spring(options);
```

<ParamField path="options" type="SpringOptions" required>
  Spring configuration

  <Expandable title="properties">
    <ParamField path="frame" type="number" required>
      Current frame number
    </ParamField>

    <ParamField path="fps" type="number" required>
      Frame rate in frames per second
    </ParamField>

    <ParamField path="from" type="number" default="0">
      Starting value
    </ParamField>

    <ParamField path="to" type="number" default="1">
      Target value
    </ParamField>

    <ParamField path="config" type="SpringConfig">
      Physics configuration

      <Expandable title="properties">
        <ParamField path="mass" type="number" default="1">
          Mass of the spring (must be > 0)
        </ParamField>

        <ParamField path="stiffness" type="number" default="100">
          Stiffness of the spring (must be > 0)
        </ParamField>

        <ParamField path="damping" type="number" default="10">
          Damping coefficient
        </ParamField>

        <ParamField path="overshootClamping" type="boolean" default="false">
          Prevent the spring from overshooting the target value
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="durationInFrames" type="number">
      Duration hint (currently ignored by spring function)
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="value" type="number">
  The calculated spring value at the given frame
</ResponseField>

### Example

```typescript theme={null}
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.

```typescript theme={null}
const duration = calculateSpringDuration(options, threshold);
```

<ParamField path="options" type="Omit<SpringOptions, 'frame'>" required>
  Spring configuration (same as spring() but without frame)
</ParamField>

<ParamField path="threshold" type="number" default="0.001">
  Distance from target to consider settled
</ParamField>

<ResponseField name="duration" type="number">
  Estimated duration in frames
</ResponseField>

### Example

```typescript theme={null}
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.

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