Table of Contents for

Web Mapping Illustrated

In Chapter 10 you learned how to change the extents of the map when using the shp2img command-line utility. With an interactive map the extents can be changed by zooming in, just like the test example with the global map application. The initial map shown by that application covers the whole world. If you are interested only in a map covering a certain area, you will want to change the initial extent of the map to suit your area of interest.

You will continue to build on the previous examples in this chapter, including the global.map file. The EXTENT line in the map file specifies what the initial extent of the map will be when MapServer starts up. This was set to:

EXTENT -180 -90 180 90

which covers the whole world. Now you will set this to zoom in to a new area, to make a map of Canada. You will do so by continuing to use the countries_simpl.shp shapefile, and also use the ogr2ogr and ogrinfo tools to assess what extent you need. Please see the procedures for using ogr2ogr and ogrinfo in Chapter 10. Example 10-5 shows the same methodology for determining the extent of Bulgaria.

These command-line programs aren’t part of MapServer. They are part of the GDAL/OGR package described in Chapter 3. The ogr2ogr utility extracts the shapes of Canada and saves them in to a new shapefile. ogrinfo is then run to see what the coordinate extents of Canada are.

The new shapefile is used only as a temporary means of determining the coordinates of the area of interest. These coordinates are then set in global.map so that MapServer focuses on Canada.

The extent of Canada, as returned from ogrinfo, is:

Extent: (-141.000000, 41.675980) - (-52.636291, 83.110458)

You can put this extent into the global.map file and see how things look. Simply copy/paste this text right into the map file and then clean it up, removing brackets and commas. Example 11-4 shows how the first few lines of the changed application look.

MAP
  SIZE 600 300
  EXTENT -141 42 -52 83
...
    CLASS
      NAME 'Canada'
      EXPRESSION 'Canada'
      OUTLINECOLOR 100 100 100
      COLOR 255 255 150
    END
...

In this example, exact coordinates aren’t required. You can round them off or drop the decimals. Note the changes to the LAYER object. The class that highlighted Bulgaria now highlights Canada instead. The LABEL object has been removed from the CLASS object. Figure 11-4 shows the initial map produced by using these new extent settings.

The extents of this map are so tight that it is hard to really get the context of the map. It is zoomed in so tightly to Canada that it’s difficult to see any of the neighboring countries.

To make the map look a little nicer, increase the extent settings by five degrees. Here are the the initial and final extents:

Figure 11-4. The initial map with Canada’s extents specified in the map file

The values of the new extent aren’t just all increased or decreased. The minimum values (the first two numbers) are decreased because I want more of the south and west of the map to be shown. The maximum values (the last two numbers) are increased to show more of the north and east parts of the map. Increased here means made more positive, not just increasing the absolute value. This holds true for the western hemisphere north of the equator, and when using latitudes and longitudes. Figure 11-5 shows where the extents are on a map. Figure 11-6 shows the resulting map that uses the final extent.

If no PROJECTION objects are set for the map or the layers, MapServer assumes they are all in the same coordinate system. Therefore, no reprojection is required. For data in decimal degrees, MapServer uses a default map projection (a.k.a. Plate Caree). This default projection isn’t the best way to display this map because it distorts several properties of the map. A large part of Canada is in the polar region, which this projection specifically distorts.

Figure 11-5. Map of showing the initial and final extents used for a map of Canada

Figure 11-6. The map with slight changes to the extent to show Canada more clearly

...
  UNITS DD

  PROJECTION
                     "proj=latlong"
                     "ellps=WGS84"
  END

  SCALEBAR
  ...
  LAYER
    NAME countries
    TYPE POLYGON
    ...
    CLASS
      NAME 'All Countries'
      OUTLINECOLOR 100 100 100
      COLOR 200 200 200
    END
    PROJECTION
                     "proj=latlong"
                     "ellps=WGS84"
    END
  END
END

PROJECTION
  "init=epsg:42304"
END

PROJECTION
  "proj=lcc"
  "ellps=GRS80"
  "lat_0=49"
  "lon_0=-95"
  "lat_1=49"
  "lat_2=77"
  "datum=NAD83"
  "units=m"
  "no_defs"
