Example 1: Building a URL to retrieve WMS data

The following link retrieves an orthoimage of Lake Tenaya in Yosemite National Park:

NO MORE AVAILABLE

It is important to follow EXACTLY the syntax given above, otherwise an error message will show up instead of an image. The first part of the URL is the server and service name. This part of the URL is the same as the previous request to the metadata. For Yosemite National Park data is needed in the UTM zone 11, hence the parameter SRS=EPSG:26911. BBOX=282587,4188958,283717,4190390 defines the xmin, ymin, xmax, ymax values of the bounding box. The width=553 and height=700 parameters define the image size in pixel. Make sure that the width/height ratio of the bounding box matches the width/height ratio of the image size, otherwise distorted images will be the outcome. The format=image/jpeg parameter specifies the output format. The OGC currently supports jpeg, png and svg as image formats, however, at the time of writing you won't find many WMS services with SVG output.

Example 2: Embedding the WMS Service in a SVG application

Step 1 - Download Files:

Download the necessary files from the map navigation tutorial and make sure you have a working copy of the Yosemite National Park example, by opening the file index.svg in your web browser and testing whether the navigation tools work.

Step 2 - Add a checkBox for Controlling Visibility and Data Loading:

Next, open the file index.svg in a text or XML editor and add a new checkbox and group element for the orthophoto layer by adding the following lines to the function init() in the script section of the file (consult the Checkbox and Radiobutton tutorial for details):

myMapApp.checkBoxes["DOQ"] = new checkBox("DOQ","checkBoxes",0,40,"checkBoxRect","checkBoxCross",true,"DOQ (Orthoimage) provided by Terraserver",labeltextStyles,12,6,undefined,toggleMapLayer);

Next, add the folowing line in the main map section (<g id="mainMapGroup" /> element) between the image with the id "ShadedRelief" and the path with the id "park_boundary". The requested WMS image will be later appended to this empty group.

<g id="DOQ" visibility="visible" />

Save the file "index.svg" and reload it in the browser. Test and see if the new checkbox toggles without an error message

Step 3 - Add a Function to Load the Image:

Copy the following ECMAScript code into the script section of the file "index.svg", after the function loadProjectSpecific():

//load usgs/terraserver orthoimage
//you have to use full pixel values, otherwise an error appears
function getOrthoImage() {
	var myRasterLayer = document.getElementById("DOQ");
	if (myRasterLayer.childNodes.length > 0) {
		var oldImage = document.getElementById("DOQImage");
		myRasterLayer.removeChild(oldImage);
	}
	if (document.getElementById("DOQ").getAttributeNS(null,"visibility") == "visible") {
		var myRasterImage = document.createElementNS(svgNS,"image");
		myRasterImage.setAttributeNS(null,"x",myMainMap.curxOrig);
		myRasterImage.setAttributeNS(null,"y",myMainMap.curyOrig);
		myRasterImage.setAttributeNS(null,"width",myMainMap.curWidth);
		myRasterImage.setAttributeNS(null,"height",myMainMap.curHeight);
		myRasterImage.setAttributeNS(null,"id","DOQImage");
		var myImageUrl = "NO MORE AVAILABLE" + myMainMap.epsg;
		myImageUrl += "&BBOX=" + parseInt(myMainMap.curxOrig) + "," + (parseInt(myMainMap.curyOrig + myMainMap.curHeight) * -1);
		myImageUrl += "," + parseInt(myMainMap.curxOrig + myMainMap.curWidth) + "," + (parseInt(myMainMap.curyOrig) * -1);
		myImageUrl += "&width=" + myMainMap.pixWidth + "&height=" + myMainMap.pixHeight + "&format=image/jpeg";
		myRasterImage.setAttributeNS(xlinkNS,"xlink:href",myImageUrl);
		myRasterLayer.appendChild(myRasterImage);
	}
}		

This code first gets a reference to the group element that will contain the orthoimage. Next, it checks whether the group already has one child and if yes, it removes a previously loaded orthoimage, e.g. after zooming or panning. It checks whether the DOQ layer is visible and if yes, it creates a new image element and sets all attributes. It also creates a new URL containing the current map extent in the BBOX argument and sets the width and height parameters. Note that it is necessary to provide full pixel values for the width and height values, hence the parseInt() method. Finally, it sets the xlink:href attribute (note the explicit use of the xlinkNS namespace) and appends the newly created image into its parent group. If the layer isn't visible, it does not create an image and therefore makes no call to the Terraserver.

Step 4 - Call the Function getOrthoImage() from the Function loadProjectSpecific():

In order to reload the image each time the user zooms and pans, add the line

