d3-geo

Картографические проекции иногда реализуются как преобразования точек. Например, проекция Меркатора:

function mercator(x, y) {
  return [x, Math.log(Math.tan(Math.PI / 4 + y / 2))];
}

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

Дискретная геометрия значительно усложняет задачу проекции сферы на плоскость. Стороны сферического многоугольника являются геодезическими линиями (отрезками больших окружностей), а не прямыми линиями. При проекции на плоскость геодезические линии представляют собой кривые во всех картографических проекциях, кроме гномонической, и, следовательно, для точной проекции требуется интерполяция по каждой дуге. D3 использует адаптивную выборку, вдохновлённую популярным методом упрощения линий, для баланса точности и производительности.

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

Сферические многоугольники также требуют конвенции о направлении обхода, чтобы определить, какая сторона многоугольника является внутренней: внешняя граница многоугольников, меньших полусферы, должна быть по часовой стрелке, а внешняя граница многоугольников, больших полусферы, должна быть против часовой стрелки. Внутренние области, представляющие отверстия, должны использовать обратное направление обхода по сравнению со своей внешней границей. Эта конвенция о направлении обхода также используется TopoJSON и ESRI shapefiles; однако, это обратная конвенция по сравнению с RFC 7946 GeoJSON. (Обратите также внимание, что стандартный GeoJSON WGS84 использует плоские прямоугольные координаты, а не сферические координаты, и, следовательно, может потребоваться склейка для удаления разрезов антимеридиана.)

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

D3 использует GeoJSON для представления географических объектов в JavaScript. (См. также TopoJSON, расширение GeoJSON, которое значительно компактнее и кодирует топологию). Для преобразования shapefiles в GeoJSON используйте shp2geo, часть пакета shapefile. См. Command-Line Cartography для введения в d3-geo и связанных инструментов.

Установка

Если вы используете NPM, npm install d3-geo. В противном случае, скачайте последнюю версию. Вы также можете загрузить его напрямую с d3js.org, либо как самостоятельную библиотеку, либо как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

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

var projection = d3.geoEqualEarth(),
    path = d3.geoPath(projection);

</script>

Попробуйте d3-geo в своём браузере.

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

Пути
Проекции (Азимутальные, Составные, Конические, Цилиндрические)
Необработанные проекции
Сферическая математика
Сферические фигуры
Потоки
Преобразования
Обрезка

Пути

Генератор геодезических путей d3.geoPath похож на генераторы фигур в d3-shape: при заданном объекте геометрии или элемента GeoJSON он генерирует строку данных пути SVG или отображает путь на Canvas. Canvas рекомендуется для динамических или интерактивных проекций, чтобы повысить производительность. Пути могут использоваться с проекциями или преобразованиями, или они могут использоваться для прямого отображения плоской геометрии на Canvas или SVG.

d3.geoPath([projection[, context]]) Источник

Создаёт новый генератор геодезических путей с настройками по умолчанию. Если задан projection, устанавливает текущую проекцию. Если задан context, устанавливает текущий контекст.

path(object[, arguments…]) Источник

Отображает заданный object, который может быть любым объектом геометрии или элемента GeoJSON:

Точка - одна позиция.
MultiPoint - массив позиций.
LineString - массив позиций, образующих непрерывную линию.
MultiLineString - массив массивов позиций, образующих несколько линий.
Polygon - массив массивов позиций, образующих многоугольник (возможно, с отверстиями).
MultiPolygon - многомерный массив позиций, образующих несколько многоугольников.
GeometryCollection - массив объектов геометрии.
Feature - элемент, содержащий один из вышеперечисленных объектов геометрии.
FeatureCollection - массив объектов элементов.

Также поддерживается тип Sphere, который полезен для отображения контура глобуса; у сферы нет координат. Любые дополнительные arguments передаются в обработчик pointRadius.

Для отображения нескольких элементов объедините их в коллекцию элементов:

svg.append("path")
    .datum({type: "FeatureCollection", features: features})
    .attr("d", d3.geoPath());

Или используйте несколько элементов пути:

