d3-geo-scale-bar

d3-geo-scale-bar

Like d3-axis but for maps, this module displays automatic scale bars for projected geospatial data.

Scale bars help viewers understand the geographic extent of maps. Printed maps, even those produced over a century ago, seldom lack them, yet scale bars are commonly missing from modern maps published on the internet. d3-geo-scale-bar makes it easy to add scale bars to maps created with d3-geo, a popular open source library for publishing maps on the web.

See it in action.

Installing

If you use NPM, npm install d3-geo-scale-bar. Otherwise, download the latest release. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-array.v1.min.js"></script>
<script src="https://d3js.org/d3-geo.v1.min.js"></script>
<script src="https://unpkg.com/d3-geo-scale-bar@0.0.2/build/d3-geo-scale-bar.min.js"></script>
<script>

var scaleBar = d3.geoScaleBar()
  .projection(d3GeoProjection)
  .fitSize([width, height], geoJsonObject);

d3.select("svg").append("g").call(scaleBar);

</script>

Try d3-geo-scale-bar in your browser.

API Reference

# d3.geoScaleBar() <>

Constructs a new scale bar generator.

# scaleBar(context) <>

Render the scale bar to the given context, which may be either a selection of SVG containers (either SVG or G elements) or a corresponding transition. Configure the scale bar with scaleBar.projection and scaleBar.fitSize before rendering.

# scaleBar.projection([projection]) <>

If projection is specified, sets the projection and returns the scale bar. If projection is not specified, returns the current projection.

# scaleBar.fitSize(size, object) <>

A convenience method combining the setter functions of scaleBar.extent and scaleBar.feature. The following two statements are equivalent:

scaleBar.extent([width, height]).feature(object);
scaleBar.fitExtent([width, height], object);

# scaleBar.extent([size]) <>

If size is specified, sets the extent such that (1) the scale bar's default top-left corner aligns with the top-left corner of the projected geospatial data, and (2) you can position the scale bar vertically with scaleBar.top and horizontally with scaleBar.left. If size is not specified, returns the current extent.

# scaleBar.feature([object]) <>

If object< is specified, passes the corresponding GeoJSON Feature or FeatureCollection to the scale bar to allow for calculation of mile and kilometer scales and for positioning of the scale bar on the projected geospatial data. If object is not specified, returns the current object.

# scaleBar.radiusMiles([miles]) <>

If miles is specified, sets the number of miles of the radius of the sphere on which the geospatial data is projected. Defaults to 3,959, the radius of the Earth. If miles is not specified, returns the current number of miles of the sphere's radius.

# scaleBar.radiusKilometers([kilometers]) <>

If kilometers is specifed, sets the number of kilometers of the radius of the sphere on which the geospatial data is projected. Defaults to 6,371, the radius of the Earth. If kilometers is not specified, returns the current number of kilometers of the sphere's radius.

# scaleBar.miles([miles]) <>

If miles is specified, sets the number of miles of the scale bar. Defaults to the largest exponent of 10 that will fit on the map. If miles is not specified, returns the current number of miles of the scale bar.

# scaleBar.kilometers([kilometers]) <>

If kilometers is specifed, sets the number of kilometers of the scale bar. Defaults to the largest exponent of 10 that will fit on the map. If kilometers is not specified, returns the current number of kilometers of the scale bar.

# scaleBar.height([height]) <>

If height is specified, sets the height of the scale bar in pixels. Defaults to 1. If height is not specified, returns the current height of the scale bar.

# scaleBar.left([left]) <>

If left is specified, sets the left position to the specified value which must be in the range [0, 1], where 0 is the left-most side of the projected geospatial data and 1 is the right-most. If left is not specified, returns the current left position which defaults to 0.

# scaleBar.top([top]) <>

If top is specified, sets the top position to the specified value which must be in the range [0, 1], where 0 is the top-most side of the projected geospatial data and 1 is the bottom-most. If top is not specified, returns the current top position which defaults to 0.