C API Users' Guide

SRM SDK Release 4.1.3

December 7, 2009

Introduction
SRM Concepts
SRM Capability
Conversion Types
Typical Usages
Sample Application

Introduction

Spatial information processing requires a robust capability to describe geometric properties such as position, direction and distance. Information may be spatially referenced to local structures (Example: building interiors) and regions (Example: cities), or spatially referenced to the Earth as a whole (Example: global weather). Information may be spatially referenced to other celestial bodies (Examples: astronomical, orbital, and geomagnetic observations). Information may also be spatially referenced to objects defined within contexts such as virtual realities (Example: 3D models). In each of these cases, a spatial reference frame is defined, with respect to which the values of geometric properties may be determined.

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 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

The SRM provides an integrated framework and precise terminology for describing spatial concepts and operations on spatial information (including positions, directions, and distances):

Spatial positions are identified by coordinates in a spatial coordinate system. The collection of spatial positions associated with a spatial object of interest, such as the Earth, is called its object-space.
A spatial reference frame specifies a spatial coordinate system by combining an abstract coordinate system with an object reference model. An abstract coordinate system may be combined with many different object reference models. Thus, a geodetic coordinate tied to the Earth object reference model WGS_1984 does not identify the same place as when tied to the Earth object reference model EUROPEAN_1950, or when tied to an object reference model for Mars.
An abstract coordinate system associates coordinates with positions in an abstract Euclidean space, which is called its position-space. Abstract coordinate systems are defined independently of any object-space. There are many spatial spherical coordinate systems for a given object-space, but there is only one abstract spherical coordinate system for a position-space.
An object reference model determines a precise relationship between position-space and the object-space for a spatial object of interest. Different object reference models for the Earth relate position-space to the object-space of the Earth in different ways. Thus, the object reference model WGS_1984 relates the position-space x-axis to the direction from the Earth's center of mass towards the intersection of the Greenwich meridian with the equator, while the object reference model EARTH_INERTIAL_J2000r0 relates the position-space x-axis to the direction from the Earth's center of mass towards the first point of Aries (see 4.5 and Clause 7).
The position-space to object-space relationship determined by an object reference model is expressed mathematically by a length-preserving embedding function called a normal embedding.
A reference datum is a geometric primitive that relates measurements and/or geometric characteristics of object-space to position-space. Object reference models use reference datums to specify the position-space to object-space relationship. An object reference model may also use reference datums to model a geometric aspect of a spatial object. Thus, an oblate ellipsoid reference datum may be used to model the figure of the Earth or other celestial bodies.
Temporal coordinate systems are introduced to describe the time-varying characteristics of spatial reference frames.
Vertical offset surfaces are introduced to define heights with respect to equipotential or other complex surfaces. In particular, the vertical offset surface EGM96_GEOID represents the geopotential surface defined by the WGS 84 EGM 96 Earth Gravitational Model that is closely associated with the mean ocean surface.

The relationships among some of these concepts are depicted in the following figure. An abstract coordinate system is based on the underlying Euclidean structure of position-space. The reference datums that comprise the object reference model determine how position-space relates to object-space. That relationship is mathematically expressed by a normal embedding. A spatial reference frame combines the abstract coordinate system with the object reference model to specify a spatial coordinate system. This allows positions to be expressed relative to a spatial object of interest, such as the Earth.

Spatial Reference Frame

A spatial coordinate system is a means of associating a unique coordinate with a point in object-space. It is defined by binding an abstract Coordinate System (CS) to a normal embedding. A spatial reference frame is a specification of a spatial coordinate system for a region of object-space. It is formed by the binding of an abstract coordinate system to the normal embedding specified by an Object Reference Model (ORM) for that object. A full specification specifies the CS and the ORM and includes values for CS parameters, if any, and a specification of the region of object-space. Some or all CS parameters may be bound by ORM parameters. In particular, a CS based on an oblate ellipsoid (or sphere) must match the parameters of the oblate ellipsoid (or sphere) Rerefence Datum of the ORM.

A spatial reference frame template is an abstraction of a collection of spatial reference frames that share the same abstract coordinate system, coordinate system parameter binding rules, and similar ORMs that model the same spatial object type. Spatial reference frames may be organized into specified sets so as to form an atlas for a large region of space. The SRM specifies a collection of spatial reference frame templates, realizations of those templates, and sets of those realizations.