svg.selectAll("path")
  .data(features)
  .enter().append("path")
    .attr("d", d3.geoPath());

Отдельные элементы пути, как правило, медленнее, чем один элемент пути. Однако отдельные элементы пути полезны для стилизации и взаимодействия (например, щелчок или наведение курсора). Отображение на Canvas (см. path.context) обычно быстрее, чем на SVG, но требует больше усилий для реализации стилизации и взаимодействия.

path.area(object) Источник

Возвращает вычисленную площадь (обычно в квадратных пикселях) для указанного объекта GeoJSON object. У точек, MultiPoint, LineString и MultiLineString геометрия площадь равна нулю. Для многоугольников и MultiPolygon геометрий, этот метод сначала вычисляет площадь внешней области, а затем вычитает площадь любых внутренних отверстий. Этот метод учитывает любую обрезку, выполненную проекцией; см. projection.clipAngle и projection.clipExtent. Это плоский аналог d3.geoArea.

path.bounds(object) Источник

Возвращает проекцию прямоугольника ограничивающей рамки (обычно в пикселях) для указанного объекта GeoJSON object. Прямоугольник ограничивающей рамки представлен двумерным массивом: [[x₀, y₀], [x₁, y₁]], где x₀ - минимальная координата x, y₀ - минимальная координата y, x₁ - максимальная координата x, а y₁ - максимальная координата y. Это полезно, например, для увеличения масштаба до определённого элемента. (Обратите внимание, что в проекции плоских координат минимальная широта обычно является максимальным значением y, а максимальная широта обычно является минимальным значением y.) Этот метод учитывает любую обрезку, выполненную проекцией; см. projection.clipAngle и projection.clipExtent. Это плоский аналог d3.geoBounds.

path.centroid(object) Источник

Возвращает проекцию центральной точки (обычно в пикселях) для заданного объекта GeoJSON object. Это полезно, например, при маркировке границ штатов или округов или при отображении карты символов. Например, несмежная карта может масштабировать каждый штат вокруг его центра. Этот метод учитывает любую обрезку, выполненную проекцией; см. projection.clipAngle и projection.clipExtent. Это плоский аналог d3.geoCentroid.

path.measure(object) Источник

Возвращает проекцию длины (обычно в пикселях) для заданного объекта GeoJSON object. У точек и MultiPoint геометрий длина равна нулю. Для многоугольников и MultiPolygon геометрий, этот метод вычисляет суммарную длину всех контуров. Этот метод учитывает любую обрезку, выполненную проекцией; см. projection.clipAngle и projection.clipExtent. Это плоский аналог d3.geoLength.

path.projection([projection]) Источник

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

END_OF_DOCUMENT_MARKER

Указанная проекция обычно является одной из встроенных проекций D3 географических проекций; однако, может использоваться любой объект, который экспонирует функцию проекция.stream, что позволяет использовать пользовательские проекции. См. преобразования D3 для получения дополнительных примеров произвольных геометрических преобразований.

path.context([context]) Исходный код

Если указан context, устанавливает текущий контекст отрисовки и возвращает генератор пути. Если context равен null, то генератор пути вернёт строку SVG пути; если контекст не null, генератор пути вместо этого вызовет методы указанного контекста для отрисовки геометрии. Контекст должен реализовывать следующий подмножество API CanvasRenderingContext2D:

context.beginPath()
context.moveTo(x, y)
context.lineTo(x, y)
context.arc(x, y, radius, startAngle, endAngle)
context.closePath()

Если context не указан, возвращает текущий контекст отрисовки, который по умолчанию равен null.

path.pointRadius([radius]) Исходный код

Если указан radius, устанавливает радиус, используемый для отображения геометрий Точка и Многоточек, на указанное число. Если radius не указан, возвращает текущую функцию доступа к радиусу, которая по умолчанию равна 4,5. Хотя радиус обычно задаётся как числовая константа, он также может быть задан как функция, вычисляемая для каждой сущности, которому передаются любые аргументы, переданные генератору пути. Например, если ваши данные GeoJSON содержат дополнительные свойства, вы можете получить доступ к этим свойствам внутри функции радиуса, чтобы изменять размер точки; альтернативно, вы можете использовать d3.symbol и проекцию для большей гибкости.

