affine fit (#1135)

* Fit a projection to a given domain
closes #1125

* tweak style

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

README.md

@@ -341,6 +341,7 @@ If the **projection** option is specified as an object, the following additional
 * projection.**parallels** - the [standard parallels](https://github.com/d3/d3-geo/blob/main/README.md#conic_parallels) (for conic projections only)
 * projection.**precision** - the [sampling threshold](https://github.com/d3/d3-geo/blob/main/README.md#projection_precision)
 * projection.**rotate** - a two- or three- element array of Euler angles to rotate the sphere
+* projection.**domain** - a GeoJSON object to fit in the center of the frame
 * projection.**inset** - inset by the given amount in pixels when fitting to the frame (default zero)
 * projection.**insetLeft** - inset from the left edge of the frame (defaults to inset)
 * projection.**insetRight** - inset from the right edge of the frame (defaults to inset)

src/projection.js

@@ -3,6 +3,7 @@ import {
   geoAlbersUsa,
   geoAzimuthalEqualArea,
   geoAzimuthalEquidistant,
+  geoPath,
   geoConicConformal,
   geoConicEqualArea,
   geoConicEquidistant,
@@ -17,6 +18,7 @@ import {
   geoTransverseMercator
 } from "d3";
 import {isObject} from "./options.js";
+import {warn} from "./warnings.js";
 
 export function Projection(
   {
@@ -32,6 +34,7 @@ export function Projection(
   if (projection == null) return;
   if (typeof projection.stream === "function") return projection; // d3 projection
   let options;
+  let domain;
 
   // If the projection was specified as an object with additional options,
   // extract those. The order of precedence for insetTop (and other insets) is:
@@ -41,6 +44,7 @@ export function Projection(
     let inset;
     ({
       type: projection,
+      domain,
       inset,
       insetTop = inset !== undefined ? inset : insetTop,
       insetRight = inset !== undefined ? inset : insetRight,
@@ -62,13 +66,31 @@ export function Projection(
   // The projection initializer might decide to not use a projection.
   if (projection == null) return;
 
-  // If there’s no need to translate, return the projection as-is for speed.
-  // TODO Maybe scale to fit features here?
-  const tx = marginLeft + insetLeft;
-  const ty = marginTop + insetTop;
-  if (tx === 0 && ty === 0) return projection;
+  // If there’s no need to translate or scale, return the projection as-is for speed.
+  let tx = marginLeft + insetLeft;
+  let ty = marginTop + insetTop;
+  if (tx === 0 && ty === 0 && domain == null) return projection;
+
+  // Otherwise wrap the projection stream with a suitable transform. If a domain
+  // is specified, fit the projection to the frame. Otherwise, translate.
+  if (domain) {
+    const [[x0, y0], [x1, y1]] = geoPath(projection).bounds(domain);
+    const kx = dx / (x1 - x0);
+    const ky = dy / (y1 - y0);
+    const k = Math.min(kx, ky);
+    if (k > 0) {
+      tx -= (k === kx ? x0 * k : ((x0 + x1) * k - dx) / 2);
+      ty -= (k === ky ? y0 * k : ((y0 + y1) * k - dy) / 2);
+      const {stream: affine} = geoTransform({
+        point(x, y) {
+          this.stream.point(x * k + tx, y * k + ty);
+        }
+      });
+      return {stream: (s) => projection.stream(affine(s))};
+    }
+    warn(`The projection could not be fit to the specified domain. Using the default scale.`);
+  }
 
-  // Otherwise wrap the projection stream with a translate transform.
   const {stream: translate} = geoTransform({
     point(x, y) {
       this.stream.point(x + tx, y + ty);

test/output/projectionFitAntarctica.svg

@@ -172,6 +172,7 @@ export {default as penguinSpeciesIsland} from "./penguin-species-island.js";
 export {default as penguinSpeciesIslandRelative} from "./penguin-species-island-relative.js";
 export {default as penguinSpeciesIslandSex} from "./penguin-species-island-sex.js";
 export {default as polylinear} from "./polylinear.js";
+export {default as projectionFitAntarctica} from "./projection-fit-antarctica.js";
 export {default as randomBins} from "./random-bins.js";
 export {default as randomBinsXY} from "./random-bins-xy.js";
 export {default as randomQuantile} from "./random-quantile.js";

test/plots/index.js

@@ -0,0 +1,19 @@
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+import {feature} from "topojson-client";
+
+export default async function () {
+  const world = await d3.json("data/countries-50m.json");
+  const land = feature(world, world.objects.land);
+  const domain = feature(
+    world,
+    world.objects.countries.geometries.find((d) => d.properties.name === "Antarctica")
+  );
+  return Plot.plot({
+    width: 600,
+    height: 600,
+    inset: 30,
+    projection: {type: "azimuthal-equidistant", rotate: [0, 90], domain},
+    marks: [Plot.geo(land, {fill: "#666"}), Plot.graticule(), Plot.geo(domain, {fill: "black"}), Plot.frame()]
+  });
+}