Plot.poi uses @mapbox/polylabel to derive centroids

Author: Fil

Diff for: package.json

@@ -89,7 +89,8 @@
   "dependencies": {
     "d3": "^7.9.0",
     "interval-tree-1d": "^1.0.0",
-    "isoformat": "^0.2.0"
+    "isoformat": "^0.2.0",
+    "polylabel": "^2.0.0"
   },
   "engines": {
     "node": ">=12"

Diff for: src/index.js

@@ -41,7 +41,7 @@ export {Vector, vector, vectorX, vectorY, spike} from "./marks/vector.js";
 export {valueof, column, identity, indexOf} from "./options.js";
 export {filter, reverse, sort, shuffle, basic as transform, initializer} from "./transforms/basic.js";
 export {bin, binX, binY} from "./transforms/bin.js";
-export {centroid, geoCentroid} from "./transforms/centroid.js";
+export {centroid, geoCentroid, poi} from "./transforms/centroid.js";
 export {dodgeX, dodgeY} from "./transforms/dodge.js";
 export {find, group, groupX, groupY, groupZ} from "./transforms/group.js";
 export {hexbin} from "./transforms/hexbin.js";

Diff for: src/marks/geo.js

@@ -4,7 +4,7 @@ import {negative, positive} from "../defined.js";
 import {Mark} from "../mark.js";
 import {identity, maybeNumberChannel} from "../options.js";
 import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform} from "../style.js";
