gerhobbelt / d3-geo-polygon

Clipping and geometric operations for spherical polygons.

d3-geo-polygon

Clipping and geometric operations for spherical polygons.

Installing

If you use NPM, npm install d3-geo-polygon. Otherwise, download the latest release. You can also load directly from unpkg. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://unpkg.com/d3-geo@1"></script>
<script src="https://unpkg.com/d3-geo-polygon@1"></script>
<script>

// new projection
var projection = d3.geoDodecahedral();

// polyhedral projections don’t need SVG or canvas clipping anymore
var projection = d3.geoPolyhedralCollignon();

// arbitrary polygon clipping on any projection
var projection = d3.geoEquirectangular()
    .preclip(d3.geoClipPolygon({
      type: "Polygon",
      coordinates: [[[-10, -10], [-10, 10], [10, 10], [10, -10], [-10, -10]]]
    }));

</script>

API Reference

# d3.geoClipPolygon(polygon) <>

Given a GeoJSON polygon, returns a clip function suitable for projection.preclip.

# clip.polygon()

Given a clipPolygon function, returns the GeoJSON polygon.

Projections

d3-geo-polygon adds polygon clipping to the polyhedral projections from d3-geo-projection. Thus, it supercedes the following symbols:

# d3.geoPolyhedral(tree, face) <>

Defines a new polyhedral projection. The tree is a spanning tree of polygon face nodes; each node is assigned a node.transform matrix. The face function returns the appropriate node for a given lambda and phi in radians.

# polyhedral.tree() returns the spanning tree of the polyhedron, from which one can infer the faces’ centers, polygons, shared edges etc.

# d3.geoPolyhedralButterfly() <>

The gnomonic butterfly projection.

# d3.geoPolyhedralCollignon() <>

The Collignon butterfly projection.

# d3.geoPolyhedralWaterman() <>

A butterfly projection inspired by Steve Waterman’s design.

New projections are introduced:

# d3.geoPolyhedralVoronoi([parents], [polygons], [faceProjection]) <>

Returns a polyhedral projection based on the polygons, arranged in a tree according to the parents list. polygons are a GeoJSON FeatureCollection of geoVoronoi cells, which should indicate the corresponding sites (see d3-geo-voronoi). An optional faceProjection is passed to d3.geoPolyhedral() -- note that the gnomonic projection on the polygons’ sites is the only faceProjection that works in the general case.

The .parents([parents]), .polygons([polygons]), .faceProjection([faceProjection]) set and read the corresponding options.

# d3.geoCubic() <>

The cubic projection.

# d3.geoDodecahedral() <>

The dodecahedral projection.

# d3.geoIcosahedral() <>

The icosahedral projection.

# d3.geoAirocean() <>

Buckminster Fuller’s Airocean projection (also known as “Dymaxion”), based on a very specific arrangement of the icosahedron which allows continuous continent shapes. Fuller’s triangle transformation, as formulated by Robert W. Gray (and implemented by Philippe Rivière), makes the projection almost equal-area.

# d3.geoCahillKeyes() <>
# d3.geoCahillKeyes

The Cahill-Keyes projection, designed by Gene Keyes (1975), is built on Bernard J. S. Cahill’s 1909 octant design. Implementation by Mary Jo Graça (2011), ported to D3 by Enrico Spinielli (2013).

# d3.geoTetrahedralLee(orientation) <>
# d3.geoLeeRaw

Lee’s tetrahedral conformal projection.

# Default angle is +30°, apex up (-30° for base up, apex down).

Default aspect uses projection.rotate([30, 180]) and has the North Pole at the triangle’s center -- use projection.rotate([-30, 0]) for the South aspect.

# d3.geoCox() <>
# d3.geoCoxRaw

The Cox conformal projection.