SRM defined the following SRF Templates (SRFT):

Celestiocentric (CC)
Local Space Rectangular 3D (LSR_3D)
Celestiodetic (CD)
Planetodetic (PD)
Local Tangent Space Euclidean (LTSE)
Local Tangent Space Azimuthal Spherical (LTSAS)
Local Tangent Space Cylindrical (LTSC)
Lococentric Euclidean 3D (LCE_3D)
Celestiomagnetic (CM)
Equatorial Inertial (EI)
Solar Ecliptic (SEC)
Solar Equatorial (SEQ)
Solar Magnetic Ecliptic (SME)
Solar Magnetic Dipole (SMD)
Heliospheric Aries Ecliptic (HAEC)
Heliospheric Earth Ecliptic (HEEC)
Heliospheric Earth Equatorial (HEEQ)
Mercator (M)
Oblique Mercator Spherical (OMS)
Transverse Mercator (TM)
Lambert Conformal Conic (LCC)
Polar Stereographic (PS)
Equidistant Cylindrical (EC)
Local Space Rectangular 2D (LSR_2D)
Local Space Azimuthal LSA)
Local Space Polar (LSP)

SRM defined the following SRF Sets and their intrinsic SRF template types:

Alabama State Plane Coordinate System (SPCS) - TM
Geo-Tile Reference System Global Coordinate System (GTRS GCS) - LTSE
Japan Rectangular Plane CS - TM
Lambert NTF - LCC
Universal Polar Stereographic (UPS) - PS
Universal Transverse Mercator (UTM) - TM
Wisconsin State Plane Coordinate System (SPCS) - LCC

SRM defined the following Standard SRFs and their intrinsic SRF template types:

British National Grid (BNG) - TM
British OSGRS80 Grid - TM
Delaware State Plane Coordinate System (SPCS) 1983 - TM
Geocentric WGS 1984 - CC
Geodetic Australia 1984 - CD
Geodetic WGS 1984 - CD
Geodetic North America 1983 - CD
Irish Grid 1965 - TM
Irish Transverse Mercator 1989 - TM
Lambert 1993 - LCC
Lambert II Wide - LCC
Mars Planetocentric 2000 - CD
Mars Planetographic 2000 - PD
Maryland State Plane Coordinate System (SPCS) 1983 - LCC

Reference Datum (RD)

A reference datum is a geometric primitive in position-space. Reference datums are points or directed curves in 2D position-space or points, directed curves or oriented surfaces in 3D position-space.

A reference datum is bound when the reference datum in position-space is identified with a corresponding constructed entity (i.e., a measured or conceptual geometric aspect of a spatial object) in object-space. The term "corresponding" in this context means that each position-space reference datum is bound to a constructed geometric entity of the same geometric object type. That is, position-space points are bound to object-space points, position-space lines to object-space lines, position-space curves to object-space curves, position-space planes to object-space planes, and position-space surfaces to object-space surfaces.

Object Reference Model (ORM)

A set of bound Reference Datums can be selected so as to be compatible with only one normal embedding. In this way, a set of bound RDs with properly constrained relationships can specify a unique normal embedding. Such a constrained set of bound RDs is called an object reference model.

An object reference model (ORM) for a spatial object is a set of bound RDs for which there exists exactly one normal embedding that is compatible with each bound RD in the set. In the 3D case, this unique embedding shall also be right-handed.

An ORM is object-fixed if each of its RD bindings are object-fixed, otherwise it is called object-dynamic. The object-fixed definition assumes that the object itself is not changing in time by an amount significant for the accuracy and time scale of an application. The normal embedding determined by an ORM is, correspondingly, either an object-fixed embedding or an object-dynamic embedding.

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

Reference Transformation (RT)

A reference transformation (RT) for an ORM is a similarity transformation from the ORM normal embedding to the normal embedding of the reference ORM for that object, ORM_R. The reference transformation for an ORM, ORM_S, shall be denoted by H_SR.

For 3D ORMs, a reference transformation shall be specified by the seven parameters of the corresponding seven-parameter embedding specification. For 2D ORMs, a reference transformation shall be specified by the four parameters of the corresponding four-parameter embedding specification.

