.. index::
   single: PROJECTION
    
.. _projection:

*****************************************************************************
 PROJECTION
*****************************************************************************

.. index::
   single: Geographical reference systems

.. index::
   single: Map projections
   
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 :ref:`MAP` object) and one projection object for
each layer (in the :ref:`LAYER` objects) to be projected.  MapServer
relies on the :term:`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
:term:`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**

.. code-block:: mapfile

    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 <http://trac.osgeo.org/proj/wiki/GenParms>`__ page.    
    
**Example 2: EPSG Projection Use**

.. code-block:: mapfile

    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**

.. code-block:: mapfile

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

**Example 4: epsg Projection Use**

.. code-block:: mapfile  

    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:

.. code-block:: mapfile

    PROJECTION
       "init=epsg:3857"
    END

PROJECTION AUTO
---------------

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

.. code-block:: mapfile  

    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
----------------------------------

.. index::
   triple: MAP; CONFIG; PROJ_LIB

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

.. code-block:: mapfile

  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 :ref:`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 :ref:`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.

.. _`PROJ.4`: http://trac.osgeo.org/proj/
.. _`Cartographical Map Projections`: http://www.progonos.com/furuti/MapProj/Normal/TOC/cartTOC.html
.. _`email list archives`: http://lists.osgeo.org/pipermail/mapserver-users/
