Geo Paths

For cartographic visualizations, D3 supports a handful of components for displaying and manipulating geographic data. These components use the GeoJSON format—a standard way of representing geographic features in JavaScript. (See also the TopoJSON format, an extension of GeoJSON that is significantly more compact.) To convert shapefiles to GeoJSON, use ogr2ogr, part of the GDAL package.

Some other tools you may be interested in:

The primary mechanism for displaying geographic data is d3.geo.path. This class is similar to d3.svg.line and the other SVG shape generators: given a geometry or feature object, it generates the path data string suitable for the "d" attribute of an SVG path element. The d3.geo.path class can render directly to Canvas, which may offer better performance when animating the projection.

# d3.geo.path()

Creates a new geographic path generator with the default settings: the albersUsa projection and a point radius of 4.5 pixels.

# path(feature[, index])

Returns the path data string for the given feature, which may be any GeoJSON feature or geometry object:

The type "Sphere" is also supported, which is useful for rendering the outline of the globe. A sphere has no coordinates. An optional index may be specified, which is passed along to the pointRadius accessor; the index is passed automatically when the path generator is invoked by selection.attr.

To display multiple features, you can place them in a single feature collection and a single path element:

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

Alternatively, you can create multiple distinct path elements:

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

Using distinct path elements is typically slower than a single path element for a collection. However, distinct path elements are preferred if you want interact with features separately (e.g., using CSS :hover or click events).

# path.projection([projection])

If projection is specified, sets the projection used by the path generator to the specified projection function. If projection is not specified, returns the current projection, which defaults to albersUsa. The projection is typically one of D3's built-in geographic projections; however, any function can be used. A projection function takes a two-element array of numbers representing the coordinates of a location, [longitude, latitude], and returns a similar two-element array of numbers representing the projected pixel position [x, y]. For example, a rudimentary spherical Mercator projection:

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

Internally, this point projection function is wrapped with a fallback stream transformation that performs adaptive resampling. However, the fallback stream does not perform any clipping or cutting. For more control over the stream transformation, the projection may be specified as an object that implements the stream method. The stream method takes a stream listener as input, and returns a wrapped stream listener that projects the input geometry; in other words, it implements projection.stream.

If projection is null, the path uses the identity transformation, where the input geometry is not projected and is instead rendered directly in raw coordinates. This can be useful for fast rendering of already-projected geometry, or for fast rendering of the equirectangular projection.

# path.context([context])

If context is specified, sets the render context and returns the path generator. If the context is null, then the path generator will return an SVG path string when invoked on a given feature. If the context is non-null, the path generator will instead call methods on the specified context to render geometry. The context must implement the following methods:

Note that this is a subset of the canvas element’s 2D rendering context, and thus a canvas context can be passed to the path generator, in which case geometry will be rendered directly to the canvas. If context is not specified, returns the current render context, which defaults to null.

# path.area(feature)

Computes the projected area (in square pixels) for the specified feature. Point, MultiPoint, LineString and MultiLineString features have zero area. For Polygon and MultiPolygon features, this method first computes the area of the exterior ring, and then subtracts the area of any interior holes. This method observes any clipping and resampling performed by the projection stream.

# path.centroid(feature)

Computes the projected centroid (in pixels) for the specified feature. This is handy for, say, labeling state or county boundaries, or displaying a symbol map. The noncontiguous cartogram example scales each state around its centroid. This method observes any clipping and resampling performed by the projection stream.

# path.bounds(feature)

Computes the projected bounding box (in pixels) for the specified feature. This is handy for, say, zooming in to a particular feature. This method observes any clipping and resampling performed by the projection stream.

# path.pointRadius([radius])

If radius is specified, sets the radius used to display Point and MultiPoint features to the specified number. If radius is not specified, returns the current radius. While the radius is commonly specified as a number constant, it may also be specified as a function which is computed per feature, being passed the feature and index arguments from the path function. For example, if your GeoJSON data has additional properties, you might access those properties inside the radius function to vary the point size; alternatively, you could d3.svg.symbol and a projection for more control over the display.

Shape Generators

# d3.geo.greatArc()

Constructs a feature generator for creating the great arc between two geographic points, using a segment of a great circle. The great arc represents the shortest path between the two points on the surface of the sphere.

# greatArc(arguments…)

Returns a GeoJSON LineString approximating a great circle segment. The source and target accessors specify how to determine the source and target points for the given arguments; the default accessors expect a single argument with source and target properties: {source: …, target: …}.

# greatArc.distance(arguments…)

Returns the length of the great arc between the two points represented by arguments in radians. To convert the angular distance to a linear one, simply multiply by the radius of the sphere, which is around 6,371km on average for Earth. The source and target accessors specify how to determine the source and target points for the given arguments; the default accessors expect a single argument with source and target properties: {source: …, target: …}.

# greatArc.source([source])

If source is specified, sets the source-accessor to the specified function or constant point, [longitude, latitude]. If source is not specified, returns the current source-accessor. This accessor is invoked every time the interpolator is called. The default is function(d) { return d.source; }.

# greatArc.target([target])

If target is specified, sets the target-accessor to the specified function or constant point, [longitude, latitude]. If source is not specified, returns the current target-accessor. This accessor is invoked every time the interpolator is called. The default is function(d) { return d.target; }.

# greatArc.precision([precision])

If precision is specified, sets the maximum segment length of the interpolated path in degrees. If precision is not specified, returns the current precision, which defaults to 6°.

# d3.geo.circle

Constructs a feature generator for creating circles centered at a given geographic location with a given radius in degrees.

# circle(arguments…)

Returns a GeoJSON Polygon approximating a circle. The origin accessor specifies how to determine the origin for the given arguments; the default accessor uses the constant ⟨0°,0°⟩.

# circle.origin([origin])

If origin is specified, sets the circle origin. A two-element coordinate array should be specified, or an accessor function. If origin is not specified, returns the current origin, which defaults to ⟨0°,0°⟩.

# circle.angle([angle])

If angle is specified, sets the angular radius of the circle in degrees. If angle is not specified, returns the current radius, which defaults to 90°.

# circle.precision([precision])

If precision is specified, sets the precision of the interpolated circle segments in degrees. These interpolated segments are inserted when a feature is clipped by the circle. If precision is not specified, returns the current precision, which defaults to 6°.

Spherical Math

# d3.geo.area(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.geo.centroid(feature)

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

# d3.geo.bounds(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. See also path.bounds, which computes the projected bounding box on the Cartesian plane.

# d3.geo.interpolate(a, b)

Returns an interpolator given the two locations a and b. Each location must be represented as a two-element array of [longitude, latitude]. 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.