Skip to content

Geo Paths

Jump to bottom Edit New page
mbostock edited this page Dec 24, 2012 · 46 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.

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). An optional index may be specified, which is passed along to the pointRadius accessor.

# 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. Typically, the projection is one of D3's built-in projections; however, any function can be used. The function takes a two-element array of numbers representing the coordinates of a single position, [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
  ];
}

If you want to use a projection that D3 does not already support, you might be able to adapt Proj4js.

# path.area(feature)

Computes the projected area (in square pixels) for the specified feature. Point, MultiPoint, LineString and MultiLineString features are ignored, returning zero. For Polygon and MultiPolygon features, this method first computes the area of the exterior ring, and then subtracts the area of any interior holes.

# path.centroid(feature)

Computes the projected centroid (in pixels) for the specified feature. This method is currently only supported for Polygon and MultiPolygon features. 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.

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