d3-tile

Квадродеревянные тайлы часто используются для представления большой многомасштабной геометрии и изображений, как, например, в «свайп-картах». d3.tile предоставляет удобный механизм для вычисления координат тайлов, которые должны быть видны в заданном области просмотра. В отличие от специализированных библиотек для свайп-карт, таких как Leaflet, крошечный низкоуровневый API d3.tile не зависит от способа отображения тайлов и предлагает большую гибкость. d3.tile хорошо работает с d3-geo для географических карт и d3-zoom для взаимодействия.

Примеры можно найти в коллекции d3-tile на Observable.

Установка

Если вы используете NPM, npm install d3-tile. В противном случае скачайте последнюю версию. Вы также можете загрузить её напрямую как самостоятельную библиотеку. Поддерживаются ES модули, AMD, CommonJS и среды Vanilla. В среде Vanilla экспортируется глобальная переменная d3.

<script src="https://cdn.jsdelivr.net/npm/d3-tile@1"></script>
<script>

const tile = d3.tile();
const tiles = tile({k: 256, x: 480, y: 250});

</script>

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

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

Создаёт новую схему тайлов с настройками по умолчанию.

const tile = d3.tile();

tile(…arguments) · Исходный код, Примеры

Вычисляет набор отображаемых тайлов, учитывая текущие настройки, вычисляя масштаб и смещение путём вызова соответствующих аксессоров с заданными arguments. Возвращает массив массивов [x, y, z], представляющих целочисленные координаты x (горизонтальная), y (вертикальная) и z (увеличение) любых тайлов, которые пересекают текущую область просмотра; это видимые тайлы. Возвращаемый массив тайлов также имеет свойства tiles.scale и tiles.translate, которые вместе с индивидуальными значениями x и y тайла определяют предполагаемое расположение тайла в области просмотра.

Например, следующая функция вычисляет пиксельные координаты верхнего левого угла заданного тайла в текущей области просмотра:

function position(tile, tiles) {
  const [x, y] = tile;
  const {translate: [tx, ty], scale: k} = tiles;
  return [(x + tx) * k, (y + ty) * k];
}

И в использовании:

const tile = d3.tile();
const tiles = tile({k: 256, x: 480, y: 250});
for (const t of tiles) {
  console.log(`tile ${t} is at ${position(t, tiles)}`);
}

Для получения дополнительной информации о координатах тайлов см. Zoomable Tiles.

tile.extent([extent]) · Исходный код

Если extent указан, устанавливает область просмотра этой схемы тайлов на указанный массив [[x0, y0], [x1, y1]], где [x0, y0] — верхний левый угол, а [x1, y1] — нижний правый угол, и возвращает эту схему тайлов. Если extent не указан, возвращает текущую область просмотра, которая по умолчанию равна [[0, 0], [960, 500]].

const tile = d3.tile().extent([[100, 200], [300, 400]]);

Установка области просмотра неявно устанавливает размер области просмотра.

tile.size([size]) · Исходный код

Если size указан, устанавливает размер области просмотра этой схемы тайлов на указанный массив чисел [width, height] и возвращает эту схему тайлов. Если size не указан, возвращает текущий размер области просмотра, который по умолчанию равен [960, 500].

const tile = d3.tile().size([200, 200]);

Это удобный метод для установки области просмотра viewport extent на [[0, 0], [width, height]].

tile.scale([scale]) · Исходный код

Если scale указан, устанавливает функцию масштаба этой схемы тайлов и возвращает эту схему тайлов. Если scale — функция, она вызывается при вызове схемы тайлов, получив те же аргументы, что и схема тайлов; эта функция должна вернуть число, указывающее желаемую ширину и высоту тайла мира [0, 0, 0].

const tile = d3.tile().scale(t => t.scale).translate(t => t.translate);
const tiles = tile({scale: 1024, translate: [100, 200]});

Если scale не является функцией, предполагается, что это константа, и она будет обернута в функцию.

const tile = d3.tile().scale(1024).translate([100, 200]);

Если scale не указан, возвращает текущую функцию масштабирования схемы, которая по умолчанию:

function scale(transform) {
  return transform.k;
}

Это значение по умолчанию совместимо с преобразованием d3-zoom.

tile.translate([translate]) · Исходный код

