====== The Spatial Reference System (SRS) Module ======

This module is based on the specifications: //ISO 19111 – Geographic information – Spatial Referencing by Coordinates// and //OGC - Implementation Specification: Coordinate Transformation Services// and at providing the mechanisms to represent a coordinate that describes a position on or near the Earth's surface and are referenced to a model of the Earth. Coordinates are referenced to a Coordinate Reference System (CRS). A Coordinate Reference System is a Coordinate System (CS) – an abstract mathematical concept without any relationship to a physical object – that is referenced through a Datum to the Earth or some other object such as a vessel.

The SRS module offers this concepts, as classes of the namespace ''te::srs'': including:''SpatialReferenceSystem'', ''GeographicCoordinateSystem'',''ProjectedCoordinateSystem'', ''GeographicCoordinateSystem'', ''Ellipsoid'' and ''Datum''. Check the [[http://www.dpi.inpe.br/terralib5/codedocs_5.0.0/df/dbb/group__srs.html|DOxygen documentation of this module]], where these and other classes are documented in details.

===== SRS Representation =====

In practice, users can describe an SRS in different ways, such as:
  * an arbitrary textual description (e.g. "UTM Zone 26S Datum WGS84")
  * a [[http://www.opengeospatial.org/standards/wkt-crs|Well-known text representation of coordinate reference systems]], from OGC
  * an unique ID given by a responsible authority SRS Id and Authority responsible (e.g. [[https://www.epsg-registry.org/|EPSG]] 32726)
  * a textual description as proposed by the [[https://github.com/OSGeo/proj.4/wiki|PROJ.4 - Cartographic Projections Library]] (e.g. ''+proj=utm +zone=26 +south +ellps=WGS84 +datum=WGS84 +units=m +no_defs ''). 

The class ''SpatialReferenceSystemMananger'' is responsible for handling the Spatial Reference in TerraLib applications. The manager is a singleton, i.e., there is only one instance of this class per application. By default the SRS Manager is initialized in TerraLib from the ''srs.json'' file, that can be founded in  the subdirectory ''share/terralib/json'' of your local codebase folder.

The snippet code bellow exemplifies how to manipulate the Manager. Note that the names from this module are in the namespace ''te::srs''.

<code cpp>
{
  int nsrs = te::srs::SpatialReferenceSystemManager::getInstance().size();
  std::cout << "There are " << nsrs << " available in the SRS Manager.\n";

  std::cout << "Searching for an SRS named \"WGS 84\": \n";
  std::pair<std::string,int> myid = te::srs::SpatialReferenceSystemManager::getInstance().getIdFromName("WGS 84");
  std::cout << "WGS 84 => " << myid.second << " from " << myid.first << " authority." << std::endl;

  std::cout << "Searching for an SRS with the ID \"EPSG:4326\": \n";
  std::string myname = te::srs::SpatialReferenceSystemManager::getInstance().getName(4326);
  std::cout << "EPSG:4326 => " << myname << std::endl;
}
</code>
===== Coordinate Transformation =====
TerraLib uses the [[https://github.com/OSGeo/proj.4/wiki|PROJ.4]] library to implement coordinate transformations. The access and call to PROJ.4 is encapsulated in the class ''Converter'', that will be responsible by transforming coordinates from a source SRS Id to a target SRS ID, both represented by an unique integer identifier or SRID. The SRID should exist in the SRSManager described above.

The code snippet below shows how an application can request a ''Converter'' to convert some coordinates.

<code cpp>
{
  // ...
  te::srs::Converter converter;

  converter.setSourceSRID(4326);      // the SRS id for geographic coordinates over a WGS84 datum
  converter.setTargetSRID(32723);     // the SRS id for projected coordinates of UTM / WGS84 datum, Zone 23 South

  // Converting a single coordinate
  double llX = -45.0;
  double llY = 0.0;

  double xyX;
  double xyY;

  converter.convert(llX,llY,xyX,xyY);

  std::cout.precision(10);
  std::cout << "EPSG:4326 (" << llX << "," << llY << ") => ";
  std::cout << "EPSG:32723 (" << xyX << "," << xyY << ")\n";

  llX = -44.0;
  llY = 0.0;
  converter.convert(llX,llY,xyX,xyY);

  std::cout.precision(10);
  std::cout << "EPSG:4326 (" << llX << "," << llY << ") => ";
  std::cout << "EPSG:32723 (" << xyX << "," << xyY << ")\n";
// ...
}
</code>

Coordinate conversion is implicitly done by the geometry module when implementing the ''transform'' method, as illustrated in the code snippet below.
<code cpp>
{
  // ...
  // Converting a geometry
  te::gm::Geometry* geom = new te::gm::Point(-45.0,-23.0,4326);
  geom->asText(std::cout);

  std::cout << std::endl;

  geom->transform(31985);
  geom->asText(std::cout);

  delete geom;
  // ...
}
</code>

===== Module Dependencies =====