For a list of supported reference tranformations for each ORM see the ORM-RT Relationship Table. Notice that the leading part of the RT names is the name of the ORM with which they are associated.

Coordinate System

An abstract coordinate system is a means of identifying positions in position-space by coordinate n-tuples. An abstract coordinate system is completely defined in terms of the mathematical structure of position-space. In SRM, the term "coordinate system" is defined to mean "abstract coordinate system".

A temporal coordinate system is defined as a means of identifying events in the time continuum by coordinate 1-tuples using an abstract coordinate system of coordinate system type 1D. A spatial coordinate system is defined as an abstract coordinate system suitably combined with a normal embedding as a means of identifying points in object-space by coordinate n-tuples.

Coordinate

A coordinate is an element of the coordinate system domain. In particular, if the domain is a subset of 3D Euclidean space (R3), each coordinate is called a 3D coordinate. If the domain is a subset of 2D Euclidean space (R2), each coordinate is called a 2D coordinate. Surface coordinates are defined as the projection of the 3D coordinate onto the surface of an RD.

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

SRM Capability

The SRM API supports the following functionality:

Instantiation and access
1. SRFs
  1. SRF templates (e.g., LSR 3D, TM, Celestiodetic, Celestiocentric)
  2. SRF set members (e.g., UTM zone 12 Northern 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
Conversion
1. Coordinate conversion between SRFs
2. Direction conversion between SRFs
3. Orientation conversion between SRFs
Validation
1. Coordinate validation within a SRF
2. Direction validation within a SRF
3. Orientation validation within a SRF
Calculation
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)

Note that SRM 4.1 release only supports the EGM_96 Geoid and WGS_84 Ellipsoid DSS codes for the Vertical Separation Offset calculation. See the Release Notes for additional information.

Conversion Types

There are three types of coordinate conversions:

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.
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.
Reflexive
Reflexive conversions are the cases where the source and the target SRFs are of the same type. 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, to convert from a CD SRF to another CD SRF with a different ORM/RT pair. In that case, 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 type of conversions applied to the coordinates is transparent to the users. The users can invoke the SRM_ChangeCoordinateSRF() method, regardless of whether the conversion is direct, indirect, or reflexive. The API will perform the conversion in a most efficient way. If a conversion is not supported between the two given SRFs, then the call to SRM_ChangeCoordinateSRF() will return the proper status code.

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

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

	LSA	CC	CD	CM	EC	EI	HAEC	HEEC	HEEQ	LCC	LCE_3D	LSR_2D	LSR_3	LTSAS	LTSC	LTSE	M	OM	PD	LSP	PS	SEC	SEQ	SME	SMD	TM