getOrthoImage();

to the end of the function loadProjectSpecific() in the file "index.svg".

Step 5 - Extend the toggleMapLayer Function to Load the Orthoimage:

In this final step the toggleMapLayer(id,checkStatus,labelText) function needs to be extended (in the script section of the file index.svg) to call the function getOrthoImage() if the user turns a layer on. This is necessary, because otherwise the image would only load after the next zoom or pan event. Add the following lines at the end of the function:

if (checkStatus) {
	if (id == "DOQ") {
		getOrthoImage();
	}
}

Save the files "index.svg" and reload the project in a browser. It should now be possible to browse within the orthophotos of the Terraserver and always automatically get the appropriate resolution. Toggling the checkbox should show and hide the image.

This is the final example that should appear after working through part one of this tutorial.

Example 3: Creating/Editing a UMN Map File

Following is the map file provided in the tar.gz file. Most of the code is self-explanatory, even more with the provided comments:

#
# Start of map file
#
MAP
  # project name
  NAME Yosemite_Relief
  STATUS ON
  # default size
  SIZE 600 600
  # maximum map extent
  EXTENT 244000 4150000 308000 4231000
  UNITS METERS
  # path variable to our map data, in our case the tif files
  SHAPEPATH "data"
  # default color for nodata values: white
  IMAGECOLOR 255 255 255
  # parameters for the output format
  # see also the documentation at
  # https://mapserver.gis.umn.edu/doc44/mapfile-reference.html#outputformat
  OUTPUTFORMAT
  	NAME jpeg
  	DRIVER "GD/JPEG"
  	# quality setting: 0 is minimum quality, 100 is maximum quality
  	FORMATOPTION QUALITY=70
  	# data format
  	MIMETYPE "image/jpeg"
  	# currently, there is no real grayscale jpeg output available
  	IMAGEMODE RGB
  	EXTENSION "jpg"
  END
  PROJECTION
  		# projection: UTM zone 11, Datum NAD83/GRS80 Spheroid
		"init=epsg:26911"
  END
  WEB
  	METADATA
  		# the title of the WMS service
  		WMS_TITLE "Yosemite Shaded Relief"
  		# this contains the URL to your WMS service, it includes the absolute path to your hillshading.map file
  		# if you don't want to use an absolute path in this URL you can set a "RewriteRule" in your web server configuration
  		WMS_ONLINERESOURCE "your.server.name/your-cgi-directory/mapserv?map=/absolute/path/to/map_file/hillshading.map&"
  		# projection information
  		WMS_SRS "EPSG:26911"
  	END
  END

  # Start of layer definitions
  # All layers share one group name: hillshade
  # this group name can be used instead of the individual layers
  # has the advantage of automatically delivering different resolutions
  #
  LAYER
    	# name of individual map layer
    	NAME "hillshade_detailed"
    	# group name - we prefer group name over the real layer name in order to automatically
    	# deliver the right dataset according to min/max scale settings
    	GROUP "hillshade"
    	# file name of the geographic resource
    	DATA "relief_detailed_smooth.tif"
    	# type is raster data
    	TYPE RASTER
    	# turn on layer
    	STATUS ON
    	# display layer only in map scales of 50000 and larger, means scale values < 50000
    	MAXSCALE 50000
    	# metadata section
    	METADATA
      		# title of layer
      		WMS_TITLE "Yosemite Shaded Relief Analytical, Detailed"
      		# more detailed explanation
      		WMS_ABSTRACT "Shaded Relief of the Yosemite National Park, Analytical Hillshading, finer resolution"
      		# projection information
      		WMS_SRS "EPSG:26911"
    	END
    	PROJECTION
    		"init=epsg:26911"
    	END
  END
  LAYER
    	NAME "hillshade_middle"
    	GROUP "hillshade"
    	DATA "relief_detailed.tif"
    	TYPE RASTER
    	STATUS ON
    	# display layer for scale values: 50000 < scaleValue < 100000
    	MINSCALE 50000
    	MAXSCALE 100000
	
    	METADATA
      		WMS_TITLE "Yosemite Shaded Relief Analytical, Normal"
      		WMS_ABSTRACT "Shaded Relief of the Yosemite National Park, Analytical Hillshading, normal resolution"
      		WMS_SRS "EPSG:26911"
    	END
    	PROJECTION
    		"init=epsg:26911"
    	END
  END
  LAYER
    	NAME "hillshade_rough"
    	GROUP "hillshade"
    	DATA "relief_hand.tif"
    	TYPE RASTER
    	STATUS ON
    	# display layer only in map scales of 100000 and smaller, means scale values > 100000
    	MINSCALE 100000
	
    	METADATA
      		WMS_TITLE "Yosemite Shaded Relief Manual"
      		WMS_ABSTRACT "Shaded Relief of the Yosemite National Park, Manual Hillshading"
      		WMS_SRS "EPSG:26911"
    	END
    	PROJECTION
    		"init=epsg:26911"
    	END
   END
  
