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 aims to provide 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 entities used to represent the different types of Spatial Reference System (SRS) can be seen in the class diagram shown below.

SRS should be represented by a simple human-readable name, PROJ4 description, WKT description, SRS Id and Authority responsible, that are used to describe the different components of a SRS. The Well-known Text Representation of Spatial Reference Systems, from OGC, is considered the standard textual representation for Spatial Reference System. However other textual representations exist, for example the descriptions used by the PROJ.4 - Cartographic Projections Library. Although it is not a OGC standard, PROJ.4 descriptions are used to represent SRS whenever PROJ.4 is used to perform transformations between two different SRS.

A Mananger is responsible for building SRS from textual representations identified by its types. The figure below shows the classes involved in this operation.

The code snippets below exemplifies how to add a SRS UTM zone 17, south hemisphere, based on the WGS84 datum, and get informantion from the SRS Id:

{
SpatialReferenceSystemManager::getInstance().add("WGS 84 / UTM zone 17S",
                                           "PROJCS[\"WGS 84 / UTM zone 17S\",GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563]],PRIMEM[\"Greenwich\",0],UNIT[\"degree\",0.01745329251994328]],PROJECTION[\"Transverse_Mercator\"],PARAMETER[\"latitude_of_origin\",0],PARAMETER[\"central_meridian\",-81],PARAMETER[\"scale_factor\",0.9996],PARAMETER[\"false_easting\",500000],PARAMETER[\"false_northing\",10000000],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH],UNIT[\"metre\",1]]",
                                           "+proj=utm +zone=17 +south +ellps=WGS84 +datum=WGS84 +units=m +no_defs",
                                           32717);
 
  name = SpatialReferenceSystemManager::getInstance().getName(32717);
  Proj4 = SpatialReferenceSystemManager::getInstance().getP4Txt(32717);
  WKT = SpatialReferenceSystemManager::getInstance().agetWkt(32717);
 
// ...
}

The manager is by default initialized using the descriptions in JSON format, in a file called SRS “srsjson.txt”. This file is located in the TerraLib resources directory, init_files sub directory. This file can be appended with more descriptions if the user needs.

An object of the class Converter is responsible by transforming coordinates from a source SRS Id to a target SRS Id, both represented by an unique integer identifier. TerraLib SRS module provide an implementation of a Converter using the same mapping from integer identifiers to descriptions as used SpatialReferenceSystemManager. The code snippet below shows how an application can request a Converter to convert some coordinates.

{
  // ...
  // requesting a pointer to a converter
  std::auto_ptr<te::srs::Converter> converter(new te::srs::Converter());
 
  converter->setSourceSRS(4326);      // the SRS id for geographic coordinates over a WGS84 datum
  converter->setTargetSRS(31985);     // the SRS id for projected coordinates of UTM / WGS84 datum, Zone 17 South
 
  // Converting a single coordinate
  double llX = -45.5;
  double llY = -23.0;
 
  double xyX;
  double xyY;
 
  converter->convert(llX,llY,xyX,xyY);
  converter->invert(xyX,xyY,llX,llY);
 
  // Converting a list of coordinates
  double* xs = new double[3];
  double* ys = new double[3];
 
  xs[0] = -45.5;
  xs[1] = -45.6;
  xs[2] = -45.7;
 
  ys[0] = -23.0;
  ys[1] = -23.1;
  ys[2] = -23.2;
 
  converter->convert(xs,ys,3,1);
// ...
}

Coordinate conversion is implicitly done by the geometry module when implementing the transform method, as illustrated in the code snippet below.

{
  // ...
  // 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;
  // ...
}

The code snippet below shows how an application can add an SRS Id, Authority code. This automatically makes the SRSID recognizable by the Converter.

{
  // ...
  // Adding a new SRS ID with your PROJ4 and WKT description
  // 
  SpatialReferenceSystemManager::getInstance().add("SIRGAS 2000 / UTM zone 25S",
                                           "PROJCS[\"SIRGAS 2000 / UTM zone 25S\",GEOGCS[\"SIRGAS 2000\",DATUM[\"Sistema_de_Referencia_Geocentrico_para_America_del_Sur_2000\",SPHEROID[\"GRS 1980\",6378137,298.257222101],TOWGS84[0,0,0,0,0,0,0]],PRIMEM[\"Greenwich\",0],UNIT[\"degree\",0.01745329251994328]],PROJECTION[\"Transverse_Mercator\"],PARAMETER[\"latitude_of_origin\",0],PARAMETER[\"central_meridian\",-33],PARAMETER[\"scale_factor\",0.9996],PARAMETER[\"false_easting\",500000],PARAMETER[\"false_northing\",10000000],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH],UNIT[\"metre\",1]]",
                                           "+proj=utm +zone=25 +south +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs",
                                           31985);
  converter->setSourceSRID(31985);
  converter->setTargetSRID(4326);
 
  xyX = 500000 * 0.001;   // meter to kilometer
  xyY = 10000000 * 0.001; // meter to kilometer
 
	converter->convert(xyX,xyY,llX,llY);
  // ...
}