Если translate указан, устанавливает функцию смещения этой схемы тайлов и возвращает эту схему тайлов. Если translate — функция, она вызывается при вызове схемы тайлов, получив те же аргументы, что и схема тайлов; эта функция должна вернуть массив чисел [x, y], указывающих желаемые координаты центра тайла мира [0, 0, 0].

const tile = d3.tile().scale(t => t.scale).translate(t => t.translate);
const tiles = tile({scale: 1024, translate: [100, 200]});

Если translate не является функцией, предполагается, что это константный массив [x, y], и он будет обернут в функцию.

const tile = d3.tile().scale(1024).translate([100, 200]);

Если translate не указан, возвращает текущую функцию смещения схемы, которая по умолчанию:

function translate(transform) {
  return [transform.x, transform.y];
}

Это значение по умолчанию совместимо с преобразованием d3-zoom.

tile.clampX([clamp]) · Исходный код, Примеры

Если clamp указан, устанавливает, будут ли видимые тайлы ограничены в измерении x, и возвращает эту схему тайлов. Если clamp не указан, возвращает, включено ли ограничение по x, которое по умолчанию равно true. Если ограничение по x отключено, схема тайлов может возвращать тайлы, которые находятся за пределами обычных границ 0 ≤ x < 2^z «мирового» тайла [0, 0, 0].

const tile = d3.tile().clampX(false);

См. d3.tileWrap для преобразования этих координат в обернутые координаты мира, и Wrapped Tiles для примера.

tile.clampY([clamp]) · Исходный код

Если clamp указан, устанавливает, будут ли видимые тайлы ограничены в измерении y, и возвращает эту схему тайлов. Если clamp не указан, возвращает, включено ли ограничение по y, которое по умолчанию равно true. Если ограничение по y отключено, схема тайлов может возвращать тайлы, которые находятся за пределами обычных границ 0 ≤ y < 2^z «мирового» тайла [0, 0, 0].

const tile = d3.tile().clampY(false);

См. d3.tileWrap для преобразования этих координат в обернутые координаты мира, и Wrapped Tiles для примера. См. также tile.clampX.

tile.clamp([clamp]) · Исходный код

Если clamp указан, устанавливает tile.clampX и tile.clampY на указанное boolean значение clamp и возвращает эту схему тайлов. Если clamp не указан, возвращает true, если tile.clampX и tile.clampY оба равны true, и false в противном случае.

const tile = d3.tile().clamp(false);

tile.tileSize([tileSize]) · Исходный код, Примеры

Если tileSize указан, устанавливает ширину и высоту тайла этой схемы тайлов на указанное число tileSize и возвращает эту схему тайлов. Если tileSize не указан, возвращает текущий размер тайла схемы, который по умолчанию равен 256. 256 и 512 — наиболее распространённые размеры тайлов.

const tile = d3.tile().tileSize(512);

tile.zoomDelta([zoomDelta]) · Исходный код, Примеры

Если zoomDelta указан, устанавливает смещение масштабирования этой схемы тайлов на указанное число zoomDelta и возвращает эту схему тайлов. Если zoomDelta не указан, возвращает текущее смещение масштабирования, которое по умолчанию равно 0. Смещение масштабирования влияет на выбор координаты z, основываясь на текущем масштабе; значение смещения масштабирования по умолчанию 0 выберет z, ближайшее к отображаемому размеру; смещение масштабирования -1 использует z - 1, давая тайлы в два раза больше (более низкое разрешение); смещение масштабирования +1 использует z + 1, давая тайлы в два раза меньше (более высокое разрешение). Последнее может быть уместно для отображения тайлов 256×256 в пространстве 128×128 на экране с высоким разрешением.

const tile = d3.tile().zoomDelta(2);

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

Для заданных координат тайла tile [x, y, z], где x и y могут находиться вне «мирового» тайла [0, 0, 0], возвращает обернутые координаты тайла [x′, y′, z], где j = 2 ^ z, x′ = x - ⌊x / j⌋ * j и y′ = y - ⌊y / j⌋ * j. Эта функция чаще всего используется в сочетании с tile.clampX, чтобы разрешить горизонтальную обёртку веб-тайлов Меркатора.

d3.tileWrap([-1, 0, 1]) // [1, 0, 1]
d3.tileWrap([-1, 0, 2]) // [3, 0, 2]

См. Wrapped Tiles для примера.