IPosition80

This interface allows the user to control the position and orientation of an object or location on the terrain and the distance from which the object is viewed when flying to it or performing a flight pattern (e.g. circling) around it. .

 

	Properties
	Altitude	Gets and sets the altitude of the IPosition80 object.
	AltitudeType	Gets and sets an enum determining how the altitude is interpreted.
	Cartesian	Gets and sets a Boolean that determines whether calculations are based on a Cartesian coordinate system.
	Distance	Gets and sets the distance from the camera to the position.
	Pitch	Gets and sets the tilt angle of the camera or object.
	Roll	Gets and sets the roll angle of the object.
	X	Gets and sets the x-coordinate.
	Y	Gets and sets the y-coordinate
	Yaw	Gets and sets the direction angle of the camera or object.
	Methods
	AimTo	Returns an IPosition80 object that represents the same position as the caller’s coordinates and the angles that are directed toward the given coordinates.
	ChangeAltitudeType	Converts the altitude type of the caller to a new altitude type.
	Copy	Returns a copy of the IPosition80 object.
	DistanceTo	Measures the distance between two coordinates.
	Init	Initializes a new instance of IPosition80.
	InitFrom	Initializes an IPosition object based on a string of comma separated position values.
	IsEqual	Compares the property values of this position to another position.
	Lerp	Moves a coordinate a given percentage toward another coordinate.
	Move	Moves a coordinate a specific distance.
	MoveByOrientation	Moves an IPosition object by a specified Forward-Backward, Right-Left and Up-Down offset.
	MoveToward	Moves a coordinate the specified distance toward another coordinate.
	ToAbsolute	Returns an IPosition80 object that is converted to absolute height.
	ToRelative	Returns an IPosition80 object that is converted to height relative to terrain.
	ToString	Returns a string of comma separated position values.

Altitude

Gets and sets the altitude of the IPosition80 object according to the Altitude Type value.

 

JavaScript
Altitude

 

C#
double Altitude { get; set; }

 

C++
HRESULT Altitude([out, retval] double* pVal) HRESULT Altitude([in] double pVal)

AltitudeType

Gets and sets an enum determining how the altitude is interpreted. The following are the possible values:

§   ATC_TERRAIN_RELATIVE      = 0
Places the position’s pivot point at a specified altitude above the ground.

§   ATC_PIVOT_RELATIVE            = 1
Places each point of the object at a specified altitude above the pivot point altitude, defined by its Point Altitude. The pivot is located at the center of the object.

§   ATC_ON_TERRAIN                   = 2
The altitude is ignored and the coordinate is on the terrain itself.

§   ATC_TERRAIN_ABSOLUTE    = 3
Places the position’s pivot point at a specified altitude above the terrain database vertical datum base ellipsoid.

§   ATC_3DML_RELATIVE            = 4
Places the object’s pivot point at a specified altitude above the 3DML layer.

Note:    ATC_PIVOT_RELATIVE and ATC_ON_TERRAIN values apply only for 2D shapes and polygons. ATC_3DML_RELATIVE only applies to image and text labels.

 

JavaScript
AltitudeType

 

C#
AltitudeTypeCode AltitudeType { get; set; }

 

C++
HRESULT AltitudeType([out, retval] AltitudeTypeCode* pVal) HRESULT AltitudeType([in] AltitudeTypeCode pVal)

Cartesian

Gets and sets a Boolean that determines whether calculations are based on a Cartesian coordinate system. When using a flat terrain database, the calculation is always based on a Cartesian system.

 

JavaScript
Cartesian

 

C#
bool Cartesian { get; set; }

 

C++
HRESULT Cartesian([out, retval] VARIANT_BOOL* pVal) HRESULT Cartesian([in] VARIANT_BOOL pVal)

Distance

If the IPosition object is used to create a location object, the distance specifies a distance from which the x, y, and altitude coordinates must be viewed. If this property is set to -1, the recommended viewing distance for the object, based on its size, will be automatically calculated when needed (e.g. before Fly To operation).

 

JavaScript
Distance

 

C#
double Distance { get; set; }

 

