Introduction:

This package contains a partial port to C of Dr TS. Kelso's PASCAL library sgp4-plb26a. This library contains files with functions for calculating the position and velocity of a satellite using the NORAD SGP4 and SDP4 routines and from these the azimuth, elevation, range and range rate of same. Routines are also included for calculating the position of the sun and the illumination status and eclipse depth of the satellite.

The port to C includes most of the sources needed for making the above calculations and for reading and checking two-line Keplerian element sets (TLE's) from a file, as available from many sources on the Internet. Some of the files in the PASCAL library are PC-specific and have not been ported to C or they have been substituted or modified with some functions I developed myself. A simple main() function is included to demonstrate the use of the C sgp4/sdp4 library and functions for reading and testing a TLE set from a file.

Contents:

This package should contain the following files:

1. This README file.

2. The COPYING file with copyright details.

3. sgp4sdp4.c: The source-code of the ported SGP4 and SDP4 routines and some extra functions for testing and setting flow control flags.

4. sgp_in.c: Functions for reading a TLE set from a file and verifying, converting and pre-processing the Keplerian element set.

5. sgp_math.c: Various mathematical functions used by other routines.

6. sgp_obs.c: Functions for calculating the geodetic position of the observer and converting the ECI position and velocity of a satellite to observer-centered azimuth, elevation, range and range rate. Also calculating the observer-centered position of the sun.

7. sgp_time.c: Functions needed to calculate and convert time in various formats, e.g. Julian, calender etc.

8. solar.c: Functions for calculating the position of the sun.

9. main.c: A basic main() function to demonstrate the use of the sgp4/sdp4 library to read a TLE set and calculate and print satellite predictions.

10. sgp4sdp4.h: A header file that should be #include'd in all source files using this library.

11. Makefile: A simple makefile for building the 'ephem' binary.

Building and testing:

Run make in the sgp4sdp4 source directory to compile the binary executable. Run ephem to start the test program, but please note you need to include a file in the same directory including TLE sets in NASA format as available on the Internet. There are fresh sets uploaded regularly at Dr TS Kelso's site at www.celestrak.com . Please note that you should edit main.c to enter the directory path for this file, it is currently set at amateur.txt and to also enter the observer's geodetic coordinates (lat and lon in rads and altitude in km). This is only a skeleton test application!

Known bugs:

It appears that the original NORAD routines have been modified to correct some discrepancies in the calculated satellite position data, at least for some TLE sets of deep-space orbits. I have incorporated a fix for one bug at the end of the Lyddane modification in the 'dpper' section of the Deep routine, as suggested by Ron Matson.

There are also suggested fixes for the discrepancy in satellite position data at 0 epoch time, between SDP4 and SGP routines. I have not made any changes to the NORAD routines, as the fixes appear to be for newer, modified SGP4/SDP4 routines. I will leave this to Celestial Mechanics programming gurus to be safe!

Hidden bugs?

There may well be (even should be) some hidden bugs in the ported C source as I made a big effort to streamline the flow and structure of the FORTRAN routines, especially getting rid of all goto's. Although I have been careful with the changes, the TLE sets in NORAD's report do not result in program flow in all the branches of control statements so that its not possible to check the integrity of the C source in all circumstances. However I have made sure that the results produced by my C routines agree to the 5th or 6th digit of NORAD's examples.

The most complicated part of the NORAD routines is the 'dpsec' part of the Deep routine where most of the changes to flow control and structure were made. This is were bugs affecting the deep-space routines may be hiding. I have conducted tests using KD2BD's PREDICT tracker using modified tle sets to force program flow through all the branches of if() statements and after fixing a number of bugs, I have close agreement with predict with a wide variety of orbital element sets. Still, there is no guarantee that some circumstances will not trigger a hidden bug.

Using the sgp4sdp4 package:

In order to use the ephemeris functions in sgp4sdp4 you will need to #include the sgp4sdp4.h header in your own source files. There are comments in all files describing the various functions and there use. There are also comments in the main() function describing the steps needed to get results from the package.

The routines that calculate satellite position (SGP4 and SDP4) all have the same interface as follows: (double tsince, tle_t *tle, vector_t *pos, vector_t *vel ).

tsince is the time interval in minutes since epoch time.

tle_t *tle is a pointer to a structure that holds the TLE set of the satellite. Please see sgp4sdp4.h for details.

vector_t *pos, vector_t *vel are structures holding the calculated Cartesian position x, y, z and velocity xdot, ydot, zdot data for the satellite. Please see sgp4sdp4.h for details.

Please note that all three arguments are safer declared static if they are declared outside the main() function.

All the flags controlling program flow must be cleared before a new TLE set is used or when a different ephemeris function is called. This is done by using ClearFlags(ALL_FLAGS); See main.c for details.

Disclaimer:

I have ported the sgp-plb Pascal routines to C so that I can use them in my satellite tracking projects. I am releasing this source-code in the hope that other developers can benefit, as I have benefitted from available open source software.

I can make no guarantee explicit or implicit as to the integrity and usability of these software modules and I cannot be held responsible for any damage or loss incurred by using them. Use the material in this package at your own risk.

References:

Dr. TS. Kelso maintains an excellent web-site with a lot of information and software for tracking celestial objects. A pdf version of the NORAD Spacetrack report #3 is also included: http://celestrack.com/

Change Log:

Version 0.1: Was the first relased after local bug-fixing.

Version 0.2: Function Date_Time was re-written to include calculation of tm_wday and tm_isdst members in the struct tm type value it returns.

Version 0.3: A suggested modification to the 4-quadrant AcTan() function was incorporated in order to make it agree with the original NORAD code. Thanks to Mr. Ed Savage for this.

Version 0.4: Made changes to the source code after checking with cppcheck and clang analyzer, mainly to improve style.

Neoklis Kyriazis August 31 2001.