regular grids

riatelab · Oct 14, 2024 · 876ac0c · 876ac0c
1 parent 7fd1b4c
commit 876ac0c
Show file tree

Hide file tree

Showing 90 changed files with 761 additions and 391 deletions.
diff --git a/docs/container_create.js.html b/docs/container_create.js.html
diff --git a/docs/container_draw.js.html b/docs/container_draw.js.html
diff --git a/docs/container_render.js.html b/docs/container_render.js.html
diff --git a/docs/data/search.json b/docs/data/search.json
diff --git a/docs/effect_blur.js.html b/docs/effect_blur.js.html
diff --git a/docs/effect_clippath.js.html b/docs/effect_clippath.js.html
diff --git a/docs/effect_radialgradient.js.html b/docs/effect_radialgradient.js.html
diff --git a/docs/effect_shadow.js.html b/docs/effect_shadow.js.html
diff --git a/docs/global.html b/docs/global.html
diff --git a/docs/grid_arbitrary.js.html b/docs/grid_arbitrary.js.html
diff --git a/docs/grid_diamond.js.html b/docs/grid_diamond.js.html
diff --git a/docs/grid_dot.js.html b/docs/grid_dot.js.html
diff --git a/docs/grid_h3.js.html b/docs/grid_h3.js.html
diff --git a/docs/grid_hexbin.js.html b/docs/grid_hexbin.js.html
diff --git a/docs/grid_make.js.html b/docs/grid_make.js.html
diff --git a/docs/grid_square.js.html b/docs/grid_square.js.html
diff --git a/docs/grid_triangle.js.html b/docs/grid_triangle.js.html
diff --git a/docs/helpers_tooltip.js.html b/docs/helpers_tooltip.js.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/legend_box.js.html b/docs/legend_box.js.html
diff --git a/docs/legend_choro-horizontal.js.html b/docs/legend_choro-horizontal.js.html
diff --git a/docs/legend_choro-vertical.js.html b/docs/legend_choro-vertical.js.html
diff --git a/docs/legend_circles-half.js.html b/docs/legend_circles-half.js.html
diff --git a/docs/legend_circles-nested.js.html b/docs/legend_circles-nested.js.html
diff --git a/docs/legend_circles.js.html b/docs/legend_circles.js.html
diff --git a/docs/legend_mushrooms.js.html b/docs/legend_mushrooms.js.html
diff --git a/docs/legend_spikes.js.html b/docs/legend_spikes.js.html
diff --git a/docs/legend_squares-nested.js.html b/docs/legend_squares-nested.js.html
diff --git a/docs/legend_squares.js.html b/docs/legend_squares.js.html
diff --git a/docs/legend_symbol-horizontal.js.html b/docs/legend_symbol-horizontal.js.html
diff --git a/docs/legend_symbol-vertical.js.html b/docs/legend_symbol-vertical.js.html
diff --git a/docs/legend_typo-horizontal.js.html b/docs/legend_typo-horizontal.js.html
diff --git a/docs/legend_typo-vertical.js.html b/docs/legend_typo-vertical.js.html
diff --git a/docs/mark_circle.js.html b/docs/mark_circle.js.html
diff --git a/docs/mark_footer.js.html b/docs/mark_footer.js.html
diff --git a/docs/mark_graticule.js.html b/docs/mark_graticule.js.html
diff --git a/docs/mark_halfcircle.js.html b/docs/mark_halfcircle.js.html
diff --git a/docs/mark_header.js.html b/docs/mark_header.js.html
diff --git a/docs/mark_north.js.html b/docs/mark_north.js.html
diff --git a/docs/mark_outline.js.html b/docs/mark_outline.js.html
diff --git a/docs/mark_path.js.html b/docs/mark_path.js.html
diff --git a/docs/mark_scalebar.js.html b/docs/mark_scalebar.js.html
diff --git a/docs/mark_spike.js.html b/docs/mark_spike.js.html
diff --git a/docs/mark_square.js.html b/docs/mark_square.js.html
diff --git a/docs/mark_symbol.js.html b/docs/mark_symbol.js.html
diff --git a/docs/mark_text.js.html b/docs/mark_text.js.html
diff --git a/docs/mark_tile.js.html b/docs/mark_tile.js.html
diff --git a/docs/plot_plot.js.html b/docs/plot_plot.js.html
diff --git a/docs/plot_plot_choro.js.html b/docs/plot_plot_choro.js.html
diff --git a/docs/plot_plot_prop.js.html b/docs/plot_plot_prop.js.html
diff --git a/docs/plot_plot_propchoro.js.html b/docs/plot_plot_propchoro.js.html
diff --git a/docs/plot_plot_proptypo.js.html b/docs/plot_plot_proptypo.js.html
diff --git a/docs/plot_plot_symbol.js.html b/docs/plot_plot_symbol.js.html
diff --git a/docs/plot_plot_typo.js.html b/docs/plot_plot_typo.js.html
diff --git a/docs/tool_addfonts.js.html b/docs/tool_addfonts.js.html
diff --git a/docs/tool_centroid.js.html b/docs/tool_centroid.js.html
diff --git a/docs/tool_choro.js.html b/docs/tool_choro.js.html
diff --git a/docs/tool_dissolve.js.html b/docs/tool_dissolve.js.html
diff --git a/docs/tool_dodge.js.html b/docs/tool_dodge.js.html
diff --git a/docs/tool_dotstogrid.js.html b/docs/tool_dotstogrid.js.html
diff --git a/docs/tool_featurecollection.js.html b/docs/tool_featurecollection.js.html
diff --git a/docs/tool_geotable.js.html b/docs/tool_geotable.js.html
diff --git a/docs/tool_height.js.html b/docs/tool_height.js.html
diff --git a/docs/tool_merge.js.html b/docs/tool_merge.js.html
diff --git a/docs/tool_proj4d3.js.html b/docs/tool_proj4d3.js.html
diff --git a/docs/tool_project.js.html b/docs/tool_project.js.html
diff --git a/docs/tool_radius.js.html b/docs/tool_radius.js.html
diff --git a/docs/tool_random.js.html b/docs/tool_random.js.html
diff --git a/docs/tool_replicate.js.html b/docs/tool_replicate.js.html
diff --git a/docs/tool_rewind.js.html b/docs/tool_rewind.js.html
diff --git a/docs/tool_ridge.js.html b/docs/tool_ridge.js.html
diff --git a/docs/tool_symbols.js.html b/docs/tool_symbols.js.html
diff --git a/docs/tool_typo.js.html b/docs/tool_typo.js.html
diff --git a/docs/tool_unproject.js.html b/docs/tool_unproject.js.html
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -53,6 +53,7 @@
     "dicopal": "^0.6.4",
     "docs": "^0.3.2-canary.0",
     "documentation": "^14.0.3",
