Географические пути

Справочник API ▸ Geo ▸ Географические пути

Для картографических визуализаций D3 поддерживает несколько компонентов для отображения и управления географическими данными. Эти компоненты используют формат GeoJSON — стандартный способ представления географических объектов в JavaScript. (См. также формат TopoJSON, расширение GeoJSON, которое значительно более компактно.) Для преобразования шейп-файлов в GeoJSON используйте ogr2ogr, часть пакета GDAL.

Некоторые другие инструменты, которые могут вас заинтересовать:

• TopoJSON — упрощение шейп-файлов, построение топологии и сжатие GeoJSON.
• Shapely — манипулирование плоскими геометрическими объектами.
• ColorBrewer — шкалы цветов для карт.
• PostGIS — геопространственная база данных.

Основной механизм для отображения географических данных — d3.geo.path. Этот класс похож на d3.svg.line и другие генераторы SVG-форм: на основе объекта геометрии или объекта элемента он генерирует строку данных пути, подходящую для атрибута «d» элемента SVG path. Класс d3.geo.path может определять отрисовку непосредственно в Canvas, что может обеспечить лучшую производительность при анимации проекции.

d3.geo.path()

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

path(feature[, index])

Возвращает строку данных пути для данного feature, который может быть любым объектом GeoJSON-функции или геометрии:

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

Также поддерживается тип «Сфера», который полезен для отображения контура глобуса. У сферы нет координат. Можно указать необязательный index, который передаётся в аксессор pointRadius; index передаётся автоматически, когда генератор пути вызывается с помощью selection.attr.

Важно: внутренняя часть многоугольника — все точки, вокруг которых многоугольник обходит по часовой стрелке. Если ваш входной GeoJSON содержит многоугольники в неправильном порядке обхода, вам необходимо их перевернуть, например, с помощью ST_ForceRHR; вы также можете преобразовать свой GeoJSON в TopoJSON, и это произойдёт автоматически.

Для отображения нескольких элементов вы можете поместить их в один набор элементов и один элемент пути:

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

В качестве альтернативы, вы можете создать несколько отдельных элементов пути:

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

Использование отдельных элементов пути обычно медленнее, чем один элемент пути для набора. Однако отдельные элементы пути предпочтительнее, если вы хотите взаимодействовать с элементами отдельно (например, используя события CSS :hover или клик).

path.projection([projection])

Если projection указан, задаёт проекцию, используемую генератором пути, на заданную функцию проекции. Если projection не указан, возвращает текущую проекцию, которая по умолчанию равна albersUsa. Проекция обычно является одной из встроенных географических проекций D3; однако можно использовать любую функцию. Функция проекции принимает массив из двух элементов чисел, представляющих координаты местоположения, [долгота, широта], и возвращает аналогичный массив из двух элементов чисел, представляющих спроецированную позицию пикселя [x, y]. Например, примитивная сферическая проекция Меркатора:

function mercator(coordinates) {
  return [
    coordinates[0] / 360,
    (-180 / Math.PI * Math.log(Math.tan(Math.PI / 4 + coordinates[1] * Math.PI / 360))) / 360
  ];
}

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

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

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

path.context([context])

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

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

Обратите внимание, что это подмножество 2D-контекста отрисовки элемента canvas 2D контекста отрисовки элемента canvas, и поэтому контекст canvas можно передать генератору пути, в этом случае геометрия будет отрисовываться непосредственно в canvas. Если context не указан, возвращает текущий контекст отрисовки, который по умолчанию равен null.

path.area(feature)

Вычисляет спроецированную площадь (в квадратных пикселях) для указанного feature. У объектов типа Point, MultiPoint, LineString и MultiLineString площадь равна нулю. Для объектов типа Polygon и MultiPolygon этот метод сначала вычисляет площадь внешнего кольца, а затем вычитает площадь внутренних отверстий. Этот метод учитывает любые операции обрезки и ресемплации, выполняемые потоком проекции.

path.centroid(feature)

