d3-geo

What is d3-geo?

The d3-geo package is part of the D3 (Data-Driven Documents) JavaScript library that focuses on geographical projections, transformations, and shapes. It allows for the creation of maps, the manipulation of geographic data, and the rendering of geographic shapes in web applications. The package provides a comprehensive set of tools for working with geography in the context of data visualization.

What are d3-geo's main functionalities?

Creating a Map Projection

This feature allows you to create a map projection, which is a method for representing the surface of the Earth on a flat surface. The example code demonstrates how to create an Albers USA projection, which is commonly used for maps of the United States.

const projection = d3.geoAlbersUsa();

Generating a Path from GeoJSON

This feature enables the generation of SVG path data from GeoJSON objects using a specified projection. The example code shows how to create a path generator with the Albers USA projection, which can then be used to render geographic features from GeoJSON data.

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

Computing Geodesic Distances

This feature allows for the computation of the spherical distance between two points specified by longitude and latitude. The example code calculates the distance between two geographic points, which can be useful for various geographic analyses.

const distance = d3.geoDistance([lon1, lat1], [lon2, lat2]);

Other packages similar to d3-geo

topojson

TopoJSON is an extension of GeoJSON that encodes topology. While d3-geo focuses on geographic projections and rendering, TopoJSON provides tools for encoding and simplifying geographic data, making it complementary to d3-geo for efficient transmission of geographic data.

leaflet

Leaflet is a leading open-source JavaScript library for mobile-friendly interactive maps. Unlike d3-geo, which is primarily focused on data visualization and projections, Leaflet is geared towards providing a full-fledged mapping solution with features like tile layering, user interactions, and plugins for extended functionalities.

README

d3-geo

…

Installing

If you use NPM, npm install d3-geo. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

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

var stream = d3.geoStream();

</script>

Try d3-geo in your browser.

API Reference

# d3.geoArea(feature)

Returns the spherical area of the specified feature in steradians. See also path.area, which computes the projected area on the Cartesian plane.

# d3.geoBounds(feature)

Returns the spherical bounding box for the specified feature. The bounding box is represented by a two-dimensional array: [​[left, bottom], [right, top]​], where left is the minimum longitude, bottom is the minimum latitude, right is maximum longitude, and top is the maximum latitude.

# d3.geoCentroid(feature)

Returns the spherical centroid of the specified feature. See also path.centroid, which computes the projected centroid on the Cartesian plane.

# d3.geoDistance(a, b)

Returns the great-arc distance in radians between the two location a and b. Each location must be specified as a two-element array [longitude, latitude] in degrees.

# d3.geoLength(feature)

Returns the great-arc length of the specified feature in radians. For polygons, returns the perimeter of the exterior ring plus that of any interior rings.

# d3.geoInterpolate(a, b)

Returns an interpolator given the two locations a and b. Each location must be specified as a two-element array [longitude, latitude] in degrees. The returned interpolator is a function which takes a single parameter t as input, where t ranges from 0 to 1. A value of 0 returns the location a, while a value of 1 returns the location b. Intermediate values interpolate from a to b along the spanning great arc.

# d3.geoRotation(angles)

Returns a rotation operator for the given angles, which must be a two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis. If the rotation angle gamma is omitted, it defaults to 0.

# rotation(location)

Rotates the given location according to the angles specified for this rotation, in the order described above. The location must be specified as a two-element array [longitude, latitude] in degrees. Returns a new array representing the rotated location.

# rotation.invert(location)

Rotates the given location according to the angles specified for this rotation, but with the order described above reversed. The location must be specified as a two-element array [longitude, latitude] in degrees. Returns a new array representing the rotated location.

Shapes

# d3.geoCircle()

Returns a new circle generator.

# circle(arguments…)

Returns a new GeoJSON geometry object of type “Polygon” approximating a circle on the surface of a sphere, with the current center, radius and precision. Any arguments are passed to the accessors.

# circle.center([center])

If center is specified, sets the circle center to the specified location [longitude, latitude] in degrees, and returns this circle generator. The center may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator. If center is not specified, returns the current center accessor, which defaults to:

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

# circle.radius([radius])

