Interpolate

Generic functions

detroit.interpolate(a: None, b: None) → Callable[[float], None]

detroit.interpolate(a: bool, b: bool) → Callable[[float], bool]

detroit.interpolate(a: float | int, b: float | int) → Callable[[float], float]

detroit.interpolate(a: str, b: str) → Callable[[float], str]

detroit.interpolate(a: Color, b: Color) → Callable[[float], str]

detroit.interpolate(a: datetime, b: datetime) → Callable[[float], datetime]

detroit.interpolate(a: list[int | float], b: list[int | float]) → Callable[[float], list[int | float]]

detroit.interpolate(a: list | tuple, b: list | tuple) → Callable[[float], list]

detroit.interpolate(a: list | tuple, b: list | tuple) → Callable[[float], list]

detroit.interpolate(a: dict, b: dict) → Callable[[float], dict]

Returns an interpolator between the two arbitrary values a and b.

None	Returns a constant function based on b value (= None)
bool	Returns a constant function based on b value
int	See d3.interpolate_number
float	See d3.interpolate_number
str	See d3.interpolate_rgb if string can be formatted as a color else for a generic string, see d3.interpolate_string
Color	See d3.interpolate_rgb
datetime	See d3.interpolate_date
list[int | float]	See d3.interpolate_number_array
list | tuple	Returns an interpolator which recursively interpolates based on input values
dict[U, V]	See d3.interpolate_object

Parameters:

• a (Any) – Left bound of the interpolator

• b (Any) – Right bound of the interpolator

Returns:

Interpolator function where input value is a flaot between 0 and 1 and it outputs a value between a and b:

\[\begin{split}interpolator: [0, 1] & \longrightarrow \mathbb [a, b] \\ x & \longmapsto y\end{split}\]

Return type:

Callable[[float], Any]

Examples

>>> interpolator = d3.interpolate(10, 20)
>>> interpolator(0)
10.0
>>> interpolator(1)
20.0
>>> interpolator(0.5)
15.0

detroit.quantize(interpolator: Callable[[float], float], n: int) → list[float]

detroit.piecewise(interpolate: Callable[[U, U], Callable[[float], V]], values: list[U] | None = None) → Callable[[float], V]

Typed functions

detroit.interpolate_array(a: list[int | float], b: list[int | float]) → Callable[[float], list[int | float]]

Returns an interpolator between the two arrays a and b.

Parameters:

• a (list[int | float]) – Array a

• b (list[int | float]) – Array b

Returns:

Interpolator function

Return type:

Callable[[float], list[int | float]]

Examples

>>> interpolator = d3.interpolate_array([0, 10, 20], [30, 40, 50])
>>> interpolator(0)
[0, 10, 20]
>>> interpolator(1)
[30, 40, 50]
>>> interpolator(0.5)
[15.0, 25.0, 35.0]

detroit.interpolate_basis(values: list[float]) → Callable[[float], float]

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[-1] at \(t = 1\).

Parameters:

values (list[float]) – List of inputs

Returns:

Interpolator function

Return type:

Callable[[float], float]

Examples

>>> interpolator = d3.interpolate_basis([0, 10, 20])
>>> interpolator(0)
0.0
>>> interpolator(1)
20.0
>>> interpolator(0.5)
10.0

detroit.interpolate_basis_closed(values: list[float]) → Callable[[float], float]

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^2\) continuity when repeated around \(t\) in \([0, 1]\).

Parameters:

values (list[float]) – List of inputs

Returns:

Interpolator function

Return type:

Callable[[float], float]

Examples

>>> interpolator = d3.interpolate_basis_closed([0, 10, 20])
>>> interpolator(0)
5.0
>>> interpolator(1)
-10.0
>>> interpolator(0.5)
14.375

detroit.interpolate_cubehelix(start: str, end: str) → Callable[[float], str]

Returns a Cubehelix color space interpolator between the two colors a and b using a configurable gamma. If the gamma is not specified, it defaults to 1.0. The colors a and b need not be in Cubehelix; they will be converted to Cubehelix using d3.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 an RGB string.

Parameters:

• a (str) – String a

