(NOTE: This page is slightly modified from its original so as to fit the envirnonment. Many links do not work well. Download of tle2azel code is redirected to our site.)

1. PURPOSE

(What do you know, a program similar to this one exists already with the exact same name! https://sourceforge.jp/projects/tle2azel/)

This program reads in a NASA two line elements (TLE) and uses an SGP4/SDP4 propagator to propagate the elements. tle2azel is built on pyephem, which is based on xephem's computation engine. This code can thus read files in ephem database (edb) format also.

The code runs in two modes:

  1. Table generation - Generate output tables in user-specified format
  2. Visibility - Determines whether an object is visible given certain constraints

It is my hope that in the near future, one can use visibility results to do table generation, but as of the writing of this document, they must be run separately.

2. DOWNLOAD

Get the a copy here: http://www.opengps.net/gbt/tle2azel/download
(NOTE: THIS URL NO LONGER EXIST!)

(modified) Get the a copy here: tle2azel-1.13b.tar.gz

The newest version is 1.13b, released 19 September 2005.

3. REQUIRED SOFTWARE

4. USAGE

The program can be used in two modes: interactive and batch. With batch mode, all inputs are read from various files, while interactive mode gives the user an opportunity to enter information into a prompt.

Any of the parameters specified below will override the text files.

The program outputs to standard output.

tle2azel [options] [-V][-T] -i <tle-file>

TLE/EDB propagator/visibility tool built on pyephem
Version 1.12

MODES  ---------------
-V Visibility mode : Run in Visibility mode (ON by default)
-T Table mode      : Run in Table mode (OFF by default)
                     When both -V and -T mode is given, objects will
                     first be checked for visibility, then a table
                     will be generated for all visible objects
COMMON   -------
-i <filename>      : input file containing TLEs or EDB (must be specified)
-t [start],durat   : time: start time (UTC), duration (minutes)
                     start time can be left out, -tduration also valid
                     if start time left out, current time default
-n name            : name of object (must be in input file)
                     If not specified, will use ALL objects in TLE
-r pres,temp       : Refraction: pressure (mB), temperature (C).
                     Refraction corrections off by default (-r0,0)
-l location        : Location: lat,long,altitude(m)
 
VISIBILITY MODE -------
-p ra,dec          : Point of interest
                     ra  - hh:mm:ss or hh.ff
                     dec - dd:mm:ss or dd.ff
-d az,el           : Same as -p, except az,el (degrees)
                     az - dd:mm:ss or dd.ff
                     el - dd:mm:ss or dd.ff
-a angle           : Visible if within <angle> degrees of point
                     Angle can have format: 
                        -a 10 : 10 degrees
                        -a 10arcmin : 10 arc minutes
                        -a 10arcsec : 10 arc seconds
                     Keep in mind that TLE's have accuracies approx. < 10 arcmin
TABLE MODE -------------
-o <filename>      : output file name (stdout default)
-f <filename>      : output format file (config/format.txt default)
-s value           : step time in seconds. Overrides config/time.txt

5. INPUT FILES

5.1. location.txt

lat,long,altitude (in meters) example file:

38:25:59.265,-79:50:23.419,855.0
    or
38.433129166666667,-79.839838611111105,855.0

5.2. time.txt

start time (UTC), Duration (minutes), time step (in seconds)

example file:

2004/07/16 09:30:00.00,30,60

5.3. atmosphere.txt

temperature (in C), pressure (in mB)

example file:

15.0,1010.0

5.4. format.txt

'%s %s %f %f' % (str1,str2,float1,float2)

Format string used by python to print the output table when in Table Generation mode.

This is a python format string (called by python method eval(string)). Several values are possible here:

  1. Already formatted values:
    • date : prints date in format 'yyyy mm dd hh:mm:ss' (GBT compliant)
    • az : prints azimuth in format 'xxx.xxx' degrees (gbt compliant)
    • el : prints elevation in format 'xxx.xxx' degrees (gbt compliant)
    • ra : prints right ascension in format 'hh:mm:ss.ff' (gbt compliant)
    • dec: prints declination in format '+dd:mm:ss.f' (gbt compliant)
  2. Other available values

6. EXAMPLES

6.1. Visibility Mode

tle2azel determines 'visibility' of an object in three stages:

  1. Visible Objects - Does a coarse propagation of all objects to determine which are visible (positive elevation angle) in the time of interest
  2. Interesting Objects - Does a second pass using Visible Objects to determine which of these objects come 'close' to the area of interest. At this point it also records when the object enters and exits the area of interest (this may happen more than once)
  3. InArea Objects - The final stage - uses coarse enter/exit times recorded in the previous stage and does a 'fine step' to determine the boundary when the object enters/exits the area of interest.

tle2az makes sure that no objects can be missed (well, with a high degree of confidence) by using its mean motion (revolutions/day) when calculating the time step used for propagation.

Depending on amount of TLE entries, duration, etc. one might want to tweak the parameters VISIBLE_DEGSTEP, INTERESTING_DEGSTEP and AREA_POINTS. These parameters appear in the tle2azel.py source code as constants and are well documented in the source.

6.1.1. RA/DEC

Now, say we are staring at the big dipper, the star at the tip of the 'handle' is Alkaid. With a Right Ascension and Declination of 13h 47min 32,4sec and +49d 18' 48" respectively (according to this site).

Our criteria:

  1. Visibility mode: -V
  2. Must approach the big dipper: -p ra,dec
  3. Must approach big dipper to within 10 degrees: -a angle
  4. Location at Green Bank, WV,USA: -l lat,long,alt
  5. Start time and duration : -t start,duration
  6. Must not correct for atmospheric refraction: -r pres,temp
  7. Must be a bright object: -i <filename.txt>

To get TLE's of the 100 (or so) brightest objects, head over to celestrak.

tle2azel.py -V -p"13:47:32.4,49:18:48" -a 10
    -l"38:25:59.266,-79:50:23.423,855.46" -t"2005/07/25 04:00:00,60"
    -r0,0 -i catalog/visual.txt

If you have a location.txt,time.txt and atmosphere file then these can be left out and the command line simplifies to:

tle2azel.py -V -p"13:47:32.4,49:18:48" -a 10 -i catalog/visual.txt

Before showing the output, for those with really good telescopes, we can constrain the 'angle' around or point of interest to a few arc minutes by typing:

tle2azel.py -V -p"13:47:32.4,49:18:48" -a 10arcmin -i catalog/visual.txt

NOTE: It doesn't make much sense to go less than 10 arcmin, TLEs just aren't that accurate, see http://www.opengps.net/gbt/tle_accuracy

The output will look something like this (for the first command):

Total Objects       : 126
Visible Objects     : 32
Interesting Objects : 4
InArea Objects      : 3

Observer
--------
Lat,Long,Alt :   38:25:59.266, -79:50:23.423, 855.460 meters
Pressure,Temp:   0mB,0C
Start Time   :   2005/7/25 03:59:59 UTC
Stop Time    :   2005/7/25 04:59:59 UTC
Time step    :   1 second(s)

Files
-----
Input File   :   catalog/visual.txt
Output File  :   stdout
Output Format:   "%s %.4f %.4f" % (date,az,el)

Visibility Area

Right Ascension (hh:mm:ss) : 13:47:32.40
Declination (dd:mm:ss)     : 49:18:48.00
Angle (dd:mm:ss)     : 10:00:00.00


       NAME      DURAT     ENTER     EXIT    AZ    EL    RA    DEC    dAZ   dEL
                 (min)     (UTC)    (UTC)  (deg) (deg)  (hr)   (deg)  (deg/min)
      ------     -----     -----    ------ ----- -----  ----   -----  ---   ---

ISIS 1             2.5   04:23:48 04:26:17 308.81 34.40 13.99  49.16   9.1  -3.2
COSMOS 2180 R/B    1.4   04:25:11 04:26:35 306.88 35.21 14.15  47.97 -13.0   7.0
SL-16 R/B          1.0   04:03:11 04:04:12 312.74 26.77 12.80  49.01  16.1  -8.2
Total Objects
Indicates that 126 objects were found in the TLE file
Visible Objects
For the given time and duration, 32 of these objects were visible
Interesting Objects
Indicates that 4 of the 32 visible objects approach close to the area of interest, but a finer time-step must be used to tell for sure that they are in the field of interest.
InArea Objects
3 out of the 4 interesting objects actually are in our area of interest.

The program then proceeds to print some configuration settings and the 4 objects, indicating their az/el and ra/dec values for (enterTime-exitTime)/2 (Thus the position of the object when it has spent 50% of its time in the area of interest. The very last two columns dAZ and dEL shows the rate of change of angle (az and el) when the object is around the area of interest (in degrees per minute).

6.1.2. AZ/EL

Instead of using a RA/DEC, the same can be done by replacing the -p flag with -d. The following will find all bright objects in the time span in time.txt that will go right overhead:

tle2azel.py -V -d"0,90" -a 10 -i catalog/visual.txt

To find all visible GPS satellites within a 80 degree cone (thus 'horizon' is 10 deg up) starting at elevation 90 degrees (straight up), type

tle2azel.py -V -d"0,90" -a 80 -i catalog/gps-ops.txt

To find if PRN 03 is visible in this period, just add a -n PRN 03 option:

tle2azel.py -V -d"0,90" -a 80 -i catalog/gps-ops.txt -n "PRN 03"

6.2. Table Generation Mode

When running in table generation mode -T, tle2azel will compute az/el positions for all objects in the tle file. (If no -n criteria given). When the -V flag is also given (-V -T), then tle2azel will first determine which objects are visible and then compute az/el tables for all visible objects.

6.2.1. AZ/EL table

Let's see what IRIDIUM satellites are close to Alkaid and then generate an az/el table for it:

./tle2azel.py -V -p"13:47:32.4,49:18:48" 
    -a 10 -l"38:25:59.266,-79:50:23.423,855.46" 
    -t"2005/07/25 04:00:00,60" -i catalog/iridium.txt

Total Objects       : 92
Visible Objects     : 24
Interesting Objects : 6
InArea Objects      : 2

Observer
--------
Lat,Long,Alt :   38:25:59.266, -79:50:23.423, 855.460 meters
Pressure,Temp:   0mB,0C
Start Time   :   2005/7/25 03:59:59 UTC
Stop Time    :   2005/7/25 04:59:59 UTC
Time step    :   1 second(s)

Files
-----
Input File   :   catalog/iridium.txt
Output File  :   stdout
Output Format:   "%s %.4f %.4f" % (date,az,el)

Visibility Area

Right Ascension (hh:mm:ss) : 13:47:32.40
Declination (dd:mm:ss)     : 49:18:48.00
Angle (dd:mm:ss)     : 10:00:00.00


       NAME        DURAT    ENTER     EXIT    AZ    EL    RA    DEC    dAZ   dEL
                   (min)    (UTC)    (UTC)  (deg) (deg)  (hr)   (deg)  (deg/min)
      ------       -----    -----    ------ ----- -----  ----   -----  ---   ---

IRIDIUM 25           0.8 04:12:26 04:13:13 316.68 24.02 12.52  50.70  17.1  -5.0
IRIDIUM 76           1.0 04:02:57 04:03:57 317.02 29.85 12.90  53.77  20.9  -6.4

OK, it appears IRIDIUM 25 and IRIDIUM 76 are visible around that area, now let's instruct the program to generate a az/el table for IRIDIUM 25:

./tle2azel.py -T -l"38:25:59.266,-79:50:23.423,855.46"
    -t"2005/07/25 04:12:26,1" -s 10  
    -i catalog/iridium.txt -n "iridium 25"

Note that the only changes to the command line was to remove the -V flag (take it out of visibility mode`` and to add the -n iridium 25 flag (tell it only to propagate this satellite. Also the time period was changed based on our previous visibility results.

Object
------
Object name  :   IRIDIUM 25
Object epoch :   2005/7/19 07:21:20

Observer
--------
Lat,Long,Alt :   38:25:59.266, -79:50:23.423, 855.460 meters
Pressure,Temp:   0mB,0C
Start Time   :   2005/7/25 04:12:26 UTC
Stop Time    :   2005/7/25 04:13:26 UTC
Time step    :   10.0 second(s)

Files
-----
Input File   :   catalog/iridium.txt
Output File  :   stdout
Output Format:   "%s %.4f %.4f" % (date,az,el)


# OBJECT        :   IRIDIUM 25
# LAT,LONG,ALT  :   38:25:59.266, -79:50:23.423, 855.460 meters
# PRESSURE,TEMP :   0mB,0C
2005 07 25 04:12:26 299.5196 29.0334
2005 07 25 04:12:35 302.7371 28.3414
2005 07 25 04:12:45 305.8108 27.5780
2005 07 25 04:12:55 308.7351 26.7560
2005 07 25 04:13:05 311.5074 25.8876
2005 07 25 04:13:15 314.1284 24.9841
2005 07 25 04:13:25 316.6012 24.0557

6.2.2. RA/DEC table

Now to change the format of the output to RA/DEC, we do the following: Edit format.txt file and place the following string in it:

"%s %s %s" % (date,ra,dec)

Let's rerun this:

--- snip ---
2005 07 25 04:12:26 13:38:20.43 +39:45:21.0
2005 07 25 04:12:35 13:28:20.75 +41:56:09.5
2005 07 25 04:12:45 13:17:53.30 +43:58:46.5
2005 07 25 04:12:55 13:06:59.18 +45:52:43.6
2005 07 25 04:13:05 12:55:40.06 +47:37:40.5
2005 07 25 04:13:15 12:43:58.26 +49:13:25.1
2005 07 25 04:13:25 12:31:56.69 +50:39:52.5

Note how the RA/DEC is indeed within our area of interest.

6.2.3. Range/Velocity table

Say we want to print the object's range (km) and line of sight velocity (km/s), how would we do it? Well, according to the pyephem manual, we can use object.range and object.range_velocity to do this. These are in meters and meters/second respectively. Let's change to format string in format.txt to include this:

"%s %.4f %.4f %0.2f %0.2f" % (date,az,el, object.range/1000.0,object.range_velocity/1000.0)

Let's rerun and see the output:

--- snip ---
2005 07 25 04:12:26 299.5196 29.0334 1395.04 1.89
2005 07 25 04:12:35 302.7371 28.3414 1416.48 2.18
2005 07 25 04:12:45 305.8108 27.5780 1440.93 2.45
2005 07 25 04:12:55 308.7351 26.7560 1468.23 2.71
2005 07 25 04:13:05 311.5074 25.8876 1498.22 2.96
2005 07 25 04:13:15 314.1284 24.9841 1530.74 3.19
2005 07 25 04:13:25 316.6012 24.0557 1565.63 3.40

These Iridiums are fast movers!

OpenGPS | University of Colorado

U N I V E R S I T Y  O F  C O L O R A D O 

stephan.esterhuizen@colorado.edu
http://www.pythion.com/
Copyright © 2006 - The Regents of the University of Colorado

Last modified: Thursday, 18-Aug-2005 21:53:52 MDT