An IlvCoordinate object is a point defined by two values in double precision. More...

#include <ilviews/maps/coord.h>

Public Member Functions
	IlvCoordinate (IlDouble x=0.0, IlDouble y=0.0)
	This constructor initializes a new instance of `IlvCoordinate`. More...

IlBoolean	isCloseTo (const IlvCoordinate &other, IlDouble tolerance=0.0) const
	Checks if two coordinates are close. More...

IlDouble	lat () const
	Returns the latitude value. More...

void	lat (IlDouble lat)
	Sets the latitude value. More...

IlDouble	lon () const
	Returns the longitude value. More...

void	lon (IlDouble lon)
	Sets the longitude value. More...

void	move (IlDouble x, IlDouble y)
	This member function takes existing coordinates and moves them to another position. More...

IlvCoordinate &	operator= (const IlvCoordinate &c)
	Assignment operator. More...

int	operator== (const IlvCoordinate &c) const
	Equality operator. More...

IlBoolean	toDD (IlString &output) const
	Converts this object into a DD-formatted string. More...

IlBoolean	toDMS (IlString &output) const
	Converts this object into a DMS-formatted string. More...

IlBoolean	toMGRS (IlString &output, const IlvEllipsoid *ellipsoid=0) const
	Converts this object into an MGRS string representation. More...

IlBoolean	toMGRS (IlUShort &zoneNumber, char &zoneDesignator, IlString &squareId, IlUInt &easting, IlUInt &northing, const IlvEllipsoid *ellipsoid=0) const
	Converts this object into MGRS values. More...

IlBoolean	toUTM (IlString &output, const IlvEllipsoid *ellipsoid=0) const
	Converts this object into an UTM/UPS string representation. More...

IlBoolean	toUTM (IlUShort &zoneNumber, char &zoneDesignator, IlDouble &easting, IlDouble &northing, const IlvEllipsoid *ellipsoid=0) const
	Converts this object into UTM/UPS values. More...

void	translate (const IlvCoordinate &dc)
	Translates an `IlvCoordinate`. More...

void	translate (IlDouble dx, IlDouble dy)
	Translates an `IlvCoordinate`. More...

IlDouble	x () const
	Returns the `x` value. More...

void	x (IlDouble x)
	Sets the x value. More...

IlDouble	y () const
	Returns the `y` value. More...

void	y (IlDouble y)
	Sets the y value. More...

Static Public Member Functions
static IlBoolean	FromDD (const IlString &input, IlvCoordinate &output)
	Converts a DD-formatted string into an `IlvCoordinate` object. More...

static IlBoolean	FromDMS (const IlString &input, IlvCoordinate &output)
	Converts a DMS-formatted string into an `IlvCoordinate` object. More...

static IlBoolean	FromMGRS (const IlString &input, IlvCoordinate &output, const IlvEllipsoid *ellipsoid=0)
	Converts a UTM/UPS-formatted string into an `IlvCoordinate` object. More...

static IlBoolean	FromMGRS (IlUShort zoneNumber, char zoneDesignator, const IlString &squareId, IlUInt easting, IlUInt northing, IlvCoordinate &output, const int precision, const IlvEllipsoid *ellipsoid=0)
	Converts MGRS coordinates into an `IlvCoordinate` object. More...

static IlBoolean	FromUTM (const IlString &input, IlvCoordinate &output, const IlvEllipsoid *ellipsoid=0)
	Converts a UTM/UPS-formatted string into an `IlvCoordinate` object. More...

static IlBoolean	FromUTM (IlUShort zoneNumber, char zoneDesignator, IlDouble easting, IlDouble northing, IlvCoordinate &output, const IlvEllipsoid *ellipsoid=0)
	Converts UTM/UPS coordinates into an `IlvCoordinate` object. More...

Detailed Description

An IlvCoordinate object is a point defined by two values in double precision.

Library: ilvmaps

An IlvCoordinate object is a point defined by two values in double precision. The class IlvCoordinate is the basic data structure for computing projections.

The x and y values designate either the Cartesian coordinates resulting from a forward projection or the latitude (in y) and the longitude (in x) obtained by inverse computation.

Constructor & Destructor Documentation

◆ IlvCoordinate()

IlvCoordinate::IlvCoordinate	(	IlDouble	x = `0.0`,
		IlDouble	y = `0.0`
	)

This constructor initializes a new instance of IlvCoordinate.

Parameters

x	The initial `x` value.
y	The initial `y` value.

Member Function Documentation

◆ FromDD()

static IlBoolean IlvCoordinate::FromDD	(	const IlString &	input,
		IlvCoordinate &	output
	)

static

Converts a DD-formatted string into an IlvCoordinate object.

The input string must represent two floating point values: one for the latitude angle and one for the longitude. They can be separated by a comma character.

Each value can be expressed in degrees (if followed by the °, d or D character) or in radians (if followed by the r or R character). If not specified, degrees are expected.

Each value can be followed by the northing (N, n, S or s) or easting (E, e, W or w) indication. The S, s, W or w indication changes the sign of the value it applies to. By default, the first value is considered as a North-pointing angle and the second value is considered as a East-pointing angle.
The two values must not have both a northing indicator, or both an easting indicator: if one has a northing indicator, then the other must have an easting information (or nothing, then e is presumed), and vice versa.

Space characters and additional characters are discarded.

Examples of valid input:

10 20
10, 20
10N 20E
20E 10N
10N -20W
48.866667n, 2.333333e
22.970722S -0.7536743r

Examples of invalid input:

10
10x 20E
48.866667n 2.333333n

Parameters

input	The string to be parsed.
output	Set to the parsed coordinates on success.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: toDD(IlString&).

◆ FromDMS()

static IlBoolean IlvCoordinate::FromDMS	(	const IlString &	input,
		IlvCoordinate &	output
	)

static

Converts a DMS-formatted string into an IlvCoordinate object.

The input string must represent two angle values: one for the latitude angle and one for the longitude. They can be separated by a comma character.

Each value represents a value expressed in degrees, minutes and seconds, made of a value for the degrees part (followed by the °, d or D character) followed by the minutes part (followed by the ', m or M character), followed by the seconds part (followed by the ", s or S character). Any of these part may be omitted.

Each value can be followed by the northing (N, n, S or s) or easting (E, e, W or w) indication. The S, s, W or w indication changes the sign of the value it applies to. By default, the first value is considered as a North-pointing angle and the second value is considered as a East-pointing angle.
The two values must not have both a northing indicator, or both an easting indicator: if one has a northing indicator, then the other must have an easting information (or nothing, then e is presumed), and vice versa.

Space characters and additional characters are discarded.

Examples of valid input:

10D 20D

12D34'56.78sN 12'W

Parameters

input	The string to be parsed.
output	Set to the parsed coordinates on success.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: toDMS(IlString&).

◆ FromMGRS() [1/2]

static IlBoolean IlvCoordinate::FromMGRS	(	const IlString &	input,
		IlvCoordinate &	output,
		const IlvEllipsoid *	ellipsoid = `0`
	)

static

Converts a UTM/UPS-formatted string into an IlvCoordinate object.

The input string must represent a valid UTM (Universal Transverse Mercator) / UPS (Universal Polar Stereographic) value:

[<zoneNb>]<zoneDesignator> <MGRSsquareId> <easting>[mE] <northing>[mN]

<zoneNb> is the UTM zone number: an integer value between 1 and
1. If omitted, this indicates a polar area, handled by the UPS projection (that is, a latitude below -80° or above 84°).
<zoneDesignator> is the UTM zone designator: a letter that indicates the latitude band (or an UPS quadrant, when the latitude is beyond the UTM valid values).
<MGRSsquareId> is the MGRS square identifier.
<easting> is the easting planar coordinate value in the indicated zone, in meters.
<northing> is the northing planar coordinate value in the indicated zone, in meters.

Space characters and additional characters are discarded.

Examples of valid input:

31 U DQ 48265 11920
23KPQ8739465628
ZAE5747585497

Parameters

input	The MGRS coordinates string to be parsed.
output	Set to the parsed coordinates on success.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: FromMGRS(IlUShort, char, const IlString&, IlUInt, IlUInt, IlvCoordinate&, const IlvEllipsoid*), toMGRS(IlString&, const IlvEllipsoid*).

◆ FromMGRS() [2/2]

static IlBoolean IlvCoordinate::FromMGRS	(	IlUShort	zoneNumber,
		char	zoneDesignator,
		const IlString &	squareId,
		IlUInt	easting,
		IlUInt	northing,
		IlvCoordinate &	output,
		const int	precision,
		const IlvEllipsoid *	ellipsoid = `0`
	)

static

Converts MGRS coordinates into an IlvCoordinate object.

Parameters

zoneNumber	The input UTM zone number (between 1 and 60) or `0` indicating an UPS coordinate (below -80° latitude or above 84°).
zoneDesignator	The UTM zone designator character. Note that `A`, `B`, `Y` and `Z` indicate polar areas, using the UPS conversion.
squareId	The MGRS square identifier.
easting	The input value for easting in the MGRS square, in meters.
northing	The input value for northing in the MGRS square, in meters.
output	Set to the parsed coordinates on success.
precision.	How many MGRS precision digits are there [2:5]. This is used in result validation.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: toMGRS(IlUShort&, char&, IlString&, IlUInt&, IlUInt&, const IlvEllipsoid*), FromMGRS(const IlString&, IlvCoordinate&, const IlvEllipsoid*).

◆ FromUTM() [1/2]

static IlBoolean IlvCoordinate::FromUTM	(	const IlString &	input,
		IlvCoordinate &	output,
		const IlvEllipsoid *	ellipsoid = `0`
	)

static

Converts a UTM/UPS-formatted string into an IlvCoordinate object.

The input string must represent a valid UTM (Universal Transverse Mercator) / UPS (Universal Polar Stereographic) value:

[<zoneNb>]<zoneDesignator> <easting>[mE] <northing>[mN]

<zoneNb> is the UTM zone number: an integer value between 1 and
1. If omitted, this indicates a polar area, handled by the UPS projection (that is, a latitude below -80° or above 84°).
<zoneDesignator> is the UTM zone designator: a letter that indicates the latitude band (or an UPS quadrant, when the latitude is beyond the UTM valid values).
<easting> is the easting planar coordinate value in the indicated zone, in meters.
<northing> is the northing planar coordinate value in the indicated zone, in meters.

Space characters and additional characters are discarded.

Examples of valid input:

31U 448265 5411920
23 K 687394.89mE 7465628.95mN
Z 2057475mE 1785497mN

Parameters

input	The UTM/UPS coordinates string
output	Set to the parsed coordinates on success.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: FromUTM(IlUShort, char, IlDouble, IlDouble, IlvCoordinate&, const IlvEllipsoid*), toUTM(IlString&, const IlvEllipsoid*).

◆ FromUTM() [2/2]

static IlBoolean IlvCoordinate::FromUTM	(	IlUShort	zoneNumber,
		char	zoneDesignator,
		IlDouble	easting,
		IlDouble	northing,
		IlvCoordinate &	output,
		const IlvEllipsoid *	ellipsoid = `0`
	)

static

Converts UTM/UPS coordinates into an IlvCoordinate object.

Parameters

zoneNumber	The input UTM zone number (between 1 and 60) or `0` indicating an UPS coordinate (below -80° latitude or above 84°).
zoneDesignator	The UTM zone designator character. Note that `A`, `B`, `Y` and `Z` indicate polar areas, using the UPS conversion.
easting	The input value for easting, in meters.
northing	The input value for northing, in meters.
output	Set to the parsed coordinates on success.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the parsing was successful and IlFalse otherwise.

See also: toUTM(IlUShort&, char&, IlDouble&, IlDouble&, const IlvEllipsoid*) const, FromUTM(const IlString&, IlvCoordinate&, const IlvEllipsoid*).

◆ isCloseTo()

IlBoolean IlvCoordinate::isCloseTo	(	const IlvCoordinate &	other,
		IlDouble	tolerance = `0.0`
	)		const

Checks if two coordinates are close.

Parameters

other	The coordinates to compare to.
tolerance	The tolerance value.

Returns: IlTrue if the distance between the x and y values of the current coordinates and the one of the coordinates other are less than the value specified by the parameter tolerance.

◆ lat() [1/2]

IlDouble IlvCoordinate::lat ( ) const

Returns the latitude value.

This is a synonym for the y value.

Returns: The latitude value, in radians.

See also: y().

◆ lat() [2/2]

void IlvCoordinate::lat ( IlDouble lat )

Sets the latitude value.

This is a synonym for the y value.

Parameters

lat	The new latitude value, in radians.

See also: y(IlDouble).

◆ lon() [1/2]

IlDouble IlvCoordinate::lon ( ) const

Returns the longitude value.

This is a synonym for the x value.

Returns: The longitude value, in radians.

See also: x().

◆ lon() [2/2]

void IlvCoordinate::lon ( IlDouble lon )

Sets the longitude value.

This is a synonym for the x value.

Parameters

lon	The new longitude value, in radians.

See also: x(IlDouble).

◆ move()

void IlvCoordinate::move	(	IlDouble	x,
		IlDouble	y
	)

This member function takes existing coordinates and moves them to another position.

Parameters

x	The new x value.
y	The new y value.

◆ operator=()

IlvCoordinate& IlvCoordinate::operator= ( const IlvCoordinate & c )

Assignment operator.

Parameters

c	The coordinates that are copied to the current object.

Returns: This object, updated with the new coordinates.

◆ operator==()

int IlvCoordinate::operator== ( const IlvCoordinate & c ) const

Equality operator.

This member function tests whether two coordinates are equal. Because a strict comparison of floating values may not be significant, you can also use the function isCloseTo().

Parameters

c	The coordinates to compare to.

Returns: 0 if c is different than the current object.

◆ toDD()

IlBoolean IlvCoordinate::toDD ( IlString & output ) const

Converts this object into a DD-formatted string.

The ouput is the latitude value, in degrees (in the range [-180, 180)), followed by a comma sign, followed by the longitude value, in degrees (in the range [-90, 90]).

Parameters

output Set to the string representation of this object.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromDD(const IlString&, IlvCoordinate&).

◆ toDMS()

IlBoolean IlvCoordinate::toDMS ( IlString & output ) const

Converts this object into a DMS-formatted string.

The ouput is the latitude value followed by the longitude value, both expressed in degrees, minutes and seconds.

Parameters

output Set to the DMS string representation of this object.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromDMS(const IlString&, IlvCoordinate&).

◆ toMGRS() [1/2]

IlBoolean IlvCoordinate::toMGRS	(	IlString &	output,
		const IlvEllipsoid *	ellipsoid = `0`
	)		const

Converts this object into an MGRS string representation.

Parameters

output	Set to the MGRS string representation of this object.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromMGRS(const IlString&, IlvCoordinate&, const IlvEllipsoid*), toMGRS(IlUShort&, char&, IlString&, IlUInt&, IlUInt&, const IlvEllipsoid*) const.

◆ toMGRS() [2/2]

IlBoolean IlvCoordinate::toMGRS	(	IlUShort &	zoneNumber,
		char &	zoneDesignator,
		IlString &	squareId,
		IlUInt &	easting,
		IlUInt &	northing,
		const IlvEllipsoid *	ellipsoid = `0`
	)		const

Converts this object into MGRS values.

Parameters

zoneNumber	Set to the UTM zone number (between 1 and 60) or `0` indicating an UPS coordinate (below -80° latitude or above 84°).
zoneDesignator	Set to the UTM zone designator character. Note that `A`, `B`, `Y` and `Z` indicate polar areas, using the UPS conversion.
squareId	Set to the MGRS square identifier.
easting	Set to the easting value, in meters.
northing	Set to the northing value, in meters.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromMGRS(IlUShort, char, const IlString&, IlUInt, IlUInt, IlvCoordinate&, const IlvEllipsoid*), toMGRS(IlString&, const IlvEllipsoid*) const.

◆ toUTM() [1/2]

IlBoolean IlvCoordinate::toUTM	(	IlString &	output,
		const IlvEllipsoid *	ellipsoid = `0`
	)		const

Converts this object into an UTM/UPS string representation.

Parameters

output	Set to the UTM/UPS string representation of this object.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromUTM(const IlString&, IlvCoordinate&, const IlvEllipsoid*), toUTM(IlUShort&, char&, IlDouble&, IlDouble&, const IlvEllipsoid*) const.

◆ toUTM() [2/2]

IlBoolean IlvCoordinate::toUTM	(	IlUShort &	zoneNumber,
		char &	zoneDesignator,
		IlDouble &	easting,
		IlDouble &	northing,
		const IlvEllipsoid *	ellipsoid = `0`
	)		const

Converts this object into UTM/UPS values.

Parameters

zoneNumber	Set to the UTM zone number (between 1 and 60) or `0` indicating an UPS coordinate (below -80° latitude or above 84°).
zoneDesignator	Set to the UTM zone designator character. Note that `A`, `B`, `Y` and `Z` indicate polar areas, using the UPS conversion.
easting	Set to the easting value, in meters.
northing	Set to the northing value, in meters.
ellipsoid	The ellipsoid to be used for the conversion. If omitted or set to `0` then `IlvEllipsoid::WGS84()` is used.

Returns: IlTrue if the conversion was successful and IlFalse otherwise.

See also: FromUTM(IlUShort, char, IlDouble, IlDouble, IlvCoordinate&, const IlvEllipsoid*), toUTM(IlString&, const IlvEllipsoid*) const.

◆ translate() [1/2]

void IlvCoordinate::translate ( const IlvCoordinate & dc )

Translates an IlvCoordinate.

This member function shifts existing coordinates to another location by means of a delta-distance approach. This member function performs the same operation as translate(IlDouble dx, IlDouble dy), except that instead of specifying a distance by means of x and y values, the translation is taken from the dc parameter.

Parameters

dc	The translation values to apply to this object.

◆ translate() [2/2]

void IlvCoordinate::translate	(	IlDouble	dx,
		IlDouble	dy
	)

Translates an IlvCoordinate.

This member function shifts existing coordinates to another location by means of a delta-distance approach. The dx and dy values represent the distance between the current position of the coordinates and the target position.

Parameters

dx	The `x` translation.
dy	The `y` translation.

◆ x() [1/2]

IlDouble IlvCoordinate::x ( ) const

Returns the x value.

Returns: The x value.

See also: lon().

◆ x() [2/2]

void IlvCoordinate::x ( IlDouble x )

Sets the x value.

Parameters

x	The new x value.

See also: lon(IlDouble).

◆ y() [1/2]

IlDouble IlvCoordinate::y ( ) const

Returns the y value.

Returns: The y value.

See also: lat().

◆ y() [2/2]

void IlvCoordinate::y ( IlDouble y )

Sets the y value.

Parameters

y	The new y value.

See also: lat(IlDouble).

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IlvCoordinate()

Member Function Documentation

◆ FromDD()

◆ FromDMS()

◆ FromMGRS() [1/2]

◆ FromMGRS() [2/2]

◆ FromUTM() [1/2]

◆ FromUTM() [2/2]

◆ isCloseTo()

◆ lat() [1/2]

◆ lat() [2/2]

◆ lon() [1/2]

◆ lon() [2/2]

◆ move()

◆ operator=()

◆ operator==()

◆ toDD()

◆ toDMS()

◆ toMGRS() [1/2]

◆ toMGRS() [2/2]

◆ toUTM() [1/2]

◆ toUTM() [2/2]

◆ translate() [1/2]

◆ translate() [2/2]

◆ x() [1/2]

◆ x() [2/2]

◆ y() [1/2]

◆ y() [2/2]