• b (str) – String b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_cubehelix("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(238, 0, 209)'

detroit.interpolate_cubehelix.set_gamma(gamma: float) → CubeHelixInterpolator

Sets gamma and returns itself. See gamma error in picture scaling for more information.

Parameters:

gamma (float) – Gamma value

Returns:

Itself

Return type:

CubeHelixInterpolator

detroit.interpolate_cubehelix_long(start: str, end: str) → Callable[[float], str]

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

Parameters:

• a (str) – String a

• b (str) – String b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_cubehelix_long("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(238, 0, 209)'

detroit.interpolate_date(a: datetime, b: datetime) → Callable[[float], datetime]

Returns an interpolator between the two dates a and b.

Parameters:

• a (datetime) – Date a

• b (datetime) – Date b

Returns:

Interpolator function

Return type:

Callable[[float], datetime]

Examples

>>> from datetime import datetime
>>> interpolator = d3.interpolate_date(datetime(2000, 1, 1), datetime(2000, 1, 2))
>>> interpolator(0)
datetime.datetime(2000, 1, 1, 0, 0)
>>> interpolator(1)
datetime.datetime(2000, 1, 2, 0, 0)
>>> interpolator(0.5)
datetime.datetime(2000, 1, 1, 12, 0)

detroit.interpolate_discrete(range_: list[T]) → Callable[[float], T]

Returns a discrete interpolator for the given array of values.

Parameters:

range (list[T]) – List of elements

Returns:

Interpolator function

Return type:

Callable[[float], T]

Examples

>>> interpolator = d3.interpolate_discrete(["a", "b", "c"])
>>> interpolator(0)
'a'
>>> interpolator(1)
'c'
>>> interpolator(0.5)
'b'

detroit.interpolate_hcl(a: str, b: str) → Callable[[float], str]

Returns a CIELChab color space interpolator between the two colors a and b. The colors a and b need not be in CIELChab; they will be converted to CIELChab using d3.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 an RGB string.

Parameters:

• a (str) – Color string a

• b (str) – Color string b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_hcl("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(245, 0, 134)'

detroit.interpolate_hcl_long(a: str, b: str) → Callable[[float], str]

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

Parameters:

• a (str) – Color string a

• b (str) – Color string b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_hcl_long("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(0, 130, 64)'

detroit.interpolate_hsl(a: str, b: str) → Callable[[float], str]

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 d3.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 an RGB string.

Parameters:

• a (str) – String a

• b (str) – String b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_hsl("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(255, 0, 255)'

detroit.interpolate_hsl_long(a: str, b: str) → Callable[[float], str]

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

Parameters:

• a (str) – String a

• b (str) – String b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_hsl_long("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(0, 255, 0)'

detroit.interpolate_hue(a: float, b: float) → Callable[[float], float]

Returns an interpolator between the two hue angles a and b. If either hue is NaN, the opposing value is used. The shortest path between hues is used. The return value of the interpolator is a number in \([0, 360)\).

Parameters:

• a (float) – Hue angle a

• b (float) – Hue angle b

Returns:

Interpolator function

Return type:

Callable[[float], float]

Examples

>>> interpolator = d3.interpolate_hue(45, 180)
>>> interpolator(0)
45.0
>>> interpolator(1)
180.0
>>> interpolator(0.5)
112.5

detroit.interpolate_lab(a: str, b: str) → Callable[[float], str]

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

Parameters:

• a (str) – Color string a

• b (str) – Color string b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_lab("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(1)
'rgb(0, 0, 255)'
>>> interpolator(0.5)
'rgb(193, 0, 136)'

detroit.interpolate_number(a: int | float, b: int | float) → Callable[[float], float]

Returns an interpolator between the two numbers a and b.

Parameters:

• a (Number) – a value

• b (Number) – b value

Returns:

Interpolator function

Return type:

Callable[[float], float]

Examples

>>> interpolator = d3.interpolate_number(10, 20)
>>> interpolator(0)
10.0
>>> interpolator(1)
20.0
>>> interpolator(0.5)
15.0

detroit.interpolate_number_array(a: list[int | float], b: list[int | float] | None) → Callable[[float], list[int | float]]

Returns an interpolator between the two arbitrary values a and b.

Parameters:

• a (list[T]) – a value

• b (list[T] | None) – b value

Returns:

Interpolator function

Return type:

Callable[[float], list[int | float]]

Examples

>>> interpolator = d3.interpolate_number_array([0, 10, 20], [30, 40, 50])
>>> interpolator(0)
[0, 10, 20]
>>> interpolator(1)
[30, 40, 50]
>>> interpolator(0.5)
[15.0, 25.0, 35.0]

detroit.interpolate_object(a: dict[U, V], b: dict[U, V]) → Callable[[float], dict[U, V]]

Returns an interpolator between the two objects a and b.

Parameters:

• a (dict[U, V]) – Object a

• b (dict[U, V]) – Object b

Returns:

Interpolator function

Return type:

Callable[[float], dict[U, V]]

Examples

>>> interpolator = d3.interpolate_object({"a": [0, 10, 20]}, {"a": [30, 40, 50]})
>>> interpolator(0)
{'a': [0, 10, 20]}
>>> interpolator(1)
{'a': [30, 40, 50]}
>>> interpolator(0.5)
{'a': [15.0, 25.0, 35.0]}

detroit.interpolate_rgb(start: str, end: str) → Callable[[float], str]

Returns an interpolator between the two colors start and end.

Parameters:

• start (Number) – start value

• end (Number) – end value

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_rgb("red", "blue")
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(0.5)
'rgb(128, 0, 128)'
>>> interpolator(1)
'rgb(0, 0, 255)'

detroit.interpolate_rgb.set_gamma(y: float) → RGBGammaInterpolator

Sets gamma and returns itself. See gamma error in picture scaling for more information.

Parameters:

y (float) – Gamma value

Returns:

Itself

Return type:

RGBGammaInterpolator

detroit.interpolate_rgb_basis(colors: list[str]) → Callable[[float], str]

Returns a uniform nonrational B-spline interpolator through the specified array of colors, which are converted to RGB color space. Implicit control points are generated such that the interpolator returns colors[0] at t = 0 and colors[-1] at t = 1. Opacity interpolation is not currently supported. See also d3.interpolate_basis, and see scale_chromatic for examples.

Parameters:

colors (list[str]) – List of colors to interpolate

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_rgb_basis(["red", "green", "blue"])
>>> interpolator(0)
'rgb(255, 0, 0)'
>>> interpolator(0.5)
'rgb(42, 85, 42)'
>>> interpolator(1)
'rgb(0, 0, 255)'

detroit.interpolate_rgb_basis_closed(colors: list[str]) → Callable[[float], str]

Returns a uniform nonrational B-spline interpolator through the specified array of colors, which are converted to RGB color space. The control points are implicitly repeated such that the resulting spline has cyclical \(C^2\) continuity when repeated around t in [0,1]; this is useful, for example, to create cyclical color scales. Opacity interpolation is not currently supported. See also d3.interpolate_basis_closed, and see scale_chromatic for examples.

Parameters:

colors (list[str]) – List of colors to interpolate

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_rgb_basis_closed(["red", "green", "blue"])
>>> interpolator(0)
'rgb(170, 21, 42)'
>>> interpolator(0.5)
'rgb(11, 61, 122)'
>>> interpolator(1)
'rgb(255, 0, 255)'

detroit.interpolate_round(a: int | float | str, b: int | float | str) → Callable[[float], int]

Returns an interpolator between the two numbers a and b.

Parameters:

• a (int | float | str) – a value

• b (int | float | str) – b value

Returns:

Interpolator function

Return type:

Callable[[float], int]

Examples

>>> interpolator = d3.interpolate_round("1.2", "10.4")
>>> interpolator(0)
1
>>> interpolator(1)
10
>>> interpolator(0.5)
6

detroit.interpolate_string(a: str, b: str) → Callable[[float], str]

Returns an interpolator between the two strings a and b.

Parameters:

• a (str) – String a

• b (str) – String b

Returns:

Interpolator function

Return type:

Callable[[float], str]

Examples

>>> interpolator = d3.interpolate_string("10.", "20.")
>>> interpolator(0)
'10.0'
>>> interpolator(1)
'20.0'
>>> interpolator(0.5)
'15.0'

detroit.interpolate_zoom(a: list[float], b: list[float]) → Callable[[float], float]

An interpolator for zooming smoothly between two views 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.

Parameters:

• a (list[float]) – View a

• b (list[float]) – View b

Returns:

Interpolator function

Return type:

Callable[[float], float]

Examples

>>> interpolator = d3.interpolate_zoom([0, 0, 1], [10, 10, 5])
>>> interpolator(0)
[0.0, 0.0, 1.0]
>>> interpolator(1)
[10.00000000000023, 10.00000000000023, 5.0000000000001155]
>>> interpolator(0.5)
[1.666666666666673, 1.666666666666673, 10.775486583496573]

detroit.interpolate_zoom.set_rho(rho: float) → ZoomRho

Sets rho value and returns itself. When rho is closed to 0, the interpolator is almost linear.

Parameters:

rho (float) – Rho value

Returns:

Itself

Return type:

ZoomRho