END

<42304> +proj=lcc +ellps=GRS80 +lat_0=49 +lon_0=-95 +lat_1=49 +lat_2=77 +datum=NAD83 +units=m no_defs <>

Modifying the map extent

Just changing the map projection won’t give you a working map. You still need to change the extent settings for the map. These need to be set in meter units because the projection in the example uses meter units (units=m) rather than decimal degrees. How do you choose what extent to use? This is where it helps to know a bit about map projections, although some simple guessing and testing of extent values is perfectly valid too.

Here is one way to help determine what extent you want to have. The extents will be set in meter units, relative to the latitude of origin and central meridian of the projection. These details are listed in Example 11-6. The central meridian is -95° longitude, and the latitude of origin is 49° north. When the extent of the map is set, the southwest and northeast corners will be the distance, in meters, from the central point: -95°, 49°. For example

EXTENT -3000000 -1000000 3000000 1000000

sets the extent to start at 3,000 km west and 1,000 km south of the central point, and extend to 3,000 km east and 1,000 km north. If you go back to Figure 11-5, you can use the map grid to help determine where the center point is. It is centrally located but south of the center of the country, along the U.S. border. Now you can decide how wide and tall you want your extent to be. Figure 11-6 is a good map to give you an idea of distances. The scale bar provides a reference for the width of Canada. Setting an extent that is 6,000 km wide isn’t unreasonable. Figure 11-7 shows the resulting map using the above extents.

Figure 11-7. An initial guess for setting the map extents using an LCC projection of Canada

The initial guess wasn’t too bad, though you can see that the map is shifted too far south and not far enough east. Through a process of tweaks and changes, you can determine an optimal extent to use. For example, you can decrease the minimum y and increase the maximum y values in the extent. Test out a few variations. Here is one extent that works well:

EXTENT -2400000 -900000 3100000 4000000

With these extents, MapServer produced the map shown in Figure 11-8. Grid lines were added to the map to show the difference in the shape of features that the projection change makes. Compare it to the regular rectangles in Figure 11-6.

Figure 11-8. Final map extents set for a map of Canada

There is a lot of extra space on the left and right sides of the map in Figure 11-8. This can be easily fixed by changing the size of the map image.

This mapping application was originally set up to show the whole world using a global project, which works great assuming the world map is twice as wide as it is tall. The map SIZE setting has been 600×300 throughout these exercises. That’s a width to height ratio of 2 to 1. The previous map shows that Canada is roughly square using that LCC map projection. You can change the size of your map to be roughly 1 to 1, and the map will fit much better to the extents of Canada. Change the size setting to something like 400×400 or 600×600, and see how it looks. This is done by changing the SIZE setting near the beginning of the map file: SIZE 600 600.

The resulting map is shown in Figure 11-9. Notice how much better Canada fits into the map image.

Before you can start mapping this, you need to change the image dimensions used in the HTML template file, global.html. The image width and height was hardcoded. To make the map more flexible, you can replace the hardcoded image dimensions with MapServer variables. This allows the HTML template to dynamically set the image dimensions based on the settings in the map file.

To use the MapServer variables instead, change line 7 in global.html. Replace the width and height numbers with the [mapwidth] and [mapheight] variables. It should look like this:

<INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]" border=0 ALT="Map Image">

Figure 11-9. Map of Canada with a map SIZE setting ratio of 1:1

Likewise, you need to change the imgxy variable to automatically use the center of the image instead of the hardcoded center pixel value:

  <INPUT type="hidden" name="imgxy" value="[mapcentroidx] [mapcentroidy]">

So far, the application has only one real tool. You can point and click to zoom in to an area. You haven’t been able to zoom out (other than by hitting the Back button in your web browser) or move the map sideways to recenter your view. Now you’ll add add three options to the web page, one for zooming in, another for zooming out and one to recenter the map on a new location.

If you are already familiar with HTML forms, this will be a snap. All you’re doing is adding an HTML form control that passes another CGI variable to the MapServer program. In the application so far, zooming was hardcoded. Instead, you will make a three-way option using three radio buttons.

