interpolate

interpolate is a small Dart utility for performing piecewise linear interpolation between numeric ranges. It is useful for mapping values from one numeric scale to another (for example, scaling sensor readings, animating values, or remapping ranges in data pipelines).

Table of contents

• Features
• Installation
• Quick start
• API reference
• Extrapolation behavior
• Examples
• Edge cases & validation
• Tests & development
• Contributing
• License

Features

• Piecewise linear interpolation across an arbitrary input range
• Symmetric output ranges (one-to-one mapping) with configurable extrapolation
• Small, dependency-free implementation suitable for Flutter and Dart projects

Installation

Add interpolate to your pubspec.yaml dependencies:

dependencies:
  interpolate: ^1.0.0

Then run:

dart pub get

(or flutter pub get for Flutter projects)

Quick start

import 'package:interpolate/interpolate.dart';

final interp = Interpolate(
  inputRange: [10.0, 20.0, 30.0],
  outputRange: [1.0, 0.0, 1.0],
  extrapolate: Extrapolate.clamp, // optional
);

final value = interp.eval(15.0); // -> 0.5

This maps 15 (halfway between 10 and 20) to 0.5 (halfway between 1 and 0).

API reference

Note: keep in sync with the package source. This section documents the public surface expected from the package.

Interpolate

• Constructor:

  • Interpolate({required List inputRange, required List outputRange, Extrapolate extrapolate = Extrapolate.clamp})
  • inputRange and outputRange must have the same length (>= 2). inputRange must be strictly increasing.
  • extrapolate controls behavior for values outside the input range (see below).

• Methods:

  • double eval(double x) — Evaluate the interpolated output for input x.
    • Returns a double value computed by linear interpolation between the two surrounding points in inputRange.
    • For x exactly equal to an entry in inputRange, the corresponding outputRange value is returned.

Extrapolate enum

enum Extrapolate {
  extend,     // No clamping — values outside input range continue the linear slope of the end segment
  clamp,      // Clamps both ends to the nearest output value (no extension)
  clampStart, // Clamp below the lowest input value, extend above
  clampEnd,   // Clamp above the highest input value, extend below
}

Extrapolation behavior (details)

• extend: If the input is below the first input value or above the last input value, the function continues the line defined by the first (or last) segment.
• clamp: Values below the first input return outputRange.first. Values above the last input return outputRange.last.
• clampStart: Values below the first input return outputRange.first. Values above are extended using the final segment slope.
• clampEnd: Values above the last input return outputRange.last. Values below are extended using the first segment slope.

Examples

1. Basic mapping

final interp = Interpolate(
  inputRange: [0.0, 100.0],
  outputRange: [0.0, 1.0],
);
print(interp.eval(50.0)); // 0.5

2. Multi-segment mapping

final interp = Interpolate(
  inputRange: [0.0,  50.0, 100.0],
  outputRange: [0.0,  0.8,  1.0],
);
print(interp.eval(75.0)); // interpolates between 50->100 mapping 0.8->1.0 -> 0.9

3. Extrapolation

final clampInterp = Interpolate(
  inputRange: [0.0, 1.0],
  outputRange: [0.0, 10.0],
  extrapolate: Extrapolate.clamp,
);
print(clampInterp.eval(-5.0)); // 0.0 (clamped)

final extendInterp = Interpolate(
  inputRange: [0.0, 1.0],
  outputRange: [0.0, 10.0],
  extrapolate: Extrapolate.extend,
);
print(extendInterp.eval(2.0)); // 20.0 (extends slope)

Edge cases & validation

• inputRange must be strictly increasing. If two adjacent entries are equal or decreasing, the behaviour is undefined and the library may throw an error or return null — validate your ranges before constructing the Interpolate instance.
• inputRange and outputRange must have the same length and at least two elements. An assertion or exception will be raised if this requirement is not met.
• For inputs exactly equal to an inputRange entry, the mapped output is the corresponding outputRange value (no interpolation required).

Tests & development

Run the package tests with:

dart test

(or flutter test in Flutter projects)

To run the example in example/, run the example project's main file or use the Dart/Flutter tooling as appropriate.

Contributing

Contributions, bug reports and feature requests are welcome.

• Fork the repository
• Create a feature branch
• Add tests for any new behaviour
• Open a pull request with a clear description of changes

Please follow the repository code style and include tests where applicable.

License

This project is licensed under the terms in the LICENSE file.