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 используйте shp2json, часть пакета shapefile. См. Command-Line Cartography для знакомства с d3-geo и связанными инструментами.

Установка

Если вы используете npm, npm install d3-geo. Вы также можете загрузить последнюю версию на GitHub. Для обычного HTML в современных браузерах импортируйте d3-geo с jsDelivr:

<script type="module">

import {geoEqualEarth, geoPath} from "https://cdn.jsdelivr.net/npm/d3-geo@3/+esm";

const projection = geoEqualEarth();
const path = geoPath(projection);

</script>

Для устаревших сред вы можете загрузить UMD-пакет d3-geo с CDN, основанной на npm, такой как jsDelivr; экспортируется глобальная переменная d3:

<script src="https://cdn.jsdelivr.net/npm/d3-array@3"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-geo@3"></script>
<script>

const projection = d3.geoEqualEarth();
const path = d3.geoPath(projection);

</script>

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

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

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

Пути

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

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

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

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

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

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

Также поддерживается тип Sphere, который полезен для отрисовки контура глобуса; у сферы нет координат. Любые дополнительные arguments передаются в accessor 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 object. У точек, многоточий, линий и многолиний площадь равна нулю. Для многоугольников и многоугольников этот метод сначала вычисляет площадь внешней цепочки, а затем вычитает площадь любых внутренних отверстий. Этот метод учитывает любые операции обрезки, выполняемые проекцией; см. 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.digits([digits]) Источник

Если указано digits (как число, большее или равное нулю), устанавливает количество дробных знаков для координат, сгенерированных в строках SVG-путей. Если projection не указана, возвращает текущее число знаков, которое по умолчанию равно 3.

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

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

END_OF_DOCUMENT_MARKER

path.projection([projection]) Source

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

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

path.context([context]) Source

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

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

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

path.pointRadius([radius]) Source

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

Проекции

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

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

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

projection(point) Source

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

projection.invert(point) Source

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

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

projection.stream(stream) Source

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

projection.preclip([preclip])

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

projection.postclip([postclip])

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

projection.clipAngle([angle]) Source

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

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

projection.clipExtent([extent]) Source

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

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

projection.scale([scale]) Source

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

projection.translate([translate]) Source

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

projection.center([center]) Source

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

projection.angle([angle]) Source

Если указан 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]) Источник

Если указано 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) Источник

Устанавливает масштаб и сдвиг проекции так, чтобы заданный GeoJSON object оказался в центре заданного 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);

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

projection.fitSize(size, object) Источник

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

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

projection.fitWidth(width, object) Источник

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

projection.fitHeight(height, object) Источник

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. Albers USA с территориями для расширения на все территории США, и d3-composite-projections для получения дополнительных примеров.

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

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

conic.parallels([parallels]) Источник

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

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

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

d3.geoConicConformal() Источник
d3.geoConicConformalRaw(phi0, phi1) Источник

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

d3.geoConicEqualArea() Источник
d3.geoConicEqualAreaRaw(phi0, phi1) Источник

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

d3.geoConicEquidistant() Источник
d3.geoConicEquidistantRaw(phi0, phi1) Источник

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

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

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

END_OF_DOCUMENT_MARKER

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

project(lambda, phi)

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

project.invert(x, y)

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

d3.geoProjection(project) Source

Создает новую проекцию из указанной необработанной проекции, project. Функция project принимает долготу и широту заданной точки в радианах, часто обозначаемые как lambda (λ) и phi (φ), и возвращает массив из двух элементов [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 object в стерадианах. Это сферический эквивалент path.area.

d3.geoBounds(object) Source

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

d3.geoCentroid(object) Source

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

d3.geoDistance(a, b) Source

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

d3.geoLength(object) Source

Возвращает длину большой дуги указанного GeoJSON object в радианах. Для многоугольников возвращает периметр внешней линии плюс периметры внутренних линий. Это сферический эквивалент 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 object содержит указанную point, или false, если object не содержит point. Точка должна быть задана как массив из двух элементов [долгота, широта] в градусах. Для геометрий Point и MultiPoint используется точный тест; для сферы всегда возвращается true; для других геометрий применяется пороговое значение.

d3.geoRotation(angles) Source

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

rotation(point) Source

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

rotation.invert(point) Source

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

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

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

END_OF_DOCUMENT_MARKER

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 объекта в указанный поток проекции. Хотя в качестве входных данных поддерживаются как функции, так и геометрические объекты, интерфейс потока описывает только геометрию, и поэтому дополнительные свойства функций недоступны для потоков.

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() Источник

Обрезка

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

preclip(поток)

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

См. проекция.preclip.

postclip(поток)

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

См. проекция.postclip.

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

d3.geoClipAntimeridian

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

d3.geoClipCircle(угол)

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

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

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

d3-geo

Установка

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

Пути

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

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

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

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

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

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

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

path.projection([projection]) Source

path.context([context]) Source

path.pointRadius([radius]) Source

Проекции

projection(point) Source

projection.invert(point) Source

projection.stream(stream) Source

projection.preclip([preclip])

projection.postclip([postclip])

projection.clipAngle([angle]) Source

projection.clipExtent([extent]) Source

projection.scale([scale]) Source

projection.translate([translate]) Source

projection.center([center]) Source

projection.angle([angle]) Source

projection.reflectX([reflect])

projection.reflectY([reflect])

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

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

projection.fitExtent(extent, object) Источник

projection.fitSize(size, object) Источник

projection.fitWidth(width, object) Источник

projection.fitHeight(height, object) Источник

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

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

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

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

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

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

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

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

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

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

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

conic.parallels([parallels]) Источник

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

d3.geoConicConformal() Источник d3.geoConicConformalRaw(phi0, phi1) Источник

d3.geoConicEqualArea() Источник d3.geoConicEqualAreaRaw(phi0, phi1) Источник

d3.geoConicEquidistant() Источник d3.geoConicEquidistantRaw(phi0, phi1) Источник

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

d3.geoEquirectangular() Source d3.geoEquirectangularRaw

d3.geoMercator() Source d3.geoMercatorRaw

d3.geoTransverseMercator() Source d3.geoTransverseMercatorRaw

d3.geoNaturalEarth1() Source d3.geoNaturalEarth1Raw

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

project(lambda, phi)

project.invert(x, y)

d3.geoProjection(project) Source

d3.geoProjectionMutator(factory) Source

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

d3.geoArea(object) Source

d3.geoBounds(object) Source

d3.geoCentroid(object) Source

d3.geoDistance(a, b) Source

d3.geoLength(object) Source

d3.geoInterpolate(a, b) Source

d3.geoContains(object, point) Source

d3.geoRotation(angles) Source

rotation(point) Source

rotation.invert(point) Source

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

d3.geoCircle() Source

circle(arguments…) Source

circle.center([center]) Source

circle.radius([radius]) Source

circle.precision([angle]) Source

d3.geoGraticule() Source

graticule() Source

graticule.lines() Source

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

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

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

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

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

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

d3.geoConicConformal() Источник
d3.geoConicConformalRaw(phi0, phi1) Источник

d3.geoConicEqualArea() Источник
d3.geoConicEqualAreaRaw(phi0, phi1) Источник

d3.geoConicEquidistant() Источник
d3.geoConicEquidistantRaw(phi0, phi1) Источник

d3.geoEquirectangular() Source
d3.geoEquirectangularRaw

d3.geoMercator() Source
d3.geoMercatorRaw

d3.geoTransverseMercator() Source
d3.geoTransverseMercatorRaw

d3.geoNaturalEarth1() Source
d3.geoNaturalEarth1Raw