transformation package for IDL and C
The CXFORM package contains a set of routines to convert spacecraft
from one system to another, i.e., GSE-->GSM. It is written in
C and can be
used as either a C library (.so or .dll) or as an IDL function on most
(via its DLM -- Dynamically Loadable Module -- interface).
It has been tested under SunOS v5.7, Microsoft Windows 2000/XP, Mac OS
& 10.4, and Linux kernel release 2.4.20. It has previously
been tested under
Solaris 2.6 and DEC OSF/1 V4.0.
It is largely based on Mike Hapgood's excellent introduction to
transformations, along with Markus Fraenz' "Heliospheric Coordinate
and Christopher Russell's "Geophysical Coordinate Transformations":
Note that since this follows much of Hapgood's formulae that are
simplicity and efficiency, he specifies a level of precision of 0.001
up to the year 2100 for each rotation angle, which has been deemed
for space physics applications. The disclaimer applies that these
be used for mission-critical flight applications due to their margin of
Formal testing has been completed as of 2004/12/01. The results
can be found
here on the CXFORM web page. In
general, they are within 1% of the results of
SSCWeb's calculations (based
on GEOPACK), and in many cases are within
If you find CXFORM to be useful (or have other comments), please let
For one example of CXFORM in a production environment, visit the USGS
EarthNow! Landsat Image Viewer.
By converting satellite positions and
velocities from GEI to GEO, the exact ground track can be computed,
city names and the track itself to be properly located.
DOWNLOAD / INSTALLATION
Precompiled binaries (with source code):
* = these libraries were compiled under Mac OS X 10.5 and may not work
prior versions. If this appears to be the case,
download the source
compile using instructions in install.txt. You will need the
included in Xcode.
** = contains compiled C library, but does not contain compiled IDL code
because a Linux machine with IDL installed was not
See install.txt for instructions
(also included in above files).
USAGE FROM IDL
The function prototype is
new_pos = CXFORM( pos, source_frame, dest_frame,
is a vector of length 3, containing the position
in source_frame coordinates. It
can also be a 2-D
array of size [3, M], where M is
the number of points
source_frame is an ASCII string
naming the source
coordinate system, e.g., 'GSE',
"Coordinate Systems Implemented"
dest_frame is also an ASCII
string, naming the destination
is "ephemeris seconds past J2000 (1 Jan 2000 12:00)".
The "date2es" function converts a
time (mm,dd,yyyy) to Ephemeris
J2000. See the included
"date2es.pro" file for more
new_pos is the
position, in dest_frame coordinates.
IDL> es = date2es(9,30,1999,7,5,0) ; Sep.
30, 1999 07:05:00 UTC
IDL> pos = cxform([1,0,0], 'GSE', 'GEO', es)
DOUBLE = Array
IDL> imp8GEI = fltarr(3, 5)
IDL> imp8Time = lonarr(5)
IDL> help, imp8GEI
FLOAT = Array[3, 5]
IDL> help, imp8Time
IDL> imp8GEI[*,0] = [-32.562, 20.085, -10.471]
IDL> imp8GEI[*,1] = [-34.415, 4.229, -6.173]
IDL> print, imp8GEI
IDL> imp8Time = [-43200, 43200, 129600, 216000,
IDL> imp8GEO = cxform(imp8GEI, 'GEI', 'GEO',
IDL> print, imp8GEO
Note that if your data is imported as [M, 3] instead of [3, M], you can
transpose it using IDL's TRANSPOSE function:
IDL> correctArr = fltarr(3, M)
IDL> correctArr = TRANSPOSE(originalArr)
USAGE FROM C
See main.c included in this package for
an example of using CXFORM in C.
See install.txt for instructions on
building it on your platform.
The bulk of the testing used SSCWeb's
Locator Tabulator as the data source.
As stated in the introduction, this service uses GEOPACK for its
An included file, tester.c, was used to read in data from SSCWeb and
compare it to the results of CXFORM. In addition, one data point
was used from
transformation package documentation as a sanity check and also
as a test for the heliospheric systems that are not present in SSCWeb.
ACE data, year 2000, ~40k
Geotail data, year
1993, ~40k data points
IMP-8 data, year 2003,
~40k data points
HelioCoords documentation, 1 data point
COORDINATE SYSTEMS IMPLEMENTED
Equatorial Inertial, also known as True
Equator and True Equinox of Date, True of Date (TOD),
ECI, or GCI
J2000 Geocentric Equatorial
Inertial for epoch J2000.0
(GEI2000), also known as Mean
Equator and Mean Equinox
also known as Greenwich Rotating
Coordinates (GRC), or Earth-fixed
Tangential Normal (Earth-centered)
GSEQ Geocentric Solar
Heliocentric Earth Ecliptic
Heliocentric Aries Ecliptic
Heliocentric Earth Equatorial
* = this system has not been implemented/tested and should be treated
ADDING NEW COORDINATE SYSTEMS
This package has been designed to allow for easy additions of new
All you need to do is define one transformation between the new system
of the existing ones. Once you do that, the Perl script will
generate code to
convert to all others. This, of course, means that a working copy
of Perl must
be installed. You will need the IxHash module if it is not
It can be found at http://search.cpan.org/dist/Tie-IxHash/
Here's what you do:
1. Edit the file cxform-manual.c and add a new function,
where `xxxx' is any existing coordinate frame,
and `yyyy' is the new one.
2. Run "perl gen_cxform_auto.pl cxform-manual.c" from the
prompt. This will
create a new cxform-auto.c with support for
your new coordinate system.
3. Build and install a new CXFORM library as described in
4. Run and test it in IDL/C. That's it!
If it works, please send me your code. I will include it in the
distribution (with appropriate credit to you, of course).
Ed Santiago: Last released version from Ed.
Ryan Boller: First modified version from Ryan. Added
and GSEQ systems,
IGRF model, slightly different time
Windows support, additional documentation, and
2004/03/19 v0.4 Ryan Boller: Updated Makefile to
auto-detect platform and
build under Mac OS X. HEEQ system now implemented by Kristi
Ryan Boller: Fixed small discrepancy in calculation of
and lambda0. Results now match those of SSCWeb's (GEOPACK-
based) when the mag pole lat/lon is fixed to their values,
they haven't updated their IGRF coefficients.
Ryan Boller: Finished comprehensive testing, posted results.
Updated IGRF to Revision
9. Moved cxRound, date2es, and
gregorian_calendar_to_jd to cxform-manual.c so it is included
the shared library.
Ryan Boller: Updated IGRF coefficients to 10th generation.
Fixed IDL DLM interface under Windows XP & IDL 6.0+. Updated
Ryan Boller: Updated Mac compiler flags to compile 32- and
64-bit versions on Intel- and PPC-based CPUs. Fixed memory pointer
problem on 64-bit machines (now using IDL_MEMINT instead of IDL_LONG
KNOWN ISSUES / TODOs
- Mac shared object does not link with C objects. May need to
convert to a
dylib. The shared object does work with the IDL DLM
- RTN System needs to be tested for accuracy.
NASA Official: Dr.
Last Updated: November 25, 2003