
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 Rom 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 norad.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 norad.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.

Neoklis Kyriazis  <neoklis@my-deja.com>   August 31  2001.
