Lab 2: Mapping Data with Leaflet.js, MapBox.js, and TileMill
============================================================
Ryan Mullins | [RyanMullins@psu.edu](mailto:RyanMullins@psu.edu)
# Overview
In lab 2 we switch from a data collection and preparation focus, to a data representation focus. You will cover the following topics in Lab 2.
1. The basic components of a tiled web map.
2. The tools used to create the support content for a web map.
3. The tools and process used to create a static web map.
# 1 Components of a Web Map
Web maps are increasingly becoming more varied and powerful tools for conveying a message to a reader. This is due in no small part, to the advancements made in browser technology and development tools. At present, the most common web map is a tiled map (sometimes you will see them called Slippy Maps, a term popularized by OSM). Web maps made using various JavaScript graphics libraries, such as [D3.js](http://d3js.org), are becoming more popular as well. Each has their advantages and disadvantages, but this lab will focus on making tiled maps.
A tiled map uses three two basic components — a mapping library and a collection of images, or tiles — to display a map of the world or a region at discrete zoom levels, or scales. At high zoom levels (larger scales) it is impossible to display the entire world at once, so different tiles are generated for the various zoom levels. A mapping library manages which of these tiles should be shown for a region at different zoom levels. The typical size of a tile image is 256 pixels by 256 pixels. Tiled maps are also associated with the ability to change zoom level and pan to different regions based on interactions (the term Slippy Map comes from the ability to slip between zoom levels and regions). There are a large number of closed and open source mapping libraries, including libraries from Google, Microsoft Bing, the Open Layers project, and more. In this lab we will make use of the [Leaflet.js](http://leafletjs.com/) mapping library, an open-source library released in 2011 that has quickly become the most used open-source mapping library on the web. You will also be using [TileMill](https://www.mapbox.com/tilemill/) to create the tiles that Leaflet.js will manage.
There are, of course, some drawbacks to tiled maps. The most glaring of these is the projection that is commonly used, the Web Mercator. As you're well aware, Mercator projections suffer from severe distortion, which can cause serious misinterpretation problems whenever relative size of places or relative distances among places matters.
# 2 Creating Map Tiles with TileMill
As we discussed previously, tiled maps use a mapping library and set of tiles to display a map on a web page. The first section of this lab focuses on creating and publishing the tiles for your map to a hosting service. You will be using [TileMill](https://www.mapbox.com/tilemill/) to create your tiles, and publishing them to MapBox.
## 2.1 MapBox Hosting Services and TileMill
[MapBox](https://www.mapbox.com/) is a company dedicated to creating web maps. Their primary function is to provide hosting services for map tiles. They offer a variety of [plans](https://www.mapbox.com/plans/), from free to premium, that allow for different volumes of storage and views. You will be using their free hosting services in these labs. Please be sure to sign up for their free plan at your earliest convenience.
MapBox has also created a number of open-source tools to make it easier for cartographers to design and publish maps using their services. One of these tools is [TileMill](https://www.mapbox.com/tilemill/). TileMill is a free application, available for OS X, Windows, and Ubuntu Linux, that allows you to import various data sources, style them, and create map tiles. You can download TileMill from the link above. It is also available in all of the Penn State Geography Department computer labs.
## 2.2 How To: Creating Basic Map Tiles with TileMill
Now you can get to work making tiles. This is a step-by-step walk-through (with pictures!) of how to take the data you collected in Lab 1 and transform that into tiles for a web map.
### Step 1: Creating a New Project
First things first, time to open up TileMill (or [download](https://www.mapbox.com/tilemill/) it if you haven't done so yet). When you open TielMill you will be greeted with something similar to what's shown in Figure 2.1.
In the center you will see a series of example projects that come pre-installed. On the side is a menu that lets you switch between what is shown in the center area. The "Editor" button is likely inactive as you don't have any projects open at the moment. There are other tabs for the manual, settings, and plug-ins, of these the manual will be the most valuable to you.
Time to make a new project. Click on the "New project" button in the upper left of the projects page (Figure 2.1). When you do this, you will be presented with a little pop-up (Figure 2.2) asking for some information about this new project. The most important, and only required, piece of information is the "Filename". Filenames can only be alphanumeric, no special characters or punctuation, and good practice is to use [CamelCase](http://en.wikipedia.org/wiki/CamelCase) notation. CamelCaseMeansTheFirstLetterOfAnyWordIsCapitalizedAndYouDoNotHaveSpacesOrPunctuationBetweenWordsLikeThis. It may seem a bit weird, but you'll get used to it. I will discuss CamelCase more in Section 3 because it is a huge part of my coding style and understanding how I use it will make things a bit easier to read and understand.
You can use the "Name" field to give it a more readable and descriptive name. I am boring and this is a demo, so I went with the name of the course. The "Description" field is exactly what you think and can be useful, but is not required. Leave the "Image format" alone, 24-bit PNGs are awesome and the only other option is a JPEG...
Cool. So now you have a new project to do work in. It should be shown on the "Projects" page (listed alphabetically, Figure 2.3), if it is not then something went wrong and you should try to make another one. If the problem persists, contact [MapBox Support](http://support.mapbox.com/).
Click on the project to open it in the Editor.
### Step 2: Adding Data Layers
And now you have a map, albeit a pretty bare one at the moment. Your project probably looks something similar to what is shown in Figure 2.4. Another quick review of the interface, in the center of everything is the map preview. This is a live rendering of what your tiles are going to look like once they are created. To the right of that is the CartoCSS editor that you use to control how your map looks, more on that later. In the upper left you will notice some interface controls. The "+" and "-" buttons control zoom level, though you can also do that with your scroll wheel or track pad gestures. The arrows toggle between a full-screen map-view and the split map-editor view. The last piece is probably the most important, it's the editing tools menu (Figure 2.5) in the bottom left.
TileMill has a pretty great set of editing tools built in, going down the list... The pointing finger thing (technical term, obviously) let's you control the templates. This is where you can add a legend and even some interactivity to your maps. We will get to the interaction bits in the next lab, but the legend is pretty easy to figure out and can make a world of difference. You type in text and it makes it appear, it is that simple. You can do all sorts of advanced things too, look for more advanced tutorials [here](https://www.mapbox.com/tilemill/docs/guides/advanced-legends/).
Below the pointy finger thing is a button with the letter "A" in it. Clicking on this will bring up an absolutely massive list of all the fonts you can use in your tiles. Be careful, it is pretty easy to get lost in there. Below this is a pair of curly braces (that's "{ }" those kind, plan on becoming familiar with these), and clicking on that brings up a reference guide for CartoCSS. This is definitely going to become your friend.
At the bottom is the really interesting bit though. It may look like a stack of papers, but it really lets you see which data layers are being used in this map. Click on it and a little pop-up appears showing the data layers in the map (Figure 2.5). You should only see the "#countries" layer in there now, how about you spice things up a bit. You are going to add a new data layer to the map, using the alaskaFires.csv as the source. Click on the "Add layer" button and a pop-up will appear, much like it did with the new project, asking for some information (Figure 2.6).
It is always easiest to start with the datasource. At the top of the pop-up you will notice three tabs — File, SQLite, and PostGIS. These are options for the type of datasource you want to use. Your datasource is the _alaskaFires.csv_ file you created in Lab 1, so you want to select the File option. In real life, or with data from your job or something like that, you might find that SQLite or PostGIS do a better job of storing and managing your data since they are databases designed to do just that. For these labs we are just going to focus on using files.
Click on the browse button, navigate to where your _alaskaFires.csv_ file is on your computer, and click the "Done" button to the right of the file path. Now you can customize the ID and Class attributes for this data, if you so choose (Figure 2.7) though TileMill usually generates good names automatically. You will not need to put anything in the advanced field. When you are happy with the names, click the "Save & Style" button and watch as TileMill magically adds all of those data points to the map (Figure 2.8)
### Step 3: Styling Data Layers
At this point your map should look something like what you see in Figure 2.8. Blue ocean, off-white land masses, red dots for all the fires. It could definitely look better. Next, we will look at what you can do with CartoCSS to improve the design. But before we go jumping into the deep end with CartoCSS, we should probably figure out what we want to change and how we can go about doing that.
We will start by looking at the attributes of the data and trying to find something interesting to represent. If you open up the _alaskaFires.csv_ file in a spreadsheet or text editor, you will notice that it has a lot of attributes, 32 to be exact (Figure 2.9).
I have had ample time to examine this data, and I have found that some attributes are easier than others to understand and represent in a meaningful way (information about all attributes and their meanings can be found [here](http://wildfire.cr.usgs.gov/firehistory/about.html)). Of the attributes available, "ORGANIZATION", "SIZECLASSN", "PROTECTION", and "FIRETYPE" stand out as the some of the most relevant attributes to a firefighter. Each of these is represented by a small number (less than 10) of unique values. We have four attributes to choose from... but which one to choose?
A topical theme that occurred coincidentally is that all of the fires were initially colored red, which is kind of what fire looks like in nature. We want to keep this theme going, but instead of a single color why not have different colors based on some attribute related to the fire... like the size classes. There is an attribute, "SIZECLASSN", that defines 8 discrete size classes with values ranging from 0 to 7 that we can use to define the styling of these markers.
Up next: colors. Penn State Geography has a rich history of color research. The seminal outcome from this being [ColorBrewer](http://colorbrewer2.org), a collection of some proven and tested recommendations for color schemes to use on maps. The "SIZECLASSN" data is sequential with 8 classes, and since it deals with fire we want to use a color scheme that conveys that. On ColorBrewer I select 8 class breaks, a sequential scheme, and see what looks like fire. In the multi-hue category there is a nice gradient that goes from yellow to red, much like fire. Now we have everything we need to make the data pretty, time to write some CSS-like stuff.
Back in TileMill make sure you can see the CartoCSS editor. You should see three little sections of code ‐ `Map`, `#countries`, and something similar to `#alaskaFires`. These are blocks of CSS that define the style for the specified selector. Lab 0 covered selectors in the context of HTML, but here they function a bit differently. In CartoCSS each selector defines the style for a layer, given that layers ID using the "#" character, or a class of features, given the class name after a "." character. At the moment you have two selectors, "#countries" and "#alaskaFires", that define the style for a layer. Inside of the curly braces for each of these selectors you see some properties that are being defined. Look at the `marker-fill-color` property in the `#alaskaFires` selector. This property controls the fill color of the circle markers for the fires, and we want to set the color based on the "SIZECLASSN" value for each fire.
To do this you need need to make use of conditionals, a feature of CartoCSS that functions just like conditionals in JavaScript (see Section 3.2 of Lab 0). The conditional syntax goes like this: `[nameOfAttribute conditionalOperator value] { property: value; }`. You can use this syntax to create conditional appearances for any attribute of any data layer in your map.
You need to make 8 conditional statements, one for each class, that sets the `marker-fill-color` property for each class, being sure to use the hexadecimal color values from ColorBrewer. You can see the exact code I used to do this in Figure 2.10. Once you write these, click the "Save" button in the top right corner and watch the map refresh, you should see something like what I have created in Figure 2.10.
And that is all you need to do to customize the appearance of your map. You can do this to any attribute you like... and you will for the deliverable, but we will discuss that later. Right now you need to generate your tiles and publish them to a place where you can access them.
### Step 4: Publishing Tiles to MapBox
Data: check.
Tile design: check.
Now to generate and publish them. Luckily, TileMill provides all sorts of functionality to do this using their Export system. In the upper right corner you will see the "Export" button, clicking on it will bring down a drop-down list (Figure 2.11). The first option, "Upload", is the one you want, but the ones below it allow you to create a series of images locally that you can transfer to a server you have set up.
After you select the "Upload" option one of two things will happen. If you have not linked TileMill to your MapBox account, you will be asked to do so. This is just a simple form asking for your email and password to log in to your MapBox account. When TileMill is linked to your account it is only granted permission to upload tiles space associated with your account, and to remove existing tiles from it; it cannot change you password, personal, or billing information at present.
The second option is for the exporter view to show up (Figure 2.12). This view allows you to select the region and zoom level range that you want to export, while adding metadata (name, description, and attribution) and setting the default map center.
Perhaps the most important piece of information in this view is the size of the exported tiles, measured in bytes of data and located below the zoom level selector. Unless you chose to pay for more, you signed up for a free MapBox account at the beginning of this lab. This gives you 50MB of data storage, so you need to be conscious of how much space any one project is taking up on your account. The only real way to control size is to adjust the region and zoom levels.
Region is selected by manipulating the edges of the box in the middle of the screen. You can move each edge independently, or hold down shift while clicking and dragging to make a completely new selection. Zoom level is selected using a slider. You can choose any range from level 0 (the entire world) to level 22 (about the footprint of the average American house). The trick for this lab is to make it so that you don't use all of that 50MB of storage.
I did some playing around while writing this lab and I think I found some decent settings (Figure 2.13). Since we are only concerned with Alaska, the first thing I did was constrain the export view to that region, roughly -180,50 to -129,72. Next I looked to find exactly which zoom levels would be useful. Zoom level 4 was pretty much the bare minimum for making it large enough to see details when the map loads. The upper limit was a bit more difficult. I found that level 9 offered enough detail that you could see individual fires well enough and kept the export size under 10MB. Levels 10 and 11 also seemed to work, but they pushed the total export size over 10MB, though not too far. Your choice might be different based on the data you chose to include. Including lots of information on smaller features like airports and infrastructure could require a higher maximum zoom level. Just be cautious in your decision. Next you set the map center point. To do this simply click in roughly the center of the bounding box for your map extents and it will drop a pin in the box. There should bet text in the pin, something like Z4, which is the zoom level at that point. Together, the location of the pin and the text within it mean that the map will automatically center at that location and show the tiles at the zoom level number when loaded using MapBox.js. There is also a version field, but I would not use it as it tends to just cause problems.
Once you figure out the parameters of your export (don't forget to attribute your sources), click on the "Upload" button. This process can take a while, especially if your export covers a larger zoom range. When it is completed the View Exports window will update with a button to view the map on MapBox.com (Figure 2.14). Click this button and see how it looks.
## 2.3 Advanced Topics and Tutorials
This lab has just barely scratched the surface of what can be done with TileMill. There are a slew of more advanced examples on the TileMill web page. You can check them out [here](https://www.mapbox.com/tilemill/docs/guides/add-shapefile/).
## 2.4 Deliverables
And so concludes Section 2 and Part A of Lab #2. The deliverable for this labs has three parts:
First, simply create a free MapBox account. You will need this later on and it provides me an easy way to check your progress through Part A.
Second, create map tiles for the data you downloaded in Lab 1 using TileMill and publish them to MapBox. The data on these tiles should include the fire data from the walk-through above, as well as some representation of the extra dataset(s) you collected in Lab 1.
Third, submit an update in the Lab 2 Part A dropbox containing a link to the tiles you made on MapBox.com (found using the link from the View Exports view).
Grading information can be found in Section 5.
# 3 Making a Web Map
And now for something completely... related. Part B of this lab, covered in this third section, gets into actually making and publishing a web map. You will be using the Leaflet.js mapping library and the MapBox.js plug-in for Leaflet to make a map from the tiles you created.
## 3.1 Leaflet.js and MapBox.js
Leaflet.js is an open-source mapping library created in 2011 by Vladimir Agafonkin, then working at CloudMade. It is an extremely lightweight library that handles tile management, basic interaction (panning and zooming), and provides simple classes for various data overlays. But maybe the biggest advantage of Leaflet was the plug-in support. Making plug-ins for Leaflet is incredibly easy, and the community quickly started creating them to handle anything that Leaflet did not support out of the box.
MapBox.js is one of those plug-ins. It was created to simplify the integration process with MapBox services. So, if you host your tiles on MapBox, like you did in Part A, you can simply provide a unique ID to the MapBox.js plug-in and it will handle most everything for you.
## 3.2 How To: Creating a Simple Web Map
Time to start using these tools. Below is another step-by-step walk-through, like the one from Section 2.
### Step 1: Downloading the Source Code
Before you do anything else, you should download some source code I prepared. To download, go to the [repository on GitHub](https://github.com/RyanMullins/Geog461W.SP2014.Labs) and click the "Download ZIP" button along the right side of the screen (Figure 3.1). This will download a ZIP archive of the entire repository onto your machine. Unzip this archive and navigate to the _Lab2/Code_ directory. This directory contains a single file, yourNameHere-FireMap.html, open that file in your text editor (if you do not have one, I recommend [Sublime Text](http://www.sublimetext.com/2)).
### Step 2: Importing the Leaflet.js Library and MapBox.js Plug-In
The first order of business should be to rename the file you just opened. It will make things a lot easier for me to grade if you use the naming convention I showed in the example. Simply do a save as and rename the file to include your name (see class syllabus on Angel for standard naming conventions). Now that the file is ready to go, let us take a look at exactly what is going on inside it.
This file is an HTML file, which means it can contain any mix of HTML markup, JavaScript code, and CSS styling information. At the moment, the page contains a combination of HTML and CSS, with a placeholder for some JavaScript. Below is a copy of all of the markup and CSS in the file, and just in case anything starts going sideways on you, just replace the contents of the file with this and start over. Let's go through the contents (mostly) line by line.
```HTML
Geog 461W | Lab 2 | Making a Fire Map
Fire Map
```
From the Lab 0 handout you should be familiar with the syntax you're seeing; a series of HTML elements, some with and others without content. The first line defines the type of document that the browser is seeing, in this case HTML 5. Following this is the header information. This includes metadata about the page (all of those `` tags), the title for the page displayed in the tabs for the browser, and then some style information. You should take the time to fill in the metadata about the author and keywords. You do not need to worry about anything else, for now, unless you really dislike my title.
Below the header information is the body. I have kept this pretty simple. There is a `