LSA	R	.	.	.	.	.	.	.	.	.		D .	.	.	.	.	.	.	.	.I	.	.	.	.	.	.
CC	.	R	D	D	I	D	D	D	D	I	D	.	.	I	I	D	I	I	I	.	I	.D	. D	. D	D	I
CD	.	D	R	.I	D	I	I	I	I	D	I.	.	.	I	I	I	D	D	D	.	D	.I	I .	. I	I	D
CM	.	D	I	.R	I	I	I.	.I	I.	I.	I.	.	.	I	I	I.	.I	I.	I.	.	I	I	I.	.I	I.	I.
EC	.	I	D	I	R	I	I	I	I	I	I	.	.	I	I	I	I	I	I	.	I	.I	I .	. I	I	I
EI	.	D	I	I	I	R	I	.I	I.	.I.	.I.	.	.	I	I	I.	.I	I.	I.	.	I	I	I.	.I	I.	I.
HAEC	.	D	I	I	I	.I	R	.I	I.	I	I	.	.	I	I	I	I	I	I	.	I	.I	I .	. I	I	I
HEEC	.	D	I	I	I	.I	.I	R	. I.	I	I	.	.	I	I	I	I	I	I	.	I	.I	I .	. I	I	I
HEEQ	.	D	I	I	I	.I	.I	I.	R	I	I	.	.	I	I	I	I	I	I	.	I	.I	I .	. I	I	I
LCC	.	I	D	I	I	.I	I	I	I	R	I.	.	.	I	I	I	I	I	I	.	I	.I	I .	. I	I	I
LCE_3D		D	I	I	.I	I	I	I	I	I	R			I	I	I	I	I	I		I	I	I	I	I	I
LSR_2D	.D	.	.	.	.	.	.	.	.	.		R	.	.	.	.	.	.	.	. D	.	.	.	.	.	.
LSR_3D	.	.	.	.	.	.	.	.	.	.		.	R	.	.	.	.	.	.	.	.	.	.	.	.	.
LTSAS	.	I	I	I	I	I.	I	I	I	I	I	.	.	R	I	D	I	I	I	.	I	.I	I .	. I	I	I
LTSC	.	I	I	I	I	.I	I	I	I	I	I	.	.	I	R	D	I	I	I	.	I	.I	I .	. I	I	I
LTSE	.	D	I	I	I	. I	I	I	I	I	I	.	.	D	D	R	I	I	I	.	I	.I	I .	. I	I	I
M	.	I	D	I	I	. I	I	I	I	I	I	.	.	I	I	I	R	I	I	.	I	.I	I .	. I	I	I
OM	.	I	D	I	I	. I	I	I	I	I	I	.	.	I	I	I	I	R	I	.	I	.I	I .	. I	I	I
PD	.	I	D	I	I	. I	I	I	I	I	I	.	.	I	I	I	I	I	R	.	I	.I	I .	. I	I	I
LSP	. I	.	.	.	.	.	.	.	.	.	.	. D .	.	.	.	.	.	.	.	.R	.	.	.	.	.	.
PS	.	I	D	I	I	. I	I	I	I	I	I	.	.	I	I	I	I	I	I	.	R	.I	I .	. I	I	I
SEC	.	D	I	I	I	. I	I.	. I	I.	I.	I.	.	.	I	I	I	I	I	I	.	I	. R	. I	. I	. I	I .
SEQ	.	D.	I .	I	I	. I	I	. I	I.	I.	I.	.	.	I	I	I	I	I	I	.	I	I	. R	. I	I .	I
SME	.	D	I	I	I	. I	.I	. I	I.	I.	I.	.	.	I	I	I	I	I	I	.	I	. I	. I	. R	I	I
SMD	.	D	I .	I	I	. I	.I	. I	I.	I.	I.	.	.	I	I	I	I	I	I	.	I	. I	. I	I .	. R	.I
TM	.	I	D	I	I	. I	I	I	I	I	I	.	.	I	I	I	I	I	I	.	I	. I	I	I	.I	R

Typical Usages

A few typical API usages are described in this section

Convert a coordinate from one SRF to another

In order to convert a coordinate from one SRF to another, the user has to:

Allocate the SRF to which the coordinate to be converted is associated (source).
Allocate the SRF to which the resulting converted coordinate is associate (target).
Allocate the source coordinate.
Allocate the target coordinate with default values.
Compute the target coordinate.

The users should re-use the allocated SRFs for the coordinate conversions to minimize the one-time initialization cost. The source and target coordinates must be both 2D, 3D, or surface.

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

Allocate a SRF
There are three ways to allocate SRFs depending whether they are instances of SRF Templates, SRF Sets, or standard SRFs. Once a SRF is allocated, its parameter values cannot be changed:
1. Allocate a SRF Template:
  There are 26 SRF Template types in SRM. These include SRF_Celestiodetic, SRF_Celestiocentric, SRF_LocalSpaceRectangular3D, and Transverse Mercator. Use specific SRM_<SRFT>_Create functions to allocate these types of SRF. For example, to allocate a Celestiodetic SRF using the WGS 1984 ORM with the Identity reference transformation:
```
SRM_Status_Code status;
SRM_Celestiodetic cd_srf;
status = SRM_CD_Create( SRM_ORMCOD_WGS_1984,
                        SRM_RTCOD_WGS_1984_IDENTITY,
                        &cd_srf );
	
```
2. Allocate a SRF Set member:
  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). These SRF Set members can be allocated by invoking the SRM_CreateSRFSetMember function with proper SRM SET Code and member code. For example, to allocate an UTM member zone 12 in North hemisphere using the WGS 1984 ORM with the Identity reference transformation:
