clip: geojson (#2243)

* clip: geojson
* All GeoJSON, with a centralized duck typing test
* clip: {type: "Sphere"} is equal to clip: "sphere"
* Add a path factory to the context
* switch/case
* promote "sphere" to {type:"Sphere"}; needs a unique shared object to avoid duplicating the clip-path
* Use a local sphere, simplify memoization
* inline memoizeGeo as an IIFE

---------

Co-authored-by: Mike Bostock <mbostock@gmail.com>

Author: Fil

docs/features/marks.md

@@ -493,7 +493,7 @@ All marks support the following style options:
 * **clip** - whether and how to clip the mark
 * **tip** - whether to generate an implicit [pointer](../interactions/pointer.md) [tip](../marks/tip.md) <VersionBadge version="0.6.7" />
 
-If the **clip** option is *frame* (or equivalently true), the mark is clipped to the frame’s dimensions; if the **clip** option is null (or equivalently false), the mark is not clipped. If the **clip** option is *sphere*, then a [geographic projection](./projections.md) is required and the mark will be clipped to the projected sphere (_e.g._, the front hemisphere when using the orthographic projection).
+If the **clip** option is *frame* (or equivalently true), the mark is clipped to the frame’s dimensions. If the **clip** option is null (or equivalently false), the mark is not clipped. If the **clip** option is *sphere*, the mark will be clipped to the projected sphere (_e.g._, the front hemisphere when using the orthographic projection); a [geographic projection](./projections.md) is required in this case. Lastly if the **clip** option is a GeoJSON object <VersionBadge pr="2243" />, the mark will be clipped to the projected geometry. 
 
 If the **tip** option is true, a [tip mark](../marks/tip.md) with the [pointer transform](../interactions/pointer.md) will be derived from this mark and placed atop all other marks, offering details on demand. If the **tip** option is set to an options object, these options will be passed to the derived tip mark. If the **tip** option (or, if an object, its **pointer** option) is set to *x*, *y*, or *xy*, [pointerX](../interactions/pointer.md#pointerX), [pointerY](../interactions/pointer.md#pointerY), or [pointer](../interactions/pointer.md#pointer) will be used, respectively; otherwise the pointing mode will be chosen automatically. (If the **tip** mark option is truthy, the **title** channel is no longer applied using an SVG title element as this would conflict with the tip mark.)
 

src/context.d.ts

@@ -1,4 +1,4 @@
-import type {GeoStreamWrapper} from "d3";
+import type {GeoPath, GeoStreamWrapper} from "d3";
 import type {MarkOptions} from "./mark.js";
 
 /** Additional rendering context provided to marks and initializers. */
@@ -18,6 +18,9 @@ export interface Context {
   /** The current projection, if any. */
   projection?: GeoStreamWrapper;
 
+  /** A function to draw GeoJSON with the current projection, if any, otherwise with the x and y scales. */
+  path: () => GeoPath;
+
   /** The default clip for all marks. */
   clip?: MarkOptions["clip"];
 }

src/mark.d.ts

@@ -1,3 +1,4 @@
+import type {GeoPermissibleObjects} from "d3";
 import type {Channel, ChannelDomainSort, ChannelValue, ChannelValues, ChannelValueSpec} from "./channel.js";
 import type {Context} from "./context.js";
 import type {Dimensions} from "./dimensions.js";
@@ -296,11 +297,12 @@ export interface MarkOptions {
    *
    * - *frame* or true - clip to the plot’s frame (inner area)
    * - *sphere* - clip to the projected sphere (*e.g.*, front hemisphere)
+   * - geojson - a GeoJSON object, typically with polygonal geometry
    * - null or false - do not clip
    *
    * The *sphere* clip option requires a geographic projection.
    */
-  clip?: "frame" | "sphere" | boolean | null;
+  clip?: "frame" | "sphere" | GeoPermissibleObjects | boolean | null;
 
   /**
    * The horizontal offset in pixels; a constant option. On low-density screens,

src/marks/geo.js

@@ -1,4 +1,4 @@
-import {geoGraticule10, geoPath, geoTransform} from "d3";
+import {geoGraticule10} from "d3";
 import {create} from "../context.js";
 import {negative, positive} from "../defined.js";
 import {Mark} from "../mark.js";
@@ -35,7 +35,7 @@ export class Geo extends Mark {
   }
   render(index, scales, channels, dimensions, context) {
     const {geometry: G, r: R} = channels;
-    const path = geoPath(context.projection ?? scaleProjection(scales));
+    const path = context.path();
     const {r} = this;
     if (negative(r)) index = [];
     else if (r !== undefined) path.pointRadius(r);
@@ -55,20 +55,6 @@ export class Geo extends Mark {
   }
 }
 
-// If no projection is specified, default to a projection that passes points
-// through the x and y scales, if any.
-function scaleProjection({x: X, y: Y}) {
-  if (X || Y) {
-    X ??= (x) => x;
-    Y ??= (y) => y;
-    return geoTransform({
-      point(x, y) {
-        this.stream.point(X(x), Y(y));
-      }
-    });
-  }
-}
-
 export function geo(data, options = {}) {
   if (options.tip && options.x === undefined && options.y === undefined) options = centroid(options);
   else if (options.geometry === undefined) options = {...options, geometry: identity};

src/options.js

@@ -169,11 +169,24 @@ export function dataify(data) {
 export function arrayify(values) {
   if (values == null || isArray(values)) return values;
   if (isArrowVector(values)) return maybeTypedArrowify(values);
-  switch (values.type) {
+  if (isGeoJSON(values)) {
+    switch (values.type) {
+      case "FeatureCollection":
+        return values.features;
+      case "GeometryCollection":
+        return values.geometries;
+      default:
+        return [values];
+    }
+  }
+  return Array.from(values);
+}
+
+// Duck typing test for GeoJSON
+function isGeoJSON(x) {
+  switch (x?.type) {
     case "FeatureCollection":
-      return values.features;
     case "GeometryCollection":
-      return values.geometries;
     case "Feature":
     case "LineString":
     case "MultiLineString":
@@ -182,9 +195,10 @@ export function arrayify(values) {
     case "Point":
     case "Polygon":
     case "Sphere":
-      return [values];
+      return true;
+    default:
+      return false;
   }
-  return Array.from(values);
 }
 
 // An optimization of type.from(values, f): if the given values are already an
@@ -602,12 +616,13 @@ export function maybeNamed(things) {
   return isIterable(things) ? named(things) : things;
 }
 
-// TODO Accept other types of clips (paths, urls, x, y, other marks…)?
-// https://github.com/observablehq/plot/issues/181
 export function maybeClip(clip) {
   if (clip === true) clip = "frame";
   else if (clip === false) clip = null;
-  else if (clip != null) clip = keyword(clip, "clip", ["frame", "sphere"]);
+  else if (!isGeoJSON(clip) && clip != null) {
+    clip = keyword(clip, "clip", ["frame", "sphere"]);
+    if (clip === "sphere") clip = {type: "Sphere"};
+  }
   return clip;
 }
 

src/plot.js

@@ -1,4 +1,4 @@
-import {creator, select} from "d3";
+import {creator, geoPath, select} from "d3";
 import {createChannel, inferChannelScale} from "./channel.js";
 import {createContext} from "./context.js";
 import {createDimensions} from "./dimensions.js";
@@ -11,7 +11,7 @@ import {frame} from "./marks/frame.js";
 import {tip} from "./marks/tip.js";
 import {isColor, isIterable, isNone, isScaleOptions} from "./options.js";
 import {dataify, lengthof, map, yes, maybeIntervalTransform, subarray} from "./options.js";
-import {createProjection, getGeometryChannels, hasProjection} from "./projection.js";
+import {createProjection, getGeometryChannels, hasProjection, xyProjection} from "./projection.js";
 import {createScales, createScaleFunctions, autoScaleRange, exposeScales} from "./scales.js";
 import {innerDimensions, outerDimensions} from "./scales.js";
 import {isPosition, registry as scaleRegistry} from "./scales/index.js";
@@ -236,6 +236,11 @@ export function plot(options = {}) {
     facetTranslate = facetTranslator(fx, fy, dimensions);
   }
 
+  // A path generator for marks that want to draw GeoJSON.
+  context.path = function () {
+    return geoPath(this.projection ?? xyProjection(scales));
+  };
+
   // Compute value objects, applying scales and projection as needed.
   for (const [mark, state] of stateByMark) {
     state.values = mark.scale(state.channels, scales, context);

src/projection.js

@@ -296,3 +296,17 @@ export function getGeometryChannels(channel) {
   for (const object of channel.value) geoStream(object, sink);
   return [x, y];
 }
+
+// If no projection is specified, default to a projection that passes points
+// through the x and y scales, if any.
+export function xyProjection({x: X, y: Y}) {
+  if (X || Y) {
+    X ??= (x) => x;
+    Y ??= (y) => y;
+    return geoTransform({
+      point(x, y) {
+        this.stream.point(X(x), Y(y));
+      }
+    });
+  }
+}

src/style.js

@@ -1,4 +1,4 @@
-import {geoPath, group, namespaces, select} from "d3";
+import {group, namespaces, select} from "d3";
 import {create} from "./context.js";
 import {defined, nonempty} from "./defined.js";
 import {formatDefault} from "./format.js";
@@ -306,24 +306,20 @@ export function* groupIndex(I, position, mark, channels) {
 function applyClip(selection, mark, dimensions, context) {
   let clipUrl;
   const {clip = context.clip} = mark;
-  switch (clip) {
-    case "frame": {
-      // Wrap the G element with another (untransformed) G element, applying the
-      // clip to the parent G element so that the clip path is not affected by
-      // the mark’s transform. To simplify the adoption of this fix, mutate the
-      // passed-in selection.node to return the parent G element.
-      selection = create("svg:g", context).each(function () {
-        this.appendChild(selection.node());
-        selection.node = () => this; // Note: mutation!
-      });
-      clipUrl = getFrameClip(context, dimensions);
-      break;
-    }
-    case "sphere": {
-      clipUrl = getProjectionClip(context);
-      break;
-    }
+  if (clip === "frame") {
+    // Wrap the G element with another (untransformed) G element, applying the
+    // clip to the parent G element so that the clip path is not affected by
+    // the mark’s transform. To simplify the adoption of this fix, mutate the
+    // passed-in selection.node to return the parent G element.
+    selection = create("svg:g", context).each(function () {
+      this.appendChild(selection.node());
+      selection.node = () => this; // Note: mutation!
+    });
+    clipUrl = getFrameClip(context, dimensions);
+  } else if (clip) {
+    clipUrl = getGeoClip(clip, context);
   }
+
   // Here we’re careful to apply the ARIA attributes to the outer G element when
   // clipping is applied, and to apply the ARIA attributes before any other
   // attributes (for readability).
@@ -356,11 +352,21 @@ const getFrameClip = memoizeClip((clipPath, context, dimensions) => {
     .attr("height", height - marginTop - marginBottom);
 });
 
-const getProjectionClip = memoizeClip((clipPath, context) => {
-  const {projection} = context;
-  if (!projection) throw new Error(`the "sphere" clip option requires a projection`);
-  clipPath.append("path").attr("d", geoPath(projection)({type: "Sphere"}));
-});
+const getGeoClip = (function () {
+  const cache = new WeakMap();
+  const sphere = {type: "Sphere"};
+  return (geo, context) => {
+    let c, url;
+    if (!(c = cache.get(context))) cache.set(context, (c = new WeakMap()));
+    if (geo.type === "Sphere") geo = sphere; // coalesce all spheres.
+    if (!(url = c.get(geo))) {
+      const id = getClipId();
+      select(context.ownerSVGElement).append("clipPath").attr("id", id).append("path").attr("d", context.path()(geo));
+      c.set(geo, (url = `url(#${id})`));
+    }
+    return url;
+  };
+})();
 
 // Note: may mutate selection.node!
 export function applyIndirectStyles(selection, mark, dimensions, context) {