C++ API Users' Guide

1. Introduction
2. SRM Concepts
3. SRM Capability
4. Conversion Types
5. Typical Usages
6. Sample Application

Introduction

It is often necessary to represent position in several different spatial reference frames, simultaneously, according to the context in which the position is to be used. Each spatial reference frame corresponds to a particular way of expressing position. Spatial reference frames may be relative to moving objects (Examples: planets and spacecraft), and therefore have values that are a function of time. It is necessary to specify the time to which the spatial position refers, and the time for which the spatial reference frame is defined.

The Spatial Reference Model (SRM) defines the conceptual model and the methodologies that allow the description, and transformation or conversion, of geometric properties within or among spatial reference frames. The Spatial Reference Model (SRM) supports unambiguous specification of the positions, directions, distances, and times associated with spatial information. It also defines algorithms for precise transformation of positions, directions and distances among different spatial reference frames.

SRM Concepts

Spatial Reference Frame

A spatial reference frame template is the basis for realizing spatial reference frames that share the same CS, similar ORMs, and the same structure in the binding of CS parameter values. Spatial reference frames may be organized into specified sets so as to form an atlas for a large region of space. SRM specifies a collection of spatial reference frame templates (SRFTs), realizations of those templates (Standard SRFs), and sets of those realizations (SRFSs).

SRM defined the following SRF Templates:

1. Celestiocentric (CC)
2. Local Space Rectangular 3D (LSR_3D)
3. Celestiodetic (CD)
4. Planetodetic (PD)
5. Local Tangent Space Euclidean (LTSE)
6. Local Tangent Space Azimuthal Spherical (LTSAS)
7. Local Tangent Space Cylindrical (LTSC)
8. Celestiomagnetic (CM)
9. Equatorial Inertial (EI)
10. Solar Ecliptic (SEC)
11. Solar Equatorial (SEQ)
12. Solar Magnetic Ecliptic (SME)
13. Solar Magnetic Dipole (SMD)
14. Heliospheric Aries Ecliptic (HAEC)
15. Heliospheric Earth Ecliptic (HEEC)
16. Heliospheric Earth Equatorial (HEEQ)
17. Mercator (M)
18. Oblique Mercator Spherical (OMS)
19. Transverse Mercator (TM)
20. Lambert Conformal Conic (LCC)
21. Polar Stereographic (PS)
22. Equidistant Cylindrical (EC)
23. Local Space Rectangular 2D (LSR_2D)
24. Local Space Azimuthal (AZ)
25. Local Space Polar (Polar )

SRM defined the following SRF Sets:

1. Alabama State Plane Coordinate System (SPCS)
2. Geo Tile Reference System Global Coordinate System (GTRS GCS)
3. Japan Rectangular Plane CS
4. Lambert NTF
5. Universal Polar Stereographic (UPS)
6. Universal Transverse Mercator (UTM)
7. Wisconsin State Plane Coordinate System (SPCS)

SRM defined the following Standard SRFs:

1. British National Grid (BNG)
2. Delaware State Plane Coordinate System (SPCS) 1983
3. Geocentric Datum Australia 1994
4. Geocentric WGS 1984
5. Geodetic Australia 1984
6. Geodetic WGS 1984
7. Geodetic Europe 1950
8. Geodetic North America 1983
9. Geodetic WGS 1984
10. Irish Grid 1965
11. Irish Transverse Mercator 1989
12. Lambert 1993
13. Lambert II Wide
14. Mars Planetocentric 2000
15. Mars Planetographic 2000
16. Maryland State Plane Coordinate System (SPCS) 1983

Object Reference Model

Examples of ORMs are: World Geodesic System 1984 (WGS 1894), COAMPS, and Heliocentric Arieas Ecliptic.

H_SR

Reference Datum

Coordinate Systems

Coordinate

Examples of coordinates are: Celestiocentric 3D coordinate, Local Space Rectangular 2D coordinate, and Transverse Mercator surface coordinate.

SRM Capability

1. Instantiate and access
   1. SRFs
      1. SRF templates (e.g., LSR 3D, TM, Celestiodetic, Celestiocentric)
      2. SRF set members (e.g., UTM zone 12 Southern Hemisphere, GTRS cell 1234, UPS Northern Pole)
      3. Standard SRFs (e.g., British National Grid)
   2. Coordinates
      1. 2D coordinates
      2. 3D coordinates
      3. Surface coordinates
   3. Directions
   4. Orientations
2. Conversion
   1. Coordinate conversion between SRFs
   2. Direction conversion between SRFs
   3. Orientation conversion between SRFs