END # Map File

Comments in the map file are led in with the prefix "#". These lines are ignored by the map file parser. At a production site these comments probobly won't be needed. Removing them to speeds up the application. Each section is closed with an END statement. The MAP section contains metadata information on the project: name, projection, default size, extent, etc. An important setting is the SHAPEPATH directive which is a relative or absolute path in relation to the map file location. This directory can not only contain ESRI shapefiles, but every Mapserver supported geodata format, in this case the tif files and their corresponding world files.

Within the MAP the OUTPUTFORMAT section can be found which defines the format and quality settings of the output format. In this case the jpeg format is used. The jpeg format is the prefered output format for aerial images, satellite images and continuous tone shaded reliefs. For images with fewer colors and larger homogenous areas, the png or gif format would be preferable. While the jpeg compression is a lossy compression, the png and gif compression mechanisms are lossless. However, jpeg compression works better on photos. Note, that in the OUTPUTFORMAT section the color mode is also defined(IMAGEMODE which can have values RGB for 24bit color images or PC256 for 8bit indexed color images) and quality settings. The jpeg quality settings range between zero (minimum quality) and 100 (maximum quality). For more information on the OUTPUTFORMAT section see the OUTPUTFORMAT documentation.

The PROJECTION section contains the projection information as explained in part one of this tutorial. In this case, the UTM projection, zone 11 with NAD83 datum is used. The WEB --> METADATA section contains the information displayed as metadata for the GetCapabilities method as described in part one of this tutorial.

The LAYER section is more or less self explaining. Important is the filename specified with the DATA directive. TYPE RASTER indicates that raster data is being used. The GROUP directive in combination with the MINSCALE and MAXSCALE parameters are very useful directives for level of detail switches. All map layers that share the same group name are processed like an individual layer. The MINSCALE and MAXSCALE parameters decide internally which layer will actually be used. For the external WMS interface the three layers defined in this map file seem to be just one single layer named "hillshade". Please note that if you use the GROUP directive, that you have to define the MINSCALE and MAXSCALE directives as well. If you omit these directives you will get just a white image. Incorrectly defining minimum and maximum scale thresholds are also common error sources. If your application does not behave as expected, double check those settings! Finally, the METADATA and PROJECTION settings are used as above in the MAP section.

Looking at the data directory, you will find the tiny text files with the ".wld" extension. These files contain the georeferencing information. Without that information, the mapserver cannot relate the image coordinates to real world coordinates. Have a look at the file "relief_hand.wld":

                  19.99891657442289 
                   0.00000000000000 
                   0.00000000000000 
                 -19.99891657442289 
              244151.01352907511000 
             4232226.28952664600000 

It has 6 lines. The first line specifies the cell size in map units, the second and third line define rotation and skewing parameters, in many cases (if the image was already rectified to the native projection system) these parameters will be zero. The fourth line is again the cellsize, in this case with a negative sign, indicating that we progress with georeferencing from the top left corner to the lower right corner. The fifth and sixth line contain the x and y coordinates of the center of the top left pixel. As an alternative to the separate world files, the mapserver also supports geotiff files where the georeferencing information resides in the tiff header of the file.

For performance reasons it is suggested to store the input data as uncompressed tiff files. Using that scheme, data can be extracted more quickly than with compressed files. Disk storage is cheap compared with processing time on busy map servers. Jpeg files and compressed tiff files take longer to extract data. If your input raster file exceeds a certain pixel range (e.g. 4000x4000 pixel) it is suggested to tile your data as described in the map server UMN Raster Howto (sections "Rasters and Tile Indexing" and "Raster Display Performance Tips"). Reducing color depth also helps if the full 24bit color range is not needed. It is recommended to have a look at the raster how-to, if you deal with larger amounts of raster data or need the more advanced features, such as classifying or querying individual raster values.

After modifiying the map file, you could try your new WMS service. First, you can try the GetCapabilities method by directing your browser to the address:

your.server.name/your-cgi-directory/mapserv?map=/absolute/path/to/your/map/file/
hillshade.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities	

Of course you need to replace your server name, cgi-bin directory and absolute path to your map file. If you do not like to reveal the absolute path values in the URL, you can define a RewriteRule directive in your webserver configuration.

Finally, direct your browser to a URL requesting an image.