Проекции

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

Азимутальные
Составные
Конические
Цилиндрические

Для многих других проекций см. d3-geo-projection. Вы можете реализовать пользовательские проекции с помощью d3.geoProjection или d3.geoProjectionMutator.

projection(point) Исходный код

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

projection.invert(point) Исходный код

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

Этот метод определён только для обратимых проекций.

projection.stream(stream) Исходный код

Возвращает поток проекции для указанного выходного потока. Любая входная геометрия проектируется перед потоком в выходной поток. Типичная проекция включает в себя несколько геометрических преобразований: входная геометрия сначала преобразуется в радианы, поворачивается на трёх осях, обрезается до малого круга или разрезается вдоль антимеридиана, и, наконец, проектируется на плоскость с адаптивной ресемплинг, масштабом и смещением.

projection.preclip([preclip])

Если указан preclip, устанавливает сферическую обрезку проекции на указанную функцию и возвращает проекцию. Если preclip не указан, возвращает текущую функцию сферической обрезки (см. preclip).

projection.postclip([postclip])

Если указан postclip, устанавливает картизианскую обрезку проекции на указанную функцию и возвращает проекцию. Если postclip не указан, возвращает текущую функцию картизианской обрезки (см. postclip).

projection.clipAngle([angle]) Исходный код

Если указан angle, устанавливает радиус круга обрезки проекции на указанный угол в градусах и возвращает проекцию. Если angle равен null, переключается на разрез по антимеридиану, а не на обрезку малого круга. Если angle не указан, возвращает текущий угол обрезки, который по умолчанию равен null. Обрезка малого круга независима от обрезки области просмотра через projection.clipExtent.

См. также projection.preclip, d3.geoClipAntimeridian, d3.geoClipCircle.

projection.clipExtent([extent]) Исходный код

Если указан extent, устанавливает область обрезки области просмотра проекции на указанные границы в пикселях и возвращает проекцию. Границы extent задаются как массив [[x₀, y₀], [x₁, y₁]], где x₀ — левая сторона области просмотра, y₀ — верхняя, x₁ — правая и y₁ — нижняя. Если extent равен null, обрезка области просмотра не выполняется. Если extent не указан, возвращает текущую область обрезки области просмотра, которая по умолчанию равна null. Обрезка области просмотра независима от обрезки малого круга через projection.clipAngle.

См. также projection.postclip, d3.geoClipRectangle.

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

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

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

Если указан translate, устанавливает смещение трансляции проекции на указанный массив из двух элементов [t_x, t_y] и возвращает проекцию. Если translate не указан, возвращает текущее смещение трансляции, которое по умолчанию равно [480, 250]. Смещение трансляции определяет координаты пикселей центра проекции center. По умолчанию смещение трансляции помещает ⟨0°,0°⟩ в центр области 960×500.

projection.center([center]) Исходный код

Если указан center, устанавливает центр проекции на указанный center, массив из двух элементов долготы и широты в градусах, и возвращает проекцию. Если center не указан, возвращает текущий центр, который по умолчанию равен ⟨0°,0°⟩.

projection.angle([angle]) Исходный код

Если указан angle, устанавливает угол поворота проекции после проекции на плоскости на указанный angle в градусах и возвращает проекцию. Если angle не указан, возвращает текущий угол проекции, который по умолчанию равен 0°. Обратите внимание, что может быть быстрее вращать во время отрисовки (например, с помощью context.rotate), а не во время проекции.

projection.rotate([angles]) Исходный код

Если указан rotation, устанавливает трёхосевой сферический поворот проекции на указанные angles, которые должны быть массивом из двух или трёх элементов чисел [lambda, phi, gamma], задающих углы поворота в градусах относительно каждой сферической оси. (Эти соответствуют курсу, тангажу и рысканию.) Если угол поворота gamma опущен, он по умолчанию равен 0. См. также d3.geoRotation. Если rotation не указан, возвращает текущий поворот, который по умолчанию [0, 0, 0].

