Retrun to document top page

### Nemo Library, section 4

NCS concise direction cosine (CDC) encoding and decoding
```   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).
·
```

 nemo_NcsToU64() NCS (3 doubles) to CDC (U8 integer) nemo_U64ToNcs() CDC (U8 integer) to NCS (3 doubles)

nemo_NcsToU64()
```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.
nemo_U64ToNcs()```

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.