2b:null 2c:["$","title",null,{"children":"Zoomable Map with Tile Cache | Jeshurun Hembd | Observable"}] 31:T8fd,tileOptions = [ { name: "CartoDB Voyager", url: (x, y, z) => `https://${ "abc"[Math.abs(x + y) % 3] }.basemaps.cartocdn.com/rastertiles/voyager/${z}/${x}/${y}${ devicePixelRatio > 1 ? "@2x" : "" }.png`, cssTileSize: () => 256, realTileSize: () => rescalePixels(256), }, { name: "Stamen Terrain", url: (x, y, z) => `https://stamen-tiles-${ "abc"[Math.abs(x + y) % 3] }.a.ssl.fastly.net/terrain/${z}/${x}/${y}${ devicePixelRatio > 1 ? "@2x" : "" }.png`, cssTileSize: () => 256, realTileSize: () => rescalePixels(256), }, { name: "Stamen Toner", url: (x, y, z) => `https://stamen-tiles-${ "abc"[Math.abs(x + y) % 3] }.a.ssl.fastly.net/toner/${z}/${x}/${y}${ devicePixelRatio > 1 ? "@2x" : "" }.png`, cssTileSize: () => 256, realTileSize: () => rescalePixels(256), }, { name: "Stamen Toner (hybrid)", url: (x, y, z) => `https://stamen-tiles-${ "abc"[Math.abs(x + y) % 3] }.a.ssl.fastly.net/toner-hybrid/${z}/${x}/${y}${ devicePixelRatio > 1 ? "@2x" : "" }.png`, cssTileSize: () => 256, realTileSize: () => rescalePixels(256), }, { name: "Stamen Toner (lite)", url: (x, y, z) => `https://stamen-tiles-${ "abc"[Math.abs(x + y) % 3] }.a.ssl.fastly.net/toner-lite/${z}/${x}/${y}${ devicePixelRatio > 1 ? "@2x" : "" }.png`, cssTileSize: () => 256, realTileSize: () => rescalePixels(256), selected: true }, { name: "Stamen Watercolor", url: (x, y, z) => `https://stamen-tiles-${ "abc"[Math.abs(x + y) % 3] }.a.ssl.fastly.net/watercolor/${z}/${x}/${y}.png`, cssTileSize: () => 256, realTileSize: () => 256, // No @2x tile scaling on hi-res screens }, { name: "OSM Mapnik", url: (x, y, z) => `https://${"abc"[Math.abs(x + y) % 3]}.tile.osm.org/${z}/${x}/${y}.png`, cssTileSize: () => 256, realTileSize: () => 256, // No @2x tile scaling on hi-res screens }, { name: "Wikimedia Maps", url: (x, y, z) => `https://maps.wikimedia.org/osm-intl/${z}/${x}/${y}.png`, cssTileSize: () => 256, realTileSize: () => 256, // No @2x tile scaling on hi-res screens } ]32:[] 2f:{"id":"b0a081381d6cf3a3","slug":"zoomable-map-with-tile-cache","title":"Zoomable Map with Tile Cache","thumbnail":"6b6d9d70d5cdd0c5169b950a661da11054994608d100f53c84d24fb86c6a3d60","access_level":"public","create_time":"$D2019-09-03T04:28:05.477Z","update_time":"$D2022-01-26T23:06:12.766Z","view_time":null,"first_public_time":"$D2019-09-04T23:26:51.228Z","fork":{"id":"a5b9539c407b155e","slug":"raster-tiles-canvas","title":"Raster Tiles (Canvas)","owner":{"id":"863951e3ebe4c0ae","login":"d3","name":"D3"}},"stars":9,"starred":false,"owner":{"type":"team","id":"54b0aa2cda468b5a","login":"jjhembd","name":"Jeshurun Hembd","avatar_url":"https://avatars-next.observableusercontent.com/d42857c40a13c8179e0491536477452e54d4f6808ec32ed4d8fbdad81c03758d","tier":"starter_2024"},"version":1030,"publish_version":1030,"role":null,"authored":false,"authors":[{"type":"individual","id":"4e65ca212a169cf2","login":"jjhembd","name":"Jeshurun Hembd","avatar_url":"https://avatars-next.observableusercontent.com/d42857c40a13c8179e0491536477452e54d4f6808ec32ed4d8fbdad81c03758d","tier":null}],"members":[{"type":"individual","id":"4e65ca212a169cf2","login":"jjhembd","name":"Jeshurun Hembd","avatar_url":"https://avatars-next.observableusercontent.com/d42857c40a13c8179e0491536477452e54d4f6808ec32ed4d8fbdad81c03758d","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"subscribed":null,"forks":7,"collection":null,"type":"notebook","body":{"title":"Zoomable Map with Tile Cache","cells":[{"id":0,"value":"md`# Zoomable Map with Tile Cache`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":487,"value":"md`In [Pieces of a Map](https://observablehq.com/@jjhembd/pieces-of-a-map), we listed 4 key pieces for a tiled web map:\n1. A source of map tiles -- either raster images or vector data\n2. A factory function to request tile data, and return an image\n3. A cache to store recently-used tiles in memory\n4. A tile layout function to manage and update the map's position, and arrange the appropriate tiles on a Canvas\n\nIn this notebook, we add pan and zoom functionality by switching to [d3-tile](https://github.com/d3/d3-tile) and [d3-zoom](https://github.com/d3/d3-zoom) for the 4th piece.`;","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":3,"value":"viewof mapContext = {\n const context = DOM.context2d(width, height);\n context.canvas.value = context;\n return context.canvas;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":424,"value":"md`## 1. Tile source`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":122,"value":"viewof tileSource = {\n const form = html`\n \n `;\n let deviceFactor = 1;\n form.i.onchange = () => {\n form.value = tileOptions[form.i.selectedIndex];\n form.dispatchEvent(new CustomEvent(\"input\"));\n };\n form.i.selectedIndex = Math.max(0, tileOptions.findIndex(o => o.selected));\n form.value = tileOptions[form.i.selectedIndex];\n return form;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":430,"value":"md`## 2. Tile factory function\nWe borrow the buildFactory method from [Pieces of a Map](https://observablehq.com/@jjhembd/pieces-of-a-map). It takes a getURL method as an argument, but assumes tile indices will be supplied in [z, x, y] order. We therefore re-order the arguments of our url method:`;","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":193,"value":"factory = buildFactory((z, x, y) => tileSource.url(x, y, z))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":470,"value":"md`## 3. Tile cache\nWe again use the [tile-rack](https://www.npmjs.com/package/tile-rack) module. Note that this resolves the flickering issues observed in [Zoomable Map Tiles](https://observablehq.com/@d3/zoomable-map-tiles). If a requested tile is not ready yet, the cache will *synchronously* return a lower-resolution parent tile, with no delay in the rendering.`;","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":727,"value":"md`tile-rack's initCache method needs to know the pixel size of the tiles created by the supplied tile factory function. We have to be careful here: while all our tile sources return images with a CSS *display* size of 256 pixels, some of them return \"@2x\" tiles for high-resolution screens. In this case, the actual pixel size will be 512 pixels.\n\nAn even more challenging case is when the user *changes* the display resolution: either by dragging the browser window to another screen, or perhaps by Ctrl+scrollwheel magnification. In this case, we may need to replace all our tiles. \n\nWe ensure the correct tile size by watching devicePixelRatio for any changes, following a [tip from MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio#Example_2_Monitoring_screen_resolution_or_zoom_level_changes).`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":773,"value":"mutable cacheTileSize = tileSource.realTileSize();","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":776,"value":"resolutionString = {\n let mqString = `(resolution: ${devicePixelRatio}dppx)`;\n matchMedia(mqString).addEventListener(\"change\", () => {\n mutable cacheTileSize = tileSource.realTileSize();\n });\n return mqString;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":197,"value":"cache = tileRack.initCache(cacheTileSize, factory)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":502,"value":"md`## 4. Tile layout manager`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":852,"value":"md`### Finding the right tiles\nWe use [d3-tile](https://github.com/d3/d3-tile) to get the indices of the tiles needed for our viewport, along with translation and scaling information.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":10,"value":"tile = d3\n .tile()\n .tileSize(tileSource.cssTileSize())\n .size([width, height])\n .clampX(false) // Allow panning across longitude 180 degrees","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":525,"value":"md`The returned tile object is a little hard to decipher. It is a *function* that returns an array of tile indices, when called with a *transform function* as an argument.`;","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":646,"value":"tileset = tile(transform)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":795,"value":"md`We can define our initial transform function from a [longitude, latitude] pair and a zoom level, using a projection. The transform is declared as a mutable value, so it can be updated later.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":954,"value":"mutable transform = d3.zoomIdentity\n .translate(width / 2, height / 2) // Center at the middle of the Canvas\n .scale(2 ** 21) // Start at zoom level 13, plus 2 ** 8 tile size\n .translate(...projection(lonLatSF).map((c) => -c)) // Center on San Francisco","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":912,"value":"projection = d3\n .geoMercator()\n .scale(1 / (2 * Math.PI))\n .translate([0, 0])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":914,"value":"lonLatSF = [-122.4183, 37.775]","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1026,"value":"As a quick cross-check: we should be able to use the transform and projection to find the pixel coordinates (measured from the top left corner of the Canvas) where a given [lon, lat] will appear on the map:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":1024,"value":"transform.apply(projection(lonLatSF))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":531,"value":"md`### Updating the map position and zoom\nTo dynamically update the transform function when the map is panned or zoomed, we use [d3-zoom](https://github.com/d3/d3-zoom).`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":744,"value":"zoom = d3\n .zoom()\n .scaleExtent([1 << 8, 1 << 26])\n .extent([[0, 0], [width, height]])\n .on(\"zoom\", () => {\n mutable transform = d3.event.transform;\n })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":790,"value":"md`Now we attach this zoom object to our map canvas, and set the initial transform.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":788,"value":"d3\n .select(mapContext.canvas)\n .call(zoom)\n .call(zoom.transform, mutable transform)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":826,"value":"md`### Rendering the map\nThe map will need to be re-rendered whenever the user changes the zoom transform by a pan or zoom action. We therefore define a side-effect cell that references the transform, and draws the map. If the transform changes, this cell will be re-evaluated.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":883,"value":"upate = {\n drawTiles(mapContext, tileset);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":890,"value":"md`We also want to re-render whenever a tile finishes loading into the cache, since we may be able to replace a lower-resolution parent tile that we had used temporarily. We therefore listen for the \"tilesLoaded\" event from the tile factory.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":880,"value":"factory.element.addEventListener(\n \"tileLoaded\",\n () => drawTiles(mapContext, tileset),\n false\n)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":590,"value":"md`We render directly to a Canvas. This avoids the subsample gap issue observed in [Zoomable Map Tiles](https://observablehq.com/@d3/zoomable-map-tiles). (See [Fil's notebook](https://observablehq.com/d/32027f96a5d4aa89) for a fix using SVG filters).`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":344,"value":"function drawTiles(ctx, tiles) {\n ctx.clearRect(0, 0, width, height);\n let scale = tiles.scale;\n // Edit translation: make sure the first tile starts at an integer pixel coordinate\n const tx = Math.round(tiles.translate[0] * scale) / scale;\n const ty = Math.round(tiles.translate[1] * scale) / scale;\n // If we are on an integer zoom level, all tiles will now be pixel-aligned\n\n for (const [x, y, z] of tiles) {\n const [xw, yw, zw] = d3.tileWrap([x, y, z]);\n let tileBox = cache.retrieve([zw, xw, yw]);\n if (!tileBox) continue;\n drawTileBox(ctx, tileBox, x + tx, y + ty, scale);\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":592,"value":"md`For the drawImage arguments, recall that [tile-rack](https://www.npmjs.com/package/tile-rack) sometimes returns a lower-resolution parent tile. The tiles come in a box, with cropping info indicating which part of the tile to use.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":281,"value":"function drawTileBox(ctx, box, x, y, scale) {\n ctx.drawImage(\n box.tile.img,\n box.sx,\n box.sy,\n box.sw,\n box.sw,\n x * scale,\n y * scale,\n scale,\n scale\n );\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":212,"value":"md`## Appendix: Imports and other constants`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":444,"value":"$31","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":721,"value":"function rescalePixels(cssTileSize) {\n return devicePixelRatio > 1 ? 2 * cssTileSize : cssTileSize;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":14,"value":"height = 600","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":191,"value":"import {buildFactory} from \"@jjhembd/pieces-of-a-map\";","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":195,"value":"tileRack = import(\"tile-rack@0.0.2\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5,"value":"d3 = require(\"d3@5\", \"d3-geo@1\", \"d3-tile@1\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W32","stdlib":"1","titling":"auto"}} 30:"$2f:body"