Geo Paths - zziuni/d3 GitHub Wiki

Wiki ▸ API Reference ▸ Geo ▸ Geo Paths

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()

지리 경로 제네레이터를 새로 생성한다. 기본값은 albersUsa 투영법과 반지름 4.5 픽셀의 포인트다.

# 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 polygons, you should specify the style property "fill-rule" as "evenodd" on path elements. This ensures that geographic features with holes (such as South Africa surrounding Lesotho) are displayed correctly. To display multiple features, you can either place them in a single feature collection and a single path element, or create multiple distinct path elements:

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

An optional index may be specified, which is passed along to the pointRadius accessor.

# path.projection([projection])

projection 인자를 지정하면, 패스 제네레이터로 지정한 projection 함수의 투영법 사용한다. projection 인자를 지정 안하면, 현재 투영법을 반환한다. 기본값은 albersUsa다. 일반적으로 투영법은 D3에 내장된 projections중 하나지만 어떤 함수도 사용가능하다. 그 함수는 [longitude(경도), latitude(위도)]의 단일 지점 좌표를 나타내는 두개의 요소를 가진 배열을 인자로 받는다. 그리고 [x,y]의 투영된 픽셀 지점을 나타내는 요소가 두개인 배열을 반환한다. 예를 들어 다음은 기초적인 구면 Mercator 투영법(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
  ];
}

Proj4js를 추가하면 D3가 지원하지 않는 투영법을 사용할 수 있다.

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