d3-interpolate

What is d3-interpolate?

The d3-interpolate package provides a variety of interpolation methods for smooth transitions between values in data visualization and animation. It is part of the D3 (Data-Driven Documents) suite of tools, which are used for manipulating documents based on data. d3-interpolate can interpolate numbers, colors, strings, arrays, objects, and even transform strings for complex animations.

What are d3-interpolate's main functionalities?

Number Interpolation

Interpolates between two numbers. Given a starting number and an ending number, it creates a function that takes a parameter 't' between 0 and 1 and returns the interpolated value.

const interpolate = d3.interpolateNumber(0, 10);
console.log(interpolate(0.5)); // 5

Color Interpolation

Interpolates between two colors. It creates a function that takes a parameter 't' and returns the color that is 't' of the way from the start color to the end color.

const interpolate = d3.interpolateRgb('blue', 'red');
console.log(interpolate(0.5)); // rgb(128, 0, 128)

Object Interpolation

Interpolates between two objects. It interpolates each property of the object that can be interpolated and returns a new object with the interpolated values.

const interpolate = d3.interpolateObject({x: 0}, {x: 10});
console.log(interpolate(0.5)); // {x: 5}

Array Interpolation

Interpolates between two arrays. It interpolates each element of the array and returns a new array with the interpolated values.

const interpolate = d3.interpolateArray([0, 1], [10, 20]);
console.log(interpolate(0.5)); // [5, 10.5]

String Interpolation

Interpolates between two strings that represent transform operations. It is useful for smoothly transitioning SVG elements through transform changes.

const interpolate = d3.interpolateString('rotate(0)', 'rotate(90)');
console.log(interpolate(0.5)); // rotate(45)

Other packages similar to d3-interpolate

lerp

A small library for linear interpolation of numbers. It is more focused and lightweight compared to d3-interpolate, which offers a broader range of interpolation options.

chroma-js

A library for all kinds of color conversions and color scales. While it includes color interpolation, it is more comprehensive in terms of color manipulation compared to d3-interpolate.

animejs

A powerful animation library that includes interpolation among its features. It is more focused on complex animations and has a broader scope than d3-interpolate.

README

d3-interpolate

This module provides a variety of interpolation methods for blending between two values. Values may be numbers, colors, strings, arrays, or even deeply-nested objects. For example:

var i = d3_interpolate.number(10, 20);
i(0.0); // 10
i(0.2); // 12
i(0.5); // 15
i(1.0); // 20

The returned function i is called an interpolator. Given a starting value a and an ending value b, it takes a parameter t in the domain [0, 1] and returns the corresponding interpolated value between a and b. An interpolator typically returns a value equivalent to a at t = 0 and a value equivalent to b at t = 1.

You can interpolate more than just numbers. To find the perceptual midpoint between steelblue and brown:

d3_interpolate.lab("steelblue", "brown")(0.5); // "#8e5c6d"

Here’s a more elaborate example demonstrating type inference used by value:

var i = d3_interpolate.value({colors: ["red", "blue"]}, {colors: ["white", "black"]});
i(0.0); // {colors: ["#ff0000", "#0000ff"]}
i(0.5); // {colors: ["#ff8080", "#000080"]}
i(1.0); // {colors: ["#ffffff", "#000000"]}

Note that the generic value interpolator detects not only nested objects and arrays, but also color strings and numbers embedded in strings!

Installing

If you use NPM, npm install d3-interpolate. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using Rollup or your preferred bundler. You can also load directly from d3js.org:

<script src="https://d3js.org/d3-color.v0.3.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v0.2.min.js"></script>

In a vanilla environment, a d3_interpolate global is exported. Try d3-interpolate in your browser.

API Reference

# d3_interpolate.value(a, b)

Returns an interpolator between the two arbitrary values a and b. The interpolator implementation is based on the type of the end value b, using the following algorithm:

1. If b is a color, rgb is used.
2. If b is a string, string is used.
3. If b is an array, array is used.
4. If b is an object and not coercible to a number, object is used.
5. Otherwise, number is used.

Based on the chosen interpolator, a is coerced to a suitable corresponding type. The behavior of this method may be augmented to support additional types by pushing custom interpolator factories onto the values array.

# d3_interpolate.number(a, b)

Returns an interpolator between the two numbers a and b. The returned interpolator is equivalent to:

function interpolate(t) {
  return a * (1 - t) + b * t;
}

Caution: avoid interpolating to or from the number zero when the interpolator is used to generate a string. When very small values are stringified, they may be converted to scientific notation, which is an invalid attribute or style property value. For example, the number 0.0000001 is converted to the string "1e-7". This is particularly noticeable with interpolating opacity. To avoid scientific notation, start or end the transition at 1e-6: the smallest value that is not stringified in scientific notation.

# d3_interpolate.round(a, b)

Returns an interpolator between the two numbers a and b; the interpolator is similar to number, except it will round the resulting value to the nearest integer.

# d3_interpolate.string(a, b)

Returns an interpolator between the two strings a and b. The string interpolator finds numbers embedded in a and b, where each number is of the form understood by JavaScript. A few examples of numbers that will be detected within a string: -1, 42, 3.14159, and 6.0221413e+23.

For each number embedded in b, the interpolator will attempt to find a corresponding number in a. If a corresponding number is found, a numeric interpolator is created using number. The remaining parts of the string b are used as a template: the static parts of the string b remain constant for the interpolation, with the interpolated numeric values embedded in the template.

