1  
  2  Introduction:
  3  =============
  4  
  5  This package contains a partial port to C of Dr TS. Kelso's PASCAL library
  6  sgp4-plb26a. This library contains files with functions for calculating the
  7  position and velocity of a satellite using the NORAD SGP4 and SDP4 routines
  8  and from these the azimuth, elevation, range and range rate of same. Routines
  9  are also included for calculating the position of the sun and the illumination
 10  status and eclipse depth of the satellite.
 11  
 12  The port to C includes most of the sources needed for making the above 
 13  calculations and for reading and checking two-line Keplerian element sets
 14  (TLE's) from a file, as available from many sources on the Internet. Some of
 15  the files in the PASCAL library are PC-specific and have not been ported to C
 16  or they have been substituted or modified with some functions I developed
 17  myself. A simple main() function is included to demonstrate the use of the C
 18  sgp4/sdp4 library and functions for reading and testing a TLE set from a file.
 19  
 20  Contents:
 21  =========
 22  
 23  This package should contain the following files:
 24  
 25  1. This README file.
 26  
 27  2. The COPYING file with copyright details.
 28  
 29  3. sgp4sdp4.c: The source-code of the ported SGP4 and SDP4 routines and some
 30                 extra functions for testing and setting flow control flags.
 31  
 32  4. sgp_in.c: Functions for reading a TLE set from a file and verifying,
 33               converting and pre-processing the Keplerian element set.
 34  
 35  5. sgp_math.c: Various mathematical functions used by other routines.
 36  
 37  6. sgp_obs.c: Functions for calculating the geodetic position of the observer
 38                and converting the ECI position and velocity of a satellite to
 39                observer-centered azimuth, elevation, range and range rate. Also
 40                calculating the observer-centered position of the sun.
 41  
 42  7. sgp_time.c: Functions needed to calculate and convert time in various 
 43                 formats, e.g. Julian, calendar etc.
 44  
 45  8. solar.c: Functions for calculating the position of the sun.
 46  
 47  9. main.c: A basic main() function to demonstrate the use of the sgp4/sdp4
 48             library to read a TLE set and calculate and print satellite 
 49             predictions.
 50  
 51  10. sgp4sdp4.h: A header file that should be #include'd in all source files
 52                  using this library.
 53  
 54  11. Makefile: A simple makefile for building the 'ephem' binary.
 55  
 56  
 57  Building and testing:
 58  =====================
 59  
 60  Run make in the sgp4sdp4 source directory to compile the binary executable.
 61  Run ephem to start the test program, but please note you need to include a
 62  file in the same directory including TLE sets in NASA format as available 
 63  on the Internet. There are fresh sets uploaded regularly at Dr TS Kelso's
 64  site at www.celestrak.com . Please note that you should edit main.c to 
 65  enter the directory path for this file, it is currently set at amateur.txt
 66  and to also enter the observer's geodetic coordinates (lat and lon in rads
 67  and altitude in km). This is only a skeleton test application!
 68  
 69  Known bugs: 
 70  ===========
 71  
 72  It appears that the original NORAD routines have been modified to
 73  correct some discrepancies in the calculated satellite position data,
 74  at least for some TLE sets of deep-space orbits. I have incorporated
 75  a fix for one bug at the end of the Lyddane modification in the 
 76  'dpper' section of the Deep routine, as suggested by Rom Matson.
 77  
 78  There are also suggested fixes for the discrepancy in satellite
 79  position data at 0 epoch time, between SDP4 and SGP routines. I have
 80  not made any changes to the NORAD routines, as the fixes appear to be
 81  for newer, modified SGP4/SDP4 routines. I will leave this to Celestial
 82  Mechanics programming gurus to be safe!
 83  
 84  Hidden bugs?
 85  ============
 86  
 87  There may well be (even should be) some hidden bugs in the ported C
 88  source as I made a big effort to streamline the flow and structure of
 89  the FORTRAN routines, especially getting rid of all goto's. Although
 90  I have been careful with the changes, the TLE sets in NORAD's report
 91  do not result in program flow in all the branches of control statements
 92  so that its not possible to check the integrity of the C source in all
 93  circumstances. However I have made sure that the results produced by my
 94  C routines agree to the 5th or 6th digit of NORAD's examples.
 95  
 96  The most complicated part of the NORAD routines is the 'dpsec' part of
 97  the Deep routine where most of the changes to flow control and 
 98  structure were made. This is were bugs affecting the deep-space 
 99  routines may be hiding. I have conducted tests using KD2BD's PREDICT
100  tracker using modified tle sets to force program flow through all the
101  branches of if() statements and after fixing a number of bugs, I have
102  close agreement with predict with a wide variety of orbital element sets.
103  Still, there is no guarantee that some circumstances will not trigger a
104  hidden bug.
105  
106  Using the sgp4sdp4 package:
107  ===========================
108  
109  In order to use the ephemeris functions in sgp4sdp4 you will need to
110  #include the sgp4sdp4.h header in your own source files. There are
111  comments in all files describing the various functions and there use.
112  There are also comments in the main() function describing the steps
113  needed to get results from the package.
114  
115  The routines that calculate satellite position (SGP4 and SDP4) all 
116  have the same interface as follows:
117  (double tsince, tle_t *tle, vector_t *pos, vector_t *vel ).
118  
119  tsince is the time interval in minutes since epoch time.
120  
121  tle_t *tle is a pointer to a structure that holds the TLE set of
122  the satellite. Please see norad.h for details.
123  
124  vector_t *pos, vector_t *vel are structures holding the calculated
125  Cartesian position x, y, z and velocity xdot, ydot, zdot data
126  for the satellite. Please see norad.h for details.
127  
128  Please note that all three arguments are safer declared static if
129  they are declared outside the main() function.
130  
131  All the flags controlling program flow must be cleared before a new
132  TLE set is used or when a different ephemeris function is called. 
133  This is done by using ClearFlags(ALL_FLAGS); See main.c for details.
134  
135  Disclaimer:
136  ===========
137  
138  I have ported the sgp-plb Pascal routines to C so that I can use them
139  in my satellite tracking projects. I am releasing this source-code in 
140  the hope that other developers can benefit, as I have benefitted from
141  available open source software. 
142  
143  I can make no guarantee explicit or implicit as to the integrity and
144  usability of these software modules and I cannot be held responsible
145  for any damage or loss incurred by using them. Use the material in 
146  this package at your own risk.
147  
148  References:
149  ===========
150  
151  Dr. TS. Kelso maintains an excellent web-site with a lot of information
152  and software for tracking celestial objects. A pdf version of the 
153  NORAD Spacetrack report #3 is also included: http://celestrack.com/
154  
155  Change Log:
156  ================
157  
158  Version 0.1: Was the first released after local bug-fixing.
159  
160  Version 0.2: Function Date_Time was re-written to include calculation
161  of tm_wday and tm_isdst members in the struct tm type value it returns.
162  
163  Version 0.3: A suggested modification to the 4-quadrant AcTan() function
164  was incorporated in order to make it agree with the original NORAD code.
165  Thanks to Mr. Ed Savage for this.
166  
167  Neoklis Kyriazis  <neoklis@my-deja.com>   August 31  2001.