TerraLib and TerraView Wiki Page

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
wiki:documentation:devguide:srs_module [2016/01/11 15:40]
lubia
wiki:documentation:devguide:srs_module [2016/01/20 11:15] (current)
lubia [Coordinate Transformation]
Line 1: Line 1:
-====== The Spatial Reference System Module ======+====== 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. 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. 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: In practice, users can describe an SRS in different ways, such as:
Line 13: Line 15:
 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 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 ​shows how to retrieve ​the number of SRS currently available ​in the Manager.+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> <code cpp>
 { {
- int nsrs = SpatialReferenceSystemManager::​getInstance().size();​ +  ​int nsrs = te::srs::SpatialReferenceSystemManager::​getInstance().size();​ 
- ​std::​cout << "There are " << nsrs << " available in the SRS Manager ";+  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>​ </​code>​
- 
 ===== Coordinate Transformation ===== ===== Coordinate Transformation =====
-TerraLib uses the [[https://​github.com/​OSGeo/​proj.4/​wiki|PROJ.4]] library to implement coordinate transformations. The simplest way to do it is by creating an object of 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. The SRSID should exist in the SRSManager described above.+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. The code snippet below shows how an application can request a ''​Converter''​ to convert some coordinates.
Line 30: Line 39:
 { {
   // ...   // ...
-  ​// requesting a pointer to a converter +  te::​srs::​Converter converter;
-  std::​auto_ptr<​te::​srs::​Converterconverter(new te::​srs::​Converter());+
  
-  converter->​setSourceSRS(4326); ​     // the SRS id for geographic coordinates over a WGS84 datum +  converter.setSourceSRID(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+  converter.setTargetSRID(32723);     // the SRS id for projected coordinates of UTM / WGS84 datum, Zone 23 South
  
   // Converting a single coordinate   // Converting a single coordinate
-  double llX = -45.5+  double llX = -45.0
-  double llY = -23.0;+  double llY = 0.0;
  
   double xyX;   double xyX;
   double xyY;   double xyY;
  
-  converter->convert(llX,​llY,​xyX,​xyY); +  converter.convert(llX,​llY,​xyX,​xyY);​
-  converter->​invert(xyX,​xyY,​llX,​llY);+
  
-  ​// Converting a list of coordinates +  ​std::​cout.precision(10);​ 
-  ​double* xs new double[3]+  ​std::cout << "​EPSG:​4326 (" << llX << ","​ << llY << "​) ​=> "
-  ​double* ys = new double[3];+  ​std::cout << "​EPSG:​32723 (" << xyX << ","​ << xyY << "​)\n"​;
  
-  ​xs[0] = -45.5+  ​llX = -44.0
-  ​xs[1] -45.6+  ​llY 0.0
-  ​xs[2] = -45.7;+  ​converter.convert(llX,​llY,​xyX,​xyY);
  
-  ​ys[0] = -23.0+  ​std::cout.precision(10)
-  ​ys[1] -23.1+  ​std::cout << "​EPSG:​4326 (" << llX << ","​ << llY << "​) ​=> "
-  ​ys[2] = -23.2; +  ​std::cout << "​EPSG:​32723 ​(" << xyX << "," << xyY << ")\n";
- +
-  converter->​convert(xs,ys,3,1);+
 // ... // ...
 } }
Line 81: Line 86:
 </​code>​ </​code>​
  
-The code snippet below shows how an application can add an SRS Id, Authority code. This automatically makes the SRSID recognizable by the Converter. +===== Module Dependencies =====
- +
-<code cpp> +
-+
-  // ... +
-  // 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);​ +
-  // ... +
-+
-</​code>​ +