31:[{"id":"798a51d9193c59efce7426c09040b312dfd0c84bc762d54fdd1af6f864bfaab254ff9200c6c6025e5b4738eae691fdb41b70bfe4d1db86c824d2c4c4cb889052","href":"https://static.observableusercontent.com/files/798a51d9193c59efce7426c09040b312dfd0c84bc762d54fdd1af6f864bfaab254ff9200c6c6025e5b4738eae691fdb41b70bfe4d1db86c824d2c4c4cb889052","name":"westport-house.json","type":"application/json","lastModified":1669763727097.978,"size":63146}] 2f:{"title":"Extended Projections / Observable Plot","cells":[{"id":0,"value":"

Extended Projections / Observable Plot

Observable Plot › Extended Projections · API

\n\n# Plot: Extended Projections\n\nPlot has a handful of [built-in projections](/@observablehq/plot-projection) that allow to make maps, both large-scale—to draw a region, a city, or even a floor plan—, and small-scale, for the entire globe. However literally hundreds of projections have been created over the years, by mathematicians, artists, designers, geographers, cartographers… D3 includes dozens of them in its [d3-geo-projection](https://observablehq.com/collection/@d3/d3-geo-projection) and [d3-geo-polygon](https://observablehq.com/collection/@d3/d3-geo-polygon) modules, and they all can be used with Plot.","pinned":false,"hidden":false,"mode":"md"},{"id":959,"value":"To make them easier to write, our examples will be created with a composite mark that draws a globe with land masses and a graticule:","pinned":false,"hidden":false,"mode":"md"},{"id":961,"value":"globe = Plot.marks([Plot.graticule(), Plot.geo(land, {fill: \"currentColor\"}), Plot.sphere()])","pinned":true,"hidden":false,"mode":"ojs"},{"id":1075,"value":"> _A note about this notebook:_ for more enjoyment, we use a different projection for each example. But don’t get distracted too much: the techniques apply equally to all the projections. Also, most of the maps are computed with a fixed width, in order to avoid long computation times when the browser window is resized. Because there are lots of them on the page!","pinned":false,"hidden":false,"mode":"md"},{"id":1032,"value":"Now, let’s make a butterfly! D3’s geoPolyhedralWaterman (from [d3-geo-polygon](https://github.com/d3/d3-geo-polygon/blob/master/README.md#geoPolyhedralWaterman)) function can be used to create the projection at a scale that exactly fits the chart’s width and height. ","pinned":false,"hidden":false,"mode":"md"},{"id":1037,"value":"globe.plot({\n width: 928,\n height: 464,\n projection: d3.geoPolyhedralWaterman().rotate([20, 0]).fitExtent([[0, 0], [928 - 1, 464]], { type: \"Sphere\" }),\n caption: \"A butterfly projection inspired by Steve Waterman.\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1069,"value":"All well and good, but it’s a bit of a bummer to have to repeat the dimensions, substract margins and insets—and derive new dimensions when we’re making facets.\n\nTo make this simpler, the **projection** option can be specified as a function that receives as input the width and height of the frame (minus any inset), and returns an adjusted projection.","pinned":false,"hidden":false,"mode":"md"},{"id":1094,"value":"globe.plot({\n width,\n height: width / 3,\n facet: {data: [\"facet 1\", \"facet 2\"], x: d => d},\n projection: ({ width, height }) =>\n d3.geoBaker().fitSize([width, height], { type: \"Sphere\" }),\n caption: \"A butterfly projection inspired by Steve Waterman.\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1089,"value":"Now, instead of returning the fully set-up projection, we could return a non-scaled projection (ignoring width and height), and use the projection **domain** option—delegating the nitty-gritty work to Plot. The domain is the {type: \"Sphere\"} GeoJSON object, because we want the whole map to fit the frame.","pinned":false,"hidden":false,"mode":"md"},{"id":1049,"value":"globe.plot({\n width: 928,\n height: 464,\n insetRight: 1,\n projection: {type: d3.geoAirocean, domain: { type: \"Sphere\" }},\n caption: \"Buckminster Fuller’s Airocean projection (aka Dymaxion)\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1155,"value":"Note the absence of parentheses after d3.geoAirocean: the type here is the projection’s factory function. If we want to apply some of the options, like a rotate, angle, clipAngle (and any other methods that belong to D3’s projections…), we can specify the projection **type** option as a function; its first argument is an object that contains, on top of the width and height of the frame (minus the insets), the other values defined in the projection option.","pinned":false,"hidden":false,"mode":"md"},{"id":1152,"value":"globe.plot({\n width: 450,\n height: 400,\n insetRight: 1,\n projection: {\n type: (options) =>\n d3.geoSatellite()\n .rotate(options.rotate ?? [0, 0])\n .distance(options.distance ?? 2)\n .tilt(options.tilt ?? 0)\n .angle(options.angle ?? 0)\n .fitSize(\n [options.width, options.height],\n options.domain ?? { type: \"Sphere\" }\n ),\n rotate: [-120, 15],\n tilt: -32,\n distance: 3,\n angle: 20\n },\n caption: \"The configurable satellite projection.\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1035,"value":"## Clipping\n\nSome projections require clipping to the sphere, to avoid bleeding in the non-convex parts of their outline. This has to be applied, for now, on the marks themselves (and not on the sphere mark).","pinned":false,"hidden":false,"mode":"md"},{"id":1222,"value":"viewof clipGoode = Inputs.toggle({label: \"clip to sphere\", value: true})","pinned":false,"hidden":false,"mode":"ojs"},{"id":95,"value":"Plot.plot({\n width: 928,\n height: 412,\n projection: {type: d3.geoInterruptedHomolosine, inset: 2, domain: {type: \"Sphere\"}},\n marks: [\n Plot.graticule({ clip: clipGoode ? \"sphere\" : undefined }),\n Plot.geo(land, { fill: \"currentColor\", clip: clipGoode ? \"sphere\" : undefined }),\n Plot.sphere()\n ],\n caption: \"Goode’s interrupted homolosine projection\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1228,"value":"By default, Plot clips all projections to the frame. This can make the svg paths smaller, and avoids bleeding between frames. Uncheck to option below to see what happens if you explicitly specify clip: false on a large-scale projection, when the plot has margins or facets.","pinned":false,"hidden":false,"mode":"md"},{"id":472,"value":"viewof clip = Inputs.toggle({label: \"clip to frame\", value: true})","pinned":false,"hidden":false,"mode":"ojs"},{"id":463,"value":"Plot.plot({\n width: 740,\n height: 230,\n facet: { data: [1, 2], x: [\"left\", \"right\"] },\n fx: { label: \"facet\" },\n projection: {\n type: ({ width, height }) =>\n d3\n .geoGnomonic()\n .rotate([0, -90])\n .translate([width / 2, height / 2]),\n clip\n },\n marks: [\n Plot.geo(land, { fill: \"currentColor\", fillOpacity: 0.5, clip }),\n Plot.graticule({ clip }),\n Plot.frame({ stroke: clip ? \"steelblue\" : \"red\" })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":106,"value":"## Custom projections and stream functions ⚠️ \n\nFor more customization (read: niche and experimental maps), you are not limited to what D3 offers. You can to create your own projection. In that case, the projection must implement the [stream API](https://github.com/d3/d3-geo/blob/main/README.md#streams), or be a function that takes the options object as input and returns such a stream.\n\nFor example, here’s a projection created with [d3.geoProjection](https://github.com/d3/d3-geo/blob/main/README.md#geoProjection), which creates a spherical projection from a simple function of _x_, _y_ (longitude and latitude _in radians_), post-rotation, and returns a position vector.","pinned":false,"hidden":false,"mode":"md"},{"id":1324,"value":"globe.plot({\n width: 928,\n height: 400,\n projection: {\n type: () =>\n d3.geoProjection((x, y) => [x + 0.4 * y ** 3, y - 0.1 * x]).rotate([0, 40]),\n domain: { type: \"Sphere\" },\n inset: 10\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":21,"value":"## Now, you may go and make your own maps…\n\n… but before that, have a look at the Cahill-Keyes projection. Isn’t it gorgeous?","pinned":false,"hidden":false,"mode":"md"},{"id":22,"value":"globe.plot({\n width: 928,\n height: 464,\n margin: 1,\n projection: {type: () => d3.geoCahillKeyes(), domain: {type: \"Sphere\"}},\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":5,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":23,"value":"d3 = require.alias({\n d3: \"d3@7.7.0/dist/d3.min.js\",\n \"d3-geo\": \"d3@7.7.0/dist/d3.min.js\",\n \"d3-array\": \"d3@7.7.0/dist/d3.min.js\",\n \"d3-geo-projection\": \"d3-geo-projection@4.0.0/dist/d3-geo-projection.min.js\",\n \"d3-geo-polygon\": \"d3-geo-polygon@1.12.1/dist/d3-geo-polygon.min.js\"\n})(\"d3\", \"d3-geo-projection\", \"d3-geo-polygon\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":212,"value":"import {land} from \"@observablehq/plot-projection\"","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}