Skip to content

Geo Paths

Jump to bottom Edit New page
mbostock edited this page Dec 24, 2012 · 54 revisions

Wiki ▸ API Reference ▸ Geo ▸ 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:

  • TopoJSON - shapefile simplification, topology construction and GeoJSON compression.
  • Shapely - manipulation of planar geometry objects.
  • ColorBrewer - color scales for maps.
  • PostGIS - a geospatial database.

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:

  • Point - a single position.
  • MultiPoint - an array of positions.
  • LineString - an array of positions forming a continuous line.
  • MultiLineString - an array of arrays of positions forming several lines.
  • Polygon - an array of arrays of positions forming a polygon (possibly with holes).
  • MultiPolygon - a multidimensional array of positions forming multiple polygons.
  • GeometryCollection - an array of geometry objects.
  • Feature - a feature containing one of the above geometry objects.
  • FeatureCollection - an array of feature objects.

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, and also for fast rendering of the equirectangular projection.

# 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.

# d3.geo.area(feature)

…

# d3.geo.centroid(feature)

…

# d3.geo.bounds(feature)

Given a GeoJSON feature, returns the corresponding bounding box. 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.geo.greatArc()

Constructs a new interpolator to approximate the shortest path between two geographic points, using a segment of a great circle.

# greatArc([…])

Returns a GeoJSON LineString approximating a great circle segment. If source and target accessors are in use, they will retrieve the source and target points from the given arguments. By default, they expect {source: …, target: …}.

# greatArc.distance([…])

Returns the great circle distance along this great circle segment, in radians. If source and target accessors are in use, they will retrieve the source and target points from the given arguments. By default, they expect {source: …, target: …}. 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.

# 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.greatCircle
# d3.geo.circle

Represents a geographic circle with arbitrary radius and origin, which can be used to clip geographic features. This is particularly useful for azimuthal projections.

# 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 89.9°.

# 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°.

# circle.clip(feature[, index])

Clips a given GeoJSON feature or geometry object against this circle.

Add a custom footer
Add a custom sidebar

Clone this wiki locally