projection.precision([precision]) Исходный код

Если указан precision, устанавливает порог для адаптивной ресемплинг проекции на указанное значение в пикселях и возвращает проекцию. Это значение соответствует расстоянию Douglas–Peucker. Если precision не указан, возвращает текущую точность ресемплинг проекции, которая по умолчанию равна √0.5 ≅ 0.70710…

projection.fitExtent(extent, object) Source

Устанавливает масштаб (scale) и сдвиг (translate) проекции таким образом, чтобы заданный объект GeoJSON object был в центре заданного extent. Область extent задается как массив [[x₀, y₀], [x₁, y₁]], где x₀ — левая сторона области, y₀ — верхняя, x₁ — правая, а y₁ — нижняя. Возвращает проекцию.

Например, чтобы масштабировать и сдвинуть проекцию New Jersey State Plane для того, чтобы объект GeoJSON nj был в центре области 960×500 с отступом 20 пикселей с каждой стороны:

var projection = d3.geoTransverseMercator()
    .rotate([74 + 30 / 60, -38 - 50 / 60])
    .fitExtent([[20, 20], [940, 480]], nj);

Любая область обрезки (clip extent) игнорируется при определении нового масштаба и сдвига. Точность (precision), используемая для вычисления области object, вычисляется при эффективном масштабе 150.

projection.fitSize(size, object) Source

Удобный метод для projection.fitExtent, где верхний левый угол области — [0, 0]. Следующие два утверждения эквивалентны:

projection.fitExtent([[0, 0], [width, height]], object);
projection.fitSize([width, height], object);

projection.fitWidth(width, object) Source

Удобный метод для projection.fitSize, где высота автоматически выбирается из соотношения сторон объекта и заданного ограничения по ширине.

projection.fitHeight(height, object) Source

Удобный метод для projection.fitSize, где ширина автоматически выбирается из соотношения сторон объекта и заданного ограничения по высоте.

Азимутальные проекции

Азимутальные проекции отображают сферу непосредственно на плоскость.

d3.geoAzimuthalEqualArea() Source
d3.geoAzimuthalEqualAreaRaw

Азимутальная проекция с равными площадями.

d3.geoAzimuthalEquidistant() Source
d3.geoAzimuthalEquidistantRaw

Азимутальная равнорасстояная проекция.

d3.geoGnomonic() Source
d3.geoGnomonicRaw

Гномоническая проекция.

d3.geoOrthographic() Source
d3.geoOrthographicRaw

Ортографическая проекция.

d3.geoStereographic() Source
d3.geoStereographicRaw

Стереографическая проекция.

Равновеликая проекция

d3.geoEqualEarth() Source
d3.geoEqualEarthRaw

Проекция Equal Earth, разработанная Бояном Шавричем и др. в 2018 году.

Составные проекции

Составные проекции состоят из нескольких проекций, объединенных в единый дисплей. Составляющие проекции имеют фиксированные параметры обрезки, центра и поворота, поэтому составные проекции не поддерживают projection.center, projection.rotate, projection.clipAngle или projection.clipExtent.

d3.geoAlbersUsa() Source

Это составная проекция, ориентированная на США, состоящая из трёх проекций d3.geoConicEqualArea: d3.geoAlbers используется для сорока восьми штатов, а отдельные конические проекции с равными площадями используются для Аляски и Гавайев. Обратите внимание, что масштаб для Аляски уменьшен: он спроецирован с 0,35 кратным истинному относительному размеру. Эта диаграмма Филиппа Ривьера иллюстрирует, как эта проекция использует два прямоугольных вставки для Аляски и Гавайев:

Дополнительные примеры можно найти на странице d3-composite-projections.

Конические проекции

Конические проекции отображают сферу на конус, а затем развертывают конус на плоскость. Конические проекции имеют две стандартные параллели.

conic.parallels([parallels]) Source

Две стандартные параллели, определяющие структуру карты в конических проекциях.

d3.geoAlbers() Source

