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 4.0. Поддерживаются AMD, CommonJS и обычные среды. В обычных средах экспортируется глобальная переменная d3:

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

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

</script>

Попробуйте d3-interpolate в вашем браузере.

Справочник API

d3.interpolate(a, b)

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

1. Если b равно null, undefined или boolean, используется константа b.
2. Если b — число, используется interpolateNumber.
3. Если b — цвет или строка, преобразуемая в цвет, используется interpolateRgb.
4. Если b — дата, используется interpolateDate.
5. Если b — строка, используется interpolateString.
6. Если b — массив, используется interpolateArray.
7. Если b преобразуется в число, используется interpolateNumber.
8. Используется 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", два вложенных числа находятся. Остальные статические части строки — пробел между двумя числами (" ") и суффикс ("px Comic-Sans"). Результат интерполятора при t = 0.5 равен "400 24px Comic-Sans".

d3.interpolateDate(a, b) Исходный код

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

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

d3.interpolateArray(a, b) Исходный код

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

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

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

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.svg.arc для вычисления новых данных SVG-путей.

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

d3.interpolateTransformCss(a, b) Исходный код

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

d3.interpolateTransformSvg(a, b) Исходный код

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

d3.interpolateZoom(a, b) Исходный код

Возвращает интерполятор между двумя представлениями двумерной плоскости a и b, основанный на статье «Smooth and efficient zooming and panning» Ярке Дж. ван Вайка и Вима А.А. Нуйя. Каждое представление определяется как массив из трёх чисел: cx, cy и width. Первые две координаты cx, cy представляют центр окна просмотра; последняя координата width представляет размер окна просмотра.

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

Выборка

d3.quantize(interpolator, n) Исходный код

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

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

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

d3.interpolateRgb(a, b) Источник

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

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

d3.interpolateHslLong(a, b) Исходный код

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

d3.interpolateLab(a, b) Исходный код

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

d3.interpolateHcl(a, b) Исходный код

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

d3.interpolateHclLong(a, b) Источник

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

d3.interpolateCubehelix(a, b) Источник

Или, с гаммой 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, возвращает новый фабрику интерполятора того же типа, использующего указанное значение gamma. Например, чтобы интерполировать от фиолетового к оранжевому с гамма-значением 2,2 в пространстве RGB:

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

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

Сплайны

В то время как стандартные интерполяторы смешивают значение 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.