```
SRM_Status_Code status;
SRM_Object_Reference utm12_srf;
status = SRM_CreateSRFSetMember( SRM_SRFSCOD_UNIVERSAL_TRANSVERSE_MERCATOR,
                                 SRM_SRFSMUTMCOD_ZONE_12_NORTHERN_HEMISPHERE,
                                 SRM_ORMCOD_WGS_1984,
                                 SRM_RTCOD_WGS_1984_IDENTITY,
                                 &utm12_srf );
            
```
  The SRF template type for the Universal Transverse Mercator SRF is intrinsically Transverse Mercator. In other words, the allocated UTM SRF is an instance of the Transverse Mercator SRF Template, and therefore, supports all the function applicable to that SRF Template. Likewise, for example, a GTRS GCS SRF is intrinsically an instance of the Local Tangent Space Euclidean SRF Template.
3. Allocate a Standard SRF:
  There are 14 Standard SRFs currently defined in SRM. These include British National Grid Airy (BNG), Irish Grid, and the Maryland State Plane Coordinate System (SPCS). Instances of these Standard SRFs can be allocated by invoking the SRM_CreateStandardSRF() function using the proper SRF code. For example, to allocate an instance of BNG:
```
SRM_Status_Code status;
SRM_Object_Reference bng_srf;
status = SRM_CreateStandardSRF( SRM_SRFCOD_BRITISH_NATIONAL_GRID_AIRY,
                                SRM_RTCOD_OSGB_1936_ENGLAND,
                                &bng_srf );
            
```
  The SRF template type for the British National Grid SRF is intrinsically Transverse Mercator. In other words, the allocated BNG SRF is an instance of the Transverse Mercator SRF Template, and therefore, supports all the functions applicable to that SRF Template. Likewise, for example, a Maryland SPCS SRF is intrinsically an instance of the Lambert Conformal Conic SRF Template.
  The ORM parameter is pre-defined for each standard SRF. Users can only specify the reference transformation parameter that are applicable to that particular ORM. The pre-specified ORMs for the standard SRFs are as follows:
  1. British National Grid (BNG) ==> SRM_ORMCOD_OSGB_1936
  2. British OSGRS80 Grid ==> SRM_ORMCOD_ETRS_1989
  3. Delaware State Plane Coordinate System (SPCS) 1983 ==> SRM_ORMCOD_N_AM_1983
  4. Geocentric WGS 1984 ==> SRM_ORMCOD_WGS_1984
  5. Geodetic Australia 1984 ==> SRM_ORMCOD_AUSTRALIAN_GEOD_1984
  6. Geodetic WGS 1984 ==> SRM_ORMCOD_WGS_1984
  7. Geodetic North America 1983 ==> SRM_ORMCOD_N_AM_1983
  8. Irish Grid 1965 ==> SRM_ORMCOD_IRELAND_1965
  9. Irish Transverse Mercator 1989 ==> SRM_ORMCOD_ETRS_1989
  10. Lambert 1993 ==> SRM_ORMCOD_RGF_1993
  11. Lambert II Wide ==> SRM_ORMCOD_NTF_1896_PM_PARIS
  12. Mars Planetocentric 2000 ==> SRM_ORMCOD_MARS_SPHERE_2000
  13. Mars Planetographic 2000 ==> SRM_ORMCOD_MARS_2000
  14. Maryland State Plane Coordinate System (SPCS) 1983 ==> SRM_ORMCOD_N_AM_1983

Allocate a Coordinate

Each SRF Template has its specific coordinates defined. The coordinates is only valid when associated with a specific SRF. Depending on the SRF allocated, 2D, 3D or surface coordinates can be associated with it:

For example, to allocate a 3D coordinate for a Celestiodetic SRF:

SRM_Status_Code status;
SRM_Coordinate3D cd_3d_coord;
SRM_Long_Float longitude = 0.5645;
SRM_Long_Float latitude = 0.8987;
SRM_Long_Float ellipsoidal_height = 1000.0;
status = cd_srf.methods->CrateCoordinate3D( &cd_srf,
                                            longitude, latitude, ellipsoidal_height,
                                            &cd_3d_coord );

Another example, to allocate a UTM surface coordinate for a UTM SRF:

SRM_Status_Code status;
SRM_Coordinate3D utm12_3d_coord;
SRM_Long_Float easting = 500000.0;
SRM_Long_Float northing = 0.0;
SRM_Long_Float ellipsoidal_height = 1000.0;
status = utm12_srf->methods->CreateCoordinate3D( utm12_srf,
                                                 easting, northing, ellipsoidal_height,
                                                 &utm_3d_coord );

Notice that the utm12_srf is an object reference to the actual Transverse Mercator SRF. This assumes that it was instantiated using the CreateSRFSetMember() function.

Convert a source coordinate from a source SRF to a target SRF
Having allocated the source SRF, the source coordinate, the target SRF, and the target coordinate, invoke the SRM_ChangeCoordinateSRF() to calculate the target coordinate and the Valid Region. For example, to convert a Celestiodetic 3D coordinate to a Transverse Mercator SRF:
```
SRM_Status_Code status;
SRM_Coordinate_Valid_Region valid_region;
status = cd_srf.methods->ChangeCoordinate3DSRF( &cd_srf,
                                                utm12_srf,
                                                &utm12_3d_coord,
                                                &cd_3d_coord,
                                                &valid_region );
         
```
Notice that the utm12_srf is an object reference to the actual Transverse Mercator SRF. This assumes that it was instantiated using the CreateSRFSetMember() function.

Convert a direction from one SRF to another

The steps to convert a direction (source direction) from its original SRF (source SRF) to another SRF (target SRF) resulting in the final direction (target direction) is similar to converting a coordinate as follows:

Allocate a SRF (same as above).
Allocate a reference location coordinate (same as above). The restriction is that this coordinate must be a 3D coordinate.
Allocate a Direction
A Direction object can be allocated using the CreateDirection() method. For example, to allocate a Direction using a Celestiodetic 3D coordinate "cd_ref_location" associated with and a direction vector (0.0, 0.0, 1.0):
```
SRM_Status_Code status;
SRM_Direction cd_dir;
status = cd_srf.methods->CreateDirection( cd_srf,
                                          cd_ref_location,
                                          0.0, 0.0, 1.0,
                                          &cd_dir );
```
The Celectiodetic SRF "cd_srf" is the SRF associated with the reference location "cd_ref_location".
Convert a source Direction from the source SRF to a target SRF
Having allocated the source and target SRFs and Directions, invoke the ChangeDirectionSRF() method to calculate the target direction and the Valid Region. For example, to convert the Celestiodetic direction to a Transverse Mercator SRF "tm_srf":
```
SRM_Status_Code status;
status = tm_srf.methods->ChangeDirectionSRF( &tm_srf,
                                             &cd_srf,
                                             &cd_dir,
                                             &tm_dir,
                                             &valid_region );
         
```
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

The steps to convert a orientation (source orientation) from its original SRF (source SRF) to another SRF (target SRF) resulting in the final orientation (target direction) is similar to converting a direction as follows:

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

Allocate an orientation

An Orientation object can be allocated using the CreateOrientation() method. For example, to allocate a Direction using a Celestiodetic 3D coordinate "cd_ref_location" associated with and an identity matrix:

SRM_Status_Code status;
SRM_Orientation cd_ori;
SRM_Matrix_3x3 ident_mat = { {1.0, 0.0, 0.0},
                             {0.0, 1.0, 0.0},
                             {0.0, 0.0, 1.0} };
status = cd_srf.methods->CreateOrientation( &cd_srf,
                                            &cd_ref_location,
                                            ident_mat,
                                            &cd_ori );

The Celestiodetic SRF "cd_srf" is the SRF associated with the reference location "cd_ref_location".

Convert a source orientation from the source SRF to a target SRF
Having allocated the source and target SRFs and orientations, invoke the ChangeOrientationSRF() method to calculate the target orientation and the Valid Region. For example, to convert the Celestiodetic orientation to a Transverse Mercator SRF "tm_srf":
```
SRM_Status_Code status;
status = tm_srf.methods->ChangeOrientationSRF( &tm_srf,
                                               &cd_srf,
                                               &cd_ori,
                                               &tm_ori,
                                               &valid_region);
         
```
In converting an Orientation, both its reference location and the orientation matrix are converted to the target SRF. The valid region is associated with the resulting reference location.