Коническая проекция Альберса с равными площадями. Это конфигурация, ориентированная на США, проекции d3.geoConicEqualArea.

d3.geoConicConformal() Source
d3.geoConicConformalRaw(phi0, phi1) Source

Коническая конформная проекция. Параллели по умолчанию установлены на [30°, 30°], что приводит к плоскому верху. См. также conic.parallels.

d3.geoConicEqualArea() Source
d3.geoConicEqualAreaRaw(phi0, phi1) Source

Коническая проекция Альберса с равными площадями. См. также conic.parallels.

d3.geoConicEquidistant() Source
d3.geoConicEquidistantRaw(phi0, phi1) Source

Коническая равнорасстояная проекция. См. также conic.parallels.

Цилиндрические проекции

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

d3.geoEquirectangular() Source
d3.geoEquirectangularRaw

Прямоугольная проекция (plate carrée).

d3.geoMercator() Source
d3.geoMercatorRaw

Сферическая проекция Меркатора. Определяет по умолчанию projection.clipExtent так, что мир отображается на квадрат, ограниченный примерно ±85° широтой.

d3.geoTransverseMercator() Source
d3.geoTransverseMercatorRaw

Поперечная сферическая проекция Меркатора. Определяет по умолчанию projection.clipExtent так, что мир отображается на квадрат, ограниченный примерно ±85° широтой.

d3.geoNaturalEarth1() Source
d3.geoNaturalEarth1Raw

Проекция Natural Earth — псевдоцилиндрическая проекция, разработанная Томом Паттерсоном. Она не конформна и не равновелика, но приятна для восприятия на небольших масштабах карт всего мира.

Необработанные проекции

Необработанные проекции — это функции точечного преобразования, используемые для реализации пользовательских проекций; обычно они передаются в d3.geoProjection или d3.geoProjectionMutator. Они представлены здесь для упрощения получения связанных проекций. Необработанные проекции принимают сферические координаты [lambda, phi] в радианах (а не в градусах!) и возвращают точку [x, y], обычно в единичном квадрате, центрированном вокруг начала координат.

project(lambda, phi)

Проецирует указанную точку [lambda, phi] в радианах, возвращая новую точку [x, y] в безразмерных координатах.

project.invert(x, y)

Обратная функция project.

d3.geoProjection(project) Source

Создаёт новую проекцию из заданной исходной проекции, project. Функция project принимает долготу и широту заданной точки в радианах, часто обозначаемых как лямбда (λ) и фи (φ), и возвращает двумерный массив [x, y], представляющий её единичную проекцию. Функция project не должна масштабировать или смещать точку, так как эти операции применяются автоматически функциями projection.scale, projection.translate и projection.center. Аналогично, функция project не должна выполнять сферическое вращение, так как projection.rotate применяется до проекции.

Например, сферическая проекция Меркатора может быть реализована так:

var mercator = d3.geoProjection(function(x, y) {
  return [x, Math.log(Math.tan(Math.PI / 4 + y / 2))];
});

Если функция project имеет метод invert, возвращаемая проекция также будет иметь метод projection.invert.

d3.geoProjectionMutator(factory) Source

Создаёт новую проекцию из заданного исходного объекта проекции factory и возвращает функцию mutate, которую нужно вызывать при изменении исходной проекции. Функция factory должна возвращать исходную проекцию. Возвращаемая функция mutate возвращает обернутую проекцию. Например, коническая проекция обычно имеет две конфигурируемые параллели. Соответствующая функция factory, например d3.geoConicEqualAreaRaw, будет иметь вид:

// y0 and y1 represent two parallels
function conicFactory(phi0, phi1) {
  return function conicRaw(lambda, phi) {
    return […, …];
  };
}

Используя d3.geoProjectionMutator, вы можете реализовать стандартную проекцию, которая позволяет изменять параллели, повторно назначая исходную проекцию, используемую внутри d3.geoProjection:

function conicCustom() {
  var phi0 = 29.5,
      phi1 = 45.5,
      mutate = d3.geoProjectionMutator(conicFactory),
      projection = mutate(phi0, phi1);

  projection.parallels = function(_) {
    return arguments.length ? mutate(phi0 = +_[0], phi1 = +_[1]) : [phi0, phi1];
  };

  return projection;
}