Radio buttons are different from check boxes and normal buttons. When multiple radio buttons have the same name, only one can be selected at a time. This works perfectly for the task of selecting a single tool or option.

Example 11-7 shows the modified HTML template file, global.html, and Figure 11-10 shows the resulting web page from the exercise.

Figure 11-10. Adding some basic map controls to the web page

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>
<hr>

<FORM method=GET action="/cgi-bin/mapserv">
  <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
               border=0 ALT="Map Image">
  <BR>

  Zoom In
  <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >

  Re-center
  <INPUT type=radio name=zoomdir value=0 [zoomdir_0_check] >

  Zoom Out
  <INPUT type=radio name=zoomdir value=-1 [zoomdir_-1_check] >

  Zoom Size
  <INPUT type=text name=zoomsize size=4 value=[zoomsize]>

  <!-- Remove the following three lines
  <INPUT type=hidden name=zoomdir value=1 [zoomdir_1_check] >
  <INPUT type=hidden name=zoomsize size=4 value=[zoomsize]>
  -->

  <INPUT type="hidden" name="imgxy" value="[center_x] [center_y]">
  <INPUT type="hidden" name="imgext" value="[mapext]">
  <INPUT type="hidden" name="map" value="[map]">
  <INPUT type="hidden" name="savequery" value="true">
  <INPUT type="hidden" name="mapext" value="shapes">

</FORM></CENTER></BODY></HTML>

First, the radio button settings were added to the form. These are spaced out in the code example to try to show them more clearly. All three are very similar. Text will be shown beside the button, and the form code defines what each button does. The first two changed lines are formatting and labeling of the button:

<BR>
Zoom In

The <BR> tag acts as a new line, so that the tools are displayed underneath the map image. The words Zoom In start on a new line and are next to the radio button itself. The radio button is defined by the tag:

  <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >

The <INPUT...> tag is part of the CGI form on this page. It has three settings:

The final piece of text in the INPUT tag is: [zoomdir_1_check]. This is a piece of text that is replaced by MapServer when the HTML page is created. This is similar to the [img] variable used to draw the map in the page. MapServer replaces these placeholders with values after creating the map. In this case, it replaces the text with the word checked beside the button that was pressed last. If you click on Zoom In, then click on the map, it should zoom in to where you clicked on the map. At that point the Zoom In tool will still be selected. That is because it is now marked as checked. You can see this in the HTML behind the page showing the map:

<INPUT type=radio name=zoomdir value=1 checked >

If you select the Re-center button, it marks the second radio button with the checked setting:

<INPUT type=radio name=zoomdir value=0 checked >

This allows the web browser to maintain the options you selected when it draws a new map or refreshes the page.

The only other line added was to enable the box to enter in a Zoom Size:

               Zoom Size
  <INPUT type=text name=zoomsize size=4 value=[zoomsize]>

This setting tells MapServer how much to zoom in (or out) when a user clicks on the map. For example, a zoom size of 2 doubles the scale and makes features on the map appear twice as large. This was hardcoded into a hidden variable before adding the controls. These lines can now be removed from the HTML template. The zoomdir setting was also hardcoded to value=1, so that any time a user clicked on the map it only zooms in. With the new controls just added, these lines are no longer required:

               <INPUT type=hidden name=zoomdir value=1 [zoomdir_1_check] >
  <INPUT type=hidden name=zoomsize size=4 value=[zoomsize]>

One change is also required in index.html. In the earlier examples, the default action was to zoom in. You had to set the hidden zoomdir variable to value=1, which MapServer interprets as zoom in. By changing this to value=0 (zero), it makes the default action be recenter instead of zoom. This will become more important by the end of this chapter when we study the redraw button. If you hit redraw, and zoom in is selected by default, the map will not only redraws, but also zooms in. Here is the changed line in index.html:

<INPUT type="hidden" name="zoomdir" value=0>

