30:[{"id":"5a534fd924ac1f6f9b4b5bbeaa864cdf04fa110657bae45e0dbc4138d25bef8fadec842b73777694c9a6a5a81b8093c2c9e07c6be66d255d224a7691735a5cfb","href":"https://static.observableusercontent.com/files/5a534fd924ac1f6f9b4b5bbeaa864cdf04fa110657bae45e0dbc4138d25bef8fadec842b73777694c9a6a5a81b8093c2c9e07c6be66d255d224a7691735a5cfb","name":"detroit.json","type":"application/octet-stream","lastModified":1572382973436.129,"size":562084},{"id":"efcaaf9f0b260e09b6afeaee6dbc1b91ad45f3328561cd67eb16a1754096c1095f70d284acdc4b004910e89265b60eba2706334e0dc84ded38fd9209083d4cef","href":"https://static.observableusercontent.com/files/efcaaf9f0b260e09b6afeaee6dbc1b91ad45f3328561cd67eb16a1754096c1095f70d284acdc4b004910e89265b60eba2706334e0dc84ded38fd9209083d4cef","name":"land-50m.json","type":"application/octet-stream","lastModified":1572382946476.718,"size":545534}] 2e:{"title":"Web Mercator tiles","cells":[{"id":0,"value":"

Web Mercator tiles

D3 › Gallery

\n\n# Web Mercator tiles\n\nYou can use [d3.tile](https://github.com/d3/d3-tile) and [d3.geoMercator](https://d3js.org/d3-geo/cylindrical#geoMercator) together to project GeoJSON features on top of standard web Mercator tiles, such as those by Mapbox. The main challenge is that d3.tile uses planar coordinates (pixels) whereas d3.geoMercator uses spherical coordinates (longitude and latitude).","pinned":false,"hidden":false,"mode":"md"},{"id":13,"value":"To draw a map, we need to know how big to make it. For a geographic projection, this is controlled by [*projection*.scale](https://d3js.org/d3-geo/projection#projection_scale): the bigger the scale, the bigger the map. The meaning of the scale value varies by projection, but for d3.geoMercator, the scale is equal to the projected size of the Earth divided by ${tex`2\\pi`}.\n\nWe also need to specify where the map is geographically centered, and where to draw it on-screen. This requires a respective [*projection*.center](https://d3js.org/d3-geo/projection#projection_center) in geographic coordinates and a [*projection*.translate](https://d3js.org/d3-geo/projection#projection_translate) in pixels. The geographic coordinates of the projection’s center will appear at the projection’s translate. (This assumes that the projection isn’t rotated—a topic for another notebook!)","pinned":false,"hidden":false,"mode":"md"},{"id":117,"value":"To draw a 512×512px world map in the Mercator projection, then, we specify: a geographic center of 0°N 0°E, where the prime meridian and the equator intersect (and the default value); a translate of [256, 256], the center of our canvas; and a scale of ${tex`\\tfrac{512}{2 \\pi}`}.","pinned":false,"hidden":false,"mode":"md"},{"id":50,"value":"projection1 = d3.geoMercator()\n .center([0, 0])\n .translate([256, 256])\n .scale(512 / (2 * Math.PI))","pinned":true,"hidden":false,"mode":"ojs"},{"id":41,"value":"html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":70,"value":"As functions:","pinned":false,"hidden":false,"mode":"md"},{"id":58,"value":"mercatorSize = scale => scale * (2 * Math.PI)","pinned":true,"hidden":false,"mode":"ojs"},{"id":60,"value":"mercatorScale = size => size / (2 * Math.PI)","pinned":true,"hidden":false,"mode":"ojs"},{"id":124,"value":"To see how this projection translates into tiles, we need to consider how map tiles are structured. Each tile has integer coordinates [*x*, *y*, *z*] where *z* is a zoom level, *x* is a horizontal position (corresponding to longitude for web Mercator tiles) and *y* is a vertical position (likewise latitude).\n\nThe [0, 0, 0] tile shows the entire world, or at least the part covered by tiles.","pinned":false,"hidden":false,"mode":"md"},{"id":138,"value":"html`

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":159,"value":"The four [*x*, *y*, 1] tiles split the [0, 0, 0] tile into equal quadrants, which if arranged correctly will result in a world map that doubles in size, covering 512×512px.","pinned":false,"hidden":false,"mode":"md"},{"id":142,"value":"html`

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":226,"value":"Already we can make the simple case of a 512×512px world map align.","pinned":false,"hidden":false,"mode":"md"},{"id":229,"value":"html`

\n \n

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":172,"value":"More generally, of course, there’s more math required to determine which tiles should be displayed, and where, for a particular map. And that’s where [d3.tile](https://github.com/d3/d3-tile) comes in! Its API is similar to D3 geographic projections, given [*tile*.translate](https://github.com/d3/d3-tile/blob/master/README.md#tile_translate) and [*tile*.scale](https://github.com/d3/d3-tile/blob/master/README.md#tile_scale)… but different.","pinned":false,"hidden":false,"mode":"md"},{"id":193,"value":"A tile layout’s translate is the projected coordinates of the center of the “world” tile [0.5, 0.5, 0] (or equivalently [1, 1, 1]); for web Mercator tiles, this is 0°N 0°E. A tile layout’s scale is the size of the world at the current zoom level. Lastly the tile layout’s extent specifies the viewport: the top-left and bottom-right corners of the canvas.\n\nSo to repeat our simple example of a 512×512px world map:","pinned":false,"hidden":false,"mode":"md"},{"id":184,"value":"tile1 = d3.tile()\n .translate([256, 256])\n .scale(512)\n .extent([[0, 0], [512, 512]])","pinned":true,"hidden":false,"mode":"ojs"},{"id":279,"value":"The returned tile layout is a function that returns an array of tile coordinates [*x*, *y*, *z*] which you can inspect below. Here, the coordinates correspond to the four *z* = 1 tiles shown above.","pinned":false,"hidden":false,"mode":"md"},{"id":188,"value":"tile1()","pinned":true,"hidden":false,"mode":"ojs"},{"id":287,"value":"Now let’s look at a more real-world example. Given a GeoJSON feature collection of the streets of Detroit, we can create a Mercator projection that fits Detroit to the desired canvas using [*projection*.fitSize](https://d3js.org/d3-geo/projection#projection_fitSize), and a corresponding tile layout.","pinned":false,"hidden":false,"mode":"md"},{"id":296,"value":"detroit","pinned":true,"hidden":false,"mode":"ojs"},{"id":302,"value":"projection = d3.geoMercator()\n .fitSize([width, height], detroit)","pinned":true,"hidden":false,"mode":"ojs"},{"id":351,"value":"path = d3.geoPath(projection)","pinned":true,"hidden":false,"mode":"ojs"},{"id":316,"value":"tile = d3.tile()\n .size([width, height])\n .scale(projection.scale() * 2 * Math.PI)\n .translate(projection([0, 0]))","pinned":true,"hidden":false,"mode":"ojs"},{"id":308,"value":"svg``","pinned":true,"hidden":false,"mode":"ojs"},{"id":325,"value":"For crisp tiles, clamp the *projection*.scale to an exact power of two as shown in [Raster & Vector II](/@d3/raster-vector-ii). See also [Raster & Vector](/@d3/raster-vector) for how to computes the map’s aspect ratio to fit the displayed features automatically.\n\nThanks for reading! 🙏","pinned":false,"hidden":false,"mode":"md"},{"id":54,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":303,"value":"height = Math.min(width, 720)","pinned":true,"hidden":false,"mode":"ojs"},{"id":136,"value":"url = (x, y, z) => `https://api.mapbox.com/styles/v1/mapbox/light-v10/tiles/256/${z}/${x}/${y}${devicePixelRatio > 1 ? \"@2x\" : \"\"}?access_token=pk.eyJ1IjoibWJvc3RvY2siLCJhIjoiY2s5ZWRlbTM4MDE0eDNocWJ2aXR2amNmeiJ9.LEyjnNDr_BrxRmI4UDyJAQ`","pinned":true,"hidden":false,"mode":"ojs"},{"id":35,"value":"land = FileAttachment(\"land-50m.json\").json()\n .then(topology => topojson.feature(topology, topology.objects.land))","pinned":true,"hidden":false,"mode":"ojs"},{"id":289,"value":"detroit = FileAttachment(\"detroit.json\").json()\n .then(topology => topojson.feature(topology, topology.objects.detroit))","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"d3 = require(\"d3-geo@3\", \"d3-tile@1\")","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}