MeteoIODoc  1.2.17
mio::Coords Class Reference

Detailed Description

A class to handle geographic coordinate systems. This class offers an easy way to transparently convert between various coordinate systems. For any given object, as soon as a latitude/longitude can be computed/read, it will be used as a reference. This means that every subsequent change of projection system or read will be the conversion of this reference lat/lon position (until a new "set" is called). See Coords::setProj for the supported coordinate systems.

Author
Mathias Bavay
Date
2009-01-20

#include <Coords.h>

Public Types

enum  geo_distances { GEO_COSINE , GEO_VINCENTY }
 Keywords for selecting the algorithm for computing geodesic distances. More...
 
enum  FORMATS {
  DEBUG , FULL , LATLON , XY ,
  CARTESIAN
}
 Keywords for selecting the toString formats. More...
 

Public Member Functions

 Coords ()
 Default constructor This constructor builds a dummy object that performs no conversions but can be used for comparison purpose. This is more or less the equivalent of NULL for a pointer... More...
 
 Coords (const std::string &in_coordinatesystem, const std::string &in_parameters="")
 Regular constructor: usually, this is the constructor to use. More...
 
 Coords (const std::string &in_coordinatesystem, const std::string &in_parameters, std::string coord_spec)
 Local projection constructor: this constructor is only suitable for building a local projection. More...
 
 Coords (const double &in_lat_ref, const double &in_long_ref)
 Local projection onstructor: this constructor is only suitable for building a local projection. Such a projection defines easting and northing as the distance (in meters) to a reference point which coordinates have to be provided here. More...
 
 Coords (const Coords &c)
 
Coordsoperator= (const Coords &)
 Assignement operator. More...
 
bool operator== (const Coords &) const
 Operator that tests for equality. More...
 
bool operator!= (const Coords &) const
 Operator that tests for inequality. More...
 
bool isNodata () const
 move the point by the specified distance (in m) along easting and northing More...
 
void moveByXY (const double &x_displacement, const double &y_displacement)
 move the point by the specified bearing and distance (in m) More...
 
void moveByBearing (const double &i_bearing, const double &i_distance)
 
void merge (const Coords &coord2)
 Simple merge strategy. If some fields of the current object are empty, they will be filled by the matching field from the provided argument. More...
 
double getEasting () const
 
double getNorthing () const
 
double getLat () const
 
double getLon () const
 
double getAltitude () const
 
int getGridI () const
 
int getGridJ () const
 
int getGridK () const
 
bool indexIsValid () const
 Returns true if the (i,j,k) index are valid. More...
 
void getProj (std::string &proj_type, std::string &proj_args) const
 Returns the projection parameters. More...
 
short int getEPSG () const
 returns the epsg code of the current projection More...
 
const std::string toString (const FORMATS &type=DEBUG) const
 Print the content of the Coords object (useful for debugging) The Coords is bound by "<Coords>" and "</Coords>" on separate lines. More...
 
void setLatLon (const double in_latitude, const double in_longitude, const double in_altitude, const bool in_update=true)
 Set latitude and longitude The automatic update of the easting/northing can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check(). More...
 
void setLatLon (const std::string &in_coordinates, const double in_altitude, const bool in_update=true)
 Set latitude and longitude The automatic update of the easting/northing can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check(). More...
 
void setXY (const double in_easting, const double in_northing, const double in_altitude, const bool in_update=true)
 Set easting and northing The automatic update of the latitude/longitude can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check(). More...
 
void setGridIndex (const int in_grid_i, const int in_grid_j, const int in_grid_k, const bool setValid=false)
 Set grid indices This index represent the position in a cartesian grid. It can not be automatically matched with a set of geographic coordinates because it needs the information about the said grid. Therefore, the coordinate object needs to be given to a grid object that will either set (i,j) or (lat,lon)/(easting,northing) as well as the grid's matching altitude if it is not already set. Any subsequent change of either (lat,lon) or (easting,northing) will reset these indexes to IOUtils::inodata. By default, setting (i,j) will mark the coordinates as invalid (meaning that there is no match between the (i,j,k) coordinates and the lat/lon or x/y coordinates). Finally, the given indices are NOT checked for validity: such check must be done by calling Grid2DObject::gridify or Grid3DObject::gridify . More...
 
void setAltitude (const double in_altitude, const bool in_update=true)
 Set altitude at a given value. If the i,j,k indices were set, reset them to inodata, except if specified otherwise with in_update=false. More...
 