Zoom and recenter features are critical for most web mapping applications. Many users also like the ability to control what layers they see. Those using the application will need some level of control. Being able to turn layers on and off is a key part of many MapServer applications. Try to give users as much freedom to explore their maps as possible, but also try to prevent them from making major mistakes. For example, if you give complete control and allow them to turn off every layer, the map will be empty. They got what they asked for but may think that your application is broken. You will have to decide how important complete control is versus having things a bit more restrictive but predictable.

Before you get into setting up layer selection options, you need to create a new layer in the global mapping application. You could find some images to include or another shapefile showing the locations of places of interest. To keep it simple, the following example is going to create a layer that shows text labels for the countries. You can do this using the same countries_simpl shapefile dataset that is already being used in the application. Example 11-8 shows the new layer created in global.map. The new layer is called country_labels. Instead of drawing polygons or lines, tell it to only draw labels by setting TYPE ANNOTATION.

  LAYER
    NAME country_labels
    TYPE ANNOTATION
    STATUS DEFAULT
    DATA countries_simpl
    LABELITEM 'NAME'
    CLASS
      LABEL
        COLOR 255 255 255      
        OUTLINECOLOR 0 0 0
        POSITION CC
        MINFEATURESIZE 100
      END
    END
    PROJECTION
      "proj=latlong"
      "proj=WGS84"
    END
  END

With MapServer, you can set layers to be drawn two ways. One way is to force the map to always draw the layer. This is done by setting the layer to STATUS DEFAULT. The other way is to have it turned on only when requested. In this case you can set it to STATUS OFF. If a layer is set to OFF in the map file, it doesn’t mean it will never be drawn. If the layer is requested to be drawn by the web page, then it will be.

Right now there are two layers in the map file: countries and country_labels. To have the country boundaries always shown, leave the countries layer STATUS set to DEFAULT. But for country_labels, set it to STATUS OFF. This allows the user to turn off the labels.

The next place you make changes is in the index.html page. The settings in this page tell MapServer which layers to draw when drawing the first map. This is different from setting the layer to be on by default in the map file. Instead, the index.html page will pass a list of layers to draw through to the MapServer program. If the layers are available in the map file, it will request to see them. You will see the names of the layers embedded in the URL as CGI values (e.g., &layers=countries). MapServer uses these parameters to determine which layers to draw.

Back in Example 11-2 you saw the initial settings for index.html. That included this line:

  <input type="hidden" name="layer" value="countries">

Having this line as part of the initialization form meant that MapServer would be requested to draw the countries layer when the first map is drawn. Considering that the layer is already set to draw by default, this setting becomes redundant. countries will be drawn all the time anyway, and the user won’t be able to turn it off. However, keep this line, and copy it for use with the new layer that shows the labels:

  <input type="hidden" name="layer" value="country_labels">

Now when the map starts up, both layers will be drawn. If you don’t want any layers other than those set with STATUS DEFAULT to be drawn, just remove any of the lines in index.html, where name="layer".

The third place to set up layer options is in the HTML template file (global.html). MapServer puts the map image into this HTML page and displays any of the controls you want to have in your application, including a list of layers to choose from. This is the most labor-intensive part of the exercise, but it is important. This is where the user will actually see some options. The settings in global.map and index.html are hidden from the user (except in the URL) but anything shown in the HTML template page will be for the user to see.

The HTML template page already has a form defined on it. All you need to do is add in a few more controls, also known as select options. To have these displayed on the right side of the map, put the code right after the <INPUT...> tag that draws the map. Make sure there are no line breaks <BR> between the select controls and the map if you want them to be side by side. Make sure that a <BR> tag follows the select list so that the zoom/recenter controls are below everything else. Example 11-9 shows the first few lines of HTML, including the start of the SELECT tag which is needed for the layer list.

...
<FORM method=GET action="/cgi-bin/mapserv">
  <BR> <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="
  [mapheight]" border=0 ALT="Map Image">
  <SELECT multiple name="layer" size=3>
  <!--the list of layers to chose from will go here -->
  </SELECT>
  <BR>
    Zoom In <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >
...

So far the list won’t do anything. Next you need to add an entry for the country_labels layer. You should also add some text that will be displayed near the list to describe what the list is showing. Each layer that you want to show in the list needs an <OPTION...> tag like this:

