30:[] 2e:{"title":"Pieces of a Map","cells":[{"id":0,"value":"md`# Pieces of a Map`","pinned":false,"hidden":false,"mode":"ojs"},{"id":11,"value":"md`To build a tiled web map, we need the following pieces:\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`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"md`The specification for the last piece is somewhat arbitrary. Many slippy maps, such as the commonly-used [Leaflet](https://leafletjs.com), or [@Fil](https://observablehq.com/@fil)'s notebook [Seamless Zoomable Map Tiles](https://observablehq.com/@d3/seamless-zoomable-map-tiles), do not put the map on a single Canvas. Instead, they simply manage the tiles as HTML elements and use DOM manipulation or SVG tricks to position them on the screen.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":18,"value":"md`We choose to render the map on a Canvas for one simple reason: it makes the entire map accessible as a single image, for later loading into a WebGL texture.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":32,"value":"md`## 1. Tile source`","pinned":false,"hidden":false,"mode":"ojs"},{"id":21,"value":"md`We use the beautiful [Mapbox Satellite](https://www.mapbox.com/maps/satellite/) tiles. The API endpoint for 256 pixel tiles is`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":262,"value":"tileSize = 256;","pinned":false,"hidden":false,"mode":"ojs"},{"id":24,"value":"endpoint = \"https://api.mapbox.com/styles/v1/mapbox/satellite-v9/tiles/256/{z}/{x}/{y}?access_token=pk.eyJ1IjoiamhlbWJkIiwiYSI6ImNqcHpueHpyZjBlMjAzeG9kNG9oNzI2NTYifQ.K7fqhk2Z2YZ8NIV94M-5nA\";","pinned":false,"hidden":false,"mode":"ojs"},{"id":27,"value":"md`To convert this into a URL for a specific tile, we need to subsitute the appropriate values for the z, x, y indices:`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":30,"value":"tileURL = (z, x, y) => endpoint.replace(/{z}/, z).replace(/{y}/, y).replace(/{x}/, x);","pinned":true,"hidden":false,"mode":"ojs"},{"id":36,"value":"md`## 2. Tile factory function`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":55,"value":"md`For the actual behavior of the factory function, we again make some arbitrary choices--this time to fit the API of our tile cache module (see next section). We build the factory within a wrapper function, to allow construction of new tile factories by simply supplying a new tile source.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":42,"value":"function buildFactory(getURL) {\n // Input getURL is a function that returns a tile URL for the given x, y, z indices\n\n // Create a DOM element that will emit events when tiles finish loading\n const tattle = DOM.element(\"div\");\n\n function create(z, x, y, loadCallBack) {\n var tileHref = getURL(z, x, y);\n const img = loadImage(tileHref, checkData);\n const tale = new Event(\"tileLoaded\");\n\n const tile = {\n z,\n x,\n y,\n img,\n cancel,\n canceled: false,\n rendered: false\n };\n\n function checkData(err) {\n if (err) return console.log(err);\n tile.rendered = true;\n tattle.dispatchEvent(tale);\n }\n\n function cancel() {\n img.src = \"\";\n tile.canceled = true;\n }\n\n return tile;\n }\n return { create, element: tattle };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":120,"value":"factory = buildFactory(tileURL)","pinned":true,"hidden":false,"mode":"ojs"},{"id":291,"value":"md`Note that the returned tile is not simply an image: it is an object that includes the z/x/y indices, the image, a cancel() method to cancel a request, and flags indicating whether the tile is ready to use.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":65,"value":"md`## 3. Tile cache`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":69,"value":"md`The purpose of the cache is to make sure we always have tiles to cover the screen. We don't want to be stuck waiting for an HTTP response if the user pans or zooms.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":77,"value":"md`Of course, all the tiles are coming over HTTP. But if we don't have a specific tile in memory, we can temporarily use one of the tile's *parent* tiles--a lower-resolution tile from a smaller zoom level.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":74,"value":"md`A good tile cache will immediately return a tile for any requested [z,x,y] combination. Since the returned tile may be a parent tile, it should come in a \"box\" with information indicating which part of the tile to use to cover the requested [z,x,y], so that the tile can be cropped and stretched appropriately.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":81,"value":"md`We use the new [tile-rack](https://www.npmjs.com/package/tile-rack) module.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":90,"value":"cache = tileRack.initCache(tileSize, factory);","pinned":true,"hidden":false,"mode":"ojs"},{"id":94,"value":"md`## 4. Tile layout manager`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":261,"value":"md`We use the new [tile-frame](https://www.npmjs.com/package/tile-frame) module. A link to the cache.retrieve method is supplied in the .getTile property of the parameters object. We also need to define a width and height for the context's render buffer. tile-frame requires these to be a multiple of the tile size. We also specify the initial center and zoom of the map, but we can always modify those dynamically, once the map is running.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":234,"value":"mapParams = Object({\n getTile: cache.retrieve,\n width: tileSize * Math.ceil(width / tileSize),\n height: tileSize * Math.ceil(height / tileSize),\n maxZoom: 20,\n tileSize: 256,\n center: [0.5, 0.375],\n zoom: 2\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":273,"value":"md`Now we are ready to initialize the map.`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":107,"value":"map = tileFrame.init(mapParams)","pinned":true,"hidden":false,"mode":"ojs"},{"id":276,"value":"md`The map object exposes a .move() method which we can use to pan and zoom. Here are some buttons that call map.move() when they are clicked. Try zooming in to your neighborhood!`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":177,"value":"{\n const pan = html``;\n pan.left.onclick = () => move(0, -1, 0);\n pan.right.onclick = () => move(0, 1, 0);\n pan.up.onclick = () => move(0, 0, -1);\n pan.down.onclick = () => move(0, 0, 1);\n pan.out.onclick = () => move(-1, 0, 0);\n pan.in.onclick = () => move(1, 0, 0);\n return pan;\n\n function move(dz, dx, dy) {\n map.move(dz, dx, dy);\n map.drawTiles();\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":144,"value":"mapDisplay = {\n map.drawTiles(); // Force the first draw call\n return map.canvas;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":281,"value":"md`Note that when you first change the zoom or pan, the needed tiles are not in the cache yet. Some lower-resolution tiles are displayed instead. But once the higher-resolution tiles are loaded, we want to redraw the map at full resolution.\n\nWe achieve this by listening for the custom \"tileLoaded\" event from the tile factory, and calling map.drawTiles.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":325,"value":"factory.element.addEventListener(\"tileLoaded\", map.drawTiles, false)","pinned":true,"hidden":false,"mode":"ojs"},{"id":7,"value":"md`## Appendix`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":255,"value":"height = width * 0.75;","pinned":false,"hidden":false,"mode":"ojs"},{"id":193,"value":"html`\n\n`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":397,"value":"tileFrame = import(\"tile-frame@1.0.0\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":99,"value":"tileFrame_old = import(\"tile-frame@0.0.1\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":87,"value":"tileRack = import(\"tile-rack@0.0.2\");","pinned":true,"hidden":false,"mode":"ojs"},{"id":44,"value":"function loadImage(href, callback) {\n const errMsg = \"ERROR in loadImage for href \" + href;\n\n const img = new Image();\n img.onerror = () => callback(errMsg);\n img.onload = checkImg;\n img.crossOrigin = \"anonymous\";\n img.src = href;\n\n return img;\n\n function checkImg() {\n return (img.complete && img.naturalWidth !== 0)\n ? callback(null)\n : callback(errMsg);\n }\n}","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}