-import {centroid} from "../transforms/centroid.js";
+import {poi} from "../transforms/centroid.js";
 import {withDefaultSort} from "./dot.js";
 
 const defaults = {
@@ -70,7 +70,7 @@ function scaleProjection({x: X, y: Y}) {
 }
 
 export function geo(data, options = {}) {
-  if (options.tip && options.x === undefined && options.y === undefined) options = centroid(options);
+  if (options.tip && options.x === undefined && options.y === undefined) options = poi(options);
   else if (options.geometry === undefined) options = {...options, geometry: identity};
   return new Geo(data, options);
 }

Diff for: src/transforms/centroid.d.ts

@@ -20,6 +20,21 @@ export interface CentroidOptions {
  */
 export function centroid<T>(options?: T & CentroidOptions): Initialized<T>;
 
+/**
+ * Given a **geometry** input channel of GeoJSON geometry, derives **x** and
+ * **y** output channels representing the point that gives the largest possible
+ * ellipse of horizontal to vertical ratio 2 inscribed in Polygon or
+ * MultiPolygon geometries, and the classic centroid for point and line
+ * geometries. Usually a good place to anchor a label, an interactive tip, or a
+ * representative dot for a voronoi mesh. The pois are computed in screen
+ * coordinates according to the plot’s associated **projection** (or *x* and *y*
+ * scales), if any.
+ *
+ * For classic centroids, see Plot.centroid; for centroids of spherical
+ * geometry, see Plot.geoCentroid.
+ */
+export function poi<T>(options?: T & CentroidOptions): Initialized<T>;
+
 /**
  * Given a **geometry** input channel of spherical GeoJSON geometry, derives
  * **x** and **y** output channels representing the spherical centroids of the

Diff for: src/transforms/centroid.js

@@ -1,7 +1,8 @@
-import {geoCentroid as GeoCentroid, geoPath} from "d3";
+import {geoCentroid as GeoCentroid, geoPath, greatest, polygonArea, polygonContains} from "d3";
 import {memoize1} from "../memoize.js";
 import {identity, valueof} from "../options.js";
 import {initializer} from "./basic.js";
+import polylabel from "polylabel";
 
 export function centroid({geometry = identity, ...options} = {}) {
   const getG = memoize1((data) => valueof(data, geometry));
@@ -28,6 +29,55 @@ export function centroid({geometry = identity, ...options} = {}) {
   );
 }
 
+export function poi({geometry = identity, ...options} = {}) {
+  const getG = memoize1((data) => valueof(data, geometry));
+  return initializer(
+    {...options, x: null, y: null, geometry: {transform: getG}},
+    (data, facets, channels, scales, dimensions, {projection}) => {
+      const G = getG(data);
+      const n = G.length;
+      const X = new Float64Array(n);
+      const Y = new Float64Array(n);
+      let polygons, holes, ring;
+      const alpha = 2;
+      const context = {
+        arc() {},
+        moveTo(x, y) {
+          ring = [[x, -alpha * y]];
+        },
+        lineTo(x, y) {
+          ring.push([x, -alpha * y]);
+        },
+        closePath() {
+          ring.push(ring[0]);
+          if (polygonArea(ring) > 0) polygons.push([ring]);
+          else holes.push(ring);
+        }
+      };
+      const path = geoPath(projection, context);
+      for (let i = 0; i < n; ++i) {
+        polygons = [];
+        holes = [];
+        path(G[i]);
+        for (const h of holes) polygons.find(([ring]) => polygonContains(ring, h[0]))?.push(h);
+        const a = greatest(
+          polygons.map((d) => polylabel(d, 0.01)),
+          (d) => d.distance
+        );
+        [X[i], Y[i]] = a ? [a[0], -a[1] / alpha] : path.centroid(G[i]);
+      }
+      return {
+        data,
+        facets,
+        channels: {
+          x: {value: X, scale: projection == null ? "x" : null, source: null},
+          y: {value: Y, scale: projection == null ? "y" : null, source: null}
+        }
+      };
+    }
+  );
+}
+
 export function geoCentroid({geometry = identity, ...options} = {}) {
   const getG = memoize1((data) => valueof(data, geometry));
   const getC = memoize1((data) => valueof(getG(data), GeoCentroid));

Diff for: test/output/countryPois.svg

@@ -18,3 +18,20 @@ export async function countryCentroids() {
     ]
   });
 }
+
+export async function countryPois() {
+  const world = await d3.json<any>("data/countries-110m.json");
+  const land = feature(world, world.objects.land);
+  const countries = feature(world, world.objects.countries);
+  return Plot.plot({
+    projection: "orthographic",
+    marks: [
+      Plot.graticule(),
+      Plot.geo(land, {fill: "#ddd"}),
+      Plot.geo(countries, {stroke: "#fff"}),
+      Plot.text(countries, Plot.geoCentroid({fill: "red", text: "id"})),
+      Plot.text(countries, Plot.poi({fill: "green", text: "id"})),
+      Plot.frame()
+    ]
+  });
+}

Diff for: test/output/geoTipPoi.svg

@@ -60,6 +60,30 @@ export async function geoTipCentroid() {
   });
 }
 
+/** The geo mark with the tip option and the poi transform. */
+export async function geoTipPoi() {
+  const [london, boroughs] = await getLondonBoroughs();
+  const access = await getLondonAccess();
+  return Plot.plot({
+    width: 900,
+    projection: {type: "transverse-mercator", rotate: [2, 0, 0], domain: london},
+    color: {scheme: "RdYlBu", pivot: 0.5},
+    marks: [
+      Plot.geo(
+        access,
+        Plot.poi({
+          fx: "year",
+          geometry: (d) => boroughs.get(d.borough),
+          fill: "access",
+          stroke: "var(--plot-background)",
+          strokeWidth: 0.75,
+          channels: {borough: "borough"},
+          tip: true
+        })
+      )
+    ]
+  });
+}
 /** The geo mark with the tip option and the geoCentroid transform. */
 export async function geoTipGeoCentroid() {
   const [london, boroughs] = await getLondonBoroughs();

Diff for: test/plots/country-centroids.ts

@@ -2896,6 +2896,13 @@ picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.3.1:
   resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
+polylabel@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/polylabel/-/polylabel-2.0.0.tgz#9c5f2a290a6b48b37b4b13c99ca5c4ea521facbb"
+  integrity sha512-iH6nrGEf8imzlmGqKJ0fXoTjmPREvjbEzAK8LflNvAN9NFwe9FRYpIa+R7l6DJRvkXh5P6/WimlO9YcK+JtIBQ==
+  dependencies:
+    tinyqueue "^2.0.3"
+
 postcss@^8.4.38:
   version "8.4.38"
   resolved "https://registry.yarnpkg.com/postcss/-/postcss-8.4.38.tgz#b387d533baf2054288e337066d81c6bee9db9e0e"
@@ -3297,6 +3304,11 @@ text-table@^0.2.0:
   resolved "https://registry.yarnpkg.com/text-table/-/text-table-0.2.0.tgz#7f5ee823ae805207c00af2df4a84ec3fcfa570b4"
   integrity sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==
 
+tinyqueue@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/tinyqueue/-/tinyqueue-2.0.3.tgz#64d8492ebf39e7801d7bd34062e29b45b2035f08"
+  integrity sha512-ppJZNDuKGgxzkHihX8v9v9G5f+18gzaTfrukGrq6ueg0lmH4nqVnA2IPG0AEH3jKEk2GRJCUhDoqpoiw3PHLBA==
+
 to-regex-range@^5.0.1:
   version "5.0.1"
   resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4"