Document creation date: 2023-08-03

## NemoAn Open Source Libraryof Round-world Computational Primitives

User Guide and Reference Manual - C language implementation)

### Introduction

The traditional method of numerical representation of geographic coordinates consists of angular latitude and longitude (φ and λ, respectively). This coordinate form is ill-suited for processing on a digital computer. Specifically, the implementer of any application that handles large volumes of wide area geographic data must find a solution to three fundamental software engineering problems:

• Geographic coordinates, φ and λ, are numerical representation of location on a surface on an ellipsoid of rotation. Formulae that describe its surface geometry relationships are typically derived from differential equations by their polynomial expansion. These tend to be very costly to evaluate on a computer.

• Geographic coordinates on spheroidal (i.e., a "sphere-like" body - whether an ellipsoid or a sphere) surface are traditionally recorded as angular values. Numerical operations on angles require frequent evaluation of trigonometric functions (sine, cosine...), also a costly operation when compared to four algebraic operations (addition, subtraction, multiplication and division).

• If either angular (2 elements) or vector (3 elements) coordinates of a point on the spheroidal surface are recorded as an 8-byte "floating point" number each, the volume of coordinate data can become quite high, yet the granularity of location recorded in such manner exceeds by orders of magnitude the spatial resolution of any common geographical data, as well as the precision requirements of any application. In addition, such artificially high resolution forces the developer to burden the application with some form of "epsilon control mechanism", i.e., a test that determines when two points are coincident despite the fact their numerical coordinates are not identical.

Nemo library is a collection of C-language functions, that provides a path to the solution of those problems. It may work effectively for a large number of wide area or global geographical applications that are built using the following design strategy:

• Spatial relationships are initially evaluated on an ellipsoid-specific near-conformal sphere, and the refinement that brings the solution to ellipsoid geometry precision level can be performed only when and if necessary.

• Once data is ingested from conventional geographic coordinates (ellipsoid φ and λ), it is transformed to a near-conformal spherical domain, and internally recorded not as two angles, but as three direction cosines. This restricts the evaluation of trigonometric functions to only those segments of the application code that exchanges data with humans or other applications that insist on conventional ellipsoidal φ and λ coordinates.

• High-volume coordinate data is transformed into a concise vector ("concise direction cosine", CDC) form, which encodes a position on the spheroidal surface as an 8-byte integer. The resolution of this planet-wide CDC integer "grid", on the surface of a spheroid the size of Earth is 21 mm maximum, and 6 mm average. Since the point coordinates are encoded as integers, in many application contexts points can be simply considered coincident when their CDC coordinates are equal.

Effective use of the Library requires the unsrestanding of computational domains and coordinate systems used in geographical data processing.

nemo.h

### Library Sections

Section 1:   Elementary programming algorithms
Section 2:   Simple Algebra and Geometry
Section 3:   Spherical surface geometry productions
Section 4:   NCS concise direction cosine (CDC) encoding and decoding
Section 5:   Ellipsoid geometry and NCS/CFS/ellipsoid transformations
Section 6:   Sphere to plane mapping and "un-mapping"