your.server.name/your-cgi-directory/mapserv?map=/absolute/path/to/your/map/file/
hillshade.map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=hillshade&STYLES=&SRS=EPSG:26911
&BBOX=244000,4150000,308000,4231000&WIDTH=553&HEIGHT=700&FORMAT=image/jpeg

Again you should change your URL to match your server setup. You should now be able to retrieve a jpeg raster image displaying the shaded relief of Yosemite National Park, directly from your own webserver.

With UMN Mapserver >= version 4.8 it is possible to control the resampling process of raster images. In order to do so, one has to add an additional line for each raster LAYER to be resampled as follows:

PROCESSING "RESAMPLE=AVERAGE"

The following methods are available: NEAREST (default, fast, low quality), AVERAGE (slower, better quality for downsampling), BILINEAR (slower, better quality for upsampling).

Example 4: Integrating the UMN WMS Service with the SVG Mapping Application

You can continue with the example 2 created in the first section of the tutorial or use your own file "index.svg" that you created during the first part of the tutorial. Open it again in your text editor and create a new function called getRaster(layer). In this function, similar to the example 2, a potential previous image will be removed, a WMS URL will be built and a new image to be appended into its prepared parent group will be created. The argument "layer" serves as a variable to hold the layername requested. This layername is used in the function to build the URL (layername and map file name), but also within the checkbox id and group name to hold the data as described below. But first, insert the following function as written below:

//load mapserver raster images
//use full pixel values, otherwise an error will appear
function getRaster(layer) {
	var myRasterLayer = document.getElementById(layer);
	if (myRasterLayer.childNodes.length > 0) {
		var oldImage = document.getElementById(layer+"Image");
		myRasterLayer.removeChild(oldImage);
	}
	if (document.getElementById(layer).getAttributeNS(null,"visibility") == "visible") {
		var myRasterImage = document.createElementNS(svgNS,"image");
		myRasterImage.setAttributeNS(null,"x",myMainMap.curxOrig);
		myRasterImage.setAttributeNS(null,"y",myMainMap.curyOrig);
		myRasterImage.setAttributeNS(null,"width",myMainMap.curWidth);
		myRasterImage.setAttributeNS(null,"height",myMainMap.curHeight);
		myRasterImage.setAttributeNS(null,"id",layer+"Image");
		var myImageUrl = "your.server.name/your-cgi-directory/mapserv?map=/absolute/path/to/your/map/file/";
		myImageUrl += layer+".map&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=" + layer + "&STYLES=&SRS=EPSG:"+myMainMap.epsg;
		myImageUrl += "&BBOX=" + parseInt(myMainMap.curxOrig) + "," + (parseInt(myMainMap.curyOrig + myMainMap.curHeight) * -1);
		myImageUrl += "," + parseInt(myMainMap.curxOrig + myMainMap.curWidth) + "," + (parseInt(myMainMap.curyOrig) * -1);
		myImageUrl += "&width=" + myMainMap.pixWidth + "&height=" + myMainMap.pixHeight + "&format=image/jpeg";
		myRasterImage.setAttributeNS(xlinkNS,"xlink:href",myImageUrl);
		myRasterLayer.appendChild(myRasterImage);
	}
}

In the function loadProjectSpecific() (file index.svg) add the line

getRaster("hillshade");

to trigger the loading of the image after each zoom or pan.

Likewise, extend the function toggleMapLayer(id,checkStatus,labelText) (script secion of file index.js) to load the raster layer 'hillshade' upon turning on a layer. This is also explained in part one of the tutorial (integration of terraserver). Put the following three lines within the second if-statement of checkStatus (if (checkStatus) { }:

if (id == "hillshade") {
	getOrthoImage();
}

Next, in the <g /> element with the id "mainMapGroup" delete the image with the id "ShadedRelief" and replace it with a new empty group element as follows:

<g id="hillshade" visibility="visible" />

Finally, replace the creation of the checkbox to point to the id hillshade as opposed to the old id ShadedRelief:

Old version:

myMapApp.checkBoxes["ShadedRelief"] = new checkBox("ShadedRelief","checkBoxes",200,20,"checkBoxRect","checkBoxCross",true,"Shaded Relief",labeltextStyles,12,undefined,toggleMapLayer);

New version:

myMapApp.checkBoxes["hillshade"] = new checkBox("hillshade","checkBoxes",200,20,"checkBoxRect","checkBoxCross",true,"Shaded Relief",labeltextStyles,12,undefined,toggleMapLayer);

If everything works as expected, load the files to your webserver and try the new functionality of integrating the Yosemite shaded relief. This example demonstrates example 4.