| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# PROJECTION

## Background

There are thousands of geographical reference systems. In order to combine datasets with different geographical reference systems into a map, the datasets will have to be transformed (projected) to the chosen geographical reference system of the map. If you want to know more about geographical reference systems and map projections in general, please see the More Information links below, or look into Geomatics courses (Geographical Information Systems, Cartography, Geodesy), as projections are an advanced topic for beginners.

## Projections with MapServer

To set up projections you must define one projection object for the output image (in the MAP object) and one projection object for each layer (in the LAYER objects) to be projected. MapServer relies on the PROJ.4 library for projections. Projection objects therefore consist of a series of PROJ.4 keywords, which are either specified within the object directly or referred to in an EPSG file. An EPSG file is a lookup file containing projection parameters, and is part of the PROJ.4 library.

The following two examples both define the same projection (UTM zone 15, NAD83), but use 2 different methods:

Example 1: Inline Projection Parameters

    PROJECTION
      "proj=utm"
      "ellps=GRS80"
      "datum=NAD83"
      "zone=15"
      "units=m"
      "north"
      "no_defs"
    END

Note

For a list of all of the possible PROJ.4 projection parameters, see the PROJ.4 parameters page.

Example 2: EPSG Projection Use

    PROJECTION
       "init=epsg:26915"
    END

Note

This refers to an EPSG lookup file that contains a ‘26915’ code with the full projection parameters. “epsg” in this instance is case-sensitive because it is referring to a file name. If your file system is case-sensitive, this must be lower case, or MapServer (PROJ.4 actually) will complain about not being able to find this file.

Note

See http://spatialreference.org/ref/epsg/26915/ for more information on this coordinate system.

The next two examples both display how to possibly define unprojected lat/long (“geographic”):

Example 3: Inline Projection Parameters

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

Example 4: epsg Projection Use

    PROJECTION
       "init=epsg:4326"
    END

## “Web Mercator” or “Google Mercator”

The EPSG code for the commonly used “Web” or “Google” mercator projection is ‘3857’. See http://spatialreference.org/ref/sr-org/7483/ for more information on this coordinate system. This code was also unofficially referred to as EPSG:900913; you are recommended to use the official EPSG:3857 code instead, such as:

    PROJECTION
       "init=epsg:3857"
    END

## PROJECTION AUTO

The following syntax may be used in LAYERs that are OGR connections, shapefile layers or raster layers :

    PROJECTION
       AUTO
    END

- In case of a OGR connection, the projection will be retrieved from the OGR layer.

- In case of a shapefile layer, the projection will be retrieved from the associated .prj file.

- In case of raster layers refereing to single raster (DATA keyword), the projection will be retrieved from the GDAL datasource. If the raster layer refers to a tile index (OGR layer or shapefile tileindex), the projection will be retrieved according to the above describe rules.

Note

For other layer types, this syntax is invalid.

## Specifying which EPSG files to use

MAP CONFIG can be used to specify the location of EPSG files:

    MAP
      CONFIG "PROJ_LIB" "/usr/share/proj/"
      PROJECTION
        "init=epsg:3857"
      END # PROJECTION
      ...

It is important that CONFIG “PROJ_LIB” line comes before the PROJECTION block.

## Important Notes

- If all of your data in the mapfile is in the same projection, you DO NOT have to specify any projection objects. MapServer will assume that all of the data is in the same projection.

- Think of the MAP-level projection object as your output projection. The EXTENT and UNITS values at the MAP-level must be in the output projection units. Also, if you have layers in other projections (other than the MAP-level projection) then you must define PROJECTION objects for those layers, to tell MapServer what projections they are in.

- If you specify a MAP-level projection, and then only one other LAYER projection object, MapServer will assume that all of the other layers are in the specified MAP-level projection.

- Always refer to the EPSG file in lowercase, because it is a lowercase filename and on Linux/Unix systems this parameter is case sensitive.

## For More Information

- If you get projection errors, refer to the Errors to check if your exact error has been discussed.

- Search the MapServer-users email list archives, odds are that someone has faced your exact issue before.

- See the PROJ.4 user guides for complete descriptions of supported projections and coordinate systems.

- Refer to the Cartographical Map Projections page for background information on projections.

- A respected author on map projections is John P. Snyder, if you are wishing for printed material to review.