При создании изменяемой проекции функция mutate обычно не экспортируется.

Сферическая математика

d3.geoArea(object) Source

Возвращает сферическую площадь заданного GeoJSON объекта в стерадианах. Это сферический аналог path.area.

d3.geoBounds(object) Source

Возвращает сферическую ограничивающую рамку для заданного GeoJSON объекта. Ограничивающая рамка представляется двумерным массивом: [[left, bottom], [right, top]], где left — минимальная долгота, bottom — минимальная широта, right — максимальная долгота, а top — максимальная широта. Все координаты заданы в градусах. (Обратите внимание, что в проекционных плоских координатах минимальная широта обычно является максимальным значением y, а максимальная широта — минимальным значением y.) Это сферический аналог path.bounds.

d3.geoCentroid(object) Source

Возвращает сферический центр масс заданного GeoJSON объекта. Это сферический аналог path.centroid.

d3.geoDistance(a, b) Source

Возвращает расстояние по большой окружности в радианах между двумя точками a и b. Каждая точка должна быть задана как двумерный массив [долгота, широта] в градусах. Это сферический аналог path.measure для LineString из двух точек.

d3.geoLength(object) Source

Возвращает длину по большой окружности заданного GeoJSON объекта в радианах. Для многоугольников возвращает периметр внешней линии плюс периметры всех внутренних линий. Это сферический аналог path.measure.

d3.geoInterpolate(a, b) Source

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

d3.geoContains(object, point) Source

Возвращает true, только если заданный GeoJSON объект содержит заданную точку, или false, если объект не содержит точку. Точка должна быть задана как двумерный массив [долгота, широта] в градусах. Для геометрий Point и MultiPoint используется точный тест; для Sphere всегда возвращается true; для других геометрий применяется порог погрешности.

d3.geoRotation(angles) Source

Возвращает функцию вращения для заданных angles, которые должны быть дву- или трёхэлементным массивом чисел [лямбда, фи, гамма], задающих углы вращения в градусах вокруг каждой сферической оси. (Эти значения соответствуют курсу, тангажу и рысканию.) Если угол вращения гамма опущен, он по умолчанию равен 0. Также см. projection.rotate.

rotation(point) Source

Возвращает новый массив [долгота, широта] в градусах, представляющий повернутую точку заданной point. Точка должна быть задана как двумерный массив [долгота, широта] в градусах.

rotation.invert(point) Source

Возвращает новый массив [долгота, широта] в градусах, представляющий точку заданной повернутой point; обратная функция rotation. Точка должна быть задана как двумерный массив [долгота, широта] в градусах.

Сферические фигуры

Для генерации дуги большой окружности (отрезка большой окружности) просто передайте объект GeoJSON LineString функции d3.geoPath. Проекции D3 используют интерполяцию по большой окружности для промежуточных точек, поэтому генератор фигур большой окружности не нужен.

d3.geoCircle() Source

Возвращает новый генератор окружности.

circle(arguments…) Source

Возвращает новый GeoJSON геометрический объект типа «Многоугольник», приближающий окружность на поверхности сферы с текущим центром, радиусом и точностью. Любые arguments передаются в аксессоры.

circle.center([center]) Source

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

function center() {
  return [0, 0];
}

circle.radius([radius]) Source

Если radius задан, устанавливает радиус окружности в заданный угол в градусах и возвращает этот генератор окружности. Радиус также может быть задан как функция; эта функция будет вызываться всякий раз, когда окружность генерируется, получая любые аргументы, переданные генератору окружности. Если radius не задан, возвращает текущий аксессор радиуса, по умолчанию:

function radius() {
  return 90;
}

circle.precision([angle]) Source

Если precision задан, устанавливает точность окружности в заданный угол в градусах и возвращает этот генератор окружности. Точность также может быть задана как функция; эта функция будет вызываться всякий раз, когда окружность генерируется, получая любые аргументы, переданные генератору окружности. Если precision не задан, возвращает текущий аксессор точности, по умолчанию:

function precision() {
  return 6;
}

Маленькие окружности не следуют дугам большой окружности, и поэтому сгенерированный многоугольник является лишь приближением. Установка меньшего угла точности улучшает точность приближённого многоугольника, но также увеличивает стоимость его генерации и отображения.

d3.geoGraticule() Source

Создаёт генератор геометрии для создания меридианов и параллелей для отображения искажений проекции. По умолчанию меридианы и параллели располагаются через каждые 10° между ±80° широты; для полярных регионов — через каждые 90°.

graticule() Source

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

graticule.lines() Source

Возвращает массив геообъектов GeoJSON типа LineString, по одному для каждого меридиана или параллели данной сетки.

graticule.outline() Source

Возвращает геообъект GeoJSON типа Polygon, представляющий контур данной сетки, т.е. по меридианам и параллелям, определяющим её границы.

graticule.extent([extent]) Source

Если extent указан, задаёт основные и второстепенные границы этой сетки. Если extent не указан, возвращает текущие второстепенные границы, которые по умолчанию равны ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.

graticule.extentMajor([extent]) Source

Если extent указан, задаёт основные границы этой сетки. Если extent не указан, возвращает текущие основные границы, которые по умолчанию равны ⟨⟨-180°, -90° + ε⟩, ⟨180°, 90° - ε⟩⟩.

graticule.extentMinor([extent]) Source

Если extent указан, задаёт второстепенные границы этой сетки. Если extent не указан, возвращает текущие второстепенные границы, которые по умолчанию равны ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.

graticule.step([step]) Source

Если step указан, задаёт основные и второстепенные шаги для данной сетки. Если step не указан, возвращает текущий второстепенный шаг, который по умолчанию равен ⟨10°, 10°⟩.

graticule.stepMajor([step]) Source

Если step указан, задаёт основной шаг для данной сетки. Если step не указан, возвращает текущий основной шаг, который по умолчанию равен ⟨90°, 360°⟩.

graticule.stepMinor([step]) Source

Если step указан, задаёт второстепенный шаг для данной сетки. Если step не указан, возвращает текущий второстепенный шаг, который по умолчанию равен ⟨10°, 10°⟩.

graticule.precision([angle]) Source

Если precision указан, задаёт точность для данной сетки в градусах. Если precision не указан, возвращает текущую точность, которая по умолчанию равна 2,5°.

d3.geoGraticule10() Source

Удобный метод для непосредственного создания стандартной глобальной сетки 10° в виде геообъекта GeoJSON типа MultiLineString. Эквивалентно:

function geoGraticule10() {
  return d3.geoGraticule()();
}

Потоки

D3 преобразует геометрию, используя последовательность вызовов функций, а не материализацию промежуточных представлений, чтобы свести к минимуму накладные расходы. Потоки должны реализовывать несколько методов для получения входной геометрии. Потоки по своей природе состоят из состояний; значение точки зависит от того, находится ли точка внутри линии, и аналогично линия отличается от кольца многоугольника. Несмотря на название «поток», эти вызовы методов в настоящее время являются синхронными.

d3.geoStream(object, stream) Source

Потоковое отображение указанного GeoJSON object в указанный поток проекции stream. Хотя как объекты свойств, так и геообъекты поддерживаются в качестве входных данных, интерфейс потока описывает только геометрию, и поэтому дополнительные свойства объекта не видны потокам.

stream.point(x, y[, z])

Указывает точку с указанными координатами x и y (и необязательно z). Система координат не определена и зависит от реализации; например, потоки проекций требуют сферических координат в градусах в качестве входных данных. Вне контекста многоугольника или линии точка указывает на геометрический объект типа точка (Точка или Многоточие). Внутри линии или кольца многоугольника точка указывает на управляющую точку.

stream.lineStart()

Указывает начало линии или кольца. Внутри многоугольника указывает начало кольца. Первое кольцо многоугольника является внешним кольцом и обычно задаётся по часовой стрелке. Любые последующие кольца указывают на отверстия в многоугольнике и обычно задаются против часовой стрелки.

