d3-interpolate

Этот модуль предоставляет различные методы интерполяции для сглаживания между двумя значениями. Значения могут быть числами, цветами, строками, массивами или даже глубоко вложенными объектами. Например:

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

Возвращаемая функция i называется интерполятором. Учитывая начальное значение a и конечное значение b, она принимает параметр t в области [0, 1] и возвращает соответствующее интерполированное значение между a и b. Интерполятор обычно возвращает значение, эквивалентное a при t = 0, и значение, эквивалентное b при t = 1.

Вы можете интерполировать не только числа. Чтобы найти среднее значение между steelblue и brown с точки зрения восприятия:

d3.interpolateLab("steelblue", "brown")(0.5); // "rgb(142, 92, 109)"

Вот более подробный пример, демонстрирующий вывод типа, используемый interpolate:

const i = d3.interpolate({colors: ["red", "blue"]}, {colors: ["white", "black"]});
i(0.0); // {colors: ["rgb(255, 0, 0)", "rgb(0, 0, 255)"]}
i(0.5); // {colors: ["rgb(255, 128, 128)", "rgb(0, 0, 128)"]}
i(1.0); // {colors: ["rgb(255, 255, 255)", "rgb(0, 0, 0)"]}

Обратите внимание, что универсальный интерполятор значений обнаруживает не только вложенные объекты и массивы, но также и цветовые строки и числа, встроенные в строки!

Установка

Если вы используете npm, npm install d3-interpolate. Вы также можете загрузить последнюю версию на GitHub. Для обычного HTML в современных браузерах импортируйте d3-interpolate из Skypack:

<script type="module">

import {interpolateRgb} from "https://cdn.skypack.dev/d3-interpolate@3";

const interpolate = interpolateRgb("steelblue", "brown");

</script>

Для устаревших сред вы можете загрузить UMD-пакет d3-interpolate с CDN на основе npm, например, jsDelivr; экспортируется глобальная переменная d3. (Если вы используете интерполяцию цветов, загрузите также d3-color.)

<script src="https://cdn.jsdelivr.net/npm/d3-color@3"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-interpolate@3"></script>
<script>

const interpolate = d3.interpolateRgb("steelblue", "brown");

</script>

Справочник по API