3. Validation
   1. Coordinate validation within a SRF
   2. Direction validation within a SRF
   3. Orientation validation within a SRF
4. Calculations
   1. Euclidean distance
   2. Geodesic distance
   3. Point scale
   4. Vertical separation offset
   5. Convergence of the Meridian
   6. Map azimuth
   7. Natural Extent (zone)
5. Abstract space coordinate instancing in a SRF

Conversion Types

1. Direct

   These are conversions that have an algorithm implemented between the source SRF and the target SRF. For instance, the coordinate conversion from a Celestiodetic SRF to a Celestiocentric SRF is a direct conversion. This type of conversion does not involve intermediate SRFs for its computation and thus they are most efficient.

2. Indirect (a.k.a."chained" or "transitive")

   These conversions are chains of direct conversions, converting first from the source SRF to intermediate SRFs, then to the target SRF. Consequently, these conversions typically take more time to be executed. For instance, the coordinate conversion from a Transverse Mercator SRF to a Celestiocentric SRF is an indirect conversion going through an intermediary conversion to Celestiodetic SRF.

3. Reflexive

   Reflexive conversions are the cases where the source and the target SRFs are of the same class. The trivial case of this type of conversion is when the source and the target SRFs have the exact same parameter values. In that case, the identity transformation is applied to the source coordinate. Another example, when converting from a CD SRF to another CD SRF with a different ORM/HSR pair, a datum shift is performed by converting the coordinate from the source CD SRF to an intermediate CC SRF, apply the datum shift, and then to the target CD SRF.

The chart below is provided as a reference to indicate which coordinate conversions are supported in SRM Version 4.0.0. Empty cells indicate conversion not supported in 4.0.0.

• D - directly supported conversion
• I - indirectly supported conversion
• R - reflexive conversion

Typical Usages

Convert a coordinate from one SRF to another

1. Instantiate the SRF to which the coordinate to be converted (source) is associated.
2. Instantiate the SRF to which the resulting converted coordinate (target) is associate.
3. Instantiate the source coordinate.
4. Instantiate the target coordinate with default values.
5. Compute the target coordinate.

The details on how to instantiate SRFs, instantiate coordinates and convert coordinates are as follows:

1. Instantiate a SRF

   There are three ways to instantiate SRFs depending whether they are instances of SRF Templates, SRF Sets, or standard SRFs. Once a SRF is instantiated, its parameter values cannot be changed:

   1. From a SRF Template:

      There are 25 SRF Template classes in SRM. These include SRF_Celestiodetic, SRF_Celestiocentric, SRF_LocalSpaceRectangular3D, and Transverse Mercator. Use their class constructors to instantiate these types of SRFs. For example, to instantiate a Celestiodetic SRF using the WGS 1984 ORM with the Identity HSR transformation:

      SRF_Celestiodetic* cd_srf = SRF_Celestiodetic.create
                                             ( SRM_ORM_WGS_1984,
                                               SRM_HSR_WGS_1984_IDENTITY );
                  

   2. From a SRF Set:

      There are 7 SRF Sets currently defined in SRM. These include Universal Transverse Mercator (UTM), Geo Tile Reference System (GRTS) Global Coordinate System (GCS), and Universal Polar Stereographic (UPS). Each of these SRF Sets are composed of a well-defined set of members. For example, UTM is composed of 120 members (zones) while GTRS GCS has 59,896 members (cell ids). Instances of these SRF Set members can be instantiated by invoking the static createSRFSetMember method in BaseSRF class. For example, to instantiate an instance of UTM zone 12 in North hemisphere using the WGS 1984 ORM with the Identity HSR transformation:

      SRF_TransverseMercator* utm12_srf = (SRF_TransverseMercator*)BaseSRF.createSRFSetMember
                                                ( SRM_SRFS_UNIVERSAL_TRANSVERSE_MERCATOR,
                                                  SRM_SSM_UTM_ZONE_12_NORTHERN_HEMISPHERE,
                                                  SRM_ORM_WGS_1984,
                                                  SRM_HSR_WGS_1984_IDENTITY );
                  

      The SRF template type for the Universal Transverse Mercator SRF is intrinsically Transverse Mercator. In other words, the instantiated UTM SRF is actually an instance of the Transverse Mercator SRF Template, and therefore, supports all the methods defined for that SRF Template. Likewise, for example, a GTRS GCS SRF is intrinsically an instance of the Local Tangent Space Euclidean SRF Template.

   3. From a Standard SRF:

      There are 15 Standard SRFs currently defined in SRM. These include British National Grid (BNG), Irish Grid, and the Maryland State Plane Coordinate System (SPCS). Instances of these Standard SRFs can be instantiated by invoking the static createStandardSRF() method in the BaseSRF class using the proper SRF code. For example, to instantiate an instance of BNG:

      SRF_TransverseMercator* bng_stf = (SRF_TransverseMercator*)BaseSRF.createStandardSRF
                                                                    ( SRM_SRF_BRITISH_NATIONAL_GRID );
                  

      The SRF template type for the British National Grid SRF is intrinsically Transverse Mercator. In other words, the instantiated BNG SRF is actually an instance of the Transverse Mercator SRF Template, and therefore, supports all the methods defined for that SRF Template. Likewise, for example, a Maryland SPCS SRF is intrinsically an instance of the Lambert Conformal Conic SRF Template.

      There are no SRF parameter arguments for the creation of Standard SRFs because these SRFs have all their parameters pre-defined.

