Introduction

Websites and smartphone apps which show maps are very common these days. Many such sites use commercial mapping providers such as Google Maps and the like. However, such providers place restrictions on their users and the maps are often generic and do not show information for specialised users such as walkers and cyclists.

OpenStreetMap is a project to produce free, editable maps of the entire world. Users can contribute their own mapping data and the data can be used for free by anyone; see the OpenStreetMap site for more details. Users typically survey a road or path with a GPS device, such as a smartphone, and then draw the road or path on top of their GPS trace using editing software. The fact that the data is free means that developers can use it for their own pruposes, for instance, create their own maps or develop routing applications.

Leaflet is an open-source JavaScript mapping library which offers similar functionality to commercial web mapping services such as Google Maps. It allows you to embed a "slippy" map into a web page. However, unlike these other services, Leaflet can be used to display maps from a whole range of map providers, including, but not restricted to, OpenStreetMap.

Projections

An important consideration when doing web mapping is that the earth is not flat (it's more or less a sphere) while maps are flat. To display a curved surface on a flat piece of paper or computer screen, we need to do a projection and mathematically transform the latitude and longitude to coordinates suitable for representation on a flat surface. Why is this? Imagine any printed map of the earth. The map is equal width everywhere, from far northern areas such as Greenland or north Norway, to the equator. This does not match reality; since the earth is (more or less) a sphere, the circumference of the earth will be much greater at the equator than those far northern areas - indeed, at the poles, the circumference of the earth is zero!

For this reason, latitude and longitude must be transformed to so called projected coordinates if we want to represent them on a flat surface, such as a computer screen. The details of exactly how this projection is done is out of scope of this unit, but it is something to be aware of if you aim to do more with web mapping. Leaflet makes it easy for us by doing the transformation automatically.

The most common projection used with web mapping is informally referred to as the "Google Projection" (more formally, a type of Spherical Mercator), so called because Google Maps popularised it.

Details on the "Google Projection"

If you are interested, this is how the "Google Projection" works. It consists of a series of zoom levels, with 0 the most zoomed out and successive levels progressively zoomed in. How does this work? Basically, zoom level 0 is defined as a flat map of the entire world, occupying 256x256 pixels, so that 360 degrees of longitude becomes 256 pixels and 180 degrees of latitude becomes 256 pixels, as shown below:

Each successive zoom level zooms in by a factor of 2 in both directions, so that at zoom level 1, there are four 256x256 pixel tiles, each covering a quarter of the earth (N of the equator and W of the Greenwich Meridian; N of the equator and E of the Greenwich Meridian; S of the equator and W of the Greenwich Meridian and S of the equator and E of the Greenwich Meridian):

With progressive zoom levels, we continue zooming in by a factor of 2, so that zoom level 2 has 16 tiles (4x4), zoom level 3 has 64 (8x8), and so on. Each tile has an x and y coordinate where x=0 represents the leftmost column of tiles, y=0 represents the topmost row of tiles, and the tile with x=0 y=0 represents the top left tile (x=1 y=0 represents the second tile on the top row, and so on)

Images from OpenStreetMap, (c) OSM contributors, licenced under CC-by-SA.

Some examples

We will be using OpenStreetMap as the mapping provider.

Hello World in Leaflet

This is a basic example which creates a map:

Leaflet Test
 


]]>

Note the following:

• We link in the Leaflet library (a local copy is on Edward) as an external JavaScript file.
• We also link in the Leaflet CSS file; this is necessary ad Leaflet uses some advanced CSS features.
• Note how the HTML contains a div with an ID of map1. This will hold our map.
• Moving onto the JavaScript init() function, where we write our custom code:
  • We first create a map object (the variable map, of type L.Map, and associate it with div1;
  • Next we set up a map layer. Leaflet maps consist of several layers. This allows us, for instance, to overlay, the locations of points of interest on top of an underlying map. Here, the layer is a TileLayer, a layer of map tiles. The map tiles come from the server tile.openstreetmap.org. The x, y and z in the URL relate to the "Google" tiling scheme, see above; z is the zoom level. Leaflet will automatically work out the correct values to place in here.
  • Having created the layer, we add it to the map.
  • Finally, we set the latitude and longitude of the centre of the map, here latitude=50.908, longitude=-1.4.
  • Note how, when we set the centre of the map, we specify the zoom level (see discussion of "Google" tiling scheme, above). 13 and 14 are good ones to start with; try experimenting with different values.

Exercise 1

1. New York is at longitude 74 West, latitude 40.75 North (more or less). Change the example above so that it's centred on New York, at zoom level 13.
2. Find the latitude and longitude of your home town (see, for example, www.informationfreeway.org) and change the example so it's centred on your home town.
3. Use the Geolocation API (see last week) to obtain your current position, and display a Leaflet map at zoom 14 centred on that position. How you should approach this is as follows:
   • You should load the Leaflet map in your init() function, setting it to an arbitrary location;
   • Also set up your geolocation code in your init() function.
   • In your processPosition() method, to process a new position received, adjust the map to the new position. Note that you will need to make your Leaflet map variable a global variable (declare it outside any function) so that both your init() function and your processPosition() function can access it.
   You might notice, through reading the Leaflet API, that there is a shortcut way of doing this.... but for practise, use the above method!

Adding features

Most web maps have some kind of overlay on the base map, for example a series of markers plotting the locations of pubs, cafes or other points of interest. We can even draw vector shapes (lines, polygons, circles) and add them to the map. This example creates a map and adds a feature to it:

Leaflet Test
 


]]>

Hopefully this code is obvious. We simply create a marker at the specified position, and add it to the map.

The following example shows how to create circle, polyline (i.e. a line with multiple points) and polygon features:

Leaflet Test
 


]]>

Again, hopefully this should be mostly self-explanatory. The second parameter when creating a circle is the radius in metres. For polygons and polylines, we specify the shape using an array of points. Each point is an L.LatLng object.

Styling features

We can create custom styles for map features. For polygons, circles and polylines, we can set properties such as the colour and the opacity (opposite of transparency: 0 is completely transparent and 1 is completely opaque).

Leaflet Test
 


]]>

In this example, we have set the circle's fill colour (interior colour) to blue, its outline colour to red, and the opacity to 0.5.

Popups

One commonly-encountered feature of web mapping is popups, in which the user can click on a marker and be presented with additional information on that feature. These are easy to do in Leaflet: we simply call the bindPopup() method of the feature to attach a popup to that feature. bindPopup() takes one parameter, the text (you can include HTML tags) to appear in the popup. Here is an example:

Leaflet Test
 


]]>

Events

In a mapping application, we commonly need to respond to user events, for instance we might want something to happen if the user clicks on the map (such a display a new marker, for instance) or if the user finishes dragging the map to a new location (we might want to load markers from a server, for instance). It is easy to attach events in Leaflet, here is an example:

Leaflet Test
 


]]>

In the event-handling function itself (onMapClick()), we use the event object e to obtain details about the event (in this case, we are interested in the click position). The event object e is automatically passed to the event handler function by the Leaflet library. The event object has a latlng property, representing the position of the mouse click, which is of type L.LatLng. This in turn has two properties, lat and lng representing the actual latitude and longitude.

Exercise 2

1. Combine the marker and mouse click event examples, above, so that by clicking on the map, you add a marker to the map at that position.
2. Centre the map on your home town and draw a green circle with radius 5km there. Use informationfreeway.org to find the latitude and longitude of your home town. Add a popup to the circle, showing the name of the town.
3. Choose your favourite local pub, nightclub, restaurant, theatre, etc, by looking at informationfreeway.org, and draw a polyline from here (lat 50.9079 lon -1.4015) to there. Ensure it more-or-less follows roads and paths!
4. Show all the nearby points of interest from the second Geolocation exercise (from last week) on the map. You will need to send an AJAX request at the end of your init() function, and add all the features to the map in the AJAX callback.
5. Extend Question 1 to allow the user to specify details about the marker, using a jQuery Dialog (see Topic 5) to read in a type (e.g. pub, restaurant) and a description from the user, and use AJAX to save the marker on the server.