d3.interpolate(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя произвольными значениями a и b. Реализация интерполятора основана на типе конечного значения b, используя следующий алгоритм:

Если b равно null, undefined или boolean, используется константа b.
Если b — число, используется interpolateNumber.
Если b — цвет или строка, преобразуемая в цвет, используется interpolateRgb.
Если b — дата, используется interpolateDate.
Если b — строка, используется interpolateString.
Если b — массив с типом данных чисел, используется interpolateNumberArray.
Если b — обычный массив, используется interpolateArray.
Если b преобразуется в число, используется interpolateNumber.
Используется interpolateObject.

В зависимости от выбранного интерполятора, a приводится к соответствующему типу.

d3.interpolateNumber(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя числами a и b. Возвращаемый интерполятор эквивалентен:

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

Внимание: избегайте интерполяции к нулю или от нуля, когда интерполятор используется для генерации строки. При строковой записи очень маленьких значений они могут быть преобразованы в научную запись, что является недопустимым атрибутом или свойством стиля в старых браузерах. Например, число 0.0000001 преобразуется в строку "1e-7". Это особенно заметно при интерполяции непрозрачности. Чтобы избежать научной записи, начните или закончите переход на 1e-6: самое маленькое значение, которое не записывается в научной записи.

d3.interpolateRound(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя числами a и b; интерполятор похож на interpolateNumber, за исключением того, что он округляет полученное значение до ближайшего целого числа.

d3.interpolateString(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя строками a и b. Строковый интерполятор находит числа, встроенные в a и b, где каждое число имеет формат, понятный JavaScript. Вот несколько примеров чисел, которые будут обнаружены в строке: -1, 42, 3.14159, и 6.0221413e+23.

Для каждого числа, встроенного в b, интерполятор попытается найти соответствующее число в a. Если соответствующее число найдено, создается числовой интерполятор с помощью interpolateNumber. Остальные части строки b используются в качестве шаблона: статические части строки b остаются постоянными для интерполяции, а интерполированные числовые значения встраиваются в шаблон.

Например, если a равно "300 12px sans-serif", а b равно "500 36px Comic-Sans", будут найдены два встроенных числа. Остальные статические части (строки b) — пробел между двумя числами (" ") и суффикс ("px Comic-Sans"). Результатом интерполятора при t = 0,5 является "400 24px Comic-Sans".

d3.interpolateDate(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя датами a и b.

Примечание: никакая защитная копия возвращаемой даты не создается; для каждого вычисления интерполятора возвращается тот же экземпляр Date. Копия не создаётся по соображениям производительности; интерполяторы часто являются частью внутреннего цикла анимированных переходов.

d3.interpolateArray(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя массивами a и b. Если b — массив с типом данных (например, Float64Array), используется interpolateNumberArray.

Внутренне создается шаблон массива, имеющий такую же длину, как и b. Для каждого элемента в b, если существует соответствующий элемент в a, для двух элементов создаётся общий интерполятор с помощью interpolate. Если такого элемента нет, используется статическое значение из b в шаблоне. Затем, для данного параметра t, вычисляются встроенные интерполяторы шаблона. Затем возвращается обновлённый шаблон массива.

Например, если a — массив [0, 1], а b — массив [1, 10, 100], то результат интерполятора при t = 0,5 — массив [0.5, 5.5, 100].

Примечание: никакая защитная копия массива-шаблона не создается; изменения в возвращаемом массиве могут негативно повлиять на последующие вычисления интерполятора. Копия не создается по соображениям производительности; интерполяторы часто являются частью внутреннего цикла анимированных переходов.

d3.interpolateNumberArray(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя массивами чисел a и b. Внутренне создаётся шаблон массива, который имеет тот же тип и длину, что и b. Для каждого элемента в b, если существует соответствующий элемент в a, значения напрямую интерполируются в шаблон массива. Если такого элемента нет, статическое значение из b копируется. Затем возвращается обновлённый шаблон массива.

Примечание: по соображениям производительности никакая защитная копия не создаётся для массива-шаблона и аргументов a и b; изменения в этих массивах могут повлиять на последующие вычисления интерполятора.

d3.interpolateObject(a, b) · Исходный код, Примеры

Возвращает интерполятор между двумя объектами a и b. Внутренне создаётся шаблон объекта, имеющий те же свойства, что и b. Для каждого свойства в b, если существует соответствующее свойство в a, для двух элементов создаётся общий интерполятор с помощью interpolate. Если такого свойства нет, статическое значение из b используется в шаблоне. Затем, для данного параметра t, вычисляются встроенные интерполяторы шаблона, и возвращается обновлённый шаблон объекта.

Например, если a — объект {x: 0, y: 1}, а b — объект {x: 1, y: 10, z: 100}, результат интерполятора при t = 0,5 — объект {x: 0.5, y: 5.5, z: 100}.

Интерполяция объектов особенно полезна для интерполяции данных, где интерполируются данные, а не значения атрибутов. Например, вы можете интерполировать объект, описывающий дугу на круговой диаграмме, а затем использовать d3.arc для вычисления новых данных пути SVG.

Примечание: никакая защитная копия объекта шаблона не создаётся; изменения возвращённого объекта могут негативно повлиять на последующую оценку интерполятора. Копирование не выполняется по соображениям производительности; интерполяторы часто являются частью внутреннего цикла анимированных переходов.

d3.interpolateTransformCss(a, b) · Источник, Примеры

Возвращает интерполятор между двумя 2D CSS-преобразованиями, представленными a и b. Каждое преобразование разлагается на стандартное представление перемещения, поворота, наклона по оси x и масштабирования; затем эти составляющие преобразования интерполируются. Это поведение стандартизировано CSS: см. разложение матрицы для анимации.

d3.interpolateTransformSvg(a, b) · Источник, Примеры

Возвращает интерполятор между двумя 2D SVG-преобразованиями, представленными a и b. Каждое преобразование разлагается на стандартное представление перемещения, поворота, наклона по оси x и масштабирования; затем эти составляющие преобразования интерполируются. Это поведение стандартизировано CSS: см. разложение матрицы для анимации.

d3.interpolateZoom(a, b) · Источник, Примеры

Возвращает интерполятор между двумя представлениями a и b двумерной плоскости, основанный на “Гладкое и эффективное масштабирование и перемещение” Дж. ван Вейка и В. Нуйя. Каждое представление определяется как массив из трёх чисел: cx, cy и width. Первые две координаты cx, cy представляют центр области просмотра; последняя координата width — размер области просмотра.

Возвращаемый интерполятор имеет свойство duration, которое кодирует рекомендуемую продолжительность перехода в миллисекундах. Эта продолжительность основана на длине пути по кривой траектории в пространстве x,y. Если вам нужен более медленный или быстрый переход, умножьте это значение на произвольный масштабный множитель (V, как описано в исходной статье).

interpolateZoom.rho(rho) · Источник

При заданном интерполяторе масштабирования возвращает новый интерполятор масштабирования с указанной кривизной rho. Когда rho близка к 0, интерполятор почти линейный. По умолчанию кривизна равна sqrt(2).

d3.interpolateDiscrete(values) · Источник, Примеры

Возвращает дискретный интерполятор для заданного массива values. Возвращаемый интерполятор сопоставляет t в [0, 1 / n) с values[0], t в [1 / n, 2 / n) с values[1] и так далее, где n = values.length. По сути, это лёгкая шкала квантования с фиксированным областью определения [0, 1].

Выборка

d3.quantize(interpolator, n) · Источник, Примеры

Возвращает n равномерно распределённых выборок из указанного interpolator, где n — целое число, большее единицы. Первая выборка всегда находится при t = 0, а последняя — всегда при t = 1. Это может быть полезно при генерации фиксированного числа выборок из заданного интерполятора, например, для вывода области определения шкалы квантования от непрерывного интерполятора.

Предупреждение: этот метод не будет работать с интерполяторами, которые не возвращают защищённые копии своего результата, такие как d3.interpolateArray, d3.interpolateDate и d3.interpolateObject. Для этих интерполяторов вы должны обернуть интерполятор и создать копию для каждого возвращённого значения.

Цветовые пространства

d3.interpolateRgb(a, b) · Источник, Примеры

rgb

Или, с исправленным гаммой 2.2:

rgbGamma

Возвращает интерполятор цветового пространства RGB между двумя цветами a и b с настраиваемой гаммой. Если гамма не указана, она по умолчанию равна 1.0. Цвета a и b не обязательно должны быть в RGB; они будут преобразованы в RGB с помощью d3.rgb. Результатом работы интерполятора является строка RGB.

d3.interpolateRgbBasis(colors) · Источник, Примеры

Возвращает равномерный нерациональный интерполятор B-сплайна через указанный массив colors, которые преобразуются в RGB цветовое пространство. Неявные опорные точки генерируются таким образом, что интерполятор возвращает colors[0] при t = 0 и colors[colors.length - 1] при t = 1. Интерполяция непрозрачности в настоящее время не поддерживается. См. также d3.interpolateBasis, и см. d3-scale-chromatic для примеров.

d3.interpolateRgbBasisClosed(colors) · Источник, Примеры

Возвращает равномерный нерациональный интерполятор B-сплайна через указанный массив colors, которые преобразуются в RGB цветовое пространство. Опорные точки неявно повторяются, таким образом, полученный сплайн имеет циклическую C² непрерывность при повторении вокруг t в [0,1]; это полезно, например, для создания циклических цветовых шкалы. Интерполяция непрозрачности в настоящее время не поддерживается. См. также d3.interpolateBasisClosed, и см. d3-scale-chromatic для примеров.

d3.interpolateHsl(a, b) · Источник, Примеры

hsl

Возвращает интерполятор цветового пространства HSL между двумя цветами a и b. Цвета a и b не обязательно должны быть в HSL; они будут преобразованы в HSL с помощью d3.hsl. Если оттенок или насыщенность любого цвета равны NaN, используется соответствующее значение противоположного цвета. Используется кратчайший путь между оттенками. Возвращаемое значение интерполятора — строка RGB.

d3.interpolateHslLong(a, b) · Источник, Примеры

hslLong

Подобно interpolateHsl, но не использует кратчайший путь между оттенками.

d3.interpolateLab(a, b) · Источник, Примеры

lab

Возвращает интерполятор цветового пространства CIELAB между двумя цветами a и b. Цвета a и b не обязательно должны быть в CIELAB; они будут преобразованы в CIELAB с помощью d3.lab. Возвращаемое значение интерполятора — строка RGB.

d3.interpolateHcl(a, b) · Источник, Примеры

hcl

Возвращает интерполятор цветового пространства CIELCh_ab между двумя цветами a и b. Цвета a и b не обязательно должны быть в CIELCh_ab; они будут преобразованы в CIELCh_ab с помощью d3.hcl. Если оттенок или хроматичность любого цвета равны NaN, используется соответствующее значение противоположного цвета. Используется кратчайший путь между оттенками. Возвращаемое значение интерполятора — строка RGB.

d3.interpolateHclLong(a, b) · Источник, Примеры

hclLong

Подобно interpolateHcl, но не использует кратчайший путь между оттенками.

d3.interpolateCubehelix(a, b) · Источник, Примеры

cubehelix

Или, с гаммой 3.0, чтобы подчеркнуть значения высокой интенсивности:

cubehelixGamma

Возвращает интерполятор цветового пространства Cubehelix между двумя цветами a и b с настраиваемой гаммой. Если гамма не указана, она по умолчанию равна 1.0. Цвета a и b не обязательно должны быть в Cubehelix; они будут преобразованы в Cubehelix с помощью d3.cubehelix. Если значение оттенка или насыщенности любого цвета равно NaN, используется значение канала противоположного цвета. Используется кратчайший путь между оттенками. Возвращаемое значение интерполятора — строка RGB.

d3.interpolateCubehelixLong(a, b) · Источник, Примеры

cubehelixLong

Или, с гаммой 3.0, чтобы выделить значения высокой интенсивности:

cubehelixGammaLong

Как и interpolateCubehelix, но не использует кратчайший путь между оттенками.

interpolate.gamma(gamma)

Учитывая, что interpolate — это один из interpolateRgb, interpolateCubehelix или interpolateCubehelixLong, возвращает новый фабрикатор интерполятора того же типа с заданной гаммой. Например, чтобы интерполировать от фиолетового к оранжевому с гаммой 2.2 в цветовом пространстве RGB:

const interpolator = d3.interpolateRgb.gamma(2.2)("purple", "orange");

См. статью Эрика Брассера, Ошибка гаммы при масштабировании изображения, для получения дополнительной информации о коррекции гаммы.

d3.interpolateHue(a, b) · Источник, Примеры

Возвращает интерполятор между двумя углами оттенков a и b. Если какой-либо оттенок равен NaN, используется противоположное значение. Используется кратчайший путь между оттенками. Возвращаемое значение интерполятора — число в [0, 360).

Сплайны

В то время как стандартные интерполяторы смешивают значение от начального значения a при t = 0 до конечного значения b при t = 1, интерполяторы сплайнов плавно смешивают несколько входных значений для t в [0,1] с использованием кусковых полиномиальных функций. В настоящее время поддерживаются только кубические равномерные нерациональные B-сплайны, также известные как базисные сплайны.

d3.interpolateBasis(values) · Источник, Примеры

Возвращает равномерный нерациональный B-сплайн-интерполятор через указанный массив values, значения которого должны быть числами. Неявные узловые точки генерируются таким образом, что интерполятор возвращает values[0] при t = 0 и values[values.length - 1] при t = 1. См. также d3.curveBasis.

d3.interpolateBasisClosed(values) · Источник, Примеры

Возвращает равномерный нерациональный B-сплайн-интерполятор через указанный массив values, значения которого должны быть числами. Узловые точки неявно повторяются таким образом, что полученный одномерный сплайн имеет циклическую C² непрерывность при повторении вокруг t в [0,1]. См. также d3.curveBasisClosed.

Кусочно-линейные

d3.piecewise([interpolate, ]values) · Источник, Примеры

Возвращает кусочно-линейный интерполятор, комбинирующий интерполяторы для каждой смежной пары values. Возвращаемый интерполятор отображает t в [0, 1 / (n - 1)] на interpolate(values[0], values[1]), t в [1 / (n - 1), 2 / (n - 1)] на interpolate(values[1], values[2]) и так далее, где n = values.length. По сути, это лёгкая линейная шкала. Например, чтобы смешать красный, зелёный и синий цвета:

const interpolate = d3.piecewise(d3.interpolateRgb.gamma(2.2), ["red", "green", "blue"]);

Если interpolate не указан, используется по умолчанию d3.interpolate.