Encoding and decoding of spherical coordinates in concise format.

Discontinuity diagram of CDC coordinates in Orthographic projection

Description:
   Near-conformal sphere coordinates of a point consist of three (i, j and k)
   components of the normalized spherical radius-vector of the point. Each
   vector component is commonly encoded as a "double", normally an 8-byte real
   ("floating point") number data type. Each point coordinates thus require
   24 bytes of storage. This coordinate representation provides orders of
   magnitude higher spatial resolution than any application might require for
   the points or vertices of line/area data objects on the planetary surface.
   ·
   Spherical point coordinates can be encoded with a reduced numerical
   resolution (called here a "concise" form), that has a better balance
   between the storage requirements and spatial resolution, and at the same
   time can be efficiently transferred (in both directions) between the
   concise form and the three direction cosines vector form, normally
   required for spherical geometry computations.
   ·
   The concise encoding is performed by omitting the vector component with
   the largest magnitude and reducing the number of bits used to represent
   the two smaller vector components. When decoding (i.e., performing the
   "inverse" transformation to reconstruct the full vector i, j, k
   component form), the value of the omitted component can easily be
   calculated at the small cost of a single square root evaluation, as
                           i² + j² + k² = 1.0
   ·
   Important characteristics of such coordinate encoding are:
   ·
   1) Storage efficiency.
   ·
   2) Very fast transformation from and to near-conformal sphere normalized
      vector components coordinates (and, from there - if required - to
      ellipsoid vector coordinates). This is due to the fact that all
      transformations are based on closed algebraic productions that
      require no evaluation of trigonometric functions.
   ·
   3) Point location is represented by a single integer number, thus many
      applications can consider points to represemt the same location if
      their CDC coordinares are equal.
   ·
   The maximum difference ("Δ max") of a point location encoded into such
   coordinate format and decoded back from it on the planet with the size of
   the Earth is 21 mm, and the standard deviation ("σ") is 6 mm. While such
   "grid resolution" is not sufficiently fine for geodetic framework point
   coordinate computations, it is more than adequate for data storage and
   inter-system transfer of any GPS topographic detail surveys, road, sea,
   air and orbital navigation systems, terrestrial object location tracking,
   radar detection, mobile radio communication - and a large number of other
   practical applications.
   ·
   As the encoding uses the bit-level manipulation, the output data item
   is endian-sensitive. If the library is compiled and the resulting code
   executed on a big-endian hardware, and if the concise form coordinates
   are exchanged in binary form with systems executing on (much more common)
   little-endian hardware, the application must reverse byte order before
   writing and after ingesting concise coordinates.
   .
   As an example, following are the coordinates of a single location (Aoraki)
   in different coordinate formats, all commonly used by Library functions:
   .
   Ellipsoid φ and λ in angular measurement:
   -43°35′42″, 170°08′31″
   As i, j, k, NCS direction cosines:
   -0.715813189,  0.124389489, -0.687123522
   nemoPtU64 - decimal (i.e., printed using "%020lu" format specification):
   12109148219568291497
   nemoPtU64 - hexadecimal (i.e., printed using "%016lx" format specification):
   a80c56260febfea9
   Bit-string representation of two 32-bit unsigned integers:
   00001111 11101011 11111110 10101001:10101000 00001100 01010110 00100110
   (last two bits (...01) in first word indicate "i" vector components had
   the largest absolute value (0.715813189) and was thus "dropped" from the
   "concise" encoding; the last two bits (...10) of the second word indicates
   that the dropped component was negative (-0.715813189). Note that this bit
   string IS NOT the memory image of two little-endian 4-byte hardware words).
   ·

Synopsis:
   #include <nemo.h>
   nemoPtU64 nemo_NcsToU64(const nemoPtNcs *pPtNcs);
Argument:
   ptNcs:
      Pointer to nemoPtNcs structure, given NCS point coordinates.
Return Value:
   An integer of nemoPtU64 type (8-byte, unsigned), CDC encoded
   coordinates of ptNcs.
See Also:
   nemo_U64ToNcs()

Synopsis:
   #include <nemo.h>
   void nemo_U64ToNcs(nemoPtU64 ptU64, nemoPtNcs *pPtNcs);
Arguments:
   ptU64:
      An integer of nemoPtU64 type (8-byte, unsigned), given CDC encoded
      coordinates.
   ptNcs:
     Pointer to a receiving nemoPtNcs structure, returned coordinates.
     If the given CDC coordinates are invalid (cf.: NEMO_U64_UNDEF),
     all three vector components are set to NEMO_DOUBLE_UNDEF.
See Also:
   nemo_NcsToU64()