Geo Paths

API Reference ▸ Geo

For cartographic visualizations, D3 supports a handful of utilities for displaying and manipulating geographic data. These utilities are based on the GeoJSON format—a standard way of representing geographic features in JavaScript. For example, GDAL includes the ogr2ogr tool which can convert binary shapefiles into GeoJSON; the shapefile is another common representation for geographic data, frequently used by the U.S. Census Bureau.

Some other tools you may be interested in:

• Shapely - manipulation of planar geometry objects.
• MapShaper and Bloch - shapefile simplification.
• ColorBrewer - color scales for maps.
• PostGIS - a geospatial database.

The primary mechanism for displaying geographic data is d3.geo.path. In many ways, 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.

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

For example, to display multiple features:

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

An optional index may be specified, which is passed along to the pointRadius accessor. Note: you probably want to specify the style property "fill-rule" as "evenodd". Without this, geographic features with holes (such as South Africa surrounding Lesotho) will not display correctly.

# path.projection([projection])

# path.area(feature)

# path.centroid(feature)

# path.pointRadius([radius])

# d3.geo.bounds(feature)