diff --git a/README.md b/README.md index 1f7c3dd..17ccfa4 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Clipping and geometric operations for spherical polygons. If you use npm, `npm install d3-geo-polygon`. You can also download the [latest release on GitHub](https://github.com/d3/d3-geo-polygon/releases/latest). For vanilla HTML in modern browsers, import d3-geo-polygon from Skypack: -```html +```html run=false @@ -28,7 +28,7 @@ const projection = d3.geoCubic(); This module introduces a handful of additional projections. It can also be used to clip a projection with an arbitrary polygon: -```html +```html run=false const projection = d3.geoEquirectangular() .preclip(d3.geoClipPolygon({ type: "Polygon", @@ -68,73 +68,109 @@ Polyhedral projections’ default **clipPoint** depends on whether the clipping # d3.geoPolyhedralButterfly() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/butterfly.js) -[](https://observablehq.com/@d3/polyhedral-gnomonic) +[ + + world map +](https://observablehq.com/@d3/polyhedral-gnomonic) The gnomonic butterfly projection. # d3.geoPolyhedralCollignon() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/collignon.js) -[](https://www.jasondavies.com/maps/collignon-butterfly/) +[ + + world map +](https://www.jasondavies.com/maps/collignon-butterfly/) The Collignon butterfly projection. # d3.geoPolyhedralWaterman() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/waterman.js) -[](https://www.jasondavies.com/maps/waterman-butterfly/) +[ + + world map +](https://www.jasondavies.com/maps/waterman-butterfly/) A butterfly projection inspired by Steve Waterman’s design. # d3.geoBerghaus · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) The Berghaus projection. # d3.geoGingery · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) The Gingery projection. # d3.geoHealpix · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) The HEALPix projection. # d3.geoInterruptedBoggs · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) Bogg’s interrupted eumorphic projection. # d3.geoInterruptedHomolosine · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) Goode’s interrupted homolosine projection. # d3.geoInterruptedMollweide · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) Goode’s interrupted Mollweide projection. # d3.geoInterruptedMollweideHemispheres · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) The Mollweide projection interrupted into two (equal-area) hemispheres. # d3.geoInterruptedSinuMollweide · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) Alan K. Philbrick’s interrupted sinu-Mollweide projection. # d3.geoInterruptedSinusoidal · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/interrupted-clipped) +[ + + world map +](https://observablehq.com/@d3/interrupted-clipped) An interrupted sinusoidal projection with asymmetrical lobe boundaries. @@ -144,7 +180,10 @@ The two-point equidistant projection, displaying 99.9996% of the sphere thanks t # d3.geoTwoPointEquidistantUsa() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) -[](https://observablehq.com/@d3/two-point-equidistant) +[ + + world map +](https://observablehq.com/@d3/two-point-equidistant) The two-point equidistant projection with points [-158°, 21.5°] and [-77°, 39°], approximately representing Honolulu, HI and Washington, D.C. @@ -164,50 +203,74 @@ The .parents([parents]), .polygons([polygons]), . # d3.geoCubic() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cubic.js), [Examples](https://observablehq.com/@fil/cubic-projections) -[](https://observablehq.com/@fil/cubic-projections) +[ + + world map +](https://observablehq.com/@fil/cubic-projections) The cubic projection. # d3.geoDodecahedral() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/dodecahedral.js), [Examples](https://observablehq.com/@fil/dodecahedral-projection) -[](https://observablehq.com/@fil/dodecahedral-projection) +[ + + world map +](https://observablehq.com/@fil/dodecahedral-projection) The pentagonal dodecahedral projection. # d3.geoRhombic() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/rhombic.js), [Examples](https://observablehq.com/d/881a8431e638b408) -[](https://observablehq.com/d/881a8431e638b408) +[ + + world map +](https://observablehq.com/d/881a8431e638b408) The rhombic dodecahedral projection. # d3.geoDeltoidal() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/deltoidal.js), [Examples](https://observablehq.com/d/881a8431e638b408) -[](https://observablehq.com/d/881a8431e638b408) +[ + + world map +](https://observablehq.com/d/881a8431e638b408) The deltoidal hexecontahedral projection. # d3.geoIcosahedral() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/icosahedral.js), [Examples](https://observablehq.com/@fil/icosahedral-projections) -[](https://observablehq.com/@fil/icosahedral-projections) +[ + + world map +](https://observablehq.com/@fil/icosahedral-projections) The icosahedral projection. # d3.geoAirocean() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/airocean.js), [Examples](https://observablehq.com/@fil/airocean-projection) -[](https://observablehq.com/@fil/airocean-projection) +[ + + world map +](https://observablehq.com/@fil/airocean-projection) 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() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cahillKeyes.js), [Examples](https://observablehq.com/@d3/cahill-keyes)
# d3.geoCahillKeyes -[](http://www.genekeyes.com/) +[ + + world map +](https://www.genekeyes.com/) 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.geoImago() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/imago.js), [Examples](https://observablehq.com/@fil/the-imago-projection) -[](https://kunimune.home.blog/2017/11/23/the-secrets-of-the-authagraph-revealed/) +[ + + world map +](https://kunimune.home.blog/2017/11/23/the-secrets-of-the-authagraph-revealed/) The Imago projection, engineered by Justin Kunimune (2017), is inspired by Hajime Narukawa’s AuthaGraph design (1999). @@ -222,7 +285,10 @@ Horizontal shift. Defaults to 1.16. # d3.geoTetrahedralLee() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/tetrahedralLee.js), [Examples](https://observablehq.com/@fil/lee-projection)
# d3.geoLeeRaw -[](https://observablehq.com/@d3/lees-tetrahedral) +[ + + world map +](https://observablehq.com/@d3/lees-tetrahedral) Lee’s tetrahedral conformal projection. @@ -233,14 +299,20 @@ Default aspect uses _projection_.rotate([30, 180]) and has the North Pole at the # d3.geoCox() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cox.js), [Examples](https://observablehq.com/@fil/cox-conformal-projection-in-a-triangle)
# d3.geoCoxRaw -[](https://visionscarto.net/cox-conformal-projection) +[ + + world map +](https://visionscarto.net/cox-conformal-projection) The Cox conformal projection. # d3.geoComplexLog([planarProjectionRaw[, cutoffLatitude]]) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/complexLog.js), [Example](https://cgmi.github.io/complex-log-projection/)
# d3.geoComplexLogRaw([planarProjectionRaw]) -[](https://cgmi.github.io/complex-log-projection/) +[ + + world map +](https://cgmi.github.io/complex-log-projection/) Complex logarithmic view. This projection is based on the papers by Joachim Böttger et al.: diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index c9ec320..0000000 --- a/docs/index.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -theme: alt ---- - -# d3-geo-polygon - -Clipping and geometric operations for spherical polygons. - -## Installing - -If you use npm, `npm install d3-geo-polygon`. You can also download the [latest release on GitHub](https://github.com/d3/d3-geo-polygon/releases/latest). For vanilla HTML in modern browsers, import d3-geo-polygon from Skypack: - -```html run=false - -``` - -For legacy environments, you can load d3-geo-projection’s UMD bundle from an npm-based CDN such as jsDelivr; a `d3` global is exported: - -```html run=false - - - - -``` - -This module introduces a handful of additional projections. It can also be used to clip a projection with an arbitrary polygon: - -```html run=false -const projection = d3.geoEquirectangular() - .preclip(d3.geoClipPolygon({ - type: "Polygon", - coordinates: [[[-10, -10], [-10, 10], [10, 10], [10, -10], [-10, -10]]] - })); -``` - -## API Reference - -# d3.geoClipPolygon(polygon) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/clip/polygon.js), [Examples](https://observablehq.com/@mbostock/spherical-clipping) - -Given a GeoJSON *polygon* or *multipolygon*, returns a clip function suitable for [_projection_.preclip](https://github.com/d3/d3-geo#preclip). - -# clip.polygon() - -Given a clipPolygon function, returns the GeoJSON polygon. - -# d3.geoIntersectArc(arcs) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/intersect.js), [Examples](https://observablehq.com/@fil/spherical-intersection) - -Given two spherical arcs [point0, point1] and [point2, point3], returns their intersection, or undefined if there is none. See “[Spherical Intersection](https://observablehq.com/@fil/spherical-intersection)”. - -## Projections - -d3-geo-polygon adds polygon clipping to the polyhedral and interrupted projections from [d3-geo-projection](https://github.com/d3/d3-geo-projection). Thus, it supersedes the following symbols: - -# d3.geoPolyhedral(tree, face) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/index.js), [Examples](https://observablehq.com/@fil/polyhedral-projections-with-d3-geo-polygon) - -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() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/butterfly.js) - -[ - - world map -](https://observablehq.com/@d3/polyhedral-gnomonic) - -The gnomonic butterfly projection. - -# d3.geoPolyhedralCollignon() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/collignon.js) - -[ - - world map -](https://www.jasondavies.com/maps/collignon-butterfly/) - -The Collignon butterfly projection. - -# d3.geoPolyhedralWaterman() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/waterman.js) - -[ - - world map -](https://www.jasondavies.com/maps/waterman-butterfly/) - -A butterfly projection inspired by Steve Waterman’s design. - -# d3.geoBerghaus · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -The Berghaus projection. - -# d3.geoGingery · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -The Gingery projection. - -# d3.geoHealpix · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -The HEALPix projection. - -# d3.geoInterruptedBoggs · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -Bogg’s interrupted eumorphic projection. - -# d3.geoInterruptedHomolosine · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -Goode’s interrupted homolosine projection. - -# d3.geoInterruptedMollweide · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -Goode’s interrupted Mollweide projection. - -# d3.geoInterruptedMollweideHemispheres · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -The Mollweide projection interrupted into two (equal-area) hemispheres. - -# d3.geoInterruptedSinuMollweide · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -Alan K. Philbrick’s interrupted sinu-Mollweide projection. - -# d3.geoInterruptedSinusoidal · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[ - - world map -](https://observablehq.com/@d3/interrupted-clipped) - -An interrupted sinusoidal projection with asymmetrical lobe boundaries. - - -New projections are introduced: - -# d3.geoPolyhedralVoronoi([parents], [polygons], [faceProjection], [faceFind]) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/voronoi.js) - -Returns a polyhedral projection based on the *polygons*, arranged in a tree. - -The tree is specified by passing *parents*, an array of indices indicating the parent of each face. The root of the tree is the first face without a parent (with the array typically specifying -1). - -*polygons* are a GeoJSON FeatureCollection of geoVoronoi cells, which should indicate the corresponding sites (see [d3-geo-voronoi](https://github.com/Fil/d3-geo-voronoi)). An optional [_faceProjection_](#geoPolyhedral) 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. Use .faceFind(voronoi.find) for faster results. - -# d3.geoCubic() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cubic.js), [Examples](https://observablehq.com/@fil/cubic-projections) - -[ - - world map -](https://observablehq.com/@fil/cubic-projections) - -The cubic projection. - -# d3.geoDodecahedral() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/dodecahedral.js), [Examples](https://observablehq.com/@fil/dodecahedral-projection) - -[ - - world map -](https://observablehq.com/@fil/dodecahedral-projection) - -The pentagonal dodecahedral projection. - -# d3.geoRhombic() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/rhombic.js), [Examples](https://observablehq.com/d/881a8431e638b408) - -[ - - world map -](https://observablehq.com/d/881a8431e638b408) - -The rhombic dodecahedral projection. - -# d3.geoDeltoidal() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/deltoidal.js), [Examples](https://observablehq.com/d/881a8431e638b408) - -[ - - world map -](https://observablehq.com/d/881a8431e638b408) - -The deltoidal hexecontahedral projection. - -# d3.geoIcosahedral() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/icosahedral.js), [Examples](https://observablehq.com/@fil/icosahedral-projections) - -[ - - world map -](https://observablehq.com/@fil/icosahedral-projections) - -The icosahedral projection. - -# d3.geoAirocean() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/airocean.js), [Examples](https://observablehq.com/@fil/airocean-projection) - -[ - - world map -](https://observablehq.com/@fil/airocean-projection) - -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() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cahillKeyes.js), [Examples](https://observablehq.com/@d3/cahill-keyes) -
# d3.geoCahillKeyes - -[ - - world map -](https://www.genekeyes.com/) - -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.geoImago() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/imago.js), [Examples](https://observablehq.com/@fil/the-imago-projection) - -[ - - world map -](https://kunimune.home.blog/2017/11/23/the-secrets-of-the-authagraph-revealed/) - -The Imago projection, engineered by Justin Kunimune (2017), is inspired by Hajime Narukawa’s AuthaGraph design (1999). - -# imago.k([k]) - -Exponent. Useful values include 0.59 (default, minimizes angular distortion of the continents), 0.68 (gives the closest approximation of the AuthaGraph) and 0.72 (prevents kinks in the graticule). - -# imago.shift([shift]) - -Horizontal shift. Defaults to 1.16. - -# d3.geoTetrahedralLee() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/tetrahedralLee.js), [Examples](https://observablehq.com/@fil/lee-projection) -
# d3.geoLeeRaw - -[ - - world map -](https://observablehq.com/@d3/lees-tetrahedral) - -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](https://observablehq.com/@fil/lee-projection). - -# d3.geoCox() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/cox.js), [Examples](https://observablehq.com/@fil/cox-conformal-projection-in-a-triangle) -
# d3.geoCoxRaw - -[ - - world map -](https://visionscarto.net/cox-conformal-projection) - -The Cox conformal projection. - -# d3.geoComplexLog([planarProjectionRaw[, cutoffLatitude]]) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/complexLog.js), [Example](https://cgmi.github.io/complex-log-projection/) -
# d3.geoComplexLogRaw([planarProjectionRaw]) - -[ - - world map -](https://cgmi.github.io/complex-log-projection/) - -Complex logarithmic view. This projection is based on the papers by Joachim Böttger et al.: - -- [Detail‐In‐Context Visualization for Satellite Imagery (2008)](https://doi.org/10.1111/j.1467-8659.2008.01156.x) -- [Complex Logarithmic Views for Small Details in Large Contexts (2006)](https://doi.org/10.1109/TVCG.2006.126) - -The specified raw projection *planarProjectionRaw* is used to project onto the complex plane on which the complex logarithm is applied. -Recommended are [azimuthal equal-area](https://github.com/d3/d3-geo#geoAzimuthalEqualAreaRaw) (default) or [azimuthal equidistant](https://github.com/d3/d3-geo#geoAzimuthalEquidistantRaw). - -*cutoffLatitude* is the latitude relative to the projection center at which to cutoff/clip the projection, lower values result in more detail around the projection center. Value must be < 0 because complex log projects the origin to infinity. - -# complexLog.planarProjectionRaw([projectionRaw]) - -If *projectionRaw* is specified, sets the planar raw projection. See above. If *projectionRaw* is not specified, returns the current planar raw projection. - -# complexLog.cutoffLatitude([latitude]) - -If *latitude* is specified, sets the cutoff latitude. See above. If *latitude* is not specified, returns the current cutoff latitude. diff --git a/docs/index.md.sh b/docs/index.md.sh new file mode 100644 index 0000000..fa226f8 --- /dev/null +++ b/docs/index.md.sh @@ -0,0 +1,6 @@ +echo "--- +theme: alt +--- +" + +cat README.md