### Alphabetical List of Library Functions

 nemo_ArcToChordApprox() Arc to approximate chord nemo_ArcV3() Spherical arc nemo_Cc3ToEnr() 3D radius vector to ellipsoid normal nemo_CfsToEnr() Conformal sphere to ellipsoid normal nemo_ChordSqToArcApprox() Square chord to approximate arc nemo_ConicalDirect() NCS to Conical map plane nemo_ConicalInit() Initialize conical projection nemo_ConicalInverse() Conical map plane to NCS nemo_Dcos3ToLatLong() Generic 3D vector to latitude/longitude nemo_DeQueue() Remove node from a queue nemo_DirectionToAzimuth() Azimuth (angle) from direction cosines nemo_EllToNcs() Ellipsoid latitude/longitude to NCS nemo_EllipsoidChordDirect() Direct problem of geodesy on ellipsoid nemo_EllipsoidChordInverse() Second problem of geodesy on ellipsoid nemo_EllipsoidPrincipalRadii() Meridian and Prime Vertical radii nemo_EllipsoidRadius() General ellipsoid curvature radius nemo_ElrInit() Initialize the ellipsoid parameters nemo_ElrWgs84() Provide static WGS84 ellipsoid parameters nemo_EnQueue() Add node to queue end nemo_EnrToCc3() Ellipsoid normal to 3D radius vector nemo_EnrToCfs() Ellipsoid normal to conformal sphere nemo_EnrToNcs() Ellipsoid normal to near conformal sphere nemo_GeodesicVincenty() Geodesic length using Vincenty formulae nemo_GnomonicDirect() NCS to Gnomonic map plane nemo_GnomonicInit() Initialize Gnomonic projection nemo_GnomonicInverse() Gnomonic map plane to NCS nemo_LatLongToDcos3() Latitude/longitude to generic vector nemo_MeridianArcLength() Meridian arc length nemo_MidV3() Find mid-vector in 3D space nemo_NcsElrRadius() Return ellipsoid radius for an NCS point nemo_NcsElrScale() Return mapping scale between NCS abd ellipsoid nemo_NcsToEll() NCS to ellipsoid latitude/longitude nemo_NcsToEnr() NCS to ellipsoid normal nemo_NcsToU64() NCS (3 doubles) to CDC (U8 integer) nemo_NormalizeV2() Normalize generic two-componenet vector nemo_NormalizeV3() Normalize generic three-componenet vector nemo_OrthographicDirect() NCS to Ortographic map plane nemo_OrthographicInit() Initialize ortographic projection nemo_OrthographicInverse() Ortographic map plane to NCS nemo_PeekBottom() Peek the stack bottom node nemo_PeekTop() Peek the stack top node nemo_Pop() Pop a node from stack nemo_Push() Push a node to stack nemo_QueueInit() Initialize stack anchor nemo_QueuePeekFirst() Peek the queue first node nemo_QueuePeekLast() Peek the queue last node nemo_QueueSize() Report the number of nodes in the queue nemo_QueueVerify() Verify queue nemo_RandomLocal() Generate regional random point on unit sphere nemo_SphereChordCoords() Spherical Abscissa and Ordinate nemo_SphereChordDirect() Direct problem of geodesy on sphere nemo_SphereChordInverse() Inverse problem of geodesy on sphere nemo_SphereCircumcenter() Find spherical circumcenter nemo_SphereRandomLine() Generate random line on unit sphere nemo_SphereRandomLocation() Generate a random location on unit sphere nemo_SphereSegsXsct() Intersection of two great circle segments nemo_SphereTangentialPlane() Principal vectors of tangential plane nemo_StackInit() Initialize stack anchor nemo_StackInvert() Inverted the order of nodes in a stack nemo_StackSize() Report the number of nodes on the stack nemo_StackVerify() Verify stack nemo_StereographicDirect() NCS to Stereographic map plane nemo_StereographicInit() Initialize Stereographic projection nemo_StereographicInverse() Stereographic map plane to NCS nemo_StylindricalDirect() NCS to Stylindrical map plane nemo_StylindricalInit() Initialize Stylindrical projection nemo_StylindricalInverse() Stylindrical map plane to NCS nemo_U64ToNcs() CDC (U8 integer) to NCS (3 doubles) nemo_WorkMemAvailable() Report the current size of free space nemo_WorkMemCheck() Check availability of workspace block nemo_WorkMemGet() Allocate workspace block nemo_WorkMemInit() Initialize workspace instance nemo_WorkMemRevert() Revert the state of workspace instance. nemo_WorkMemUsedMax() Report life-time maximum workspace use

The content of this Reference Manual matches the Nemo Library source code published on date specified as NEMO_LIBRARY_DATE literal in the preamble of the included API header file, i.e., the date in the reference manual nemo.h and library source nemo.h must be the same.

Nemo Library is distributed in C language source code form, under 'BSD type' license, the full text of which can be found in the "license.text" file, co-resident with the source code files in the distribution archive. The text of license, with a short commentary, can be inspected here.

This Reference Manual is published under Creative Commons BY-ND 4.0 license. Author: Hrvoje Lukatela