From b27f6c9ae3c3dd19a862408754297af2084fe0a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Sun, 3 Nov 2024 10:40:42 +0100 Subject: [PATCH] reorganize the README --- README.md | 223 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 117 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index 0f19ffc..47bdb2e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Clipping and geometric operations for spherical polygons. - world map + world map ```js run=false @@ -23,6 +23,15 @@ const projection = geoEquirectangular() ## Installing +In Observable Framework, [import](https://observablehq.com/framework/imports) with the `npm:` protocol: + +```html run=false + +``` + 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 @@ -72,100 +81,6 @@ Given two spherical arcs [point0, point1] and [point2, point3], returns their in ## 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 projections’ default **clipPoint** depends on whether the clipping polygon covers the whole sphere. When the polygon’s area is almost complete (larger than 4π minus .1 steradian), clipPoint is set to false, and all point geometries are displayed, even if they (technically) fall outside the clipping polygon. For smaller polygons, clipPoint defaults to true, thus hiding points outside the clipping region. - -# 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. - -# d3.geoTwoPointEquidistant(point0, point1) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -The two-point equidistant projection, displaying 99.9996% of the sphere thanks to polygon clipping. - -# d3.geoTwoPointEquidistantUsa() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) - -[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. - -### New projections - New projections are introduced: # d3.geoPolyhedralVoronoi([parents], [polygons], [faceProjection], [faceFind]) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/polyhedral/voronoi.js) @@ -180,50 +95,50 @@ 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) -[world map](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) +[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) +[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) +[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) +[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) +[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/) +[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/) +[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). @@ -238,7 +153,7 @@ 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) +[world map](https://observablehq.com/@d3/lees-tetrahedral) Lee’s tetrahedral conformal projection. @@ -249,14 +164,14 @@ 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 -[world map](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]) -[world map](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.: @@ -275,3 +190,99 @@ If *projectionRaw* is specified, sets the planar raw projection. See above. If * # complexLog.cutoffLatitude([latitude]) If *latitude* is specified, sets the cutoff latitude. See above. If *latitude* is not specified, returns the current cutoff latitude. + +## Updated 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 projections’ default **clipPoint** depends on whether the clipping polygon covers the whole sphere. When the polygon’s area is almost complete (larger than 4π minus .1 steradian), clipPoint is set to false, and all point geometries are displayed, even if they (technically) fall outside the clipping polygon. For smaller polygons, clipPoint defaults to true, thus hiding points outside the clipping region. + +# 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. + +# d3.geoTwoPointEquidistant(point0, point1) · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) + +The two-point equidistant projection, displaying 99.9996% of the sphere thanks to polygon clipping. + +# d3.geoTwoPointEquidistantUsa() · [Source](https://github.com/d3/d3-geo-polygon/blob/main/src/reclip.js) + +[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. + +*Note:* These re-clipped projections are not supported in the legacy UMD bundle.