<OPTION value="country_labels" [country_labels_select]> Country Names</OPTION>

The pieces specific to the application have been highlighted. The first setting, value="country_labels", is the name of the layer that will be drawn when this entry is selected from the list.

The second setting [country_labels_select] is necessary for the web page to highlight layers you have selected on previous maps. This is similar to the checked settings used when creating the radio buttons for zoom/recenter. This setting should be the same as the value setting, but with _select added to it.

The third item added is the text Country Names. This is outside of the <OPTION...> tag and is text to be written on the web page. The text put here can be whatever you want it to be. It will be used as a label for this layer in the select list on the web page. With all these changes, the new web page looks like Figure 11-11.

The complete global.html file looks like Example 11-10. In the final global.html, some text describing how to use the list and what it is for has been added. A few of the tags are moved around to make the page a bit more structured.

Figure 11-11. The layer select list added to the map page

<HTML>
<HEAD><TITLE>MapServer Test</TITLE></HEAD>
<CENTER><H2>MapServer Test</H2>
<HR>

<FORM method=GET action="/cgi-bin/mapserv">
    Zoom In <INPUT type=radio name=zoomdir value=1 [zoomdir_1_check] >
    Re-center <INPUT type=radio name=zoomdir value=0 [zoomdir_0_check] >
    Zoom Out <INPUT type=radio name=zoomdir value=-1 [zoomdir_-1_check] >
    Zoom Size <INPUT type=text name=zoomsize size=4 value=[zoomsize]><BR>
  <INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
  border=0 ALT="Map Image"><BR>
  <B>Select Layers to Display: </B><BR>
	  Press "CTRL" and Click to select more than one<BR>
  <SELECT multiple name="layer" size=3>
    <OPTION value="country_labels" [country_labels_select]> Country Names</OPTION>
    <OPTION value="countries" [countries_select]> Country Boundaries</OPTION>
  </SELECT>

  <INPUT type="hidden" name="imgxy" value="[center_x] [center_y]">
  <INPUT type="hidden" name="imgext" value="[mapext]">
  <INPUT type="hidden" name="map" value="[map]">
  <INPUT type="hidden" name="savequery" value="true">
  <INPUT type="hidden" name="mapext" value="shapes">

</FORM></CENTER></BODY></HTML>

The natural next question is, how do you make the map redraw after choosing new layers? You can use the zoom or recenter tools, and it will update the map, reflecting this change, but this is hardly intuitive. The easiest way is to add a button to the page that requests a new map. HTML forms have a submit button you can use. Add this code to global.html, right after the end of the select list </SELECT>:

<BR><INPUT type="submit" value="Redraw/Update">

Now a button will appear right under the select list, as shown in Figure 11-12. You can select or deselect a layer, press the button, and see the change on the new map.

Figure 11-12. Adding a submit button to the web page to request a new map

Congratulations. You have created your own interactive web mapping applications. There is a lot more to learn but you know the basics of creating interactive maps. The rest of the chapter provides a few more tweaks and tips for further developing your application.

A legend is another key component of web mapping application and is very simple to add. It only takes a minute to modify your code to add a legend graphic to the page. The legend is a small graphic showing what colors and styles are being used to draw the map layers. So far in this example application you’ve used an embedded legend that is part of the map image. Now you will pull that legend out of the map image and have it drawn separately on the page. This requires two changes: one modification of the global.map file to remove the embedded legend and an addition to the global.html file to draw the legend on the page.

# Original legend
  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END
#-------------------
# Modified legend
  LEGEND
    STATUS ON
  END

<BR><HR>
<B>Legend</B><BR>
<IMG src="[legend]" alt="Map Legend"><HR>

<A HREF="[legend]" TARGET="_blank"><B>View Legend</B></A>

Scale bar images are created through the same process as legend images. When the scale bar isn’t used as an embedded image, it is created as a separate image. MapServer then inserts it into the HTML template wherever it finds the [scalebar] variable.

