CoordServices (ICoordServices80)

The ICoordServices80 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 ITerrain80.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 ICoordinateSystem80 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#
ICoordinateSystem80 CreateCoordinateSystem(        string WellKnownText)

 

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

 

Parameters

WellKnownText

The Well-Known Text as a string value.

pVal

An ICoordinateSystem80 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#
IPosition80 GetAimingAngles(        IPosition80 From,        IPosition80 To)

 

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

Parameters

From

An IPosition80representing the position of the first coordinate on the terrain.

To

An IPosition80representing the position of the second coordinate on the terrain.

Return Value

pVal

An IPosition80representing 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(        IPosition80 From,        IPosition80 To)

 

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

Parameters

From

An IPosition80 representing the position of the first coordinate.

To

An IPosition80 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(        ICoordinateSystem80        From,        ICoordinateSystem80        To,        double        X,        double        Y)

 

C++
HRESULT Reproject(        ICoordinateSystem80 *      From,        ICoordinateSystem80 *      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(        ICoordinateSystem80        From,        ICoordinateSystem80        To,        double        X,        double        Y,        double        Z)

 

C++
HRESULT ReprojectEx(        ICoordinateSystem80 *      From,        ICoordinateSystem80 *      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.