 |
VR-Link C# API Documentation
|
|
VR-Link C# API Documentation
|
VR-Link supports several coordinate systems and provides classes and functions for converting locations, vectors, and orientations from one system to another.
DIS and the RPR FOM in HLA specify that world locations, velocities, accelerations and orientations be represented with respect to a right-hand geocentric Cartesian coordinate system. The origin of this geocentric coordinate system is the center of the earth. The positive X-axis passes through the prime meridian at the equator; the positive Y-axis passes through 90 degrees east longitude at the equator; and the positive Z-axis passes though the north pole (as illustrated below.)
The DtVector class is typically used to represent locations and vectors in geocentric coordinates, while DtTaitBryan or DtDcm is used to represent orientation.
Geodetic coordinates are another means of specifying location in the world. VR-Link geodetic coordinates consist of latitude and longitude in radians, and altitude in meters above a certain reference ellipsoid, for example, the surface of the earth at sea level.
VR-Link uses the class DtGeodeticCoord (defined in geodeticCoord.h) to represent geodetic coordinates. A DtGeodeticCoord can be initialized from a latitude, longitude, and altitude. Negative latitudes are south latitudes; negative longitudes are west longitudes.
If the default constructor is used, the resulting object represents a latitude, longitude, and altitude of zero.
DtGeodeticCoord has the following inspectors and mutators to get and set values for the individual components of a geodetic coordinate:
DtGeodeticCoord also has member functions that enable you to convert to and from geocentric coordinates. DtGeodeticCoord::geocentric() returns the geocentric equivalent of a geodetic coordinate. For example:
After these lines of code, geoc will contain the coordinate:
{-960122.075, 5445122.868, 3170873.735}
which represents the same point in space as 30 degrees north latitude, 100 degrees east longitude, 1000 meters altitude.
A similar function is DtGeodeticCoord::getGeocentric(), which, rather than returning a geocentric coordinate, sets the value of an existing DtVector, for example:
Going in the other direction, DtGeodeticCoord::setGeocentric() sets the value of a DtGeodeticCoord to the latitude/longitude/altitude equivalent of a given geocentric coordinate:
Also in geodeticCoord.h, are the C-style functions DtGeocToGeod() and DtGeocToGeod(), which you can use instead of the member functions described previously, to convert between geocentric and geodetic coordinates, although their use is discouraged in favor of the member functions.
The default reference ellipsoid used for geocentric to geodetic conversions is WGS84, but this is configurable through the function DtUseMapDatum(), declared in geodeticCoord.h. Any DtMapDatum can be passed to this function. DtMapDatum is defined as:
VR-Link has the following DtMapDatums pre-defined in mapDatum.h:
If you want to use the ED50 reference, for example, try:
VR-Link defines a topographic coordinate system as a right-handed Cartesian coordinate system whose X-Y plane is tangent to the earth's surface at the origin, with the positive X-axis pointing north, the positive Y-axis pointing east, and the positive Z-axis pointing down (as illustrated below). Obviously, there are an infinite number of topographic coordinate systems – one for each point on the earth's surface.
A DtVector is usually used in VR-Link to represent a topographic coordinate.
The easiest way to convert between geocentric and topographic coordinates is by using a DtCoordTransform object (defined in LibMatrix.h). A DtCoordTransform is an object that can transform locations, vectors, or orientations from one Cartesian coordinate system to another.
In general, a DtCoordTransform can be constructed by passing to its constructor the origin of one system with respect to the other, and a rotation matrix that indicates the orientation of one system with respect to the other. However, in the case of a geocentric to topographic transformation, VR-Link provides the function DtGeocToTopoTransform() to initialize a DtCoordTransform for you. This function, declared in topoCoord.h, does the following:
For example, to create a DtCoordTransform that can convert between geocentric coordinates and the topographic coordinate system whose origin is at 30 degrees north latitude, 100 degrees east longitude, you can do the following:
Now, this transform can be used to convert from geocentric to topographic coordinates. For example, if we have a geocentric location in a DtEntityStateRepository, and we want to convert it to our topographic frame, we can use DtCoordTransform::coordTrans():
If we want to do the reverse, we can initialize a second DtCoordTransform to convert from topographic to geocentric using the member function setByInverse():
Now, we can use topoToGeoc() to convert to geocentric, say, for filling in a locally simulated entity's entity state repository:
In addition to coordTrans(), DtCoordTransform also has vecTrans() and eulerTrans() member functions for converting vectors (such as velocity and acceleration), and orientations (expressed as Euler angles) between two different Cartesian coordinate systems.
Converting Euler angles from geocentric to topographic coordinates (or vice versa) is often particularly useful, because topographic-referenced Euler angles correspond to heading, pitch and roll.
Using a DtCoordTransform that can convert from geocentric to topographic coordinates, we can obtain an entity's heading, pitch, and roll as follows:
Locations in the world can be specified using a UTM coordinate system. UTM coordinates are mapped to a reference ellipsoid approximating the surface of the earth using a Universal Transverse Mercator projection. The coordinates consist of easting and northing from an origin or reference location, and an altitude above a reference ellipsoid, all in meters.
In a true UTM coordinate system, the origin or reference point (0,0,0) is often a point on the equator at the center of a particular UTM zone. (The world is longitudinally divided into 60 UTM zones, each centered on an odd multiple of 3 degrees.) However, VR-Link lets you define an "offset UTM" coordinate system by passing any arbitrary reference point, to the function DtUtmInit().
You must call DtUtmInit() to establish the world location of the origin of your UTM attribute system before you use any of the UTM coordinate conversion functions. Currently, VR-Link supports the use of only one UTM reference point at a time. However, you can call DtUtmInit() multiple times in your application to define the UTM origin you want to use for the next set of conversions.
The first two arguments to DtUtmInit() are DtDegMinSec structures, representing the latitude and longitude of the reference point. DtDegMinSec has the following definition:
The following code initializes VR-Link's UTM conversion routines so that they use 35° north latitude and 122° west longitude as the reference point:
The optional (and rarely used) third argument to DtUtmInit() indicates that a particular convention should be used, whereby 500,000 meters are added to all easting values and 10,000,000 meters are added to all north values, in order to eliminate the use of negative numbers in UTM coordinates. Applications that need to use this convention should pass a value of 1 for this argument as opposed to the more common 0.
The optional fourth argument (not shown) sets the UTM Reference zone. If you do not specify this parameter, VR-Link chooses it for you.
A UTM coordinate is represented using DtUtmCoord (defined in utmCoord.h). You can construct a DtUtmCoord by passing its three components (in meters) to the constructor:
Assuming that DtUtmInit() was called as above, this DtUtmCoord would represent a point of altitude 70 meters, that is 50 meters east and 100 meters north of the reference point of 35 degrees north by 122 degrees west.
The class has a copy constructor and assignment operator defined, and has the following inspectors and mutators to access the various components: east, setEast, north, setNorth, up, setUp.
DtUtmCoord also has member functions that enable you to convert to and from geocentric or geodetic coordinates. DtUtmCoord::geocentric() and DtUtmCoord::geodetic() return the geodetic and geocentric equivalents of a UTM coordinate respectively. For example:
The member functions getGeocentric() and getGeodetic() work similarly, but fill in an existing object passed by reference to the function, rather than returning the desired object.
Alternatively, the C-style functions DtGeodToUtm(), DtUtmToGeod(), DtGeocToUtm(), and DtUtmToGeoc() can also convert locations in UTM coordinates to geocentric or geodetic coordinates, and vice-versa. However their use is discouraged in favor of the member functions.
Trouble often arises when programmers do not understand the differences between a UTM coordinate system and a topographic coordinate system that share the same origin.
Although the coordinates of a point near the origin may be similar in the two systems, they are different in several ways.
In a UTM system, Z represents altitude above the earth's surface. In the topographic frame, -Z represents height above a plane tangent to the earth's surface, which deviates from altitude above the earth's surface itself as one moves away from the origin (as illustrated below).
Neglecting the small angle between northing and north, UTM coordinates X, Y, and Z correspond to east, north, and up, while the topographic X, Y, and Z correspond to north, east, and down.
If you want a greater level of control over your coordinate conversions than that offered by the DtCoordTransform class described in 12.3.3.1 DtCoordTransform, there are several lower-level functions that can help.
If you have a rotation matrix that expresses a rotation between two coordinate systems, you can multiply that matrix by a vector, such as velocity, or acceleration using DtDcmVecMul() in order to convert that vector between the coordinate systems.
For geocentric/topographic conversions, the needed rotation matrix can be obtained using DtLatLon_to_GeocToTopo() or DtLatLon_to_TopoToGeoc(), declared in topoCoord.h. These functions take a latitude and longitude and return rotation matrices to convert between the geocentric frame and the topographic frame defined by that point on earth.
For example:
You can also use a rotation matrix to rotate a set of Euler angles from one coordinate system to another, using the function DtEulerToEuler(), declared in Euler.h, for example:
But if your goal is to obtain an entity's orientation as topographic Euler angles (heading, pitch, and roll), a more efficient way would be:
Convert the result to Euler angles using DtBodyToRef_to_Euler() as follows:
Coordinate locations cannot be transformed using only a rotation matrix. The translational offset between the two coordinate systems is also required. To transform from one cartesian system to another:
For example, to transform a location from geocentric to a topographic coordinate:
[<< Orientation, Euler Angles, and DtTaitBryan] [Home] [Top of Page] [Creating Linked Lists with DtList >>]