C++
HRESULT Distance([out, retval] double* pVal) HRESULT Distance([in] double pVal)

Pitch

Gets and sets the tilt angle.

 

JavaScript
Pitch

 

C#
double Pitch { get; set; }

 

C++
HRESULT Pitch([out, retval] double* pVal) HRESULT Pitch([in] double pVal)

Roll

Gets and sets the spin angle.

 

JavaScript
Roll

 

C#
double Roll { get; set; }

 

C++
HRESULT Roll([out, retval] double* pVal) HRESULT Roll([in] double pVal)

X

Gets and sets the x- coordinate in the project’s coordinate system units.

 

JavaScript
X

 

C#
double X { get; set; }

 

C++
HRESULT X([out, retval] double* pVal) HRESULT X([in] double pVal)

Y

Gets and sets the y- coordinate in the project’s coordinate system units.

 

JavaScript
Y

 

C#
double Y { get; set; }

 

C++
HRESULT Y([out, retval] double* pVal) HRESULT Y([in] double pVal)

Yaw

Gets and sets the yaw orientation of the object.

 

JavaScript
Yaw

 

C#
double Yaw { get; set; }

 

C++
HRESULT Yaw([out, retval] double* pVal) HRESULT Yaw([in] double pVal)

AimTo

Returns an IPosition80object that represents the same position as the caller’s coordinates and the angles that are directed toward the given coordinates.

 

JavaScript
AimTo(        Position)

 

C#
IPosition80 AimTo(        IPosition80 Position)

 

C++
HRESULT AimTo(        IPosition80* Position,        IPosition80** pVal)

Parameters

Position

An IPosition80 representing a position on the terrain.

Return Value

pVal

An IPosition80 representing the same position as the caller’s coordinates and the angles that are directed toward the given coordinates.

Exceptions

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

ChangeAltitudeType

Converts the altitude type of the caller to a new altitude type. The caller’s altitude is also changed as a result.  

 

JavaScript
ChangeAltitudeType(        AltitudeType)

 

C#
void ChangeAltitudeType(        AltitudeTypeCode AltitudeType)

 

C++
HRESULT ChangeAltitudeType(        AltitudeTypeCode AltitudeType)

Parameters

AltitudeType

An enum determining how the altitude is interpreted. The following are the possible values:

·          ATC_TERRAIN_RELATIVE = 0
Places the object’s pivot point at a specified altitude above the ground.

·          ATC_PIVOT_RELATIVE    = 1
Places each point of the object at a specified altitude above the pivot point altitude, defined by its Point Altitude. The pivot is located at the center of the object.

·          ATC_ON_TERRAIN           = 2
Creates the object on the terrain itself.

·          ATC_TERRAIN_ABSOLUTE = 3
Places the object’s pivot point at a specified altitude above the terrain database vertical datum base ellipsoid.

·          ATC_3DML_RELATIVE    = 4
Places the object's pivot point at a specified altitude above the 3DML layer.

Note:    ATC_PIVOT_RELATIVE and ATC_ON_TERRAIN values apply only for 2D shapes and polygons. ATC_3DML_RELATIVE only applies to image and text labels.

Exceptions

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

Copy

Returns an IPosition80 object that is a copy of the caller.

 

JavaScript
Copy()

 

C#
IPosition80 Copy()

 

C++
HRESULT Copy(        IPosition80** pVal)

Return Value

pVal

An IPosition80 object that has all the same properties as the caller’s.  

DistanceTo

Measures the distance between two coordinates.

 

JavaScript
DistanceTo(        Position)

 

C#
double DistanceTo(        IPosition80 Position)

 

C++
HRESULT DistanceTo(        IPosition80* Position,        double* pVal)

 

Parameters

Position

An IPosition80 representing the coordinate whose distance from the caller’s coordinates is being measured.

Return Value

pVal

The distance between the two coordinates.

Exceptions

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

Init

Initializes a new instance of the IPosition80.

 

JavaScript
Init(        X,        Y,        Altitude,        Yaw,        Pitch,        Roll,        AltitudeType,        Distance)

 