+    "h3-js": "^4.1.0",
     "rollup": "^4.10.0",
     "statsbreaks": "^1.0.6",
     "versor": "^0.2.0"

diff --git a/src/container/create.js b/src/container/create.js
@@ -32,6 +32,8 @@ import { blur as addblur } from "../effect/blur.js";
 import { shadow as addshadow } from "../effect/shadow.js";
 import { radialGradient as addradialGradient } from "../effect/radialgradient.js";
 
+import { make as addgrid } from "../grid/make.js";
+
 import { circles_nested as addcircles_nested } from "../legend/circles-nested";
 import { circles as addcircles } from "../legend/circles";
 import { squares as addsquares } from "../legend/squares";
@@ -56,6 +58,7 @@ import { plot as addplot } from "../plot/plot.js";
  * @see {@link https://observablehq.com/@neocartocnrs/geoviz}
  *
  * @property {number} [width = 1000] - width of the container.
+ * @property {number} [id = "map"] - id of the svg container.
  * @property {number} [height] - height of the container. This value is automatically calculated according to `domain`. But it can be forced by entering a value.
  * @property {object|object[]} [domain] - the domain corresponds to the geographical area to be displayed. It is defined by a geoJSON or an array containing geoJSONs.
  * @property {function|string} [projection] - d3 function of projection. See [d3-geo](https://github.com/d3/d3-geo) & [d3-geo-projection](https://github.com/d3/d3-geo-projection). You can aslo write "mercator" to use tiles. (default: "none")
@@ -74,6 +77,7 @@ import { plot as addplot } from "../plot/plot.js";
 
 export function create({
   height = null,
+  id = "map",
   //projection = d3.geoEquirectangular(),
   projection = "none",
   domain,
@@ -159,6 +163,7 @@ export function create({
       .create2("svg")
       .attr("width", width)
       .attr("height", height)
+      .attr("id", id)
       .attr("viewBox", [0, 0, width, height])
       .style("background-color", background);
     svg.append("defs").attr("id", "defs");
@@ -208,6 +213,14 @@ export function create({
       })
   );
 
+  let grid = {};
+  [{ id: "make", func: addgrid }].forEach(
+    (d) =>
+      (grid[d.id] = function () {
+        return d.func(output, arguments[0]);
+      })
+  );
+
   let legend = {};
   [
     { id: "circles_nested", func: addcircles_nested },
@@ -250,6 +263,7 @@ export function create({
   return Object.assign(output, {
     ...mark,
     legend,
+    grid,
     effect,
     render: function () {
       return addrender(output, arguments[0]);

diff --git a/src/grid/arbitrary.js b/src/grid/arbitrary.js
@@ -1,6 +1,17 @@
 import { Delaunay } from "d3-delaunay";
 const d3 = Object.assign({}, { Delaunay });
 
+/**
+ * @function grid/arbitrary
+ * @description The `grid.arbitrary` function allows to create an arbitrary geoJSON grid in SVG coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [step = 50] - step of the grid
+ * @property {number} [width = 1000] - width of the grid
+ * @property {number} [height = 500] - height of the grid
+ * @example
+ * geoviz.grid.arbitrary(50, 1000, 500)
+ */
+
 export function arbitrary(step = 50, width = 1000, height = 500) {
   let grid = [];
   let nb = Math.round((width / step) * (height / step));

diff --git a/src/grid/diamond.js b/src/grid/diamond.js
@@ -1,6 +1,16 @@
 import { range } from "d3-array";
 const d3 = Object.assign({}, { range });
 
+/**
+ * @function grid/diamond
+ * @description The `grid.diamond` function allows to create a diamond geoJSON grid in SVG coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [step = 50] - step of the grid
+ * @property {number} [width = 1000] - width of the grid
+ * @property {number} [height = 500] - height of the grid
+ * @example
+ * geoviz.grid.diamond(50, 1000, 500)
+ */
 export function diamond(step = 50, width = 1000, height = 500) {
   let size = step * Math.sqrt(2);
 

diff --git a/src/grid/diamondgeo.js b/src/grid/diamondgeo.js
diff --git a/src/grid/dot.js b/src/grid/dot.js
@@ -1,6 +1,16 @@
 import { range } from "d3-array";
 const d3 = Object.assign({}, { range });
 
+/**
+ * @function grid/dot
+ * @description The `grid.dot` function allows to create a geoJSON vith regular dots in SVG coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [step = 50] - step of the grid
+ * @property {number} [width = 1000] - width of the grid
+ * @property {number} [height = 500] - height of the grid
+ * @example
+ * geoviz.grid.dot(50, 1000, 500)
+ */
 export function dot(step = 30, width = 1000, height = 500) {
   // build grid
   let y = d3.range(0 + step / 2, height, step).reverse();

diff --git a/src/grid/dotgeo.js b/src/grid/dotgeo.js
diff --git a/src/grid/h3.js b/src/grid/h3.js
@@ -0,0 +1,31 @@
+import {
+  getRes0Cells,
+  cellToChildren,
+  isPentagon,
+  cellToBoundary,
+} from "h3-js";
+
+/**
+ * @function grid/h3
+ * @description The `grid.h3` function allows to create a hexbin geoJSON grid in geographical coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [level = 0] - level of the grid. Form 0 (large hexagons) to 4 (small hexagons). See:  https://h3geo.org
+ * @example
+ * geoviz.grid.h3(1)
+ */
+export function h3(level = 0) {
+  return {
+    type: "FeatureCollection",
+    features: getRes0Cells()
+      .map((i) => cellToChildren(i, level))
+      .flat()
+      .map((d) => ({
+        type: "Feature",
+        properties: { id: d, pentagon: isPentagon(d) },
+        geometry: {
+          type: "Polygon",
+          coordinates: [cellToBoundary(d, true).reverse()],
+        },
+      })),
+  };
+}
diff --git a/src/grid/hexbin.js b/src/grid/hexbin.js
@@ -1,6 +1,16 @@
 import { range, max } from "d3-array";
 const d3 = Object.assign({}, { range, max });
 
+/**
+ * @function grid/hexbin
+ * @description The `grid.hexbin` function allows to create a hexbin geoJSON grid in SVG coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [step = 50] - step of the grid
+ * @property {number} [width = 1000] - width of the grid
+ * @property {number} [height = 500] - height of the grid
+ * @example
+ * geoviz.grid.hexbin(50, 1000, 500)
+ */
 export function hexbin(step = 50, width = 1000, height = 500) {
   let w = step;
   let size = w / Math.sqrt(3);

diff --git a/src/grid/make.js b/src/grid/make.js
@@ -1,21 +1,52 @@
 import { square } from "./square.js";
 import { dot } from "./dot.js";
-import { dotgeo } from "./dotgeo.js";
-import { squaregeo } from "./squaregeo.js";
+import { diamond } from "./diamond.js";
+import { arbitrary } from "./arbitrary.js";
+import { hexbin } from "./hexbin.js";
+import { triangle } from "./triangle.js";
+import { h3 } from "./h3.js";
 
-export function make(svg, { step, type = "square" } = {}) {
+/**
+ * @function grid/make
+ * @description The `grid.make` function allows to create a regular grid geoJSON. For all types, For all grid types (except "h3"), the function returns a geojson with svg coordinates in the layout of the page. For type "h3", the function returns geographic coordinates in latitude and longitude.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ *
+ * @property {string} [type = "square"] - Type of grid ("square", "dot", "diamond", "hexbin" (or "hex"), "trangle", "arbitrary" (or "randmon"), "h3" (or "h3geo", "hexgeo", "hexbingeo"))
+ * @property {number} [step = 50] - step of grids (except for "h3" type)
+ * @property {number} [level = 0] - level oh geographical hexbin grids ("h3" type only). Form 0 (large hexagons) to 4 (small hexagons). See:  https://h3geo.org
+ * @example
+ * // There are several ways to use this function
+ * geoviz.grid.make(svg, { type:"diamond", step:100 })  // where svg is the container
+ * svg.grid.make({ type:"diamond", step:100 })  // where svg is the container
+ */
+
+export function make(svg, { step = 50, type = "square", level = 0 } = {}) {
   switch (type) {
     case "square":
       return square(step, svg.width, svg.height);
       break;
+    case "arbitrary":
+    case "random":
+      return arbitrary(step, svg.width, svg.height);
+      break;
     case "dot":
       return dot(step, svg.width, svg.height);
       break;
-    case "dotgeo":
-      return dotgeo(step, svg.domain, svg.projection);
+    case "diamond":
+      return diamond(step, svg.width, svg.height);
+      break;
+    case "hexbin":
+    case "hex":
+      return hexbin(step, svg.width, svg.height);
+      break;
+    case "triangle":
+      return triangle(step, svg.width, svg.height);
       break;
-    case "squaregeo":
-      return squaregeo(step, svg.domain, svg.projection);
+    case "h3":
+    case "h3geo":
+    case "hexgeo":
+    case "hexbingeo":
+      return h3(level);
       break;
   }
 }
diff --git a/src/grid/square.js b/src/grid/square.js
@@ -1,6 +1,16 @@
 import { range } from "d3-array";
 const d3 = Object.assign({}, { range });
 
+/**
+ * @function grid/square
+ * @description The `grid.square` function allows to create a square geoJSON grid in SVG coordinates.
+ * @see {@link https://observablehq.com/@neocartocnrs/regular-grids}
+ * @property {number} [step = 50] - step of the grid
+ * @property {number} [width = 1000] - width of the grid
+ * @property {number} [height = 500] - height of the grid
+ * @example
+ * geoviz.grid.square(50, 1000, 500)
+ */
 export function square(step = 50, width = 1000, height = 500) {
   // build grid
   let y = d3.range(0 + step / 2, height, step).reverse();