void setProj (const std::string &in_coordinatesystem, const std::string &in_parameters="")
 Set projection to use This projection will be used for converting between lat/lon and East/North (see the supported projections) More...
 
void setLocalRef (const double in_ref_latitude, const double in_ref_longitude)
 Set the local projection reference coordinates This projection will be used for converting between lat/lon and East/North. More...
 
void setLocalRef (const std::string in_coordparam)
 Set the local projection reference coordinates This projection will be used for converting between lat/lon and East/North. More...
 
void setDistances (const geo_distances in_algo)
 Set the algorithm to use to compute distances Various algorithm exist that offer various precision/complexity tradeoffs. More...
 
void setEPSG (const int &epsg)
 set the current projection to a given EPSG-defined projection More...
 
void check (const std::string &pre_msg="")
 Check consistency of coordinates When both latitude/longitude and easting/northing are given, there is a risk of inconsistency between these two sets of coordinates. This method checks that enough information is available (ie: at least one set of coordinates is present) and if more than one is present, that it is consistent (within 5 meters) It throws an exception if something is not right. More...
 
double distance (const Coords &destination) const
 Calculate the distance between two points. More...
 
bool isSameProj (const Coords &target) const
 Check if two Coords object are using the same projection. More...
 
void copyProj (const Coords &source, const bool i_update=true)
 Copy the projection parameters of another Coords object. More...
 

Static Public Member Functions

static Coords merge (const Coords &coord1, const Coords &coord2)
 Simple merge strategy. If some fields of the first argument are empty, they will be filled by the matching field from the second argument. More...
 

Friends

std::ostream & operator<< (std::ostream &os, const Coords &coord)
 
std::istream & operator>> (std::istream &is, Coords &coord)
 

Member Enumeration Documentation

◆ FORMATS

Keywords for selecting the toString formats.

Enumerator
DEBUG 

As much information as possible, useful for debugging.

FULL 

Provide all the usually necessary information.

LATLON 

Simplified, lat/lon only.

XY 

Simplified cartesian, only easting/northing.

CARTESIAN 

Compact representation only containing the X/Y and I/J coordinates.

◆ geo_distances

Keywords for selecting the algorithm for computing geodesic distances.

Enumerator
GEO_COSINE 