Вычисляет спроецированный центр масс (в пикселях) для указанного feature. Это полезно для, например, маркировки границ штатов или округов или отображения карты символов. Пример несмежных картограмм масштабирует каждый штат вокруг своего центра масс. Этот метод учитывает любые операции обрезки и ресемплации, выполняемые потоком проекции.

path.bounds(feature)

Вычисляет спроецированную область ограничительной рамки (в пикселях) для указанного feature. Границы ограничительной рамки представлены двумерным массивом: [[слева, сверху], [справа, снизу]], что отличается от соглашения о геоданных geo.bounds. Это полезно, например, для масштабирования в определённый элемент. Этот метод учитывает любые операции обрезки и ресемплации, выполняемые потоком проекции.

path.pointRadius([radius])

Если radius указан, устанавливает радиус для отображения объектов Point и MultiPoint на указанное число. Если radius не указан, возвращает текущий радиус. Хотя радиус обычно указывается как константа, он также может быть указан как функция, вычисляемая для каждого элемента, которому передаются аргументы feature и index из функции path. Например, если ваши данные GeoJSON имеют дополнительные свойства, вы можете обратиться к этим свойствам внутри функции radius, чтобы изменить размер точки; в качестве альтернативы, вы могли бы использовать d3.svg.symbol и проекцию для более точного управления отображением.

Генераторы форм

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

d3.geo.graticule

Строит генератор элементов для создания меридианов.

graticule()

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

graticule.lines()

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

graticule.outline()

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

graticule.extent(extent)

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

graticule.majorExtent(extent)

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

graticule.minorExtent(extent)

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

graticule.step(step)

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

graticule.majorStep(step)

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

graticule.minorStep(step)

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

graticule.precision(precision)

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

d3.geo.circle

Создает генератор объектов для создания окружностей, центрированных в заданной географической точке с заданным радиусом в градусах.

circle(arguments…)

Возвращает многоугольник GeoJSON, приближающий окружность. Функция-аксессор origin определяет, как определить начало для заданных arguments; по умолчанию используется константа ⟨0°,0°⟩.

circle.origin([origin])

Если задано значение origin, устанавливает начало окружности. Должен быть задан массив координат из двух элементов или функция-аксессор. Если origin не задано, возвращает текущее начало, которое по умолчанию равно ⟨0°,0°⟩.

circle.angle([angle])

Если задано значение angle, устанавливает угловой радиус окружности в градусах. Если angle не задано, возвращает текущий радиус, который по умолчанию составляет 90°.

circle.precision([precision])

Если задано значение precision, устанавливает точность интерполированных сегментов окружности в градусах. Эти интерполированные сегменты вставляются, когда объект усекается окружностью. Если precision не задано, возвращает текущую точность, которая по умолчанию составляет 6°.

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

d3.geo.area(feature)

Возвращает сферическую площадь указанного feature в стерадианах. См. также path.area, который вычисляет проецируемую площадь на декартовой плоскости.

d3.geo.centroid(feature)

Возвращает сферический центр тяжести указанного feature. См. также path.centroid, который вычисляет проецируемый центр тяжести на декартовой плоскости.

d3.geo.bounds(feature)

Возвращает сферическую ограничивающую прямоугольную область для указанного feature. Ограничивающая прямоугольная область представляется двумерным массивом: [​[left, bottom], [right, top]​], где left — минимальная долгота, bottom — минимальная широта, right — максимальная долгота, а top — максимальная широта. См. также path.bounds, который вычисляет проецируемую ограничивающую прямоугольную область на декартовой плоскости.

d3.geo.distance(a, b)

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

d3.geo.length(feature)

Возвращает длину по большой окружности указанного feature в радианах. Для многоугольников возвращает периметр внешнего кольца плюс периметр любых внутренних колец.

d3.geo.interpolate(a, b)

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

d3.geo.rotation(rotate)

Указывает вращение в виде массива [λ, φ, γ]. Элементы массива являются углами в градусах и определяют вращение в следующем порядке: по долготе, по широте и вокруг начала координат. Если последний элемент массива, γ, опущен, он по умолчанию равен 0. Возвращает функцию, которая вращает заданную точку, как описано ниже.

rotation(location)

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

rotation.invert(location)

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