SConvert Files

$Id: README.txt,v 1.1.1.1 2010/01/27 03:06:10 mpfauth Exp $
file:  README.txt
author:  MJ Pfauth, 10 Nov 2009

Copyright 2009, 2010 Michael J. Pfauth, mpfauth@hiwaay.net.  Distributed under
the Boost Software License, Version 1.0. (See accompanying file
LICENSE_1_0.txt or copy at http:www.boost.org/LICENSE_1_0.txt)

SConvert is set of functions for coordinate transformation and Euler angle
manipulation.  My goal was to implement a useful, simple, easy to use and
reasonably efficient set of conversions for commonly used geo- and topocentric
coordinate systems.  I use SCoord in my own work and have found it to be
useful both by itself and as part of a larger, more comprehensive set of
conversion functions.

Each part, except the altitude conversion functions of SCoord, is implemented
as a set of template functions and comes with a Makefile and a test driver.
The template functions themselves need not be compiled; just include them in
your code.  The test drivers are included as examples of how to use SConvert.

I have used SConvert with both Linux/gcc and Windows/Visual C++.  Since
SConvert is written in plain vanilla C++ there should be no problems on other
platforms, assuming a reasonably standards-compliant C++ compiler.

I do not provide M-------t Visual C++ project files because I do not use it
for personal software development.  Also, SConvert is simple enough that you
should be able to easily import it into Visual C++ on your own.

SConvert consists of 3 parts:  SCoord, SEuler and SMatrix.

SCoord contains the primary coordinate conversion functions.  It handles
conversions among these coordinate systems:
- ECI (Earth-Centered Intertial)
- Geodetic, ie latitude, longitude and altitude (WGS-84 only).  There are also
2 functions to convert between datum and geoid (mean sea level) altitudes.
- ECR/ECEF (Earth-Centered Rotating aka Earth-Centered, Earth-Fixed)
- ENU/LLE (East-North-Up aka Local Level East)
- REA range-elevation-azimuth, a spherical coordinate system whose origin is a
ENU/LLE coordinate system.

Coordinate transformations are organized as pairs: ECI <--> ECR, ECR <-->
Geodetic, ECR <--> ENU and ENU <--> REA.  The two-way arrow <--> means that
there are both forward and reverse transformations.  Position and velocity are
transformed for all pairs.  ECI <--> ECR and ECR <--> ENU also have
acceleration transformations.  Each pair also has functions for computing the
transformation matrix, a required argument for all transformation functions.

For geodetic coordinates there is an additonal pair of functions,
HeightDatumToGeoid and HeightGeoidToDatum found in height_convert.h, to
convert between datum/ellipsoid height and geoid/mean sea level (MSL)
altitudes.  Use of these functions requires linking with
libheight_convert_gcc_*.a.  (The asterisk denotes 'd' for the debug version of
the library or 'r' for the release version.)  If you are not using these two
functions then you need not link with this library.  Use of these two
functions also requires that the datum-ellipsoid height file egm96.grd be in a
location specified by the environment variable GEOID_DATA.  Also, the altitude
parameters of the ECR <--> Geodetic conversions are assumed to be datum; ie
wrt the WGS-84 ellipsoid.

The height conversion functions and egm96.grd were taken from the GeoTrans
coordinate transformation distribution.  GeoTrans was written for the US
government and is freely distributed.  It contains conversion functions for a
welter of coordinate systems and map projections.  Highly recommended; can be
found at http://earth-info.nga.mil/GandG/geotrans.

SCoord depends on SMatrix and SEuler.

Seuler is a set of Euler angle functions which handle all 12 unique Euler
angle sequences.  It contains functions to compute the direction cosine matrix
for a given set of Euler angles and also to retrieve any of the 12 Euler
sequences from a direction cosine matrix.  SEuler correctly handles cases of
gimbal lock.  Read the included Euler angle tutorial in file seuler/euler.pdf
for more detailed explanation of what Euler angles are and how to manipulate
them.  The SEuler functions are more or less direct implementations of the
equations in euler.pdf.  SEuler depends on SMatrix.

SMatrix is a minimal set of matrix functions specifically designed for
SConvert.  There are several very fine industrial-strength matix and linear
algebra packages but since I do not have an industrial-strength problem and to
accomplish my design goal of simplicity, I wrote my own stuff.

Building
SEuler and SMatrix need not be compiled; just copy the header files to your
include directory.  If you want to build the test driver, change to the source
directory and just do "make".

If you want the SCoord height conversion functions (presumably you do), then
first build the library:  make -f Makefile.lib.  The default output target is
the debug version of the library.  If you want the release version, put
OUTPUT=release on the make command line.  To build the SCoord test drivers,
then just "make" is needed.  As above, add OUTPUT=release to the make command
line to get release versions.

This is not the place for a lesson on coordinate systems.  Effective use of
SConvert requires some knowledge of and experience with coordinate systems,
though not very much.  A little searching on the web will discover much useful
information.

Effusive praise is always welcome, niggling criticism is not.  The reception
accorded constructive criticism depends on my mood.