For example, if a is "300 12px sans-serif", and b is "500 36px Comic-Sans", two embedded numbers are found. The remaining static parts of the string are a space between the two numbers (" "), and the suffix ("px Comic-Sans"). The result of the interpolator at t = .5 is "400 24px Comic-Sans".

# d3_interpolate.array(a, b)

Returns an interpolator between the two arrays a and b. Internally, an array template is created that is the same length in b. For each element in b, if there exists a corresponding element in a, a generic interpolator is created for the two elements using value. If there is no such element, the static value from b is used in the template. Then, for the given parameter t, the template’s embedded interpolators are evaluated. The updated array template is then returned.

For example, if a is the array [0, 1] and b is the array [1, 10, 100], then the result of the interpolator for t = .5 is the array [.5, 5.5, 100].

Note: no defensive copy of the template array is created; modifications of the returned array may adversely affect subsequent evaluation of the interpolator. No copy is made for performance reasons; interpolators are often part of the inner loop of animated transitions.

# d3_interpolate.object(a, b)

Returns an interpolator between the two objects a and b. Internally, an object template is created that has the same properties as b. For each property in b, if there exists a corresponding property in a, a generic interpolator is created for the two elements using value. If there is no such property, the static value from b is used in the template. Then, for the given parameter t, the template's embedded interpolators are evaluated and the updated object template is then returned.

For example, if a is the object {x: 0, y: 1} and b is the object {x: 1, y: 10, z: 100}, the result of the interpolator for t = .5 is the object {x: .5, y: 5.5, z: 100}.

Object interpolation is particularly useful for dataspace interpolation, where data is interpolated rather than attribute values. For example, you can interpolate an object which describes an arc in a pie chart, and then use d3.svg.arc to compute the new SVG path data.

Note: no defensive copy of the template object is created; modifications of the returned object may adversely affect subsequent evaluation of the interpolator. No copy is made for performance reasons; interpolators are often part of the inner loop of animated transitions.

# d3_interpolate.transform(a, b)

Returns an interpolator between the two 2D affine transforms represented by a and b. Each transform is decomposed to a standard representation of translate, rotate, x-skew and scale; these component transformations are then interpolated. This behavior is standardized by CSS: see matrix decomposition for animation.

# d3_interpolate.zoom(a, b)

Returns an interpolator between the two views a and b of a two-dimensional plane, based on “Smooth and efficient zooming and panning” by Jarke J. van Wijk and Wim A.A. Nuij. Each view is defined as an array of three numbers: cx, cy and width. The first two coordinates cx, cy represent the center of the viewport; the last coordinate width represents the size of the viewport.

The returned interpolator exposes a duration property which encodes the recommended transition duration in milliseconds. This duration is based on the path length of the curved trajectory through x,y space. If you want to a slower or faster transition, multiply this by an arbitrary scale factor (V as described in the original paper).

# d3_interpolate.values

The array of built-in interpolator factories, as used by value. Additional interpolator factories may be pushed onto the end of this array. Each factory should return an interpolator if it supports interpolating the two specified input values; otherwise, the factory should return a falsey value and other interpolators will be tried.

For example, to register a custom interpolator that formats dollars and cents, you might say:

d3_interpolate.values.push(function(a, b) {
  var re = /^\$([0-9,.]+)$/, ma, mb, f = d3.format(",.02f");
  if ((ma = re.exec(a)) && (mb = re.exec(b))) {
    a = parseFloat(ma[1]);
    b = parseFloat(mb[1]) - a;
    return function(t) {
      return "$" + f(a + b * t);
    };
  }
});

Subsequently, d3_interpolate.value("$20", "$10")(1/3) returns $16.67.

# d3_interpolate.rgb(a, b)

Returns an RGB color space interpolator between the two colors a and b. The colors a and b need not be in RGB; they will be converted to RGB using color.rgb. The return value of the interpolator is a hexadecimal RGB string.

# d3_interpolate.hsl(a, b)

Returns an HSL color space interpolator between the two colors a and b. The colors a and b need not be in HSL; they will be converted to HSL using color.hsl. If either color’s hue or saturation is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# d3_interpolate.hslLong(a, b)

Like hsl, but does not use the shortest path between hues.

# d3_interpolate.lab(a, b)

Returns a Lab color space interpolator between the two colors a and b. The colors a and b need not be in Lab; they will be converted to Lab using color.lab. The return value of the interpolator is a hexadecimal RGB string.

# d3_interpolate.hcl(a, b)

Returns an HCL color space interpolator between the two colors a and b. The colors a and b need not be in HCL; they will be converted to HCL using color.hcl. If either color’s hue or chroma is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# d3_interpolate.hclLong(a, b)

Like hcl, but does not use the shortest path between hues.

# d3_interpolate.cubehelix(a, b)

Returns a Cubehelix color space interpolator between the two colors a and b using the default gamma of 1.0. The colors a and b need not be in Cubehelix; they will be converted to Cubehelix using color.cubehelix. If either color’s hue or saturation is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# d3_interpolate.cubehelixLong(a, b)

Like cubehelix, but does not use the shortest path between hues.

# d3_interpolate.cubehelixGamma(gamma)

Returns a Cubehelix color space interpolator factory using the specified gamma. A gamma value less than one emphasizes low intensity values, while a gamma value greater than one emphasizes high intensity values. For example:

var i = d3_interpolate.cubehelixGamma(3)("purple", "orange");

# d3_interpolate.cubehelixGammaLong(gamma)

Like cubehelixGamma, but does not use the shortest path between hues.