Table of Contents
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 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”)
- an unique ID given by a responsible authority SRS Id and Authority responsible (e.g. EPSG 32726)
- a textual description as proposed by the 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
.
{ 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; }
Coordinate Transformation
TerraLib uses the 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.
{ // ... 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"; // ... }
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; // ... }