D3 · all subjects

d3-interpolate

49 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

d3-interpolate module overview

d3-interpolate interpolates numbers, colors, strings, arrays, and objects. It provides value interpolators (number, round, string, date, array, object), color interpolators in various spaces (RGB, HSL, Lab, HCL, Cubehelix), transform interpolators, and zoom interpolation.

d3-interpolate module purpose

The d3-interpolate module provides a variety of interpolation methods for blending between two values. Values may be numbers, colors, strings, arrays, or even deeply-nested objects.

Interpolator function signature and behavior

An interpolator is a function that takes a parameter t (typically in [0, 1]) and returns the corresponding interpolated value between two values a and b. An interpolator typically returns a value equivalent to a at t = 0 and a value equivalent to b at t = 1.

d3.interpolateNumber example

const i = d3.interpolateNumber(10, 20); i(0.0); // 10 i(0.2); // 12 i(0.5); // 15 i(1.0); // 20

d3.interpolateLab color interpolation example

d3.interpolateLab("steelblue", "brown")(0.5); // "rgb(142, 92, 109)" This interpolates between two colors in Lab color space and returns the perceptual midpoint at t = 0.5.

d3.interpolate generic value interpolation example

interpolateTransformCss signature

d3.interpolateTransformCss(a, b) returns an interpolator between two 2D CSS 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. For example, d3.interpolateTransformCss("translateY(12px) scale(2)", "translateX(30px) rotate(5deg)")(0.5) returns "translate(15px,6px) rotate(2.5deg) scale(1.5,1.5)".

interpolateTransformSvg signature

d3.interpolateTransformSvg(a, b) returns an interpolator between two 2D SVG 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. For example, d3.interpolateTransformSvg("skewX(-60)", "skewX(60) translate(280,0)") returns an interpolator that at 0.5 yields "translate(140,0) skewX(0)".

Transform interpolation decomposition

Both CSS and SVG transform interpolators decompose transforms to a standard representation consisting of translate, rotate, x-skew and scale components. These component transformations are then interpolated individually according to CSS matrix decomposition for animation standards.

interpolate(a, b) signature and general interpolator

d3.interpolate(a, b) returns an interpolator between two arbitrary values a and b. The interpolator implementation is based on the type of the end value b: (1) If b is null, undefined or a boolean, the interpolator returns the constant b; (2) If b is a number, interpolateNumber is used; (3) If b is a color or string coercible to a color, interpolateRgb is used; (4) If b is a Date, interpolateDate is used; (5) If b is a string, interpolateString is used; (6) If b is a typed array of numbers, interpolateNumberArray is used; (7) If b is a generic array, interpolateArray is used; (8) If b is coercible to a number, interpolateNumber is used; (9) Otherwise interpolateObject is used. The input a is coerced to the corresponding type.

interpolate example: color interpolation

d3.interpolate("red", "blue")(0.5) returns "rgb(128, 0, 128)"

interpolateNumber(a, b) signature and formula

d3.interpolateNumber(a, b) returns an interpolator between two numbers a and b. The returned interpolator is equivalent to: function interpolator(t) { return a * (1 - t) + b * t; }

interpolateNumber example

d3.interpolateNumber(20, 620)(0.8) returns 500

interpolateNumber pitfall: scientific notation in strings

Avoid interpolating to or from the number zero when the interpolator is used to generate a string, because very small values may be converted to scientific notation (e.g., 0.0000001 becomes "1e-7"), which is invalid in older browsers as an attribute or style property value. 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.

interpolateRound(a, b) signature

d3.interpolateRound(a, b) returns an interpolator between two numbers a and b, similar to interpolateNumber except the resulting value is rounded to the nearest integer.

interpolateRound example

d3.interpolateRound(20, 620)(0.821) returns 513

interpolateString(a, b) signature

d3.interpolateString(a, b) returns an interpolator between two strings a and b. The string interpolator finds all numbers embedded in a and b (numbers understood by JavaScript, including forms like -1, 42, 3.14159, and 6.0221413e+23). For each number found in b, the interpolator attempts to find a corresponding number in a and creates a numeric interpolator using interpolateNumber. The remaining static parts of string b are used as a template for the interpolation, with interpolated numeric values embedded in the template.

interpolateString example

d3.interpolateString("20px", "32px")(0.5) returns "26px"

interpolateString example with multiple embedded numbers

If a is "300 12px sans-serif" and b is "500 36px Comic-Sans", two embedded numbers are found. The static parts from b are a space " " between the numbers and the suffix "px Comic-Sans". The result at t = 0.5 is "400 24px Comic-Sans".

interpolateDate(a, b) signature

d3.interpolateDate(a, b) returns an interpolator between two Date objects a and b.

interpolateDate example

d3.interpolateDate(new Date("2014-01-01"), new Date("2024-01-01"))(0.5) returns 2019-01-01

interpolateDate pitfall: no defensive copy

No defensive copy of the returned date is created; the same Date instance is returned for every evaluation of the interpolator. No copy is made for performance reasons, as interpolators are often part of the inner loop of animated transitions.

interpolateArray example

d3.interpolateArray([0, 0, 0], [1, 2, 3])(0.5) returns [0.5, 1, 1.5]

interpolateArray example with unequal lengths

If a is [0, 1] and b is [1, 10, 100], the result at t = 0.5 is [0.5, 5.5, 100].

