.. _crs:

Projections Support 
===================

Coordinate reference systems
----------------------------

Coordinate reference systems (CRS) are encapsulated by :class:`QgsCoordinateReferenceSystem` class.
Instances of this class can be created by several different ways:

* specify CRS by its ID::

    # PostGIS SRID 4326 is allocated for WGS84
    crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.PostgisCrsId)

  QGIS uses three different IDs for every reference system:

  * :const:`PostgisCrsId` - IDs used within PostGIS databases.
  * :const:`InternalCrsId` - IDs internally used in QGIS database.
  * :const:`EpsgCrsId` - IDs assigned by the EPSG organization

  If not specified otherwise in second parameter, PostGIS SRID is used by default.

* specify CRS by its well-known text (WKT)::

    wkt = 'GEOGCS["WGS84", DATUM["WGS84", SPHEROID["WGS84", 6378137.0, 298.257223563]],\
           PRIMEM["Greenwich", 0.0], UNIT["degree",0.017453292519943295],\
           AXIS["Longitude",EAST], AXIS["Latitude",NORTH]]'
    crs = QgsCoordinateReferenceSystem(wkt)

* create invalid CRS and then use one of the :func:`create*` functions to initialize it. In following example we use Proj4 string to initialize the projection::

    crs = QgsCoordinateReferenceSystem()
    crs.createFromProj4("+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs")

It's wise to check whether creation (i.e. lookup in the database) of the CRS has been successful: :func:`isValid` must return :const:`True`.

Note that for initialization of spatial reference systems QGIS needs to lookup appropriate values in its internal database :file:`srs.db`.
Thus in case you create an independent application you need to set paths correctly with :func:`QgsApplication.setPrefixPath` otherwise it will fail to find the database.
If you are running the commands from QGIS python console or developing a plugin you do not care: everything is already set up for you.

Accessing spatial reference system information::

  print "QGIS CRS ID:", crs.srsid()
  print "PostGIS SRID:", crs.srid()
  print "EPSG ID:", crs.epsg()
  print "Description:", crs.description()
  print "Projection Acronym:", crs.projectionAcronym()
  print "Ellipsoid Acronym:", crs.ellipsoidAcronym()
  print "Proj4 String:", crs.proj4String()
  # check whether it's geographic or projected coordinate system
  print "Is geographic:", crs.geographicFlag()
  # check type of map units in this CRS (values defined in QGis::units enum)
  print "Map units:", crs.mapUnits()


Projections
-----------

You can do transformation between different spatial reference systems by using :class:`QgsCoordinateTransform` class.
The easiest way to use it is to create source and destination CRS and construct :class:`QgsCoordinateTransform` instance with them.
Then just repeatedly call :func:`transform` function to do the transformation. By default it does forward transformation,
but it is capable to do also inverse transformation::

  crsSrc = QgsCoordinateReferenceSystem(4326)    # WGS 84
  crsDest = QgsCoordinateReferenceSystem(32633)  # WGS 84 / UTM zone 33N
  xform = QgsCoordinateTransform(crsSrc, crsDest)

  # forward transformation: src -> dest
  pt1 = xform.transform(QgsPoint(18,5))
  print "Transformed point:", pt1

  # inverse transformation: dest -> src
  pt2 = xform.transform(pt1, QgsCoordinateTransform.ReverseTransform)
  print "Transformed back:", pt2