Sample Application

The following sample code converts a series of 3D coordinates from a Celestiodetic SRF to a Celestiocentric SRF using the SRM C API:

#include <stdio.h>
#include <string.h>

#include "srm.h"

#define SRM_PI_DEFINE 3.14159265358979323846

#define SRM_PI_DIV_2  1.57079632679489661923

/*
 * FUNCTION: local_ConvertFromCDToCC
 */
static int
local_ConvertFromCDToCC
(
    SRM_Celestiodetic   *cd_srf_ptr,
    SRM_Celestiocentric *cc_srf_ptr,
    SRM_Coordinate3D    *cd_coord_ptr,
    SRM_Coordinate3D    *cc_coord_ptr,
    SRM_Long_Float       src_ord1,
    SRM_Long_Float       src_ord2,
    SRM_Long_Float       src_ord3
)
{
    int                         status = 0;
    SRM_Coordinate_Valid_Region val_region;

    SRM_Long_Float tgt_ord1 = 0.0, tgt_ord2 = 0.0, tgt_ord3 = 0.0;

    if (cc_srf_ptr->methods->ChangeCoordinate3DSRF(cc_srf_ptr, cd_srf_ptr,
        cd_coord_ptr, cc_coord_ptr, &val_region) != SRM_STATCOD_SUCCESS)
    {
        status = -1;
        fprintf(stderr, "SRM_ChangeCoordinateSRF failed\n");
    }
    else if (cc_srf_ptr->methods->GetCoordinate3DValues(cc_srf_ptr,
             cc_coord_ptr, &tgt_ord1, &tgt_ord2, &tgt_ord3)
             != SRM_STATCOD_SUCCESS)
    {
        status = -1;
        fprintf(stderr,
                "Failed getting the CC coordinate values\n");
    }
    else
    {
        printf("Source (converted) "\
               "Celestiodetic 3D coordinate: "\
               "[ %lf, %lf, %lf ]\n\n",
               src_ord1, src_ord2, src_ord3);

        printf("Target (converted) "\
               "Celestiocentric 3D coordinate: "\
               "[ %lf, %lf, %lf ]\n\n",
               tgt_ord1, tgt_ord2, tgt_ord3);
    }
    return status;
} /* end local_ConvertFromCDToCC */


/*
 * FUNCTION: main
 */
