satellite prediction routines

Last modified: Wed Oct 25 13:19:35 2017.


List of Routines


Routine Descriptions

SAT0INTRO - INTRO TO USING THE AO SATELLITE PREDICTION ROUTINES.

[Next Routine] [List of Routines]
NAME:
sat0intro - Intro to using the ao satellite prediction routines.
   
   The  ao idl satxxx routines will predict passes of satellites over AO.
They interface to the predict program:
         PREDICT: A satellite tracking/orbital prediction program         
         Project started 26-May-1991 by John A. Magliacane, KD2BD       
                       Last update: 14-May-2006                     
   The routines use two line element sets (tle's) that are updated daily
at the observatory. They can only be run at AO since they are calling
the predict program which is not distributed with phil's idl routines.

 Getting started:
   @phil
   @satinit
   satpassplt,/gps
   .. will plot the gps constellation passes for the current time.

 the routines currently available can be found via:
 explain,satdoc
  .. it outputs:

satdoc - routine list (single line)

 normal routines called by user
  satdoc           - routine list (single line)
1.satinfo          - return tle entry for all satellites
2.satpass          - compute satellite pass at AO
3.satpassconst     - compute satellite pass for a constellation
4.satpassplt       - plot all sat of  constellation as they pass over AO

 utility routines used by above routines (and be user if they want)

satfindtle       - find tle file for satellite name
satsetup         - return setup info for sat routines
satinptlefile    - input an entire tle file
satlisttlefiles  - return list of tle files

*************************************************************
1. satinfo -  to find out which satellites we have tle files for:
*************************************************************
   return a structure holding info on all satellites we know about:

  n=satinfo(satI)
help,satI,/st
   NM              STRING    'GIOVE-A'
   TLEFILE         STRING    '/share/megs/phil/predict/tle/galileo.tle'
   TLE             STRUCT    ->  Array[1]

   .. The tle info for each satellite
help,satI.tle,/st
   SATNM           STRING    'GIOVE-A'
   SATNUM          INT          28922
   SATCLASS        STRING    'U'
   LAUNCHYR        LONG              2005
   LAUNCHNUM       INT             51
   LAUNCHPIECE     STRING    'A  '
   EPOCHYR         LONG              2008
   EPOCHDAY        DOUBLE           260.32344
   TMDER1          DOUBLE       2.2000000e-07
   TMDER2          STRING    ' 00000-0'
   DRAG            DOUBLE           10000.000
   EPHTYPE         STRING    '0'
   ELMNUM          INT            394
   INCLINATION     DOUBLE           56.055200
   RAASCNODE       DOUBLE           164.58550
   ECCENTRICITY    STRING    '0007843'
   ARGOFPERIGEE    DOUBLE           331.59930
   MEANANOMALY     DOUBLE           28.417500
   MEANMOTION      DOUBLE           1.7019477
   REVNUM          LONG              1690
   LINES           STRING    Array[3]

************************************************************
2. satpass - Compute a single pass for a 1 satellite:
************************************************************
 npts=satpass(satNm,passI,hhmmss=hhmmss,yymmdd=yymmdd)
   Returns and array passI[npts] that holds info for each point of the
pass.

 help,passI
 JD       DOUBLE       2.7793265e+08 .. jd for this point
 SECS     DOUBLE       1.2221659e+09 .. secs 1970 for this point
 AZ       DOUBLE           204.47500 .. source az for pnt
 ZA       DOUBLE           89.974000 .. za for this pnt
 RAHR     DOUBLE          0.23571587 .. J2000 right ascension in hours for ;
                                        this point
 DECD     DOUBLE          -66.452344 .. J2000 declination in deg for this point
 PHASE    LONG               226     .. phase in orbit 0..255
 LAT      LONG               -50     .. north lattitude of sat sub orbit point
 LON      LONG               105     .. west longitude  of sat sub orbit point
 RANGEKM  LONG             25677     .. slant range in kilometers to satellite
 ORBITNUM LONG              4142     .. orbit number. increments once each orbit.  

************************************************************
3. Compute satellite passes for a constellation of satellites
************************************************************
 npts=satpassconst(satAr,/gps)
   Returns satAr[31]. Each entry is the pass info for a single satellite
in the gps constellation.

help,satAr[0],/st
   NPNTS           LONG       92   .. pnts in pass for this satellite
   SATNM           STRING    'GPS16' .. sat Nm
   ZAMIN           FLOAT           18.8350 .. min za for pass
   SECSMIN         DOUBLE       1.2217464e+09     .. time for minza secs1970
   P               STRUCT    -> SATPASS Array[150] .. pnts in pass

 Note that satAr[0].p[150] is dimensioned as 150 but there are only
satAr[0].npts = 92 valid points in the array. The number of points
varies with each satellite pass.

************************************************************
4. plot passes for  a  satellite constellation
************************************************************
   satpassplt,yymmdd=yymmddd,hhmmss=hhmmss,satAr=satAr,v=v,/glonass
  Will plot the az,za for each of the glonass satellites for the given time.
The passInfo can be returned in satAr if you want. You can control
the vertical scale with v. 
   To get hardcopy with za 0 to 20 for 23sep08 141500 AST (when the
next L3 test is scheduled) you could:

pscol,'gpspass_1.ps',/full
hhmss=141500
yymmdd=080923
v=[0,20]
satpassplt,yymmdd=yymmdd,hhmmss=hhmmss,v=v,/gps
hardcopy
x
ldcolph

 Note that the azimuth plotted is the source azimuth.
WARNINGS:
	- the keyword: tlefile=  or tledir= keyword has been
     added to let you use non-standard locations for the
     tlefiles. I've noticed that predict only allows
     up to 48 characters for the entire filename..
     So don't use long path/filenames...

************************************************************
 for more info use
 explain,satroutine

(See /pkg/rsi/local/libao/phil/sat/sat0intro.pro)


SATCMPANGLE - COMPUTE ANGLE BETWEEN RA,DEC,JD AND SATELLITES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satcmpangle - compute angle between ra,dec,jd and satellites
SYNTAX: satcmpangle,raHr,decDec,jd,passAr,distI
ARGS:
raHr[m]:	float	right ascension hours to use
decDeg[m]: float  declination in degrees
jd[m]  :   double  julian date
passAr[n]:{}   array of satellite constellation info returned
               from satpassplt()
RETURNS:
distI[m,n]: float distance from satellite to request position
DESCRIPTION:
   Compute the angle in degrees between the requested ra,dec (j2000),jd and the
location of the satellites in passAr. 
passAr comes from satpassplt( ...satAr=satAr,/radec). Be sure that the 
/radec keyword is set in the call to satpassplt so that the ra,dec gets
computed..

(See /pkg/rsi/local/libao/phil/sat/satcmpangle.pro)


SATDOC - ROUTINE LIST (SINGLE LINE)

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satdoc - routine list (single line)

sat0intro        - Intro to using the ao satellite prediction routines.
satcmpangle      - compute angle between ra,dec,jd and satellites
satdoc           - routine list (single line)
satdocnames      - list of routine names
satfindtle       - find tle file for satellite name
satinfo          - return tle entries for all satellites
satinptlefile    - input an entire tle file
satlisttlefiles  - return list of tle files
satpass          - compute satellite pass at AO
satpassconst     - compute satellite passes for a constellation
satpassplt       - plot a satellite constellation passes over AO
satsetup         - return setup info for sat routines

(See /pkg/rsi/local/libao/phil/sat/satdoc.pro)


SATDOCNAMES - LIST OF ROUTINE NAMES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satdocnames - list of routine names

sat0intro       satcmpangle     satdoc          satdocnames     satfindtle
satinfo         satinptlefile   satlisttlefiles satpass         satpassconst
satpassplt      satsetup        

(See /pkg/rsi/local/libao/phil/sat/satdocnames.pro)


SATFINDTLE - FIND TLE FILE FOR SATELLITE NAME

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satfindtle - find tle file for satellite name
SYNTAX: tlefile=satfindtle(satNm)
ARGS:
satNm: string  name of satellite to search for.

RETURNS:
tlefile:string name of tle file. '' if not found

DESCRIPTION:
   This routine will look for a tle file based on the satNm

(See /pkg/rsi/local/libao/phil/sat/satfindtle.pro)


SATINFO - RETURN TLE ENTRIES FOR ALL SATELLITES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satinfo - return tle entries for all satellites
SYNTAX: nsat=satinfo(satI,tledir=tledir,yymmdd=yymmdd)
ARGS:
KEYWORDS:
tledir: string  directory to for tle's
             def: /share/megs/predict/tle
yymmdd: long   : if supplied, then search for this date in the  archive.
RETURNS:
nsat: long    number of satellites we found
satI[nsat]: {} array of struct holding satinfo

DESCRIPTION:
   Return info on all of the satellites we have tle's for.
The returned structure contains:
help,satI,/st
   NM              STRING    'GIOVE-A'
   TLEFILE         STRING    '/share/megs/phil/predict/tle/galileo.tle'
   TLE             STRUCT    ->  Array[1]

   .. The tle info for each satellite
help,satI[0].tle,/st
   SATNM           STRING    'GIOVE-A'
   SATNUM          INT          28922
   SATCLASS        STRING    'U'
   LAUNCHYR        LONG              2005
   LAUNCHNUM       INT             51
   LAUNCHPIECE     STRING    'A  '
   EPOCHYR         LONG              2008
   EPOCHDAY        DOUBLE           260.32344
   TMDER1          DOUBLE       2.2000000e-07
   TMDER2          STRING    ' 00000-0'
    DRAG            DOUBLE           10000.000
   EPHTYPE         STRING    '0'
   ELMNUM          INT            394
   INCLINATION     DOUBLE           56.055200
   RAASCNODE       DOUBLE           164.58550
   ECCENTRICITY    STRING    '0007843'
   ARGOFPERIGEE    DOUBLE           331.59930
   MEANANOMALY     DOUBLE           28.417500
   MEANMOTION      DOUBLE           1.7019477
   REVNUM          LONG              1690
   LINES           STRING    Array[3]

(See /pkg/rsi/local/libao/phil/sat/satinfo.pro)


SATINPTLEFILE - INPUT AN ENTIRE TLE FILE

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satinptlefile - input an entire tle file
SYNTAX: nsat=satinptlefile(filenm,tleAr,tledir=tledir)
ARGS:
filenm: string name of tle file to input. If no / in filename then
               prepend default directory.
KEYWORDS:
tledir:  string  if supplied then use this directory to  look for tle file
RETURNS:
nsat: long  number of satellites found in the file
satAr[nsat]:{}    array of tle entries found in file

DESCRIPTION:
   Input all of the satellites from a tle file
 for tle field definitions see:
 http://celestrak.com/columns/v04n03/#FAQ01

(See /pkg/rsi/local/libao/phil/sat/satinptlefile.pro)


SATLISTTLEFILES - RETURN LIST OF TLE FILES

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satlisttlefiles - return list of tle files
SYNTAX: nfiles=satlisttlefiles(tlefiles,tledir=tledir,suf=suf)
ARGS:

KEYWORDS:
tledir:  string  if supplied then the directory to  look for tle file
suf   :  string  suffix for tle files. by default use txt,tle.
yymmdd: long     if supplied, then look in archive for data for this date.

RETURNS:
nfiles: long    number of files we found
tlefiles[nfiles]: array of files we founds

DESCRIPTION:
   get a list of tle files in the requested directory (default is the
default tle directory).
  If tledir is supplied then search this directory
for any tle files.
  if yymmdd= is supplied then search archive for data for this date.
The current search looks for tle data updated on this date. It may return
nothing if a tle file was not modified on this date (need to broaden search
criteria).
  it will have to run updatetle.sc on each file found
  data is written to tmp directory.
 NOTE:
   yymmdd and tledir are mutually exclusive...

(See /pkg/rsi/local/libao/phil/sat/satlisttlefiles.pro)


SATPASS - COMPUTE SATELLITE PASS AT AO

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satpass - compute satellite pass at AO
SYNTAX: npts=satpass(satNm,passI,yymmdd=yymmdd,hhmmss=hhmmss,$
                     jd=jd,nsecs=nsecs,tlefile=tlefile,radec=radec)
ARGS:
 satNm: string     name of satellite, must match  name in tle file

KEYWORDS:
yymmdd:  long  date (AST) for pass.
hhmmss:  long  hour,min,sec of day (AST).If not provided find 
               first pass of day.
jd    :  double time for the pass
nsecs : long   if provided then the number of secs to report
               If not provided then do the entire pass. If 
               nsecs is provided, then the resolution is 1 second.
tlefile: string filename holding the two line elements for this sat.
               if '/' not in name then prepend default path.
               If this is not supplied then the program will search
               all tle files for this satellite name
radec:         If set (/radec) then include the ra,dec for each az,za position.
               This takes a little longer to run.
               
RETURNS:
   npts: long  > 0 number of entries in passI. 
               < 0 error occurred.
passI[npts]: structure holding pass info for each time point.
DESCRIPTION:
   Compute az,za,ra,dec for satellite  pass over ao for a given day.
Use yymmdd,hhmmss   or jd to specify when the passes should occur. If
no date/time is provided use the current time. 
Passes will be computed that are above the horizon for the specified time.

(See /pkg/rsi/local/libao/phil/sat/satpass.pro)


SATPASSCONST - COMPUTE SATELLITE PASSES FOR A CONSTELLATION

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satpassconst - compute satellite passes for a constellation
SYNTAX: npts=satpassconst(passAr,yymmdd=yymmdd,hhmmss=hhmmss,jd=jd,$
	 		     gps=gps,iridium=iridium,galileo=galileo,beidou=beidou,$
                globalstar=globalstar,$
	             radec=radec,verb=verb,tlefile=tlefile)
	                  
ARGS:

KEYWORDS:
gps:           if set then use the gps constellations
iridium:       if set then use the iridium constellations
glonass:       if set then use the glonass constellations
galileo:       if set then use the galileo constellations
beidou :       if set then use the chinese beidou constellations
globalstar:    if set then use the globalstar constellations
tlefile: string if provided then read all sat from this tle file.
               If you don't put a leading / then it will use
               the default location.
satNmAr[]:string if tlefile is supplied then only include
               satellites names in satNmAr[]
yymmdd:  long  date (AST) for pass.
hhmmss:  long  hour,min,sec of day (AST).If not provided find 
               first pass of day.
    jd:  double if provided then use this for the pass time.
 nsecs:  long  Instead of entire pass, compute the location
               once a second started at requested time for 
               nsecs. This gives fixed time resolution.
               .. warning.. if a satellite is not visible during
                  the requested time, predict loops forever..
 radec:        if set then include ra,dec for each az,za position.
  verb:        if set then print tlefiles as they are input
               
RETURNS:
   nsat: long  > 0 number of satellites found
               < 0 error occurred.
passAr[nsat]: array of structures holding pass info for each satellite
DESCRIPTION:
   Compute az,za,ra,dec for satellites in the specified constellation
as the specified time. The all passes should be above the horizon at the
specified time. 

(See /pkg/rsi/local/libao/phil/sat/satpassconst.pro)


SATPASSPLT - PLOT A SATELLITE CONSTELLATION PASSES OVER AO

[Previous Routine] [Next Routine] [List of Routines]
NAME:
satpassplt - plot a satellite constellation passes over AO
SYNTAX: satpassplt,yymmdd=yymmdd,hhmmss=hhmmss,jd=jd,satAr=satAr,v=v,$
                   gps=gps,iridium=iridium,glonass=glonass,galileo=galileo,$
                   beidou=beidou,$
                   globalstar=globalstar,tlefile=tlefile,wait=wait,radec=radec,$
                   samepage=samepage,ln0=ln0,usearchive=usearchive
ARGS:
KEYWORDS:
   yymmdd: long    if supplied then the AST date for the pass
   hhmmss: long    if supplied then the AST time for the pass  
   jd    : double  if supplied then the julian date for the pass
   nsecs : long    instead of plotting an entire pass, plot nsecs
                   points starting at requested time spaced by 1 sec.
                   .. warning. If a satellite is not visible during
                      this time, predict seems to loop forever...
   v[2]  : float   if supplied then then min, max za for plotting.
     gps :         if set then plot the gps constellation
  iridium:         if set then plot the iridium constellation
  glonass:         if set then plot the glonass constellation
 galileo :         if set then plot the galileo constellation
 beidou  :         if set then plot the beidou constellation
globalstar:        if set then plot the globalstar constellation
tlefile   :string  if provided then ignore constellation names. Plot
                   all satellites in this file
satNmAr[] :string  if supplied with tlefile then only plot these sat
                   names. 
wait      :        if set then wait for keyboard input before plotting
                   the next page. This is only needed for iridium and
                   globalstar (they have more than 32 satellites).
radec     :        If set then include the ra,dec in the returned info
                   This slows down the routine a little. This is only
                   used if satAr is supplied to return the info in.
samepage  :        if set then continue plotting on the current page
                   useful for constellation with only a few satellites
ln0       : int    first linenumber for display of first sat name.
                   useful if you are using samepage. Then you can
                   have the sat name appear in the frame you are writing in.
                  values .. about 0 to 31
usearchive: int    if set then search archive for date. Without this, it uses 
                   the current tle to the date,time.

RETURNS:
satAr[nsat]: {}  strucuture containing satellite info for each pass and 
                 point within a pass.
DESCRIPTION:
   Plot the passes over ao for the specified constellation at a given time. 
The time can be specified by yymmdd,hhmmss keywords or jd (julian date). If no
date is specified then the current time is used. 

   A satellite pass is included in the plot if any portion of a pass is
 above the AO horizon at the specified time.

   Only one constellation can be specified per call. If no constellation
is specified then gps is used.
   
   A maximum of 32 satellites can be plotted per page. If you want to
see each page as it is generated either make a hardcopy, or use the
/wait keyword to wait before plotting the next page.

 satAr is an array satAr[31] .. one for each satellite.

L> help,satAr,/st
   NPNTS     LONG      92      .. number of points in pass (valid pnts in P[])
   SATNM     STRING    'GPS16' .. name of satellite
   ZAMIN     FLOAT     18.8150 .. minimum za for this pass
   SECSMIN   DOUBLE    1.2221771e+09 .. time secs 1970 for za Min.
   P         STRUCT    SATPASS Array[150] .. array of points for each pass. Only the first
                                  satAr[i].npnts are valid for this pass.

 the pass structure P contains:

IDL> help,satAr.p,/st
 JD       DOUBLE       2.7793265e+08 .. jd for this point
 SECS     DOUBLE       1.2221659e+09 .. secs 1970 for this point
 AZ       DOUBLE           204.47500 .. source az for pnt
 ZA       DOUBLE           89.974000 .. za for this pnt
 RAHR     DOUBLE          0.23571587 .. J2000 right ascension in hours for this point
 DECD     DOUBLE          -66.452344 .. J2000 declination in deg for this point
 PHASE    LONG               226     .. phase in orbit 0..255
 LAT      LONG               -50     .. north lattitude of sat sub orbit point
 LON      LONG               105     .. west longitude  of sat sub orbit point
 RANGEKM  LONG             25677     .. slant range in kilometers to satellite
 ORBITNUM LONG              4142     .. orbit number. increments once each orbit.


EXAMPLE:
idl
@satinit
yymmdd=080923
hhmmss=141500
satpassplt,yymmdd=yymmdd,hhmmss=hhmmss,satAr=satAr,/gps

(See /pkg/rsi/local/libao/phil/sat/satpassplt.pro)


SATSETUP - RETURN SETUP INFO FOR SAT ROUTINES

[Previous Routine] [List of Routines]
NAME:
satsetup - return setup info for sat routines
SYNTAX: satSetupI=satsetup()
ARGS: none
KEYWORDS: none
RETURNS:
satSetupI:{}   returns strucuture containing locations of various files/dir.

DESCRIPTION:
   Call satsetup() to get the default locations for files and
directories.

(See /pkg/rsi/local/libao/phil/sat/satsetup.pro)