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

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

.. index::
   single: Geographical reference systems

.. index::
   single: Map projections

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, you
could take some Geomatics courses (Geographical Information Systems,
Cartography, Geodesy, ...).

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

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.

.. _`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/