stream.lineEnd()

Указывает конец линии или кольца. Внутри многоугольника указывает конец кольца. В отличие от GeoJSON, избыточная координата закрытия кольца не указывается с помощью point, а вместо этого подразумевается с помощью lineEnd внутри многоугольника. Таким образом, заданный входной многоугольник:

{
  "type": "Polygon",
  "coordinates": [
    [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
  ]
}

Выведет следующую серию вызовов метода в потоке:

stream.polygonStart();
stream.lineStart();
stream.point(0, 0);
stream.point(0, 1);
stream.point(1, 1);
stream.point(1, 0);
stream.lineEnd();
stream.polygonEnd();

stream.polygonStart()

Указывает начало многоугольника. Первая линия многоугольника указывает на внешнее кольцо, а любые последующие линии указывают на внутренние отверстия.

stream.polygonEnd()

Указывает конец многоугольника.

stream.sphere()

Указывает сферу (глобус; единичную сферу, центр которой находится в ⟨0,0,0⟩).

Преобразования

Преобразования — это обобщение проекций. Преобразования реализуют projection.stream и могут быть переданы в path.projection. Однако они реализуют только подмножество других методов проекции и представляют собой произвольные геометрические преобразования, а не проекции со сферических на плоские координаты.

d3.geoTransform(methods) Source

Определяет произвольное преобразование с использованием методов, определённых в указанном объекте methods. Любые неопределённые методы будут использовать методы проброса, которые передают входные данные в выходной поток. Например, чтобы отразить размер y (см. также identity.reflectY):

var reflectY = d3.geoTransform({
  point: function(x, y) {
    this.stream.point(x, -y);
  }
});

Или чтобы определить преобразование аффинной матрицы:

function matrix(a, b, c, d, tx, ty) {
  return d3.geoTransform({
    point: function(x, y) {
      this.stream.point(a * x + b * y + tx, c * x + d * y + ty);
    }
  });
}

d3.geoIdentity() Source

Преобразование тождества может быть использовано для масштабирования, перемещения и обрезки плоской геометрии. Оно реализует projection.scale, projection.translate, projection.fitExtent, projection.fitSize, projection.fitWidth, projection.fitHeight и projection.clipExtent.

identity.reflectX([reflect])

Если reflect указан, задаёт, отражается ли размер x (отрицается) в выходе. Если reflect не указан, возвращает true, если включено отражение по x, которое по умолчанию равно false.

identity.reflectY([reflect])

Если reflect указан, задаёт, отражается ли размер y (отрицается) в выходе. Если reflect не указан, возвращает true, если включено отражение по y, которое по умолчанию равно false. Это особенно полезно для преобразования из стандартных систем пространственной привязки, где положительное y указывает вверх, в системы отображения координат, такие как Canvas и SVG, где положительное y указывает вниз.

Обрезка

Проекции выполняют обрезку геометрий в двух этапах.

preclip(stream)

Предварительная обрезка происходит в географических координатах. Наиболее распространёнными стратегиями являются обрезка по линии антимеридиана или по малой окружности.

См. projection.preclip.

postclip(stream)

Последующая обрезка происходит на плоскости, когда проекция ограничена определёнными границами, такими как прямоугольник.

См. projection.postclip.

Функции обрезки реализуются как преобразования потока проекции. Предварительная обрезка работает со сферическими координатами в радианах. Последующая обрезка работает с плоскими координатами в пикселях.

d3.geoClipAntimeridian

Функция обрезки, которая преобразует поток таким образом, что геометрии (линии или многоугольники), пересекающие линию антимеридиана, разрезаются пополам, по одной стороне каждой. Обычно используется для предварительной обрезки.

d3.geoClipCircle(angle)

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

d3.geoClipRectangle(x0, y0, x1, y1)

Генерирует функцию обрезки, которая преобразует поток таким образом, что геометрии ограничены прямоугольником с координатами [[x0, y0], [x1, y1]]. Обычно используется для последующей обрезки.