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 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. More...

	Coords (const Coords &c)

Coords &	operator= (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	setPoint (const double in_x_or_lat, const double in_y_or_lon, const double in_altitude)
	Set coordinates based on the previously defined EPSG code If the EPSG code is 4326 (which represents WGS84 latitude-longitude), it sets latitude and longitude. More...

void	setPoint (const double in_x_or_lat, const double in_y_or_lon, const double in_altitude, const int epsg)
	Set coordinates based on a given EPSG code If the EPSG code is 4326 (which represents WGS84 latitude-longitude), it sets latitude and longitude. 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...

Static Public Attributes
static const std::set< int >	latlon_epsgs = {4326}

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

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

Member Enumeration Documentation

◆ 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

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

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_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

[in]	coord1	first Coords to merge, highest priority
[in]	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

[in] 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

◆ setPoint() [1/2]

void mio::Coords::setPoint	(	const double	in_x_or_lat,
		const double	in_y_or_lon,
		const double	in_altitude
	)

Set coordinates based on the previously defined EPSG code If the EPSG code is 4326 (which represents WGS84 latitude-longitude), it sets latitude and longitude.

Parameters

[in]	in_x_or_lat	latitude or easting to set based on the EPSG code
[in]	in_y_or_lon	longitude or northing to set based on the EPSG code
[in]	in_altitude	altitude to set

◆ setPoint() [2/2]

void mio::Coords::setPoint	(	const double	in_x_or_lat,
		const double	in_y_or_lon,
		const double	in_altitude,
		const int	epsg
	)

Set coordinates based on a given EPSG code If the EPSG code is 4326 (which represents WGS84 latitude-longitude), it sets latitude and longitude.

Parameters

[in]	in_x_or_lat	latitude or easting to set based on the EPSG code
[in]	in_y_or_lon	longitude or northing to set based on the EPSG code
[in]	in_altitude	altitude to set
[in]	epsg	epsg code of the coordinates

◆ 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.

Parameters

[in] type how to format the output (see FORMATS)

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

Member Data Documentation

◆ latlon_epsgs

const std::set< int > mio::Coords::latlon_epsgs = {4326}

static

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

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Member Enumeration Documentation

◆ FORMATS

◆ geo_distances

Constructor & Destructor Documentation

◆ Coords() [1/5]

◆ Coords() [2/5]

◆ Coords() [3/5]

◆ Coords() [4/5]

◆ Coords() [5/5]

Member Function Documentation

◆ check()

◆ copyProj()

◆ distance()

◆ getAltitude()

◆ getEasting()

◆ getEPSG()

◆ getGridI()

◆ getGridJ()

◆ getGridK()

◆ getLat()

◆ getLon()

◆ getNorthing()

◆ getProj()

◆ indexIsValid()

◆ isNodata()

◆ isSameProj()

◆ merge() [1/2]

◆ merge() [2/2]

◆ moveByBearing()

◆ moveByXY()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ setAltitude()

◆ setDistances()

◆ setEPSG()

◆ setGridIndex()

◆ setLatLon() [1/2]

◆ setLatLon() [2/2]

◆ setLocalRef() [1/2]

◆ setLocalRef() [2/2]

◆ setPoint() [1/2]

◆ setPoint() [2/2]

◆ setProj()

◆ setXY()

◆ toString()

Friends And Related Function Documentation

◆ operator<<

◆ operator>>

Member Data Documentation

◆ latlon_epsgs