If radius is specified, sets the circle radius to the specified angle in degrees, and returns this circle generator. The radius may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator. If radius is not specified, returns the current radius accessor, which defaults to:

function radius() {
  return 90;
}

# circle.precision([angle])

If precision is specified, sets the circle precision to the specified angle in degrees, and returns this circle generator. The precision may also be specified as a function; this function will be invoked whenever a circle is generated, being passed any arguments passed to the circle generator. If precision is not specified, returns the current precision accessor, which defaults to:

function precision() {
  return 6;
}

Small circles do not follow great arcs and thus the generated polygon is only an approximation. Specifying a smaller precision angle improves the accuracy of the approximate polygon, but also increase the cost to generate and render it.

# d3.geoGraticule()

Constructs a feature generator for creating graticules.

# graticule()

Returns a MultiLineString geometry object representing all meridians and parallels for this graticule.

# graticule.lines()

Returns an array of LineString geometry objects, one for each meridian or parallel for this graticule.

# graticule.outline()

Returns a Polygon geometry object representing the outline of this graticule, i.e. along the meridians and parallels defining its extent.

# graticule.extent([extent])

If extent is specified, sets the major and minor extents of this graticule. If extent is not specified, returns the current minor extent, which defaults to ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.

# graticule.extentMajor([extent])

If extent is specified, sets the major extent of this graticule. If extent is not specified, returns the current major extent, which defaults to ⟨⟨-180°, -90° + ε⟩, ⟨180°, 90° - ε⟩⟩.

# graticule.extentMinor([extent])

If extent is specified, sets the minor extent of this graticule. If extent is not specified, returns the current minor extent, which defaults to ⟨⟨-180°, -80° - ε⟩, ⟨180°, 80° + ε⟩⟩.

# graticule.step([step])

If step is specified, sets the major and minor step for this graticule. If step is not specified, returns the current minor step, which defaults to ⟨10°, 10°⟩.

# graticule.stepMajor([step])

If step is specified, sets the major step for this graticule. If step is not specified, returns the current major step, which defaults to ⟨90°, 360°⟩.

# graticule.stepMinor([step])

If step is specified, sets the minor step for this graticule. If step is not specified, returns the current minor step, which defaults to ⟨10°, 10°⟩.

# graticule.precision([angle])

If precision is specified, sets the precision for this graticule, in degrees. If precision is not specified, returns the current precision, which defaults to 2.5°.

Streams

Yadda yadda some introduction about how D3 transforms geometry using sequences of function calls to minimize the overhead of intermediate representations…

Stream sinks must implement several methods to traverse geometry. Sinks are inherently stateful; the meaning of a point depends on whether the point is inside of a line, and likewise a line is distinguished from a ring by a polygon.

# sink.point(x, y[, z])

Indicates a point with the specified coordinates x and y (and optionally z). The coordinate system is unspecified and implementation-dependent; for example, projection streams require spherical coordinates in degrees as input. Outside the context of a polygon or line, a point indicates a point geometry object (Point or MultiPoint). Within a line or polygon ring, the point indicates a control point.

# sink.lineStart()

Indicates the start of a line or ring. Within a polygon, indicates the start of a ring. The first ring of a polygon is the exterior ring, and is typically clockwise. Any subsequent rings indicate holes in the polygon, and are typically counterclockwise.

# sink.lineEnd()

Indicates the end of a line or ring. Within a polygon, indicates the end of a ring. Unlike GeoJSON, the redundant closing coordinate of a ring is not indicated via point, and instead is implied via lineEnd within a polygon. Thus, the given polygon input:

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

Will produce the following series of method calls on the sink:

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

# sink.polygonStart()

Indicates the start of a polygon. The first line of a polygon indicates the exterior ring, and any subsequent lines indicate interior holes.

# sink.polygonEnd()

Indicates the end of a polygon.

# sink.sphere()

Indicates the sphere (the globe; the unit sphere centered at ⟨0,0,0⟩).

# d3.geoStream(object, sink)

Streams the specified GeoJSON object to the specified stream sink. (Despite the name “stream”, these method calls are currently synchronous.) While both features and geometry objects are supported as input, the stream interface only describes the geometry, and thus additional feature properties are not visible to sinks.