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 и vanilla. В vanilla экспортируется глобальная переменная 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", два встроеные числа найдены. Остальные статические части (строки 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. Для каждого элемента в 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) Источник

Возвращает интерполятор между двумя 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, как описано в оригинальной статье).

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

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

d3.interpolateHcl(a, b) Source

Возвращает интерполятор цветового пространства HCL между двумя цветами a и b. Цвета a и b не обязательно должны быть в HCL; они будут преобразованы в HCL с помощью 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");

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

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"]);