To global.html add one simple line, just like with the legend. Place it below the map image so that it is near enough to be useful for measuring. This is shown in Example 11-13.

Figure 11-13. Legend graphic added as a separate entity on the web page

Figure 11-14. Creating a link to the legend graphic

<INPUT NAME="img" TYPE="image" SRC="[img]" width="[mapwidth]" height="[mapheight]"
             border=0 ALT="Map Image"><BR>

<IMG src="[scalebar]" alt="Map scale bar"><BR>

<B>Select Layers to Display: </B><BR>

In the SCALEBAR object of the global.map file, change STATUS EMBED to STATUS ON so that the scale bar is no longer shown on the map image itself.

The final outcome looks like Figure 11-15.

Figure 11-15. A scale bar graphic added to the web page

Just like a legend and scale bar, a reference map image can be created at the same time as a map and added to your application. This requires a bit more forethought and some preparation. You need to keep in mind the purpose of your reference map. Typically, it is used for two purposes.

The primary purpose is showing where you are zoomed in to, relative to the original extent of the map. For example, Figure 11-16 shows a MapServer-based web site (http://www.gommap.org) that uses a reference map to orient users to their current view of the map.

Figure 11-16. Gulf of Maine web mapping application showing reference map

Reference maps can also be used to recenter the main map. If you want to view a different area, just click on the reference map, and the main map will recenter on that location. This feature is particularly helpful when you want to maintain the scale of your map but move to another location. Rather than using the recenter tool on the main map over and over again, just one click in the reference map takes you there.

Adding a reference map to your application follows a similar process to adding a legend or scale bar. You add a REFERENCE object to your map file and some code to the HTML template (e.g., global.html). The only other requirement is an image file to use for the reference map. It isn’t generated with a map file or layers but is a static background map image.

You can download a small world map image in PNG or GIF format from:

The image is shown in Figure 11-17.

Figure 11-17. A reference map image

Now, save the image in the same folder as the global.map map file. Add the code highlighted in Example 11-14 to the map file. I recommend you do so somewhere near the beginning. In this example, it is shown between the LEGEND and PROJECTION objects.

...
  LEGEND
    STATUS EMBED
    POSITION LR
    TRANSPARENT TRUE
  END

  REFERENCE
    STATUS ON
    IMAGE keymap.png  # This could be keymap.gif instead
    EXTENT -180 -90 180 90
    SIZE 241 121
    COLOR -1 -1 -1
    OUTLINECOLOR 255 0 0
  END

  PROJECTION
    "proj=latlong"
...

The reference image file doesn’t have geographic coordinates saved in the file. Instead, you must specify what the extent coordinates are using the EXTENT setting. This tells MapServer that the keymap.png image covers the globe. The SIZE setting tells how wide and tall the image is (in pixels). These two settings allow MapServer to find a specific coordinate location on the reference map image. If your reference map doesn’t seem to work properly, one of these two settings may be incorrect.

When the reference map is used, it draws a rectangle on top of the keymap.png image. The COLOR setting sets what color that rectangle will be. It is red by default. COLOR -1 -1 -1 tells MapServer to not color the rectangle, but to make it transparent. The OUTLINECOLOR setting gives the rectangle a red outline.

The REFERENCE object doesn’t have projection settings. This means that the EXTENT is always specified in the same units as the output map projection. This example really only works with a map that is displayed in the lat/long projection used at the beginning of this chapter. Also, the extents will not be specified in meter units for the LCC projection used earlier. Instead, the units must be set to UNITS DD for this example to work. The map EXTENT will need to be in decimal degrees.

The global.html template file needs to be modified as well. There are two ways to do this. The first is to include another <IMG> tag, like <IMG SRC="[ref"]>. This creates a simple reference map. The other way to add the reference map lets you click on the reference map to recenter your map. Use this code instead of the previous:

<INPUT name="ref" TYPE="image" SRC="[ref]" width="241" height="121" ALT="Reference map">

This shows the image and also sets it up to take a click and change the main map image. If you add it right after the main map image, you will have a web page that looks similar to Figure 11-18. All the layer controls have been removed, and the legend and scale bar were switched back to embed.