Coordinate conversion is a multi-step process proceeding as follows:

1. Specify the source and destination spatial reference frames (SRFs), including any parameters needed to define those SRFs. The SRM_SRF_Parameters data structure contains the parameters for a SRF.

2. Call to the SRM_CreateSRFParametersPair() function, passing in the parameter structures for the source and destination SRFs, and receiving an SRM_SRF_Parameters_Pair. Hold on to this SRM_SRF_Parameters_Pair - you will need it every time you want to convert a coordinate from the source SRF to the destination SRF. Note that multiple SRM_SRF_Parameters_Pair may be simultaneously defined, then used when desired.

   Note that not all SRF pairings are currently supported, therefore SRM_CreateSRFParametersPair() may return SRM_STAT_CODE_UNSUPPORTED. See the explanation of supported conversions in Directly Supported Conversions.

3. For an individual coordinate, call either:

   
   
   • SRM_ChangeCoordinateSRF() or
   • SRM_ChangeCoordinateSRFUnvalidated(),
   
   passing in the SRM_SRF_Parameters_Pair and the source coordinate, and receiving the coordinate converted in the destination SRF.

   For an array of coordinates, call either:

   
   
   • SRM_ChangeCoordinateArraySRF() or
   • SRM_ChangeCoordinateArraySRFUnvalidated(),
   
   passing in the SRM_SRF_Parameters_Pair and a pointer to the source coordinate array, and receiving a pointer to the destination coordinate array converted in the destination SRF.

4. Repeat the previous step as needed, once for every coordinate (or coordinate array) to convert between the source and destination SRF pairing defined in the first and second steps.

5. When finished converting coordinates between two SRFs, call SRM_FreeSRFParametersPair() to release the SRM_SRF_Parameters_Pair that was allocated by the first step. Note that if multiple SRM_SRF_Parameters_Pair were defined, then each must be individually released.

The following SRF conversions are directly supported in SRM Version 3.1.2

GC <=> GCS

GC <=> LTP

GD <=> EC

GD <=> GC

GD <=> LCC

GD <=> M

GD <=> PS

GD <=> TM

GD <=> UTM

Reflexive conversions are also allowed. For example, asking to convert from the GC SRF to the GC SRF, where both SRFs share the same datum parameters, does not produce an error. No actual work is done in the conversion in this case, but no errors are returned for this conversion. Reflexive conversions may also be used to convert elevation values from feet to metres or from metres to feet, depending on the units specified in the source and destination SRFs. Also, some reflexive conversions (e.g., GCS to GCS) will convert coordinates based on the possibly different offsets defined in the parameters of the source and destination SRFs.

Some conversions are supported as a two-step process, converting from the source SRF to the GD SRF, and then converting from the GD SRF to the destination SRF. Since two coordinate conversions are being performed in these cases, these cases can take twice as long and may have up to twice the error compared to the directly supported conversions. (Directly supported conversions should not have an error of more than 0.001 metres, and the indirect conversion errors should not exceed 0.002 metres.)

In the future, we expect to add code so that the conversions that are currently indirect will be directly supported instead. For example, we expect to add code to directly convert from LCC to UTM, instead of performing the two-step conversion currently required of LCC to GD, then GD to UTM. Sometimes indirectly supported conversions are referred to as "transitive" or "chained" conversions. The user does not need to treat these conversions any differently, as far as the function calls are concerned. In order to convert from LCC to UTM, just ask for LCC to UTM. The fact that an intermediate conversion through GD is taking place is automatically handled by the conversion code.

The user calls the same functions, regardless of whether the conversion is directly supported, reflexive, or indirectly supported. If a conversion is not supported between the two SRFs selected by the user, then the call to SRM_CreateSRFParametersPair() will return the error code SRM_STAT_CODE_UNSUPPORTED.

The chart below is provided as a reference to indicate which coordinate conversions are supported in SRM Version 3.1.2

• D - directly supported conversion
• R - reflexive conversion
• I - indirectly supported conversion (a.k.a. "chained" or "transitive")

Note that GCS <=> GCS is an indirectly supported conversion. Conversion between different GCS spatial reference frames occurs via an intermediate conversion to GC, thus allowing conversion between GCS spatial reference frames specified for different cells.

Supporting a source to destination coordinate conversion doesn't always mean being able to convert all coordinates between the two SRFs. For example, when converting from GD to UTM, the GD latitude must be between -80.0 and 84.0; otherwise, an error is produced. If a call is made to SRM_ChangeCoordinateSRF() to go from GD to UTM, but the GD latitude is less than -80.0, then SRM_ChangeCoordinateSRF() will return the error value of SRM_STAT_CODE_INVALID_DEST_SRF_PARAMETERS, and no conversion will occur. If the same call is made (with the same parameter values) to SRM_ChangeCoordinateSRFUnvalidated(), then no error value is returned, but the resulting conversion is meaningless.

The SRM_ChangeCoordinateSRFUnvalidated() version of the conversion function is meant to be called only when the user is sure that the source coordinate is, and destination coordinates will be, located within the valid or extended ranges of their respective SRFs. The SRM_ChangeCoordinateSRFUnvalidated() version of the conversion function is slightly faster than the regular conversion function, but the regular conversion function should be used unless the user knows for certain that the coordinates being converted fall within the appropriate established ranges.

The function SRM_ValidateCoordinate() may be used to determine whether a coordinate lies within the valid, extended, or invalid range of a SRF.