C#
void Init(        double X = 0,        double Y = 0,        double Altitude = 0,        double Yaw = 0,        double Pitch = 0,        double Roll = 0,        AltitudeTypeCode AltitudeType = AltitudeTypeCode.ATC_TERRAIN_RELATIVE,        double Distance = 0)

 

C++
HRESULT Init(        double X,        double Y,        double Altitude,        double Yaw,        double Pitch,        double Roll,        AltitudeTypeCode AltitudeType,        double Distance)

 

Parameters

X

The x- coordinate in coordinate system units.

Y

The y-coordinate in coordinate system units.

Altitude

The altitude.

Yaw

The direction angle.

Pitch

The tilt angle.

Roll

The spin angle

AltitudeType

An enum determining how the altitude is interpreted. The following are the possible values:

§   ATC_TERRAIN_RELATIVE = 0
Places the object’s pivot point at a specified altitude above the ground.

§   ATC_PIVOT_RELATIVE = 1
Places each point of the object at a specified altitude above the pivot point altitude, defined by its Point Altitude. The pivot is located at the center of the object.

§   ATC_ON_TERRAIN = 2
Creates the object on the terrain itself.

§   ATC_TERRAIN_ABSOLUTE = 3
Places the object’s pivot point at a specified altitude above the terrain database vertical datum base ellipsoid.

§   ATC_3DML_RELATIVE = 4
Places the object's pivot point at a specified altitude above the 3DML layer.

Note:    ATC_PIVOT_RELATIVE and ATC_ON_TERRAIN values apply only for 2D shapes and polygons. ATC_3DML_RELATIVE only applies to image and text labels.

 

Distance

The distance to the camera once the camera comes to a stop.

Exceptions

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

InitFrom

Initializes an IPosition object based on a string of comma separated position values in the following order: X/Longitude, Y/Latitude, Altitude, Yaw, Pitch, Roll, Distance, AltitudeType.

 

JavaScript
InitFrom(        var)

 

C#
void InitFrom(        object var)

 

C++
HRESULT InitFrom(        VARIANT var)

Parameters

var

A string of comma separated position values in the following order: X/Longitude, Y/Latitude, Altitude, Yaw, Pitch, Roll, Distance, AltitudeType.

Exceptions

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

IsEqual

Compares the property values of this IPosition80 object to another IPosition80 object.

 

JavaScript
IsEqual(        Position)

 

C#
bool IsEqual(        IPosition80 Position)

 

C++
HRESULT IsEqual(        IPosition80* Position,        VARIANT_BOOL* pVal)

Parameters

Position

An IPosition80 representing a position, defined by its coordinates in the 3D World.

Return Value

pVal

A Boolean that determines if the two positions are identical.

Exceptions

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

Lerp

Moves a coordinate a given percentage toward another coordinate.

 

JavaScript
Lerp(        Position,        Percentage)

 

C#
IPosition80 Lerp(        IPosition80 Position,        double Percentage)

 

C++
HRESULT Lerp(        IPosition80* Position,        double Percentage,        IPosition80** pVal)

 

Parameters

Position

An IPosition80 representing the coordinate towards which the selected coordinate is being moved.

Percentage

The percentage to move.

Return Value

pVal

An IPosition80 representing the new position after the move, defined by its coordinates in the 3D World.

Exceptions

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

Move

Moves a coordinate a specific distance.

 

JavaScript
Move(        Distance,        Yaw,        Pitch)

 

C#
IPosition80 Move(        double Distance,        double Yaw,        double Pitch)

 

C++
HRESULT Move(        double Distance,        double Yaw,        double Pitch,        IPosition80** pVal)

Parameters

Distance

The distance to move.

Yaw

The direction to move the coordinate.

Pitch

The pitch angle to move the coordinate.

Return Value

pVal

An IPosition80 representing the new position after the move, defined by its coordinates in the 3D World.

Exceptions

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

MoveByOrientation

With this method you can move the IPosition80 object by a specified Forward-Backward, Right-Left and Up-Down offset, based on the set IPosition80 object’s properties (point and orientation, X and Y coordinates, altitude, Yaw Pitch and Roll values). The movement is defined by setting the forward, right, and up values in moveForward, moveRight and moveUp respectively. Use negative values to move in the opposite direction (e.g., negative value for moveForward performs a backward movement). This method replaces the deprecated ICoordServices80.MoveCoordEx method.

 

