d3-geo

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

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

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

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

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

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

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

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

Установка

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

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

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

</script>

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

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

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

Пути

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

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

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

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

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

Точка — одна позиция.
Многоточечный — массив позиций.
Линия — массив позиций, образующих непрерывную линию.
Многолинейная — массив массивов позиций, образующих несколько линий.
Полигон — массив массивов позиций, образующих полигон (возможно, с дырами).
Многоугольник — многомерный массив позиций, образующих несколько полигонов.
Коллекция геометрий — массив геометрических объектов.
Признак — признак, содержащий один из вышеперечисленных геометрических объектов.
Коллекция признаков — массив объектов признаков.

Также поддерживается тип Сфера, который полезен для отображения контура земного шара; у сферы нет координат. Любые дополнительные аргументы передаются в аксессор 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());

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

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

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

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

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

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

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

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

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

path.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 указан, устанавливает радиус, используемый для отображения геометрий Point и MultiPoint, на указанное число. Если radius не указан, возвращает текущую функцию доступа к радиусу, которая по умолчанию равна 4,5. Хотя радиус обычно задаётся как числовая константа, он также может быть задан как функция, вычисляемая для каждой записи, которому передаются любые аргументы, переданные генератору пути. Например, если ваши данные GeoJSON содержат дополнительные свойства, вы можете получить доступ к этим свойствам внутри функции radius, чтобы изменять размер точки; альтернативно, вы можете использовать d3.symbol и проекцию для большей гибкости.

Проекции

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

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

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

projection(point) Источник

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

projection.invert(point) Источник

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

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

projection.stream(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]. Смещение трансляции определяет пиксельные координаты центра проекции центра. По умолчанию смещение трансляции помещает ⟨0°,0°⟩ в центр области 960×500.

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

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

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

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

projection.reflectX([reflect])

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

projection.reflectY([reflect])

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

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

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

projection.precision([precision]) Source

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

projection.fitExtent(extent, object) Source

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

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

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

Любое ограничение обрезки игнорируется при определении нового масштаба и смещения. Точность 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, где высота автоматически выбирается из соотношения сторон объекта object и заданного ограничения по ширине.

projection.fitHeight(height, object) Source

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

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

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

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 от его истинной относительной площади. Эта диаграмма Филиппа Ривьера иллюстрирует, как эта проекция использует два прямоугольных вставки для Аляски и Гавайев:

См. Albers USA with Territories для расширения на все территории США и 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

Прямоугольная (плат-каре) проекция.

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. Они представлены здесь для облегчения вывода связанных проекций. Необработанные проекции принимают сферические координаты [лямбда, фи] в радианах (а не в градусах!) и возвращают точку [x, y], обычно в единичном квадрате, центрированном вокруг начала координат.

project(лямбда, фи)

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

project.invert(x, y)

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

d3.geoProjection(project) Источник

Создаёт новую проекцию из указанной необработанной проекции, 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) Источник

Создаёт новую проекцию из указанной необработанной проекции 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) Источник

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

d3.geoBounds(object) Источник

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

d3.geoCentroid(object) Источник

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

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

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

d3.geoLength(object) Источник

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

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

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

d3.geoContains(object, point) Источник

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

d3.geoRotation(angles) Источник

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

rotation(point) Источник

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

rotation.invert(point) Источник

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

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

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

d3.geoCircle() Источник

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

circle(arguments…) Источник

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

circle.center([center]) Источник

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

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

circle.radius([radius]) Источник

Если 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, избыточная закрывающая координата кольца не указывается с помощью точки, а вместо этого подразумевается с помощью 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, projection.angle, projection.reflectX и projection.reflectY.

Обрезка

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

preclip(stream)

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

См. projection.preclip.

postclip(stream)

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

См. projection.postclip.

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

d3.geoClipAntimeridian

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

d3.geoClipCircle(angle)

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

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

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