2. Instantiate a Coordinate

   Each SRF Template has its specific coordinates defined. The coordinates are only valid when associated with a specific SRF. Depending on the SRF instantiated, 2D, 3D or surface coordinates can be instantiated from it. There are mainly two way to instantiate coordinates:

   1. Using methods in SRF:

      A SRF instance can instantiate a coordinate associated with the SRF using the createCoordinateXX() method, where "XX" can be "2D", "3D", and "Surf" depending on the STF. For example, to instantiate a 3D coordinate for a Celestiodetic SRF:

      Coord3D_Celestiodetic* cd_3d_coord 
                         = (Coord3D_Celestiodetic*)cd_srf.createCoordinate3D( 0.8987, 0.5645, 1000.0 );
                   

      Another example to instantiate a UTM surface coordinate for a UTM SRF:

      CoordSurf_TransverseMercator utm12_surf_coord 
                         = (CoordSurf_TransverseMercator*)utm12_srf.createSurfaceCoordinate( 550.0, 320.0 );
                   

      Notice that the instantiate UTM SRF is intrinsically a TM SRF, and therefore, supports the createCoordinate3D method defined in the TM SRF Template class. Consequently, the surface coordinate instantiated by the UTM SRF is of CoordSurf_TransverseMercator class.

   2. Using the coordinate class constructors

      Each coordinate class takes in its constructor a SRF parameters to which the coordinate is associated. For example, to instantiate a 3D coordinate for a Celestiodetic SRF.:

      Coord3D_Celestiodetic cd_3d_coord 
                         = Coord3D_Celestiodetic( cd_srf, 0.17865, 0.01234, 1000.0 ));
                   

      To instantiate a UTM surface coordinate for a UTM SRF:

                   
      CoordSurf_TransverseMercator utm_surf_coord 
                         = CoordSurf_TransverseMercator( utm12_srf, 500.0, 500.0, 1000.0 );
                   

3. Convert a source coordinate from a source SRF to a target SRF

   Having instantiated the source and target SRFs and coordinates, invoke the changeCoordinateSRF() method of the target SRF to calculate the target coordinate and the Valid Region. For example, to convert a Celestiodetic 3D coordinate to a Transverse Mercator SRF:

   SRM_Coordinate_Valid_Region validRegion;
   Coord3D_TransverseMercator* utm12_3d_coord( utm12_srf ); // coordinate with default values
   validRegion = utm12_srf.changeCoordinateSRF( cd_3d_coord, utm12_3d_coord );
            

   In this example, the 3D Celestiodetic coordinate is converted to a UTM SRF. The validRegion indicates where the resulting UTM coordinate is within the valid, extended or defined regions.

Convert a direction from one SRF to another

1. Instantiate a SRF (same as above).
2. Instantiate a reference location coordinate (same as above). The restriction is that this coordinate must be a 3D coordinate.
3. Instantiate a Direction

   A Direction object can be instantiated using the createDirection() method in any subclass of BaseSRF_3D. For example, to instantiate a Direction using a Celestiodetic 3D coordinate "cd_ref_location" associated with and a direction vector (1.0, 2.0, 3.0):

   SRM_Long_Float vector[3] = { 1.0, 2.0, 3.0 };
   Direction* cd_dir = cd_srf.createDirection( cd_ref_location, vector );
           

   The Celectiodetic SRF "cd_srf" must be the same one used to instantiate both the reference location "cd_ref_location" and the direction object "cd_dir".

4. Convert a source Direction from the source SRF to a target SRF

   Having instantiated the source and target SRFs and Directions, invoke the changeDirectionSRF() method of the target SRF to calculate the target direction and the Valid Region. For example, to convert the Celestiodetic direction to a Transverse Mercator SRF "tm_srf":

   SRM_Coordinate_Valid_Region validRegion;
   validRegion = tm_srf.changeDirectionSRF( cd_dir, tm_dir);
            

   In converting a Direction, both its reference location and the vector are converted to the target SRF. The valid region is associated with the resulting reference location.