JavaScript
MoveByOrientation(        moveForward,        moveRight,        moveUp)

 

C#
IPosition80 MoveByOrientation (        double        moveForward,        double        moveRight,        double        moveUp)

 

C++
HRESULT MoveByOrientation (        double        moveForward,        double        moveRight,        double        moveUp        IPosition80** pVal)

Parameters

moveForward

The offset to move the point forward. Positive values move the forward, negative values move backwards.

moveRight

The offset to move the point to the right and left. Positive values move the point to the right, negative values move the point to the left.

moveUp 

The offset to move the point up and down. Positive values move the point up, negative values move the point down.

Return Value

Position

An IPosition80 representing the new position of the 3D coordinate being moved.

Exceptions

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

 

MoveToward

Moves a coordinate the specified distance toward another coordinate.

 

JavaScript
MoveToward(        Position,        Distance)

 

C#
IPosition80 MoveToward(        IPosition80 Position,        double Distance)

 

C++
HRESULT MoveToward(        IPosition80* Position,        double Distance,        IPosition80** pVal)

Parameters

Position

An IPosition80 representing the coordinate towards which the selected coordinate is being moved.

Distance

The distance to move, in meters.

Return Value

pVal

An IPosition80 representing the new position after the move, defined by its coordinates in the 3D World.

Exceptions

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

ToAbsolute

Returns an IPosition80 object that is converted to absolute height (ATC_TERRAIN_ABSOLUTE).

 

JavaScript
ToAbsolute(        Accuracy)

 

C#
IPosition80 ToAbsolute(        AccuracyLevel Accuracy = AccuracyLevel.ACCURACY_NORMAL)

 

C++
HRESULT ToAbsolute(        AccuracyLevel Accuracy,        IPosition80** pVal)

 

Parameters

Accuracy

An enum that determines the accuracy level. The following are the possible values:

·          ACCURACY_NORMAL = 0,

·          ACCURACY_BEST_FROM_MEMORY = 1,

·          ACCURACY_FORCE_BEST_RENDERED = 2

Return Value

pVal

An IPosition80 object that has the same x and y coordinates as the caller’s but with altitude property converted to absolute based on the caller x and y.

Exceptions

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

ToRelative

Returns an IPosition80 object that is converted to height relative to terrain (ATC_TERRAIN_RELATIVE).

 

JavaScript
ToRelative(        Accuracy)

 

C#
IPosition80 ToRelative(        AccuracyLevel Accuracy = AccuracyLevel.ACCURACY_NORMAL)

 

C++
HRESULT ToRelative(        AccuracyLevel Accuracy,        IPosition80** pVal)

Parameters

Accuracy

An enum that determines the accuracy level. The following are the possible values:

·          ACCURACY_NORMAL = 0,

·          ACCURACY_BEST_FROM_MEMORY = 1,

·          ACCURACY_FORCE_BEST_RENDERED = 2

Return Value

pVal

An IPosition80 object that has the same x and y coordinates as the caller’s but with altitude property converted to relative to terrain based on the caller x and y.

Exceptions

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

ToString

Returns a string of position values in the following order: X/Longitude, Y/Latitude, Altitude, Yaw, Pitch, Roll, Distance, AltitudeType.

 

JavaScript
ToString(        Format)

 

C#
string ToString(        string Format = "")

 

C++
HRESULT ToString(        BSTR Format,        BSTR* pVal)

 

Parameters

Format

A string defining the format of the string values file. Use ”xml” or leave empty for a comma delimited file.

Return Value

pVal

A string of position values in the following order: X/Longitude, Y/Latitude, Altitude, Yaw, Pitch, Roll, Distance, AltitudeType. If “xml” was passed as the format, the string returned will be:

<SGPosition><x>[xvalue]</x><y>%lf</y><altitude>%lf</altitude><yaw>%lf</yaw><pitch>%lf</pitch><roll>%lf</roll><distance>%lf</distance><altitudeType>%d</altitudeType>

Exceptions

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