Spherical law of cosine (See http://www.movable-type.co.uk/scripts/latlong.html)

GEO_VINCENTY 

Vincenty ellispoid formula (See T. Vincenty, "Closed formulas for the direct and reverse geodetic problems", Journal of Geodesy, 51, 3, 1977, DOI:10.1007/BF02521599, or http://www.springerlink.com/content/y7108u6862473583 for more)

Constructor & Destructor Documentation

◆ Coords() [1/5]

mio::Coords::Coords ( )

Default constructor This constructor builds a dummy object that performs no conversions but can be used for comparison purpose. This is more or less the equivalent of NULL for a pointer...

◆ Coords() [2/5]

mio::Coords::Coords ( const std::string &  in_coordinatesystem,
const std::string &  in_parameters = "" 
)

Regular constructor: usually, this is the constructor to use.

Parameters
[in]in_coordinatesystemstring identifying the coordinate system to use
[in]in_parametersstring giving some additional parameters for the projection (optional)

See setProj() for a full description of these strings

◆ Coords() [3/5]

mio::Coords::Coords ( const std::string &  in_coordinatesystem,
const std::string &  in_parameters,
std::string  coord_spec 
)

Local projection constructor: this constructor is only suitable for building a local projection.

Such a projection defines easting and northing as the distance (in meters) to a reference point which coordinates have to be provided here.

Parameters
[in]in_coordinatesystemstring identifying the coordinate system to use
[in]in_parametersstring giving some additional parameters for the projection (empty string if not applicable)
[in]coord_speccoordinate specification

The coordinate specification is prefixed by either "latlon" or "xy" (for cartesian coordinates) given as either:

  • latitude longitude altitude
  • latitude/longitude/altitude
  • (latitude; longitude; altitude)
  • (latitude, longitude, altitude)

Of course, for cartesian coordinates systems, the easting/northing/altitudes are provided instead of latitude/longitude/altitude. Latitudes and longitudes can be in any format supported by CoordsAlgorithms::dms_to_decimal.

For example, those are valid coordinates specification strings:

latlon (46.75; 9.80; 2200)
latlon (46d 43' 51", 9.80, 2200)
xy (198754, 723458, 2200)

◆ Coords() [4/5]

mio::Coords::Coords ( const double &  in_lat_ref,
const double &  in_long_ref 
)

Local projection onstructor: this constructor is only suitable for building a local projection. Such a projection defines easting and northing as the distance (in meters) to a reference point which coordinates have to be provided here.

Parameters
[in]in_lat_reflatitude of the reference point
[in]in_long_reflongitude of the reference point

◆ Coords() [5/5]

mio::Coords::Coords ( const Coords c)

Member Function Documentation

◆ check()

void mio::Coords::check ( const std::string &  pre_msg = "")

Check consistency of coordinates When both latitude/longitude and easting/northing are given, there is a risk of inconsistency between these two sets of coordinates. This method checks that enough information is available (ie: at least one set of coordinates is present) and if more than one is present, that it is consistent (within 5 meters) It throws an exception if something is not right.

Parameters
[in]pre_msgString to prepend to errors messages (for example, giving the file name that contains the error)

◆ copyProj()

void mio::Coords::copyProj ( const Coords source,
const bool  i_update = true 
)

Copy the projection parameters of another Coords object.

Parameters
sourcesource object to copy the projection from
i_updateshould the necessary coordinates be updated? (default=true)

◆ distance()

double mio::Coords::distance ( const Coords destination) const

Calculate the distance between two points.

Parameters
destinationdestination coordinate
Returns
distance in meters

◆ getAltitude()

double mio::Coords::getAltitude ( ) const
inline

◆ getEasting()

double mio::Coords::getEasting ( ) const
inline

◆ getEPSG()

short int mio::Coords::getEPSG ( ) const

returns the epsg code of the current projection

Returns
epsg code

◆ getGridI()

int mio::Coords::getGridI ( ) const
inline

◆ getGridJ()

int mio::Coords::getGridJ ( ) const
inline

◆ getGridK()

int mio::Coords::getGridK ( ) const
inline

◆ getLat()

double mio::Coords::getLat ( ) const
inline

◆ getLon()

double mio::Coords::getLon ( ) const
inline

◆ getNorthing()

double mio::Coords::getNorthing ( ) const
inline

◆ getProj()

void mio::Coords::getProj ( std::string &  proj_type,
std::string &  proj_args 
) const

Returns the projection parameters.

Parameters
[out]proj_typeprojection type
[out]proj_argsoptional arguments

◆ indexIsValid()

bool mio::Coords::indexIsValid ( ) const
inline

Returns true if the (i,j,k) index are valid.

◆ isNodata()

bool mio::Coords::isNodata ( ) const

move the point by the specified distance (in m) along easting and northing

◆ isSameProj()

bool mio::Coords::isSameProj ( const Coords target) const

Check if two Coords object are using the same projection.

Parameters
targetcoordinate to compare to
Returns
true or false

◆ merge() [1/2]

Coords mio::Coords::merge ( const Coords coord1,
const Coords coord2 
)
static

Simple merge strategy. If some fields of the first argument are empty, they will be filled by the matching field from the second argument.

Parameters
coord1first Coords to merge, highest priority
coord2second Coords to merge, lowest priority
Returns
new Coords object

◆ merge() [2/2]

void mio::Coords::merge ( const Coords coord2)

Simple merge strategy. If some fields of the current object are empty, they will be filled by the matching field from the provided argument.

Parameters
coord2extra Coords to merge, lowest priority

◆ moveByBearing()

void mio::Coords::moveByBearing ( const double &  i_bearing,
const double &  i_distance 
)

◆ moveByXY()

void mio::Coords::moveByXY ( const double &  x_displacement,
const double &  y_displacement 
)

move the point by the specified bearing and distance (in m)

◆ operator!=()

bool mio::Coords::operator!= ( const Coords in) const

Operator that tests for inequality.

Inequality operator that checks that lat/lon don't match.

Parameters
[in]inCoord object to compare to
Returns
true or false

◆ operator=()

Coords & mio::Coords::operator= ( const Coords source)

Assignement operator.

◆ operator==()

bool mio::Coords::operator== ( const Coords in) const

Operator that tests for equality.

Equality operator that checks that two coordinates objects represent the same 3D point. The comparison checks either lat/lon/alt or easting/northing/alt. If both objects have nodata coordinates, then they are equal (even if the internal projections might be set to different systems).

Parameters
[in]inCoord object to compare to
Returns
true or false

◆ setAltitude()

void mio::Coords::setAltitude ( const double  in_altitude,
const bool  in_update = true 
)

Set altitude at a given value. If the i,j,k indices were set, reset them to inodata, except if specified otherwise with in_update=false.

Parameters
[in]in_altitudealtitude above sea level, in meters
[in]in_updateshould the indices be (if necessary) recalculated? (default=true)

◆ setDistances()

void mio::Coords::setDistances ( const geo_distances  in_algo)

Set the algorithm to use to compute distances Various algorithm exist that offer various precision/complexity tradeoffs.

Parameters
[in]in_algoenum giving the algorithm to be used (see documentation for geo_distances)

◆ setEPSG()

void mio::Coords::setEPSG ( const int &  epsg)

set the current projection to a given EPSG-defined projection

Parameters
epsgepsg code

◆ setGridIndex()

void mio::Coords::setGridIndex ( const int  in_grid_i,
const int  in_grid_j,
const int  in_grid_k,
const bool  setValid = false 
)

Set grid indices This index represent the position in a cartesian grid. It can not be automatically matched with a set of geographic coordinates because it needs the information about the said grid. Therefore, the coordinate object needs to be given to a grid object that will either set (i,j) or (lat,lon)/(easting,northing) as well as the grid's matching altitude if it is not already set. Any subsequent change of either (lat,lon) or (easting,northing) will reset these indexes to IOUtils::inodata. By default, setting (i,j) will mark the coordinates as invalid (meaning that there is no match between the (i,j,k) coordinates and the lat/lon or x/y coordinates). Finally, the given indices are NOT checked for validity: such check must be done by calling Grid2DObject::gridify or Grid3DObject::gridify .

Note
To make it short: use this method with caution!!
Parameters
[in]in_grid_igrid index along the X direction
[in]in_grid_jgrid index along the Y direction
[in]in_grid_kgrid index along the Z direction
[in]setValidshould the geographic coordinates be marked as valid? (default=false, this flag should be true ONLY when calling from Grid2/3DObject)

◆ setLatLon() [1/2]

void mio::Coords::setLatLon ( const double  in_latitude,
const double  in_longitude,
const double  in_altitude,
const bool  in_update = true 
)

Set latitude and longitude The automatic update of the easting/northing can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check().

Parameters
[in]in_latitudelatitude to set
[in]in_longitudelongitude to set
[in]in_altitudealtitude to set
[in]in_updateshould the easting/northing be updated? (default=true)

◆ setLatLon() [2/2]

void mio::Coords::setLatLon ( const std::string &  in_coordinates,
const double  in_altitude,
const bool  in_update = true 
)

Set latitude and longitude The automatic update of the easting/northing can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check().

Parameters
[in]in_coordinatesstring containing the lat/lon to read
[in]in_altitudealtitude to set (optional)
[in]in_updateshould the easting/northing be updated? (default=true)

◆ setLocalRef() [1/2]

void mio::Coords::setLocalRef ( const double  in_ref_latitude,
const double  in_ref_longitude 
)

Set the local projection reference coordinates This projection will be used for converting between lat/lon and East/North.

Parameters
[in]in_ref_latitudelatitude of the local origin
[in]in_ref_longitudelongitude of the local origin

◆ setLocalRef() [2/2]

void mio::Coords::setLocalRef ( const std::string  in_coordparam)

Set the local projection reference coordinates This projection will be used for converting between lat/lon and East/North.

Parameters
[in]in_coordparamstring containing the (lat,lon) of the local origin

◆ setProj()

void mio::Coords::setProj ( const std::string &  in_coordinatesystem,
const std::string &  in_parameters = "" 
)

Set projection to use This projection will be used for converting between lat/lon and East/North (see the supported projections)

Parameters
[in]in_coordinatesystemstring identifying the coordinate system to use
[in]in_parametersstring giving some additional parameters for the projection (optional)

◆ setXY()

void mio::Coords::setXY ( const double  in_easting,
const double  in_northing,
const double  in_altitude,
const bool  in_update = true 
)

Set easting and northing The automatic update of the latitude/longitude can be turned off so that both lat/lon and east/north coordinates can be provided in order to thereafter check the coordinates by calling check().

Parameters
[in]in_eastingeasting to set
[in]in_northingnorthing to set
[in]in_altitudealtitude to set
[in]in_updateshould the easting/northing be updated? (default=true)

◆ toString()

const std::string mio::Coords::toString ( const FORMATS type = DEBUG) const

Print the content of the Coords object (useful for debugging) The Coords is bound by "<Coords>" and "</Coords>" on separate lines.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<< ( std::ostream &  os,
const Coords coord 
)
friend

◆ operator>>

std::istream& operator>> ( std::istream &  is,
Coords coord 
)
friend

The documentation for this class was generated from the following files: