Add support for projections to the standalone Plot.scale function

docs/features/scales.md

@@ -1065,3 +1065,16 @@ As another example, below are two plots with different options where the second
 const plot1 = Plot.plot({...options1});
 const plot2 = Plot.plot({...options2, color: plot1.scale("color")});
 ```
+
+Plot.scale also supports projections. <VersionBadge version="0.6.18" /> The returned projection object exposes *apply* and *invert* methods for converting between geographic and pixel coordinates, and can be passed as the **projection** option of another plot.
+
+```js
+const projection = Plot.scale({projection: {type: "mercator"}});
+projection.apply([-1.55, 47.22]) // [316.7, 224.2]
+```
+
+The projection's **width** defaults to 640, and its **height** defaults to the width times the projection's natural aspect ratio. You can override these with the **width** and **height** options, and inset the projection with the **margin** and **inset** options.
+
+```js
+const projection = Plot.scale({projection: {type: "albers-usa", domain, width: 960, height: 600}});
+```

src/scales.d.ts

@@ -2,6 +2,7 @@ import type {InsetOptions} from "./inset.js";
 import type {NiceInterval, RangeInterval} from "./interval.js";
 import type {LegendOptions} from "./legends.js";
 import type {AxisOptions} from "./marks/axis.js";
+import type {Projection, ProjectionOptions} from "./projection.js";
 
 /**
  * How to interpolate range (output) values for continuous scales; one of:
@@ -673,3 +674,4 @@ export interface Scale extends ScaleOptions {
  * ```
  */
 export function scale(options?: {[name in ScaleName]?: ScaleOptions}): Scale;
+export function scale(options: {projection: ProjectionOptions & {width?: number; height?: number}}): Projection;

src/scales.js

@@ -10,6 +10,7 @@ import {
   coerceDates
 } from "./options.js";
 import {orderof} from "./order.js";
+import {createProjection, projectionAspectRatio} from "./projection.js";
 import {registry, color, position, radius, opacity, symbol, length} from "./scales/index.js";
 import {
   createScaleLinear,
@@ -526,12 +527,28 @@ export function scale(options = {}) {
     if (!registry.has(key)) continue; // ignore unknown properties
     if (!isScaleOptions(options[key])) continue; // e.g., ignore {color: "red"}
     if (scale !== undefined) throw new Error("ambiguous scale definition; multiple scales found");
-    scale = exposeScale(normalizeScale(key, options[key]));
+    scale = key === "projection" ? scaleProjection(options[key]) : exposeScale(normalizeScale(key, options[key]));
   }
   if (scale === undefined) throw new Error("invalid scale definition; no scale found");
   return scale;
 }
 
+function scaleProjection({
+  width = 640,
+  height,
+  margin = 0,
+  marginTop = margin,
+  marginRight = margin,
+  marginBottom = margin,
+  marginLeft = margin,
+  ...projection
+}) {
+  if (height === undefined) height = width * projectionAspectRatio(projection);
+  const p = createProjection({projection}, {width, height, marginTop, marginRight, marginBottom, marginLeft});
+  if (p === undefined) throw new Error("invalid scale definition; unknown projection");
+  return p;
+}
+
 export function exposeScales(scales, context) {
   return (key) => {
     if (!registry.has((key = `${key}`))) throw new Error(`unknown scale: ${key}`);

test/scales/scales-test.js

@@ -1,5 +1,6 @@
 import * as Plot from "@observablehq/plot";
 import * as d3 from "d3";
+import * as topojson from "topojson-client";
 import assert from "../assert.js";
 import {describe, it} from "vitest";
 
@@ -2419,3 +2420,86 @@ describe("plot(…).scale('projection')", () => {
     assert.allCloseTo(projection2.invert(projection2.apply([-1.55, 47.22])), [-1.55, 47.22]);
   });
 });
+
+describe("Plot.scale({projection})", () => {
+  it("round-trips", () => {
+    for (const type of ["mercator", "equal-earth", "equirectangular"]) {
+      const projection = Plot.scale({projection: {type}});
+      assert.allCloseTo(projection.invert(projection.apply([-1.55, 47.22])), [-1.55, 47.22]);
+    }
+  });
+
+  it("matches plot.scale('projection') given explicit dimensions", () => {
+    for (const [type, height] of [
+      ["mercator", 640],
+      ["equal-earth", 311],
+      ["equirectangular", 320]
+    ]) {
+      const plot = Plot.plot({width: 640, height, margin: 0, projection: type, marks: [Plot.graticule()]});
+      const p1 = plot.scale("projection");
+      const p2 = Plot.scale({projection: {type, width: 640, height}});
+      assert.allCloseTo(p1.apply([-1.55, 47.22]), p2.apply([-1.55, 47.22]));
+    }
+  });
+
+  it("respects margins and insets", () => {
+    // standalone projection
+    const p1 = Plot.scale({projection: {type: "mercator", width: 640, height: 640, margin: 40, inset: 10}});
+    assert.allCloseTo(p1.invert(p1.apply([-1.55, 47.22])), [-1.55, 47.22]);
+    // equivalent plot-based projection
+    const p2 = Plot.plot({
+      width: 640,
+      height: 640,
+      margin: 40,
+      projection: {type: "mercator", inset: 10},
+      marks: [Plot.graticule()]
+    }).scale("projection");
+    assert.allCloseTo(p1.apply([-1.55, 47.22]), p2.apply([-1.55, 47.22]));
+    // reuse the standalone projection in a plot
+    const p3 = Plot.plot({projection: p1, marks: [Plot.graticule()]}).scale("projection");
+    assert.allCloseTo(p1.apply([-1.55, 47.22]), p3.apply([-1.55, 47.22]));
+  });
+
+  it("supports domain", async () => {
+    const us = await d3.json("data/us-counties-10m.json");
+    const domain = topojson.feature(us, us.objects.nation);
+    const p1 = Plot.scale({projection: {type: "albers-usa", domain, width: 640, height: 400}});
+    const p2 = Plot.plot({
+      width: 640,
+      height: 400,
+      margin: 0,
+      projection: {type: "albers-usa", domain},
+      marks: [Plot.graticule()]
+    }).scale("projection");
+    assert.allCloseTo(p1.apply([-98, 39]), p2.apply([-98, 39])); // center of the US
+    assert.allCloseTo(p1.invert(p1.apply([-98, 39])), [-98, 39]);
+  });
+
+  it("supports a metric domain with reflect-y", async () => {
+    const house = await d3.json("data/westport-house.json");
+    const p1 = Plot.scale({projection: {type: "reflect-y", domain: house, width: 640, height: 400}});
+    const p2 = Plot.plot({
+      width: 640,
+      height: 400,
+      margin: 0,
+      projection: {type: "reflect-y", domain: house},
+      marks: [Plot.geo(house)]
+    }).scale("projection");
+    assert.allCloseTo(p1.apply([200, 120]), p2.apply([200, 120]));
+    assert.allCloseTo(p1.invert(p1.apply([200, 120])), [200, 120]);
+  });
+
+  it("supports a metric domain with identity", async () => {
+    const house = await d3.json("data/westport-house.json");
+    const p1 = Plot.scale({projection: {type: "identity", domain: house, width: 640, height: 400}});
+    const p2 = Plot.plot({
+      width: 640,
+      height: 400,
+      margin: 0,
+      projection: {type: "identity", domain: house},
+      marks: [Plot.geo(house)]
+    }).scale("projection");
+    assert.allCloseTo(p1.apply([200, 120]), p2.apply([200, 120]));
+    assert.allCloseTo(p1.invert(p1.apply([200, 120])), [200, 120]);
+  });
+});