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 library for projections. Projection objects therefore consist of a series of PROJ 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 library.

Starting with MapServer 8 and when the PROJ 6 library or above is used, the use of EPSG codes when available, rather than the inline projection parameters, is recommended to benefit from higher accuracy coordinate reprojection.

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 projection parameters, the official PROJ site is best (https://proj.org), however the old wiki has a thorough list of PROJ parameters.

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 actually) will complain about not being able to find this file.

Note

See https://epsg.io/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 https://epsg.io/3857 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 containing a 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.

  • If the raster layer refers to a tile index with rasters in a variety of projections, the TILESRS keyword should be specified to choose the appropriate projection for the corresponding raster. See Tileindexes with tiles in different projections for more details.

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.

Note

If you receive an error such as “msProjectRect(): Projection library error. All points failed to reproject” definitely verify that you have set the (MAP-level) output projection and extent properly, as well as the projection block for each of your layers (their source projection).

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 user guides for complete descriptions of supported projections and coordinate systems.

  • Read more about the history of the Web Mercator projection.

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

  • To lookup specific EPSG projection codes, the old website https://spatialreference.org/ is unmaintained, so https://epsg.io/ is recommended instead.