interpolateNumberArray(a, b) signature

d3.interpolateNumberArray(a, b) returns an interpolator between two arrays of numbers a and b. Internally, an array template is created with the same type and length as b. For each element in b, if a corresponding element exists in a, the values are directly interpolated in the array template. If no corresponding element exists, the static value from b is copied. The updated array template is returned.

interpolateNumberArray example

d3.interpolateNumberArray([0, 1], Float64Array.of(1, 3))(0.5) returns [0.5, 2]

interpolateNumberArray pitfall: no defensive copy

No defensive copy is made of the template array or the arguments a and b; modifications of these arrays may affect subsequent evaluation of the interpolator.

interpolateObject(a, b) signature

d3.interpolateObject(a, b) returns an interpolator between two objects a and b. Internally, an object template is created with the same properties as b. For each property in b, if a corresponding property exists in a, a generic interpolator is created for the two values using interpolate. If no corresponding property exists, the static value from b is used. For a given parameter t, the template's embedded interpolators are evaluated and the updated object template is returned.

interpolateObject example

d3.interpolateObject({x: 0, y: 1}, {x: 1, y: 10, z: 100})(0.5) returns {x: 0.5, y: 5.5, z: 100}

interpolateObject example with unequal properties

If a is {x: 0, y: 1} and b is {x: 1, y: 10, z: 100}, the result at t = 0.5 is {x: 0.5, y: 5.5, z: 100}.

interpolateObject use case: dataspace interpolation

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 arc to compute the new SVG path data.

interpolateObject pitfall: no defensive copy

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.

interpolateBasis(values) signature

d3.interpolateBasis(values) returns a uniform nonrational B-spline interpolator through the specified array of values, which must be numbers. Implicit control points are generated such that the interpolator returns values[0] at t = 0 and values[values.length - 1] at t = 1.

interpolateBasis example

d3.interpolateBasis([0, 0.1, 0.4, 1])(0.5) returns 0.2604166666666667

interpolateBasisClosed(values) signature

d3.interpolateBasisClosed(values) returns a uniform nonrational B-spline interpolator through the specified array of values, which must be numbers. The control points are implicitly repeated such that the resulting one-dimensional spline has cyclical C² continuity when repeated around t in [0,1].

interpolateBasisClosed example

d3.interpolateBasisClosed([0, 0.1, 0.4, 1])(0.5) returns 0.45

interpolateDiscrete(values) signature

d3.interpolateDiscrete(values) returns a discrete interpolator for the given array of values. The returned interpolator maps t in [0, 1/n) to values[0], t in [1/n, 2/n) to values[1], and so on, where n = values.length. In effect, this is a lightweight quantize scale with a fixed domain of [0, 1].

interpolateDiscrete example

d3.interpolateDiscrete(["red", "blue", "green"])(0.5) returns "blue"

quantize(interpolator, n) signature

d3.quantize(interpolator, n) returns n uniformly-spaced samples from the specified interpolator, where n is an integer greater than one. The first sample is always at t = 0, and the last sample is always at t = 1.

quantize example

d3.quantize(d3.interpolate("red", "blue"), 4) returns ["rgb(255, 0, 0)", "rgb(170, 0, 85)", "rgb(85, 0, 170)", "rgb(0, 0, 255)"]

quantize pitfall: incompatible with non-defensive interpolators

quantize will not work with interpolators that do not return defensive copies of their output, such as interpolateArray, interpolateDate, and interpolateObject. For those interpolators, you must wrap the interpolator and create a copy for each returned value.

piecewise(interpolate, values) signature

d3.piecewise(interpolate, values) returns a piecewise interpolator, composing interpolators for each adjacent pair of values. If interpolate is not specified, defaults to interpolate. The returned interpolator maps t in [0, 1/(n-1)] to interpolate(values[0], values[1]), t in [1/(n-1), 2/(n-1)] to interpolate(values[1], values[2]), and so on, where n = values.length. In effect, this is a lightweight linear scale.

piecewise example with explicit interpolator

d3.piecewise(d3.interpolateRgb.gamma(2.2), ["red", "green", "blue"]) returns a piecewise interpolator using interpolateRgb.gamma(2.2)

piecewise example with default interpolator

d3.piecewise(["red", "green", "blue"]) returns a piecewise interpolator using the default interpolate function

interpolateZoom function signature

d3.interpolateZoom(a, b) returns an interpolator between two views a and b of a two-dimensional plane. Each view is an array of three numbers: [cx, cy, width], where cx and cy represent the center of the viewport and width represents the size of the viewport.

interpolateZoom duration property

The interpolator returned by d3.interpolateZoom 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 xy space and can be scaled by multiplying by an arbitrary factor if a slower or faster transition is desired.

interpolateZoom.rho method signature

d3.interpolateZoom.rho(rho) returns a new zoom interpolator using the specified curvature rho. The parameter rho controls the curvature of the interpolation path; when rho is close to 0, the interpolator is almost linear. The default curvature is sqrt(2).

interpolateZoom.rho example

d3.interpolateZoom.rho(0.5)([30, 30, 40], [135, 85, 60])(0.5) returns [72, 52, 51.09549882328188]

interpolateZoom algorithm basis

The zoom interpolator is based on the algorithm 'Smooth and efficient zooming and panning' by Jarke J. van Wijk and Wim A.A. Nuij.

Give your agent this brain