int main
(
    int   argc,
    char* argv[]
)
{
    SRM_Celestiocentric cc_srf;
    SRM_Celestiodetic   cd_srf;
    SRM_Coordinate3D    cc_coord;
    SRM_Coordinate3D    cd_coord;
    SRM_Long_Float      src_ord1, src_ord2, src_ord3;
    SRM_ORM_Code        src_orm = SRM_ORMCOD_WGS_1984,
                        tgt_orm = SRM_ORMCOD_WGS_1984;
    SRM_RT_Code         src_rt  = SRM_RTCOD_WGS_1984_IDENTITY,
                        tgt_rt  = SRM_RTCOD_WGS_1984_IDENTITY;

    src_ord1 = 0.0;
    src_ord2 = 0.785398163397;
    src_ord3 = 0.0;

    printf("Running SRM Sample test program...\n");

    if (SRM_CD_Create(src_orm,
                      src_rt,
                      &cd_srf) != SRM_STATCOD_SUCCESS)
    {
        fprintf(stderr, "Failed to create CD SRF\n");
    }
    else
    {
        if (SRM_CC_Create(tgt_orm,
                          tgt_rt,
                          &cc_srf) != SRM_STATCOD_SUCCESS)
        {
            fprintf(stderr, "Failed to create CC SRF\n");
        }
        else
        {
            printf("Source Celestiodetic SRF parameters :\n"\
                   "orm = %s\n"\
                   "rt  = %s\n",
                   SRM_PrintORMCode(src_orm), SRM_PrintRTCode(src_rt));
            fflush(stdout);

            printf("Target Celestiocentric SRF parameters :\n"\
                   "orm = %s\n"\
                   "rt  = %s\n",
                   SRM_PrintORMCode(tgt_orm), SRM_PrintRTCode(tgt_rt));
            fflush(stdout);

            if (cd_srf.methods->CreateCoordinate3D(&cd_srf,
                src_ord1, src_ord2, src_ord3, &cd_coord)
                != SRM_STATCOD_SUCCESS)
            {
                fprintf(stderr, "Failed to create CD coordinate\n");
            }
            else
            {
                if (cc_srf.methods->CreateCoordinate3D(&cc_srf,
                    0.0, 0.0, 0.0, &cc_coord) != SRM_STATCOD_SUCCESS)
                {
                    fprintf(stderr, "Failed to create CC coordinate\n");
                }
                else
                {
                    local_ConvertFromCDToCC(&cd_srf, &cc_srf,
                        &cd_coord, &cc_coord, src_ord1, src_ord2, src_ord3);

                    src_ord1 = 0.0;
                    src_ord2 = 0.0;
                    src_ord3 = 0.0;

                    if (cd_srf.methods->SetCoordinate3DValues(&cd_srf,
                        &cd_coord, src_ord1, src_ord2, src_ord3) !=
                        SRM_STATCOD_SUCCESS)
                    {
                        fprintf(stderr, "Failed to reset CD coordinate\n");
                    }
                    else
                    {
                        local_ConvertFromCDToCC(&cd_srf, &cc_srf,
                          &cd_coord, &cc_coord, src_ord1, src_ord2, src_ord3);
                    }

                    src_ord1 = 0.0;
                    src_ord2 = SRM_PI_DIV_2;
                    src_ord3 = 0.0;

                    if (cd_srf.methods->SetCoordinate3DValues(&cd_srf,
                        &cd_coord, src_ord1, src_ord2, src_ord3) !=
                        SRM_STATCOD_SUCCESS)
                    {
                        fprintf(stderr, "Failed to reset CD coordinate\n");
                    }
                    else
                    {
                        local_ConvertFromCDToCC(&cd_srf, &cc_srf,
                          &cd_coord, &cc_coord, src_ord1, src_ord2, src_ord3);
                    }

                    src_ord1 = 0.0;
                    src_ord2 = -SRM_PI_DIV_2;
                    src_ord3 = 0.0;

                    if (cd_srf.methods->SetCoordinate3DValues(&cd_srf,
                        &cd_coord, src_ord1, src_ord2, src_ord3) !=
                        SRM_STATCOD_SUCCESS)
                    {
                        fprintf(stderr, "Failed to reset CD coordinate\n");
                    }
                    else
                    {
                        local_ConvertFromCDToCC(&cd_srf, &cc_srf,
                          &cd_coord, &cc_coord, src_ord1, src_ord2, src_ord3);
                    }
                    cc_srf.methods->DestroyCoordinate3D(&cc_srf, &cc_coord);
                }
                cd_srf.methods->DestroyCoordinate3D(&cd_srf, &cd_coord);
            }
            cc_srf.methods->Destroy(&cc_srf);
        }
        cd_srf.methods->Destroy(&cd_srf);
    }
    return 0;
}

Executing the sample code would result the following output:

Running SRM Sample test program...
Source Celestiodetic SRF parameters :
orm = SRM_ORMCOD_WGS_1984
rt  = SRM_RTCOD_WGS_1984_IDENTITY
Target Celestiocentric SRF parameters :
orm = SRM_ORMCOD_WGS_1984
rt  = SRM_RTCOD_WGS_1984_IDENTITY
Source (converted) Celestiodetic 3D coordinate: [ 0.000000, 0.785398, 0.000000 ]

Target (converted) Celestiocentric 3D coordinate: [ 4517590.878846, -0.000000, 4487348.408860 ]

Source (converted) Celestiodetic 3D coordinate: [ 0.000000, 0.000000, 0.000000 ]

Target (converted) Celestiocentric 3D coordinate: [ 6378137.000000, -0.000000, -0.000000 ]

Source (converted) Celestiodetic 3D coordinate: [ 0.000000, 1.570796, 0.000000 ]

Target (converted) Celestiocentric 3D coordinate: [ 0.000000, -0.000000, 6356752.314144 ]

Source (converted) Celestiodetic 3D coordinate: [ 0.000000, -1.570796, 0.000000 ]

Target (converted) Celestiocentric 3D coordinate: [ -0.000000, 0.000000, -6356752.314144 ]

Return to: Top