A.2. Using Map Projections with MapServer

The projection settings in a MapServer map file are at two levels: the output map projection and the projection of the input layers of features to be drawn. Example A-1 shows a sample of the projection settings for an output map.

Example A-1. Example settings for the map to be rendered using an Albers Equal Area projection

 PROJECTION   "proj=aea"   "ellps=WGS84"   "lat_0=10"   "lon_0=-90" END 

The settings may look confusing to anyone unfamiliar with projections, but they have a straightforward purpose. If you can get these four settings clear in your mind, you'll be able to handle most projections with ease.

PROJ.4: Projection Library and Utilities

The terms used in Example A-1, proj, ellps, lat_0, lon_0, are all keywords for the projection library used behind MapServer, called PROJ.4. There are other options (e.g., datum, units, etc.), but these are the most common. PROJ.4 isn't just a set of libraries that MapServer uses. It also comes with some command-line utilities. One of these is a program called proj, which lists the available projections, ellipsoids, etc.

Running the command:

     > proj -l 

returns a list of the available map projections, including the abbreviation used in the proj= setting for MapServer.

This utility can also project coordinates interactively by keyboard or from a text file; it's perfect for bulk projection of coordinates.

For more information on PROJ.4 see http://proj.maptools.org/.

The first line in Example A-1, "proj=aea", is the most important. It specifies the name of the projection. The abbreviation aea is short for Albers Equal Area projection. Every PROJECTION...END object must have a projection name specified. You should also specify an ellipsoid, e.g., ellps=WGS84. Some functions will not require an ellps parameter to be used, but some will fail without it. If in doubt, use the World Geodetic System WGS84. All the other parameters can be optional. There are 121 projections available through PROJ.4.

The second line, "ellps=WGS84", specifies the ellipsoid to use for the projection. WGS 84 is a specific representation of the shape of the earth. Depending on the area being mapped, there may be more or less precise ellipsoids to use. There are 42 in total. Choosing one to use isn't necessarily straightforward, unless you can find one that was generated specifically for your country or region of interest. If you can find such, you will get more accurate projection results. WGS 84 is a generally useful ellipsoid for global applications.

The third line, "lat_0=10", specifies the latitude of origin as 10° north. The default latitude of origin is 0° if not specified. The projected north/south coordinates will all start at 0 at this latitude.

The final line, "lon_0=-90", sets the central meridian as 90° west or -90°. The default is 0° if not specified. The projected east/west values all start at 0 at this longitude.

To learn more about the WGS84 ellipsoid, see http://www.wgs84.com/wgs84/wgs84.htm.

A.2.1. EPSG Codes

Depending on the map projection to be used, there may be more or fewer settings required. It isn't always necessary to specify all the settings. There are some shortcuts available. One common method is to use a master spatial reference systems list that comes with PROJ.4. This text file, usually named epsg, contains predefined projections, latitude of origins, ellipsoids, etc. You can then refer to a more complex set of options using a single number. These codes are called EPSG codes. They were developed and maintained by the European Petroleum Survey Group (EPSG). See http://www.epsg.org/ for more information about the group.

Here are two examples from the EPSG definitions:

     # NAD83 / UTM zone 10N     <26910> +proj=utm +zone=10 +ellps=GRS80 +datum=NAD83             +units=m +no_defs no_defs     <>           ## WGS84 / LCC Canada     <42101> +proj=lcc +ellps=WGS84 +lat_0=0 +lon_0=-95             +lat_1=49 +lat_2=77 +x_0=0 +y_0=-8000000.0             +datum=WGS84 +units=m no_defs     <> 

As you can see, there are several options used in both of these. Both are single lines, but are shown on multiple lines here for clarity. Rather than have to specify each of these, as in Example A-1, you can simply provide the EPSG code number:

     PROJECTION       "init=epsg:26910"     END 

This automatically sets all the projection options to project the map into UTM zone 10N using the NAD83 datum. UTM zones and other projections are described in the next section.

Likewise, "init=epsg:42101" would set it to a Lambert Conformal Conic (LCC) projection, with specific options suitable for mapping Canada. This definition is considered custom, or nonstandard. It was developed independently of the EPSG organization and won't necessarily appear in the default EPSG file. Many of the custom definitions come with PROJ.4 in a separate file. If you can't find the one you need, it is worth asking for it on the MapServer mailing list or IRC channel. Simply append the additional lines of text definition to the EPSG file, and they are instantly available for use.

A.2.1.1 EPSG versus epsg

When EPSG codes are used in a MapServer PROJECTION object, the text epsg should be in lowercase. When used in other contexts (such as Open Geospatial Consortium Web Map Server requests using MapServer), the text must be uppercase. For example if you have a wms_srs attribute in a METADATA object for a layer, it would be:

"wms_srs" "EPSG:26910"

This is a common problem when using EPSG codes with MapServer.

You can specify epsg in uppercase in the PROJECTION object, but on some operating systems, you have to rename the EPSG file to uppercase.