Convert an orientation from one SRF to another

1. Instantiate a SRF (same as above).
2. Instantiate a reference location coordinate (same as above). The restriction is that this coordinate must be a 3D coordinate.
3. Instantiate an orientation

   An Orientation object can be instantiated using the createOrientation() method in any subclass of BaseSRF_3D. For example, to instantiate a Direction using a Celestiodetic 3D coordinate "cd_ref_location" associated with and an identity matrix:

   SRM_Long_Float ident_mat[3][3] = { {1.0, 0.0, 0.0}, {0.0, 1.0, 0.0}, {0.0, 0.0, 1.0} };
   Orientation* cd_ori = cd_srf.createOrientation( cd_ref_location, ident_mat );
           

   The Celestiodetic SRF "cd_srf" must be the same one used to instantiate both the reference location "cd_ref_location" and the direction object "cd_ori".

4. Convert a source orientation from the source SRF to a target SRF

   Having instantiated the source SRF and orientation and the target SRF, invoke the changeOrientationSRF() method of the target SRF to calculate the target orientation and the Valid Region. For example, to convert the Celestiodetic orientation to a Transverse Mercator SRF "tm_srf":

   SRM_Coordinate_Valid_Region validRegion;
   validRegion = tm_srf.changeOrientationSRF( cd_ori, tm_ori);
            

   The conversion of Orientation, both its reference location and the matrix (three row vectors) are converted to the target SRF. The valid region is associated with the the resulting reference location.

Sample Application

#include "BaseSRF.h"
#include "srf_all.h"
#include "Exception.h"
#include 

using namespace std;

int main (int argc, char* argv[])
{
  cout << "Running SRM Sample test program... \n" << endl;
  
  srm::SRF_Celestiocentric* CC_SRF;
  srm::SRF_Celestiodetic* CD_SRF;

  try {
    // create CC and CD SRFs
    CC_SRF = srm::SRF_Celestiocentric::create( SRM_ORM_WGS_1984, SRM_HSR_WGS_1984_IDENTITY );
    
    CD_SRF = srm::SRF_Celestiodetic::create( SRM_ORM_WGS_1984, SRM_HSR_WGS_1984_IDENTITY );
    
    cout << "Source Celestiodetic SRF parameters: " << endl;
    cout << CD_SRF->toString() << endl;
    cout << "Target Celestiocentric SRF parameters: " << endl;
    cout << CC_SRF->toString() << endl;
  } catch ( srm::Exception( ex) ) {
    cout << "Caught an exception=> " << ex.getWhat() << endl;
    return 0;
  }

  // create CD and CC 3D coordinate
  srm::Coord3D_Celestiodetic CD_Coord( CD_SRF, 0.0, 0.785398163397, 0.0 );
  srm::Coord3D_Celestiocentric CC_Coord( CC_SRF );

  // Convert from CD SRF to CC SRF
  try { 
    CC_SRF->changeCoordinate3DSRF( CD_Coord, CC_Coord );
    
    cout << "Executed changeCoordinate3DSRF" << endl;    
  } 
  catch ( srm::Exception& ex) {
    cout << "Caught an exception=> " << ex.getWhat() << endl;
    return 0;
  }

  // Print Celestiocentric coordinate values
  cout << "Source Celestiodetic 3D coordinate: "
       << "[ " << CD_Coord.get_longitude() << ", " << CD_Coord.get_latitude() 
       << ", " << CD_Coord.get_ellipsoidal_height() << " ]" << endl;
  cout << "Target (converted) Celestiocentric 3D coordinate: "
       << "[ " << CC_Coord.get_u() << ", " << CC_Coord.get_v() 
       << ", " << CC_Coord.get_w() << " ]" << endl << endl;

  // Free SRFs
  CC_SRF->release();
  cout << "Released CC SRF" << endl;
  CD_SRF->release();
  cout << "Released CD SRF" << endl;

  return 0;
}

Running SRM Sample test program... 

Source Celestiodetic SRF parameters: 
orm=> 274
hsr=> 1

Target Celestiocentric SRF parameters:
orm=> 274
hsr=> 1

Executed changeCoordinate3DSRF
Source Celestiodetic 3D coordinate: [ 0, 0.785398, 0 ]
Target (converted) Celestiocentric 3D coordinate: [ 4.51759e+06, 0, 4.48735e+06 ]

Released CC SRF
Released CD SRF

Return to: Top

Copyright © 2004 SEDRIS™