d4_geo library

Geographic projections, spherical shapes and spherical trigonometry.

Map projections are sometimes implemented as point transformations: a function that takes a given longitude lambda and latitude phi, and returns the corresponding xy position on the plane. For instance, here is the spherical Mercator projection (in radians):

num mercator(num lambda, num phi) {
  final x = lambda;
  final y = log(tan(pi / 4 + y / 2));
  return [x, y];
}

This is a reasonable approach if your geometry consists only of points. But what about discrete geometry such as polygons and polylines?

Discrete geometry introduces new challenges when projecting from the sphere to the plane. The edges of a spherical polygon are geodesics (segments of great circles), not straight lines. Geodesics become curves in all map projections except gnomonic, and thus accurate projection requires interpolation along each arc. D4 uses adaptive sampling inspired by Visvalingam’s line simplification method to balance accuracy and performance.

The projection of polygons and polylines must also deal with the topological differences between the sphere and the plane. Some projections require cutting geometry that crosses the antimeridian, while others require clipping geometry to a great circle. Spherical polygons also require a winding order convention to determine which side of the polygon is the inside: the exterior ring for polygons smaller than a hemisphere must be clockwise, while the exterior ring for polygons larger than a hemisphere must be anticlockwise. Interior rings representing holes must use the opposite winding order of their exterior ring.

D4 uses spherical GeoJSON to represent geographic features in Dart. D4 supports a wide variety of common and unusual map projections. And because D4 uses spherical geometry to represent data, you can apply any aspect to any projection by rotating geometry.

TIP: To convert shapefiles to GeoJSON, use the shapefile package.

CAUTION: D4’s winding order convention is also used by TopoJSON and ESRI shapefiles; however, it is the opposite convention of GeoJSON’s RFC 7946. Also note that standard GeoJSON WGS84 uses planar equirectangular coordinates, not spherical coordinates, and thus may require stitching to remove antimeridian cuts.

Classes

GeoAlbersUsa

A U.S.-centric composite projection of three geoConicEqualArea projections.

GeoCircle

A geometry geographic generator for creating circles.

GeoConicProjection

Conic projections project the sphere onto a cone, and then unroll the cone onto the plane.

GeoGraticule

A geometry geographic generator for creating graticules.

GeoIdentity

The identity transform can be used to scale, translate and clip planar geometry.

GeoPath

A geographic path generator that takes a given GeoJSON geometry or feature object and generates SVG path data string or renders to a Canvas.

GeoProjection

Projections transform spherical polygonal geometry to planar polygonal geometry.

GeoProjectionMutator

A projection wrapper to mutate as needed.

GeoRawProjection

Raw projections are point transformation functions that are used to implement custom projections.

GeoRotation

A raw transform that represents a rotation about each spherical axis.

GeoStream

Rather than materializing intermediate representations, streams transform geometry through function calls to minimize overhead.

GeoTransform

Transforms are a generalization of projections.

GeoTransverseMercator

The transverse spherical Mercator projection.

Constants

geoEqualEarthRaw → const GeoRawProjection

The raw Equal Earth projection, by Bojan Šavrič et al., 2018.

geoEquirectangularRaw → const GeoRawProjection

The raw equirectangular (plate carrée) projection.

geoMercatorRaw → const GeoRawProjection

The raw spherical Mercator projection.

geoNaturalEarth1Raw → const GeoRawProjection

The raw Natural Earth projection.

geoTransverseMercatorRaw → const GeoRawProjection

The raw transverse spherical Mercator projection.

Properties

geoAzimuthalEqualAreaRaw → GeoRawProjection

The raw azimuthal equal-area projection.

final

geoAzimuthalEquidistantRaw → GeoRawProjection

The raw azimuthal equidistant projection.

final

geoClipAntimeridian → GeoStream Function(GeoStream)

A clipping function which transforms a stream such that geometries (lines or polygons) that cross the antimeridian line are cut in two, one on each side.

final

geoGnomonicRaw → GeoRawProjection

The raw gnomonic projection.

final

geoOrthographicRaw → GeoRawProjection

The raw orthographic projection.

final

geoStereographicRaw → GeoRawProjection

The raw stereographic projection.

final

Functions

geoAlbers() → GeoProjection

The Albers’ equal area-conic projection.

geoArea(Map object) → double

Returns the spherical area of the specified GeoJSON object in steradians.

geoAzimuthalEqualArea() → GeoProjection

The azimuthal equal-area projection.

geoAzimuthalEquidistant() → GeoProjection

The azimuthal equidistant projection.

geoBounds(Map object) → List<List<num>>

Returns the spherical bounding box for the specified GeoJSON object.

geoCentroid(Map object) → List<double>

Returns the spherical centroid of the specified GeoJSON object.

geoClipCircle(double angle) → GeoStream Function(GeoStream)

Generates a clipping function which transforms a stream such that geometries are bounded by a small circle of radius angle around the GeoProjection.center.

geoClipRectangle(num x0, num y0, num x1, num y1) → GeoStream Function(GeoStream)

Generates a clipping function which transforms a stream such that geometries are bounded by a rectangle of coordinates [[x0, y0], [x1, y1]].

geoConicConformal() → GeoConicProjection

The conic conformal projection.

geoConicConformalRaw([List? y]) → GeoRawProjection

The raw conic conformal projection.

geoConicEqualArea() → GeoConicProjection

The Albers’ equal-area conic projection.

geoConicEqualAreaRaw([List? y]) → GeoRawProjection

The raw Albers’ equal-area conic projection.

geoConicEquidistant() → GeoConicProjection

The conic equidistant projection.

geoConicEquidistantRaw([List? y]) → GeoRawProjection

The raw conic equidistant projection.

geoContains(Map? object, List<num> point) → bool

Returns true if and only if the specified GeoJSON object contains the specified point, or false if the object does not contain the point.

geoDistance(List<num> a, List<num> b) → double

Returns the great-arc distance in radians between the two points a and b.

geoEqualEarth() → GeoProjection

The Equal Earth projection, by Bojan Šavrič et al., 2018.

geoEquirectangular() → GeoProjection

The equirectangular (plate carrée) projection.

geoGnomonic() → GeoProjection

The gnomonic projection.

geoGraticule10() → Map

A convenience method for directly generating the default 10° global graticule as a GeoJSON MultiLineString geometry object.

geoInterpolate(List<double> a, List<double> b) → List<double> Function(double)

Returns an interpolator function given two points a and b.

geoLength(Map object) → double

Returns the great-arc length of the specified GeoJSON object in radians.

geoMercator() → GeoProjection

The spherical Mercator projection.

geoNaturalEarth1() → GeoProjection

The Natural Earth projection is a pseudocylindrical projection designed by Tom Patterson.

geoOrthographic() → GeoProjection

The orthographic projection.

geoStereographic() → GeoProjection

The stereographic projection.