d3-interpolate

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

var 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:

var 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. В противном случае, загрузите последнюю версию. Вы также можете загрузить напрямую с d3js.org, как отдельную библиотеку или как часть D3. Поддерживаются AMD, CommonJS и стандартные браузерные среды.

В стандартной браузерной среде экспортируется глобальная переменная d3. (Если вы используете интерполяцию цветов, также загрузите d3-color.)

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

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

</script>

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

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

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

1. Если b равно null, undefined или булево, используйте константу b.
2. Если b – число, используйте interpolateNumber.
3. Если b – цвет или строка, преобразуемая в цвет, используйте interpolateRgb.
4. Если b – дата, используйте interpolateDate.
5. Если b – строка, используйте interpolateString.
6. Если b – массив с типом данных чисел, используйте interpolateNumberArray.
7. Если b – обычный массив, используйте interpolateArray.
8. Если b можно преобразовать в число, используйте interpolateNumber.
9. Используйте 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) · Source, Примеры

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

d3.interpolateTransformSvg(a, b) · Source, Примеры

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

d3.interpolateZoom(a, b) · Source, Примеры

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

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

interpolateZoom.rho(rho) · Source

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

d3.interpolateDiscrete(values) · Source, Примеры

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

Выборка

d3.quantize(interpolator, n) · Source, Примеры

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

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

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

d3.interpolateRgb(a, b) · Source, Примеры

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

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

d3.interpolateRgbBasis(colors) · Source, Примеры

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

d3.interpolateRgbBasisClosed(colors) · Source, Примеры

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

d3.interpolateHsl(a, b) · Source, Примеры

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

d3.interpolateHslLong(a, b) · Source, Примеры

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

d3.interpolateLab(a, b) · Source, Примеры

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

d3.interpolateHcl(a, b) · Source, Примеры

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

d3.interpolateHclLong(a, b) · Source, Примеры

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

d3.interpolateCubehelix(a, b) · Source, Примеры

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

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

d3.interpolateCubehelixLong(a, b) · Source, Примеры

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

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

interpolate.gamma(gamma)

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

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

См. статью Эрика Брассера Gamma error in picture scaling для получения дополнительной информации о коррекции гаммы.

d3.interpolateHue(a, b) · Source, Примеры

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

Сплайны

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

d3.interpolateBasis(values) · Source, Примеры

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

d3.interpolateBasisClosed(values) · Source, Примеры

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

Кусочные

d3.piecewise([interpolate, ]values) · Source, Примеры

Возвращает кусочный интерполятор, объединяющий интерполяторы для каждой смежной пары 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. По сути, это лёгкая линейная шкала. Например, чтобы смешать красный, зелёный и синий:

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

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