geometries and projections

README.md

@@ -311,6 +311,35 @@ Plot automatically generates axes for position scales. You can configure these a
 
 Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**.
 
+### Projection options
+
+The top-level **projection** option applies a (often geographic) projection in place of *x* and *y* scales. It is typically used in conjunction with [geometry marks](#geometry) to produce a map, but can be used with any mark that supports *x* and *y*, such as [dot](#dot) and [text](#text). The following built-in named projections are supported:
+
+* *equirectangular* - the equirectangular, or *plate carrée*, projection
+* *orthographic* - the orthographic projection
+* *stereographic* - the stereographic projection
+* *mercator* - the Mercator projection
+* *equal-earth* - the [Equal Earth projection](https://en.wikipedia.org/wiki/Equal_Earth_projection) by Šavrič *et al.*
+* *natural-earth* - the [Natural Earth projection](https://en.wikipedia.org/wiki/Natural_Earth_projection) by Patterson
+* *azimuthal-equal-area* - the azimuthal equal-area projection
+* *azimuthal-equidistant* - the azimuthal equidistant projection
+* *conic-conformal* - the conic conformal projection
+* *conic-equal-area* - the conic equal-area projection
+* *conic-equidistant* - the conic equidistant projection
+* *gnomonic* - the gnomonic projection
+* *transverse-mercator* - the transverse Mercator projection
+* *albers* - the Albers’ equal-area conic projection
+* *albers-usa* - a composite Albers conic equal-area projection suitable for the United States
+* *identity* - the identity projection (for pre-projected geometry)
+
+In addition to the named projections above, the **projection** option may also be specified as a [D3 projection](https://github.com/d3/d3-geo/blob/main/README.md#projections), or any custom projection that implements [*projection*.stream](https://github.com/d3/d3-geo/blob/main/README.md#projection_stream), or a function that receives a configuration object ({width, height, ...options}) and returns a projection.
+
+If the **projection** option is specified as an object, the following additional projection options are supported:
+
+* projection.**type** - one of the projection names above
+* projection.**rotate** - a two- or three- element array of Euler angles to rotate the sphere
+* projection.**precision** - the [sampling threshold](https://github.com/d3/d3-geo/blob/main/README.md#projection_precision)
+
 ### Color options
 
 The normal scale types—*linear*, *sqrt*, *pow*, *log*, *symlog*, and *ordinal*—can be used to encode color. In addition, Plot supports special scale types for color:
@@ -1209,6 +1238,28 @@ Equivalent to [Plot.dot](#plotdotdata-options) except that the **symbol** option
 
 <!-- jsdocEnd hexagon -->
 
+### Geometry
+
+[Source](./src/marks/geometry.js) · [Examples](https://observablehq.com/@observablehq/plot-geometry) · Draws polygons, lines, points, and other GeoJSON geometry, often in conjunction with a [geographic projection](#projection-options) to produce a thematic map. The **geometry** option specifies the geometry (GeoJSON object) to draw for each geometry instance; if not specified, the mark’s *data* is assumed to be GeoJSON.
+
+#### Plot.geometry(*data*, *options*)
+
+```js
+Plot.geometry(counties, {fill: d => d.properties.rate})
+```
+
+Returns a new geometry mark with the given *data* and *options*. If *data* is a GeoJSON feature collection, then the mark’s data is *data*.features; if *data* is a GeoJSON geometry collection, then the mark’s data is *data*.geometries; if *data* is some other GeoJSON object, then the mark’s data is a single-element array of [*data*]. If the **geometry** option is not specified, *data* is assumed to be a GeoJSON object or an array of GeoJSON objects.
+
+In addition to the [standard mark options](#marks), the optional **r** channel can be specified to indicate the effective radius (in pixels) of Point and MultiPoint geometries. When the radius is specified as a number, it is interpreted as a constant, which defaults to 3 pixels; otherwise it is interpreted as a channel, and uses the *r* scale. Features (or geometries) with a nonpositive radius are not drawn.
+
+#### Plot.sphere(*options*)
+
+Returns a new geometry mark with a *Sphere* geometry object and the given *options*.
+
+#### Plot.graticule(*options*)
+
+Returns a new geometry mark with a [default 10° global graticule](https://github.com/d3/d3-geo/blob/main/README.md#geoGraticule10) geometry object and the given *options*.
+
 ### Hexgrid
 
 The hexgrid mark can be used to support marks using the [hexbin](#hexbin) layout.

package.json

@@ -52,6 +52,7 @@
     "@typescript-eslint/eslint-plugin": "^5.25.0",
     "@typescript-eslint/parser": "^5.25.0",
     "canvas": "2",
+    "d3-geo-projection": "^4.0.0",
     "eslint": "^8.16.0",
     "eslint-config-prettier": "^8.5.0",
     "get-tsconfig": "^4.1.0",
@@ -65,6 +66,7 @@
     "prettier": "^2.7.1",
     "rollup": "2",
     "rollup-plugin-terser": "7",
+    "topojson-client": "^3.1.0",
     "tsx": "^3.8.0",
     "typescript": "^4.6.4",
     "typescript-module-alias": "^1.0.2",

src/channel.js

@@ -1,5 +1,6 @@
 import {ascending, descending, rollup, sort} from "d3";
 import {first, isIterable, labelof, map, maybeValue, range, valueof} from "./options.js";
+import {applyProjection} from "./projection.js";
 import {registry} from "./scales/index.js";
 import {maybeReduce} from "./transforms/group.js";
 
@@ -24,13 +25,37 @@ export function Channels(descriptors, data) {
 }
 
 // TODO Use Float64Array for scales with numeric ranges, e.g. position?
-export function valueObject(channels, scales) {
-  return Object.fromEntries(
+export function valueObject(channels, scales, {projection}) {
+  let x, y; // names of channels bound to x and y scale
+
+  const values = Object.fromEntries(
     Object.entries(channels).map(([name, {scale: scaleName, value}]) => {
-      const scale = scales[scaleName];
+      let scale;
+      if (scaleName !== undefined) {
+        if (scaleName === "x") x = x === undefined ? name : "*";
+        else if (scaleName === "y") y = y === undefined ? name : "*";
+        scale = scales[scaleName];
+      }
       return [name, scale === undefined ? value : map(value, scale)];
     })
   );
+
+  // If there is a projection, and there are both x and y channels, and those x
+  // and y channels are associated with the x and y scale respectively (and not
+  // already in screen coordinates as with an initializer), then apply the
+  // projection, replacing the x and y values. Note that the x and y scales
+  // themselves don’t exist if there is a projection, but whether the channels
+  // are associated with scales still determines whether the projection should
+  // apply; think of the projection as a combination xy-scale.
+  if (projection) {
+    if (x === "x" && y === "y") {
+      applyProjection(values, projection);
+    } else if (x || y) {
+      throw new Error("projection requires x and y channels");
+    }
+  }
+
+  return values;
 }
 
 // Note: mutates channel.domain! This is set to a function so that it is lazily

src/context.js

@@ -1,7 +1,11 @@
 import {creator, select} from "d3";
+import {maybeProjection} from "./projection.js";
 
-export function Context({document = window.document} = {}) {
-  return {document};
+export function Context(
+  {document = typeof window !== "undefined" ? window.document : undefined, projection} = {},
+  dimensions
+) {
+  return {document, projection: maybeProjection(projection, dimensions)};
 }
 
 export function create(name, {document}) {

src/dimensions.js

@@ -1,12 +1,15 @@
+import {isProjection} from "./projection.js";
 import {isOrdinalScale} from "./scales.js";
 import {offset} from "./style.js";
 
 export function Dimensions(
   scales,
+  geometry,
   {x: {axis: xAxis} = {}, y: {axis: yAxis} = {}, fx: {axis: fxAxis} = {}, fy: {axis: fyAxis} = {}},
   {
+    projection,
     width = 640,
-    height = autoHeight(scales),
+    height = autoHeight(scales, geometry || isProjection(projection)),
     facet: {
       margin: facetMargin,
       marginTop: facetMarginTop = facetMargin !== undefined ? facetMargin : fxAxis === "top" ? 30 : 0,
@@ -43,8 +46,8 @@ export function Dimensions(
   };
 }
 
-function autoHeight({y, fy, fx}) {
+function autoHeight({y, fy, fx}, geometry) {
   const nfy = fy ? fy.scale.domain().length : 1;
-  const ny = y ? (isOrdinalScale(y) ? y.scale.domain().length : Math.max(7, 17 / nfy)) : 1;
-  return !!(y || fy) * Math.max(1, Math.min(60, ny * nfy)) * 20 + !!fx * 30 + 60;
+  const ny = y ? (isOrdinalScale(y) ? y.scale.domain().length : Math.max(7, 17 / nfy)) : geometry ? 17 : 1;
+  return !!(y || fy || geometry) * Math.max(1, Math.min(60, ny * nfy)) * 20 + !!fx * 30 + 60;
 }

src/index.js

@@ -8,6 +8,7 @@ export {delaunayLink, delaunayMesh, hull, voronoi, voronoiMesh} from "./marks/de
 export {Density, density} from "./marks/density.js";
 export {Dot, dot, dotX, dotY, circle, hexagon} from "./marks/dot.js";
 export {Frame, frame} from "./marks/frame.js";
+export {Geometry, geometry, sphere, graticule} from "./marks/geometry.js";
 export {Hexgrid, hexgrid} from "./marks/hexgrid.js";
 export {Image, image} from "./marks/image.js";
 export {Line, line, lineX, lineY} from "./marks/line.js";

src/marks/area.js

@@ -46,7 +46,7 @@ export class Area extends Mark {
   render(index, scales, channels, dimensions, context) {
     const {x1: X1, y1: Y1, x2: X2 = X1, y2: Y2 = Y1} = channels;
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
       .call(applyTransform, this, scales, 0, 0)
       .call((g) =>
         g

src/marks/arrow.js

@@ -66,7 +66,7 @@ export class Arrow extends Mark {
     const wingScale = headLength / 1.5;
 
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
       .call(applyTransform, this, scales)
       .call((g) =>
         g

src/marks/bar.js

@@ -28,7 +28,7 @@ export class AbstractBar extends Mark {
   render(index, scales, channels, dimensions, context) {
     const {rx, ry} = this;
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
       .call(this._transform, this, scales)
       .call((g) =>
         g

src/marks/delaunay.js

@@ -65,6 +65,7 @@ class DelaunayLink extends Mark {
     markers(this, options);
   }
   render(index, scales, channels, dimensions, context) {
+    const {x, y} = scales;
     const {x: X, y: Y, z: Z} = channels;
     const {curve} = this;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
@@ -123,8 +124,8 @@ class DelaunayLink extends Mark {
     }
 
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
-      .call(applyTransform, this, scales)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
+      .call(applyTransform, this, {x: X && x, y: Y && y})
       .call(
         Z
           ? (g) =>
@@ -155,6 +156,7 @@ class AbstractDelaunayMark extends Mark {
     );
   }
   render(index, scales, channels, dimensions, context) {
+    const {x, y} = scales;
     const {x: X, y: Y, z: Z} = channels;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     const xi = X ? (i) => X[i] : constant(cx);
@@ -172,8 +174,8 @@ class AbstractDelaunayMark extends Mark {
     }
 
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
-      .call(applyTransform, this, scales)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
+      .call(applyTransform, this, {x: X && x, y: Y && y})
       .call(
         Z
           ? (g) =>
@@ -223,6 +225,7 @@ class Voronoi extends Mark {
     );
   }
   render(index, scales, channels, dimensions, context) {
+    const {x, y} = scales;
     const {x: X, y: Y, z: Z} = channels;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     const xi = X ? (i) => X[i] : constant(cx);
@@ -242,8 +245,8 @@ class Voronoi extends Mark {
     }
 
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
-      .call(applyTransform, this, scales)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
+      .call(applyTransform, this, {x: X && x, y: Y && y})
       .call(
         Z
           ? (g) =>

src/marks/density.js

@@ -1,5 +1,6 @@
 import {contourDensity, create, geoPath} from "d3";
-import {identity, isTypedArray, maybeTuple, maybeZ, valueof} from "../options.js";
+import {valueObject} from "../channel.js";
+import {isTypedArray, maybeTuple, maybeZ} from "../options.js";
 import {Mark} from "../plot.js";
 import {coerceNumbers} from "../scales.js";
 import {
@@ -49,8 +50,8 @@ export class Density extends Mark {
     const {contours} = channels;
     const path = geoPath();
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
-      .call(applyTransform, this, scales)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
+      .call(applyTransform, this, {})
       .call((g) =>
         g
           .selectAll()
@@ -84,15 +85,28 @@ function densityInitializer(options, fillDensity, strokeDensity) {
       : typeof thresholds?.[Symbol.iterator] === "function"
       ? coerceNumbers(thresholds)
       : +thresholds;
-  return initializer(options, function (data, facets, channels, scales, dimensions) {
-    const X = channels.x ? coerceNumbers(valueof(channels.x.value, scales[channels.x.scale] || identity)) : null;
-    const Y = channels.y ? coerceNumbers(valueof(channels.y.value, scales[channels.y.scale] || identity)) : null;
+  return initializer(options, function (data, facets, channels, scales, dimensions, context) {
     const W = channels.weight ? coerceNumbers(channels.weight.value) : null;
     const Z = channels.z?.value;
     const {z} = this;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     const {width, height} = dimensions;
 
+    // Extract the scaled (or projected!) values for the x and y channels.
+    let {x: X, y: Y} = valueObject(
+      {
+        ...(channels.x && {x: channels.x}),
+        ...(channels.y && {y: channels.y})
+      },
+      scales,
+      context
+    );
+
+    // Coerce the x and y channels to numbers (so that null is properly treated
+    // as an undefined value rather than being coerced to zero).
+    if (X) X = coerceNumbers(X);
+    if (Y) Y = coerceNumbers(Y);
+
     // Group any of the input channels according to the first index associated
     // with each z-series or facet. Drop any channels not be needed for
     // rendering after the contours are computed.

src/marks/dot.js

@@ -21,6 +21,12 @@ const defaults = {
   strokeWidth: 1.5
 };
 
+export function withDefaultSort(options) {
+  return options.sort === undefined && options.reverse === undefined
+    ? sort({channel: "r", order: "descending"}, options)
+    : options;
+}
+
 export class Dot extends Mark {
   constructor(data, options = {}) {
     const {x, y, r, rotate, symbol = symbolCircle, frameAnchor} = options;
@@ -36,9 +42,7 @@ export class Dot extends Mark {
         rotate: {value: vrotate, optional: true},
         symbol: {value: vsymbol, scale: "symbol", optional: true}
       },
-      options.sort === undefined && options.reverse === undefined
-        ? sort({channel: "r", order: "descending"}, options)
-        : options,
+      withDefaultSort(options),
       defaults
     );
     this.r = cr;
@@ -60,12 +64,13 @@ export class Dot extends Mark {
     }
   }
   render(index, scales, channels, dimensions, context) {
+    const {x, y} = scales;
     const {x: X, y: Y, r: R, rotate: A, symbol: S} = channels;
     const [cx, cy] = applyFrameAnchor(this, dimensions);
     const circle = this.symbol === symbolCircle;
     return create("svg:g", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
-      .call(applyTransform, this, scales)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
+      .call(applyTransform, this, {x: X && x, y: Y && y})
       .call((g) =>
         g
           .selectAll()

src/marks/frame.js

@@ -24,7 +24,7 @@ export class Frame extends Mark {
     const {marginTop, marginRight, marginBottom, marginLeft, width, height} = dimensions;
     const {insetTop, insetRight, insetBottom, insetLeft, rx, ry} = this;
     return create("svg:rect", context)
-      .call(applyIndirectStyles, this, scales, dimensions)
+      .call(applyIndirectStyles, this, scales, dimensions, context)
       .call(applyDirectStyles, this)
       .call(applyTransform, this, {})
       .attr("x", marginLeft + insetLeft)