Page | 1 GEO 425, Spring 2012
LAB 3: Introduction to Web Map Services
Objectives: If you have your own web server, it's great to be able to host your own geospatial data. That data can then be accessed through web API inside web pages or served through clients, such as QGIS or ArcMap. In this lab you will:
1. Learn about MapServer, WMS, and CGI applications
2. Create a basic WMS with both a raster and a vector data set
3. Integrate your WMS with other WMS sources in an interactive web page About MapServer
MapServer is a mature open source, free software project to enable you to serve maps of your own data onto the Web. This data could be in the form of shapefiles, rasters, PostGIS databases (which we learn more about later), and many other geospatial data storage formats. MapServer fits into an integrated chain (or stack) of applications to make this happen:
MapServer essentially converts your spatial data into an image file (or set of files) that are then provided as a web service. You get to control what that image looks like: how many pixels it will have, what color the elements are, labeling details, and so on. Getting all this to play together nicely is a configuration struggle, but once set up you have an impressive internet map setup. Once you know the basics you can add on fancier features. For some examples of using MapServer, see the “Open source examples for web map services (wms)” page in the “Web examples” section of the course website.
Instructions
Step 1: Setting up the MapServer Configuration File
1. MapServer reads configuration files in order to process web mapping requests. The configuration file needs to be readable by the MapServer process (not necessarily to the whole web), so both it and the directory it resides in need to be globally readable. If you didn’t publish your personal website on the Linux server and haven’t read the “Linux account guide” from the lab webpage, it would be useful for you to know that files you publish in the “public_html” folder of your home directory are accessible from the web at:
http://unix-lab.geo.msu.edu/~[your username]. Putting the MapServer configuration file in your linapps “public_html” directory would work. But it would be a bad idea - why (Question 1)? The answer may become clear to you farther down in this step.
In your home directory, make a new directory called mapserver. This directory must be globally readable and executable. The most reliable way to do this is use “chmod”, a unix command that here changes permissions for other users by adding read and execute: “chmod 755 ~/mapserver”. In the terminal window, “cd” to your home directory and issue this command to set the globally readable and executable permission for your mapserver directory.
2. Start a text editor (found under Utilities on linapps). Type the following in it: # MapServer configuration file for lab8, February 2012.
# This file sets up the display of a demonstration map # for the capabilities of MapServer.
# Written by (your name here)
Data
MapServer
Web
Server
Page | 2
Save this file to your new mapserver directory as “lab8.map”. Set the permissions so that it can be read globally. This is done similar to how you did it for the mapserver folder, but use this command for the file:”chmod 655 ~/mapserver/lab8.map”. Or to set this as the permissions for all the files in your mapserver folder you could issue this command: “chmod 655 ~/mapserver/*”. These steps are necessary, as the MapServer process must be able to read this file. If you’re curious what those numbers mean, Wikipedia has a pretty good page on chmod.
3. As you might have guessed, the pound signs in your .map file indicate comments. So far the file does not actually do any configuration. Let's change that. But first, a few sentences about the contents of a .map file. Open the file called physio_example.map in a text editor and follow along through the next paragraphs. For this basic file, there are two distinct components: the MAP section and one or more LAYER sections. The MAP section indicates the map name, the coordinate reference system of the map, the map units, the output format, as well as output image size. It has some metadata about itself that it will pass along to the map server. And there are some other things you can put in there.
The second component is the LAYER section. You will have one of these for each theme you want to map, as well as for any thematic labels you want to display. It contains information about where the layer data are and how to extract them, and what the coordinate reference system of the data are (it doesn't have to be the same as that of the MAP, as layers can be projected automatically on the fly). Data type (POINT, LINE, POLYGON, RASTER, or CONNECTION to a postgis geodatabase), symbology, color, and other rendering information are also included in the LAYER definition.
4. To give you practice in making your own MapServer map. Let’s publish a map of Michigan state roads with an elevation raster for context. To save you some time, a 90m geotiff of Michigan’s DEM and a shapefile of Michigan's state roads are posted with the files for this lab. The rougher resolution of the DEM is good for this case because we’ll be viewing the whole state at once and we don’t want MapServer to spend a lot of time crunching a lot of cell values each time it outputs this map image. Put these files in your “mapserver” directory and change their permissions to global as you did earlier for your .map file. These two layers are now ready to be sources for you MapServer map.
5. Now we need to put all the right information in your .map file. Let’s start with the contents of a .map file that we know works. Copy the contents of the sample map file we’ve been looking at to your map file,
underneath the opening comments you wrote. Since the extent, projection, and source files are different, there are some things you will need to modify to make this work. All of these things can be figured out by looking at the source files’ properties and metadata, but QGIS has a shortcut for us.
Load both of your data layers into a new QGIS project and format them so they look nice. Save your project. Then go to the menu “Plugins” and select “MapServer Export…”. Set where the resulting map file will be saved and called (don’t overwrite the .map file you started for this lab). Then in the “Map” section, give the map a name and adjust the other settings as you see fit. The example .map file outputs an image type of “png”, which I recommend you stick with. You may want to increase the width and height of the output image to something like 300 by 300. Set the MapServer url to “http://unix-lab.geo.msu.edu/cgi-bin/mapserv”. And hit “OK”. You should get an export results window showing that it wrote several sections of a map file for you (thank you QGIS!).
Page | 3 Open the QGIS created .map file side by side with your lab8.map file. You’ll see that they are similar, but the QGIS created file has some extra things that we don’t want to mess with right now. For example, we’re not going to bother with FONTSET or SYMBOLSET files today. Copy from the .map file you created in QGIS the parts you need and replace the appropriate locations in your lab8.map file. Don’t forget to update the metadata information in the WEB section. Note that the QGIS created file has the directory listing and several other parameters setup for your layers. Also, the CLASS section for the LINE layer has some symbology information. You can copy/paste the LAYER sections as a whole, but then let’s edit the layer NAME properties to make things simpler. Change the ‘michigan_dem_250k_90m’ layer name to ‘dem’ and the roads layer name to ‘roads’. Make sure you can figure out what all of the parameters in .map configuration file do. For example, what would you edit if you wanted to change the color of the road lines? What do those numbers mean and how would you figure out what numbers to replace them with? (Question 2)
5. Save the file. Double-check that the permissions are right on both the file and the directory. Step 3: Display the image in a Browser
1. Open a web browser (not Konqueror; Iceweasel would be fine). The first step is to point the browser at the MapServer cgi script. Type this URL: http://unix-lab.geo.msu.edu/cgi-bin/mapserv?
You should get a web page that says, "No query information to decode...”. This is probably a good place to define CGI (Common Gateway Interface). CGI is a very common protocol that enables web servers and server-side applications to interact. Many CGI applications exist out there; MapServer is one; as you saw earlier in this document, MapServer can create graphics files from many spatial data formats, including database queries. These files are actually generated via a URL call by a web browser. The URL you typed in the browser called the mapserv application in cgi-bin, but it didn't actually make any request to mapserv. As a result you got that kind of boring page.
2. So, what you need to do is call the mapserv application via a URL, but in that URL also pass it parameter values so it can do its thing. Type the following URL and look at it:
http://unix-lab.geo.msu.edu/cgi-bin/mapserv?map=/home/<your username>/mapserver/lab8.map&layer=dem&mode=map
Replace <your username> with the appropriate text! Can you tell what this rather nasty URL does? The first chunk, up through "mapserv?", calls the mapserv CGI. The next part, from "map=" to the next "&", is the path and file name of your map file. The third chunk, "&layer=dem" tells it to draw this layer. Remember that you called one of your LAYERS in the map file 'dem'. Finally, "&mode=map" tells mapserv to render a map in the browser. If you did not specify the mode as “map”, then it would have tried to use the default “browse” mode which requires additional configuration of a template file. Today, we just need an image. Did you get a map on the screen?
3. The final step here is to display multiple layers. Try this URL: http://unix-lab.geo.msu.edu/cgi-bin/mapserv?map=/home/<your username>/mapserver/lab8.map&layer=dem&layer=roads&mode=map Did you get the roads drawn on-screen?
Step 4: A Web page with a map!
1. While it is pretty cool to be able to generate a map image on the screen, the URL is hard to type, and it's just an image. Let's make a web page with an embedded map image. In the text editor, create a new file (store it in public_html) called "mich_roads.html". Type the following basic stuff in it:
Page | 4 <html>
<body>
<h2> Michigan State Roads, February 2012</h2> <h3>Demonstration of MapServer Web Mapping!</h3> <img src="">
<br>
<i>Created --today's date--</i> </body>
</html>
Put the current date in where indicated, and place the URL for the map image between the quotes after 'src='. Save the file and make sure the permissions are correct. Then open the file in your browser: http://unix-lab.geo.msu.edu/~<your userID>/mich_roads.html
Did it work? Do you like the size of the image on your page? Properties of the image can be modified by editing your .map file. And of course, you know how to make the web page overall fancier. Create a link to this page from personal website. (Question 3)
Step 6: The Benefits of WMS
1. There are a lot of great web map servers out there. Like a lot of things on the web, finding a reliable service can be a crap shoot. Just to give you some more ideas about what can be done with wms, let's take a look at some of them in ArcGIS. By the way, you've already made your own wms and we'll integrate these together in your own interactive web map in the next step.
2. Open a new ArcGIS map. Then open ArcCatalog in whichever way is most convenient for you. 3. Expand the "GIS Servers" folder and click "Add WMS Server".
4. In the window that opens, enter the following for the URL: http://terraservice.net/ogccapabilities.ashx? Then click "Get Layers". The window should then list layers that are available. Hit "OK".
5. Now back in ArcCatalog, you should see a new line under "GIS Servers" called "MSR Maps Map Server on terraservice.net". Expand that down at least one level, and then drag that object to the Table of Contents of your ArcMap project. It takes a few seconds for it to load. As the first layer added to your project, it will set your project’s coordinate system and current extent to match the layer you added.
6. Zoom in and play around with these layers. The USGS Raster Graphics are probably the most consistent across the US but the other image layers can be useful too. Note that the drawing order is flipped. To see the USGS Raster Graphics, you have to turn off the USGS Digital Ortho-Quadrangles. Don’t know why, that’s just the way it is.
If the images fail to load when you move to a new place in the map (it’s easy to accidently interrupt the download process), click the refresh button in the lower-left corner of your data frame. Pretty hand as a base layer, huh. There are better data sets out there, like try searching for a MODIS wms, but this TerraServer has been pretty stable for a long time. These wms images also load fairly efficiently because they are set up on a pyramid scheme where it only downloads the extent and resolution best for your current view. However, notice that there isn't a legend for these layers! Not really an issue for aerial photos, but could be an issue for other data sets. One way to overcome this issue is to distribute the link to a wms via an ArcMap layer file. For
example, "Specialty_Soil_Survey_Map.lyr" is really a wms link, but it comes with legends. Download it from the web page for this lab, add it to your project and explore it a bit.
Page | 5 7. You can also use this trick to save yourself some setup time when you want to use a wms on a different computer. Right-click your “MSR Maps Map Server” layer and select “Save as Layer File…”. Name it and save it in a good place. You can now add this wms to any ArcMap project by adding that layer file. Try it out now to see how easy it is. Make this file layer file easily available to yourself (and maybe others) by posting it within your website. (Question 4)
Step 6: Slippy Maps with OpenLayers
1. OpenLayers (http://openlayers.org/) is a free, open-source client-side map script. Working with it is kind of like working with Google Maps: it is a javascript library that you load through your web page. If you haven't already, download “ol_mi_example.html” from the lab web page. Put it in your “public_html” directory. Make sure the permissions allow global read.
2. Open the file in a text editor and browse through the script to see what it does. Notice that it sets a series of variables. First, there is “var map”, which is a required statement for OpenLayers. Then, there is “var dem” that calls on a hillshade of the US that I have associated with the .map file called “us.map”. That variable definition then specifies that the hillshade is the layer called “us_dem” in that .map file. After that is “var nex”, which pulls in a wms from NOAA with the current nexrad image. It will come in as a raster too, but because it is going on top of the “dem” map, I needed to declare that it was not the base layer (i.e. {isBaseLayer: false}). Finally, the javascript defines the variable “sta”, which references the same .map file as the “dem” variable, but instead calls the “states” layer. This is a polyline dataset that I also want to overlay onto the hillshade, so I needed to specify “transparent: ‘true’”. With all of the variables for the map layers defined, the JavaScript to draw the map with these layers with the command “map.addLayers([dem, nex, sta])”. Last, but no less important, we set the starting extent of our interactive map with “map.zoomToExtent…”. The list of four numbers that follow are the longitude and latitude values that from the initial extent (remember western hemisphere is negative values). View this html through your unix-lab webpage and try out the interactive functions (just don’t use Konquerer as a web browser). Much like Google Maps, click-dragging moves the map, double-clicking zooms in, and there are navigation buttons in the upper-left.
3. Okay, hopefully you saw that the javascript works and actually displays a hillshade with state boundaries and the current radar image drawn on it. However, the US hillshade doesn’t have a lot of contrast for looking at just Michigan and maybe we can make a more locally useful map by showing roads. By using the dem and state roads layers from that .map file you created earlier, you could make a pseudo road conditions map. Let’s do it. 4. Change the paths to the layers so they refer to your map file. Edit the variable “dem” to point to your lab8.map file’s “dem” layer. Also, use the variable “sta” line as a template to reference your roads layer. Replace “sta” with a more appropriate name like “rds”, change the path to point to your lab8.map file, and set the layers to the name of your roads layer. Now we need to make sure the “map.addLayers” list has the variables we want included. Keep “dem” in the list because we just reused that variable. “nex” stays in as we still want the radar to display as it did before. Then replace “sta” with the variable you set for the roads layer. Then, open the file in a web browser (again, probably not Konqueror). Do you have a slippy map that lets you zoom in, out, and pan around the map? Also provide a link to your OpenLayers map on your lab webpage. (Question 5)
A word about projections and OpenLayers: I need to confess that I provided you with spatial datasets that I had already converted to a GCS WGS 1984 projection. OpenLayers seems to be finicky with displaying maps in different projections. Projecting everything in to GCS WGS 1984 has been the most reliable for me. At the end of this document is some JavaScript that can be added to enable OpenLayers to handle Michigan GeoRef projections.
Page | 6 Report
Develop a short response to the first two questions and a single, lab 8 html page providing links to products asked for in the remaining questions, respectively. Email the responses and URL to your TA by the lab deadline.
1. Why is it be a bad idea to store your .map configuration file in public_html? (1 or 2 sentences) 2. How do you change the display color for a vector layer in the .map file? How would you go about
figuring out the numbers you needed to enter for the color that you wanted?
3. Make a webpage with a call to MapServer embedded within it. Link to this page from your website. 4. Provide a link on your website for downloading the layer file you created for quickly connecting to the
MSR Map Server.
5. Provide a link to your OpenLayers page that displays Michigan state roads and a DEM with the current Nexrad image.
Extra Credit. Make an OpenLayers map with spatial data of your choosing. Start by creating a .map file for the data you choose and then use an html page to display it with the OpenLayers interface. The map you create must include at least two layers that make sense displayed together. Layers can be rasters, polygons, polylines, points, or a wms from an outside source (i.e. the nexrad wms or a wms with MODIS imagery).
If you want to display points, you’ll need to provide some additional information in your .map file. Add the following text towards the bottom of the MAP section and modify as needed:
SYMBOL NAME "circle" TYPE ellipse FILLED true POINTS 1 1 END END
Using Coordinate Systems that are not Geographic with OpenLayers (i.e. Michigan GeoRef)
Also, OpenLayers can need help with projections, even if the maps display fine directly from MapServer. If you don’t use geographic coordinates, you will need to specify the projection for OpenLayers. Here is a fragment of JavaScript to demonstrate this for some Michigan GeoRef data in Leelanau County; of course you may need to alter it for your own location:
... function init() { var options = { projection:"EPSG:3078", units: 'm', maxResolution:'auto',
maxExtent: new OpenLayers.Bounds(0,0,1000000,1000000) };
map = new OpenLayers.Map('map', options); ...
See http://unix-lab.geo.msu.edu/~ashton/ms_examples/leelanau.html for a complete example using Michigan GeoRef data in Leelanau County.
