- OCaml 89%
- Python 10%
- Shell 1%
contact #
Satellite pass prediction and contact window computation.
A ground station can only talk to a satellite in low Earth orbit while the
satellite is above its horizon. That happens a few times a day, for five to
ten minutes each time, so planning a downlink starts from the list of passes.
contact computes that list from a two-line element set (TLE). Each pass has
its acquisition of signal (AOS), its loss of signal (LOS), its peak elevation
and its duration. The library also gives the satellite's elevation and
azimuth at any instant, and tells whether it is in sunlight, penumbra or
umbra. Propagation uses sgp4 (the NORAD SGP4 model), and the
coordinate transforms come from coordinate.
The US Space Force publishes each satellite's mean orbital elements at one epoch as a TLE, two text lines of 69 characters. The elements are the inclination, the right ascension of the ascending node, the eccentricity, the argument of perigee, the mean anomaly, the mean motion and a drag term. They are fitted to SGP4, an analytical model that predicts position and velocity at another time and accounts for the Earth's oblateness and for atmospheric drag (Vallado et al., Revisiting Spacetrack Report #3, AIAA 2006-6753). If you propagate the same elements with a different model, the positions come out wrong.
To find passes, the library samples the elevation, every 30 seconds by
default. When two samples fall on either side of the minimum elevation, the
edge of the pass lies between them, at a root of the elevation minus that
minimum. Contact.crossing finds the root by false position, forcing a
bisection step every other iteration, and stops once the bracket is under
1 ms wide. Because of the forced bisection the bracket at least halves every
two evaluations, so a step of s costs at most 2 log2(s / 1 ms) elevation
evaluations per edge. With the default 30 s step that is 2 log2(30,000) =
2 x 14.9, about 30 evaluations, and the reported times do not depend on the
step. A pass that rises and sets between two samples is missed.
Installation #
Install with opam:
$ opam install contact
If opam cannot find the package, it has probably not reached the public
opam-repository yet. Add the overlay repository and install from there:
$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install contact
Usage #
The example below parses a TLE, places a ground station in Los Angeles and predicts the passes over the three days that follow. The element set is an idealised one for the ISS with epoch 2026-01-01, and the window starts at that epoch:
# let tle_string =
"ISS (ZARYA)\n\
1 25544U 98067A 26001.00000000 .00001764 00000+0 39538-4 0 9991\n\
2 25544 51.6416 45.0000 0008003 90.0000 0.0000 15.49560000 15" in
let tle = Result.get_ok (Sgp4.parse_tle_string tle_string) in
let la = Contact.ground_station ~lat:34.05 ~lon:(-118.25) ~alt:0.071 in
let passes = Contact.predict tle la ~duration_days:3.0 in
List.length passes
- : int = 15
A pass holds its AOS and LOS as Unix timestamps and as ISO-8601 strings, with its peak elevation in degrees and its length in seconds:
# let tle_string =
"ISS (ZARYA)\n\
1 25544U 98067A 26001.00000000 .00001764 00000+0 39538-4 0 9991\n\
2 25544 51.6416 45.0000 0008003 90.0000 0.0000 15.49560000 15" in
let tle = Result.get_ok (Sgp4.parse_tle_string tle_string) in
let la = Contact.ground_station ~lat:34.05 ~lon:(-118.25) ~alt:0.071 in
match Contact.predict tle la ~duration_days:3.0 with
| { max_elevation; duration; _ } :: _ ->
Fmt.str "first pass: %.1f deg peak, %.0fs long"
max_elevation duration
| [] -> "no passes"
- : string = "first pass: 61.5 deg peak, 503s long"
To get the elevation at one instant without searching for passes, call
Contact.elevation:
# let tle_string =
"ISS (ZARYA)\n\
1 25544U 98067A 26001.00000000 .00001764 00000+0 39538-4 0 9991\n\
2 25544 51.6416 45.0000 0008003 90.0000 0.0000 15.49560000 15" in
let tle = Result.get_ok (Sgp4.parse_tle_string tle_string) in
let la = Contact.ground_station ~lat:34.05 ~lon:(-118.25) ~alt:0.071 in
let epoch_unix = Sgp4.epoch_unix tle in
match Contact.elevation tle la epoch_unix with
| Some el -> Fmt.str "%.2f" el
| None -> "N/A"
- : string = "-43.66"
A negative elevation means the satellite is below the horizon. A pass is
the interval on which this angle stays at or above min_elevation
(5 degrees by default).
Command line #
The contact executable reads a TLE file and a station location. The
location is either --lat and --lon, a known site named with --location
(for instance la), or --here, which asks ip-api.com over plain HTTP where
the machine is:
$ contact predict --tle iss.tle --location la --days 3
$ contact next --tle iss.tle --lat 48.85 --lon 2.35
Both commands start their search at the TLE's epoch and ignore the current
time, so next reports the first pass after the epoch.
License #
ISC. See LICENSE.md.