Function Name: Convert Coord Array

Definition

This function converts an array of coordinates in one SRF to an equivalent array of coordinates in another SRF.

Returns

SE_COORD_EXTENDED_SOURCE_COORD - if the operation succeeded, however one or more source coordinates fell within the "extended" range of the source SRF. In this case, all of the coordinates in dest_coord_array are set to the appropriate operation result.

SE_COORD_EXTENDED_DEST_COORD - if the operation succeeded, however one or more source coordinates after being converted fell within the "extended" range for the destination SRF, e.g. a GD coordinate converted to a UTM SRF and falling just outside the specified UTM zone, but not so far outside as to become invalid. In this case, all of the coordinates in dest_coord_array are set to the appropriate operation result.

SE_COORD_EXTENDED_SOURCE_AND_DEST_COORD - if the operation succeeded, however one or more source coordinates fell within the "extended" range of the source SRF, and after being converted also fell within the "extended" range for the destination SRF. In this case, all of the coordinates in dest_coord_array are set to the appropriate operation result.

NOTE: if either (SE_COORD_EXTENDED_SOURCE_COORD and SE_COORD_EXTENDED_DEST_COORD) or SE_COORD_EXTENDED_SOURCE_AND_DEST_COORD occurs then SE_COORD_EXTENDED_SOURCE_AND_DEST_COORD will be returned, else either SE_COORD_EXTENDED_SOURCE_COORD or SE_COORD_EXTENDED_DEST_COORD will be returned accordingly

SE_COORD_FAILURE - if the coordinate operation failed for reasons unspecified. In this case, *dest_coord_array is left UNCHANGED.

SE_COORD_UNSUPPORTED - if the coordinate operation (conversion and/or transformation) is unsupported. In this case, *dest_coord_array is left UNCHANGED.

SE_COORD_INVALID_SRF_PAIR - if convert_params_ptr was NULL or invalid or if coord_op_params_ptr was NULL or invalid. In this case, *dest_coord_array is left UNCHANGED.

SE_COORD_INVALID_SOURCE_COORD - There are two situations when this condition is returned:

1. if source_coord_array is NULL or points to an array containing an invalid value with respect to the source SRF. In this case, *dest_coord_array is left UNCHANGED. If the source_coord_array was not NULL, then the invalid coordinate(s) can be identified by repeatedly calling SE_ConvertCoordToGivenSystem(), once for each coordinate in the array, and examining the status code for each operation.
2. if the array_size has value ZERO.

SE_COORD_INVALID_DEST_COORD - if dest_coord_array is NULL, or points to an array containing a coordinate which after being converted is invalid for for the destination SRF, e.g. a GD coordinate of latitude 85 degrees to a UTM SRF. In this case, *dest_coord_array is left UNCHANGED. If the dest_coord_array was not NULL, then the invalid coordinate(s) can be identified by repeatedly calling SE_ConvertCoordToGivenSystem(), once for each coordinate in the array, and examining the status code for each operation.

Prototype

Parameters Notes

convert_params_ptr

 a pointer to the optimized coordinate operations parameters.

array_size

 the number of entries in the source coord array and the dest coord
 array (both arrays must have the same number of entries)

source_coord_array

 the array of incoming coordinates, the coordinates to convert

dest_coord_array

 the array where the converted coordinates will be stored. This can
 be the same location/array that source_coord_array points to, but it
 does not have to be.