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.

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)

## ◆ FORMATS

 enum mio::Coords::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)

## ◆ 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_coordinatesystem string identifying the coordinate system to use [in] in_parameters string 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_coordinatesystem string identifying the coordinate system to use [in] in_parameters string giving some additional parameters for the projection (empty string if not applicable) [in] coord_spec coordinate 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_ref latitude of the reference point [in] in_long_ref longitude of the reference point

## ◆ Coords() [5/5]

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

## ◆ 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_msg String 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
 source source object to copy the projection from i_update should the necessary coordinates be updated? (default=true)

## ◆ distance()

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

Calculate the distance between two points.

Parameters
 destination destination 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_type projection type [out] proj_args optional 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
 target coordinate 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
 coord1 first Coords to merge, highest priority coord2 second 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
 coord2 extra 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] in Coord 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] in Coord 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_altitude altitude above sea level, in meters [in] in_update should 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_algo enum 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
 epsg epsg 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_i grid index along the X direction [in] in_grid_j grid index along the Y direction [in] in_grid_k grid index along the Z direction [in] setValid should 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_latitude latitude to set [in] in_longitude longitude to set [in] in_altitude altitude to set [in] in_update should 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_coordinates string containing the lat/lon to read [in] in_altitude altitude to set (optional) [in] in_update should 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_latitude latitude of the local origin [in] in_ref_longitude longitude 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_coordparam string 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_coordinatesystem string identifying the coordinate system to use [in] in_parameters string 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_easting easting to set [in] in_northing northing to set [in] in_altitude altitude to set [in] in_update should 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.

## ◆ 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: