CoordServices (ICoordServices81) 

The ICoordServices81 interface provides a set of methods for reprojecting given coordinates between different coordinate systems. Use the SourceCoordinateSystem property to define the coordinate system your application uses. Once a coordinate system has been set by a client, every coordinate used by the client is converted from the source coordinate system used by the client to the terrain coordinate system. You can retrieve the terrain coordinate system with ITerrain81.CoordinateSystem.

TerraExplorer Pro also provides a number of service methods to perform advanced geographic-related tasks like calculating distances and angles between points. These methods are especially useful when working with globe databases, where the units are in degrees, but they work for any database.

 

	Properties
	ShiftGridURL	Gets and sets the URL of the server from which TerraExplorer reads grid shift files.
	SourceCoordinateSystem	An ICoordinateSystem81 representing the source’s coordinate system.
	Methods
	ChooseCSDialog	Opens a high-level dialog that allows the user to select, view, edit, and create a coordinate system.
	ConvertCoordinateToMGRS	Converts a given coordinate from the coordinate system of the terrain database to Military Grid Reference System coordinates.
	ConvertMGRSToCoordinate	Converts a given Military Grid Reference System coordinate to the coordinate system of the terrain database.
	CreateCoordinateSystem	Creates a coordinate system from a Well-Known Text string.
	GetAimingAngles	Returns the calculated angle between two specified 3D-coordinates.
	GetDistance	Returns the horizontal distance between two given coordinates.
	GetDistance3D	Returns the actual aerial distance between two given points.
	GetParam	Reserved. Currently not used.
	MoveCoord	Moves a 2D-coordinate by a specified west-east and south-north offset.
	MoveCoordEx	Deprecated.
	Reproject	Converts a given coordinate from one coordinate system to another.
	ReprojectEx	Converts a given 3D-coordinate from one coordinate system to another.
	SetParam	Reserved. Currently not used.

 

ShiftGridURL 

Gets and sets the URL of the server from which TerraExplorer reads grid shift files. TerraExplorer uses GeoTIFF grid shift files to shift and transform between some coordinate systems that have different datums. For backward compatibility, GSB and GTX grid shift files are also currently supported. When the Well-Known Text (WKT) of one of the coordinate systems in your project references a particular grid shift file, TerraExplorer first checks your local computer for the file. If the file was not found on your computer, TerraExplorer dynamically downloads the necessary grid shift file from the ProjData folder on the currently connected SkylineGlobe Server. If you are not connected to a server, it checks the URL set by this property for the necessary grid shift file. The default value for this property is https://cdn.proj.org.

For more information on grid shift files, see the TerraExplorer User Guide.

 

JavaScript
ShiftGridURL

 

C#
string ShiftGridURL { get; set; }

 

C++
HRESULT ShiftGridURL ([out, retval] BSTR* pVal) HRESULT ShiftGridURL ([in] BSTR* pVal)

 

ChooseCSDialog 

This method opens a high-level dialog that allows the user to select, view, edit, and create a coordinate system.

.

JavaScript
ChooseCSDialog(        Title,        WellKnownText)

 

C#
string ChooseCSDialog(        string       Title,        string       WellKnownText)

 

C++
HRESULT ChooseCSDialog(         BSTR  Title,         BSTR  WellKnownText,         BSTR *      bstrWkt )

Parameters

Title

The title of the dialog.

WellKnownText

The Well-Known Text that should display when opening the dialog box. This Well-Known Text sets the initial coordinate system.  

Return Value

bstrWkt

The unique string of the Well-Known Text of the selected coordinate system.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

ConvertCoordinateToMGRS 

This method converts a given coordinate from the coordinate system of the terrain database to Military Grid Reference System coordinates. The X and Y coordinates to be converted should be given in X and Y respectively. After the method is completed, bstrMGRS returns the converted coordinates as a string value.

 

JavaScript
ConvertCoordinateToMGRS(        X,        Y)

 

C#
string ConvertCoordinateToMGRS(        double       X,        double       Y)

 

C++
HRESULT ConvertCoordinateToMGRS(         double      X,         double      Y,         BSTR *      bstrMGRS )

Parameters

X

The X- coordinate in coordinate system units.

Y

The Y- coordinate in coordinate system units.

Return Value

bstrMGRS

The MGRS coordinate as a string value.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

ConvertMGRSToCoordinate 

This method converts a given Military Grid Reference System coordinate to the coordinate system of the terrain database. The coordinates to be converted should be given in bstrMGRS. After the method is completed, pVal returns the converted coordinates.

Note:     The returned coordinates are the MGRS coordinates of the center of the MGRS tile.  

 

JavaScript
ConvertMGRSToCoordinate(        bstrMGRS)

 

C#
ICoord2D ConvertMGRSToCoordinate(        string bstrMGRS)

 

C++
HRESULT ConvertMGRSToCoordinate (         BSTR  bstrMGRS,         ICoord2D **  pVal )

 

Parameters

bstrMGRS

The MGRS coordinate as a string value.

Return Value

pVal

An ICoord2D representing the converted MPT coordinates.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

CreateCoordinateSystem 

This method creates a coordinate system from a Well-Known Text string.

 

JavaScript
CreateCoordinateSystem(        WellKnownText)

 

C#
ICoordinateSystem81 CreateCoordinateSystem(        string WellKnownText)

 

C++
HRESULT CreateCoordinateSystem(         BSTR WellKnownText,               ICoordinateSystem81 ** pVal )

 

Parameters

WellKnownText

The Well-Known Text as a string value.

pVal

An ICoordinateSystem81 representing the coordinate system created.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

GetAimingAngles 

This method returns the calculated angle between two specified 3D-coordinates.

 

JavaScript
GetAimingAngles(        From, To)

 

C#
IPosition81 GetAimingAngles(        IPosition81 From,        IPosition81 To)

 

C++
HRESULT GetAimingAngles(         IPosition81 * From,         IPosition81 * To,         IPosition81 ** pVal )

Parameters

From

An IPosition81 representing the position of the first coordinate on the terrain.

To

An IPosition81 representing the position of the second coordinate on the terrain.

Return Value

pVal

An IPosition81 representing the position and orientation of the calculated angle.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

GetDistance 

This method returns the horizontal distance between two given coordinates.

 

JavaScript
GetDistance(        X1,        Y1,        X2,        Y2)

 

C#
double GetDistance(        double       X1,        double       Y1,        double       X2,        double       Y2)

 

C++
HRESULT GetDistance(        double       X1,        double       Y1,        double       X2,        double       Y2,        double *     Dist)

Parameters

X1

X-coordinate of the first point in coordinate system units.

Y1

Y-coordinate of the first point in coordinate system units.

X2

X-coordinate of the second point in coordinate system units.

Y2

Y-coordinate of the second point in coordinate system units.

Return Value

Dist

The calculated distance between the two points.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

GetDistance3D 

This method calculates the actual aerial distance between two points in the 3D World, taking into account the horizontal and vertical distance difference between the points.

 

JavaScript
GetDistance3D(        From,        To)

 

C#
double GetDistance3D(        IPosition81 From,        IPosition81 To)

 

C++
HRESULT GetDistance3D(        IPosition81 * From,        IPosition81 * To,        double * Dist )

Parameters

From

An IPosition81 representing the position of the first coordinate.

To

An IPosition81 representing the position of the second coordinate.

Return Value

Dist

The calculated distance between the two points.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

MoveCoord

This method moves a 2D-coordinate by a specified west-east and south-north offset. The X and Y coordinates to be converted should be given in X and Y respectively. After the method is completed, the pVal returns the new coordinates. This method can be used, for example, to calculate the coordinates for drawing a square on a globe database.

 

JavaScript
MoveCoord(        X,        Y,        moveWestEast,        moveSouthNorth)

 

C#
ICoord2D MoveCoord(        double       X,        double       Y,        double       moveWestEast,        double       moveSouthNorth)

 

C++
HRESULT MoveCoord(        double       X,        double       Y,        double       moveWestEast,        double       moveSouthNorth,        ICoord2D **  pVal )

 

Parameters

X

X-coordinate in coordinate system units.

Y

Y-coordinate in coordinate system units.

moveWestEast

The offset to move the point on the west-east axis. Positive values move the coordinate to the east, negative values move to the west.

moveSouthNorth

The offset to move the point on the south-north axis. Positive values move the coordinate to the north, negative values move to the south.

Return Value

pVal

An ICoord2D representing the new coordinates.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

Reproject 

This method converts a given coordinate from one coordinate system to another.

 

JavaScript
Reproject(        From,        To,        X,        Y)

 

C#
ICoord2D Reproject(        ICoordinateSystem81        From,        ICoordinateSystem81        To,        double       X,        double       Y)

 

C++
HRESULT Reproject(        ICoordinateSystem81 *      From,        ICoordinateSystem81 *      To,        double       X,        double       Y,        ICoord2D **  pVal )

 

Parameters

From

The coordinate system in which the coordinate is given.

To

The coordinate system to which you want to convert the coordinate.

X

X- coordinate in coordinate system units.

Y

Y- coordinate in coordinate system units.

Return Value

pVal

An ICoord2D representing the converted coordinates.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.

ReprojectEx 

This method converts a given 3D-coordinate from one coordinate system to another.

 

JavaScript
ReprojectEx(        From,        To,        X,        Y,        Z)

 

C#
ICoord3D ReprojectEx(        ICoordinateSystem81        From,        ICoordinateSystem81        To,        double       X,        double       Y,        double       Z)

 

C++
HRESULT ReprojectEx(        ICoordinateSystem81 *      From,        ICoordinateSystem81 *      To,        double       X,        double       Y,        double       Z,        ICoord3D **  pVal )

 

Parameters

From

The coordinate system in which the coordinate is given.

To

The coordinate system to which you want to convert the coordinate.

X

X- coordinate in coordinate system units.

Y

Y- coordinate in coordinate system units.

Z

Z- coordinate in coordinate system units.

 

Return Value

pVal

An ICoord3D representing the converted coordinates.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.