sattools/README-upstream.md

Satellite Tracking Toolkit

sattools is a collection of tools to facilitate photographic and video satellite tracking.

Installation

Requirements

The following software and libraries are required to compile sattools:

• gfortran
• gcc
• make
• git
• wcslib-dev
• libgsl-dev
• pgplot5
• libpng-dev
• libx11-dev
• libjpeg-dev
• libexif-dev
• dos2unix
• sextractor

On Debian/Ubuntu, these can be installed with sudo apt install git make dos2unix sextractor wcslib-dev pgplot5 libgsl-dev gfortran libpng-dev libx11-dev libjpeg-dev libexif-dev.

Build and install qfits

wget -c ftp://ftp.eso.org/pub/qfits/qfits-5.2.0.tar.gz
gunzip -c qfits-5.2.0.tar.gz | tar xvf -
cd qfits-5.2.0
chmod +w src/xmemory.c
sed -i -e "s/swapfd = open(fname, O_RDWR | O_CREAT);/swapfd = open(fname, O_RDWR | O_CREAT, 0644);/g" src/xmemory.c
./configure
make
sudo make install

The qfits code can also be obtained from https://spacecruft.org/spacecruft/qfits

Clone and install sattools

git clone https://github.com/cbassa/sattools.git
cd sattools
make

Setup environment variables

You will need to set the following environment variables to run sattools. Add these to a login file such as .bashrc.

• ST_COSPAR COSPAR observing site number,use 9990 if you do not have one. Add your site information to $ST_DATADIR/data/sites.txt.
• ST_DATADIR path to sattools directory (e.g. $HOME/software/sattools)
• ST_TLEDIR path to TLE directory (e.g. $HOME/tle)
• ST_OBSDIR path to observations directory (e.g. $HOME/satobs)
• ST_LOGIN optional space-track.org login info for TLE download (of the form ST_LOGIN="identity=username&password=password")

Final configuration steps

Add the sattools directory with executables to your PATH variable. On Ubuntu this is .profile and should be of the form PATH=<path_to_sattools>:$PATH.

Then reload the .profile file with source $HOME/.profile.

Try to download TLEs using tleupdate, which should now exist in your PATH variable.

Miscellaneous setup notes

• If you have multiple capture devices you will need to add a /etc/udev/rules.d/99-server.rules file to add symlinks and use them to address a particular camera. sattools will automatically select the camera that is scheduled for each observation. You may use a command such as udevadm info -a -n /dev/video0 to get your capture device attributes and use that to create the rules file. A sample rules file is available as guide in data/. Note that symlinks to the rules file do not work, the rules file must be modified to suit your needs and copied to /etc/udev/rules.d/
• You should install NTP support on the system and configure time/date to automatically synchronize to time servers.

Tools

• skymap: Vizualize satellites on a map of the sky. Example usage:

  • Compute and plot the path of a satellite (NORAD ID 43145), using a TLE from an input file ($ST_TLEDIR/classfd.tle) for a site (COSPAR ID 4171) at a date/time (2019-12-01T17:42:00) while looking at a particular RA/Dec (01h00m00s, +30d00m00s).

  skymap -s 4171 -t 2019-12-01T17:42:00 -c $ST_TLEDIR/classfd.tle -i 43145 -R 01:00:00 -D 30:00:00
  

• tleinfo: Display information about a set of TLEs. Example usage:

  • List values (SATNO, YEAR DOY, INCL, ASCN, ARGP, MA, ECC, MM) of the TLEs in the file bulk.tle: tleinfo -H -1
  • List orbital parameters (SEMI, PERIGEE, APOGEE, PERIOD, ECC) of the TLEs in the file bulk.tle: tleinfo -H -1 -a
  • Show human-readable info of the TLE for object 74001: tleinfo -i 74001 -f

• faketle: Calculate a TLE based on given orbit/launch parameters. Example usage:

  • Assuming a standard GTO launch from Cape Canaveral (latitude 28.5°N), GTO insertion burn (10° E, 0° N) at south-bound equator crossing +1655 seconds after launch, launch at 2019-02-22T01:45:00, perigee/apogee heights 258/59998 km, the pre-launch TLE can be generated with

    faketle -t 2019-02-22T01:45:00 -d 1655 -q 258 -Q 59998 -I 28.5 -m 0 -w 180 -n 10
    

• pass : Calculate the next passes above a given COSPAR site. Example usage:

  • List all ISS passes (NORAD ID 25544) at Dwingeloo Telescope (COSPAR site ID 9998) for the next 10 hours (3600 seconds) based on the TLE in catalog.tle (drop -a to only show the visible passes)

    pass -i 25544 -s 9998 -l 36000 -c $ST_TLEDIR/catalog.tle -a
    

  • Append -P in order to invoke skymap to plot a skymap and the sky track for each predicted pass

• satmap: Visualize satellite tracks on a map of Earth Example usage:

  • Show the ground track of all satellites in ST_TLEDIR/classfd.tle (for roughly 1.3 orbits from now on)

    satmap
    

• satorbit: Show a 3D representation of the earth, the current position, footprint and orbit of the selected object Example usage:

  • Show ISS position, footprint and orbit

    satorbit -i 25544 -c $ST_TLEDIR/catalog.tle
    

• launchtle: This tool takes an input TLE and launchtime and then corrects the epoch of the TLE for the new launch time, and adjusts the right ascension of the ascending node for how much it would have changed between the old and new launch time. Example usage:

  • Use the given pre-launch TLE of object 70002 (stored in prelaunch.tle) associated with the original launch time of 2018-11-11T03:00:00Z to correct for the new launch time at 2018-11-11T05:00:00Z and store it with a new identifier (70003 here):

    launchtle -c prelaunch.tle -i 70002 -t 2018-11-11T03:00:00 -T 2018-11-11T05:00:00 -I 70003
    

• tleupdate: Update the local database of TLEs from various sources (Space-Track, inttles and classfd.zip). Usage:

  tleupdate