3D Earth globe widget rendered with WebGL, in pure OCaml
README.md

globe #

A 3D Earth globe for showing satellites in a web page, in OCaml.

A mission dashboard needs to show where a constellation is, where each satellite is heading and what ground it covers, and it has to run in a browser tab. globe draws an interactive Earth as a cloud of dots with satellite positions, orbit trails, ground-coverage footprints, a latitude and longitude grid, labels and a star background. It is OCaml compiled to JavaScript with js_of_ocaml, drawing with WebGL2 and handling the DOM with Brr.

The package has two libraries. globe is the geometry and needs no browser: satellites propagated from a state vector (Kepler two-body), a TLE (SGP4/SDP4) or an ephemeris, the dot cloud, ray casting for picking, screen projection, visibility culling and orbital density heatmaps. globe.webgl renders those as layers of one scene, with an orbit camera that rotates, zooms and pans.

A state vector is a satellite's position and velocity at one epoch. A TLE (two-line element set) is the text format in which the mean orbital elements of tracked satellites are published, to be propagated with the SGP4 model, or SDP4 for orbits whose period is 225 minutes or more. An ephemeris is a table of positions, and often velocities, at successive times. J2000 is the Earth-centred inertial frame whose axes are fixed by the Earth's mean equator and equinox at 12:00 TT on 1 January 2000; CCSDS messages call it EME2000.

Installation #

Install with opam:

$ opam install globe

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install globe

Usage #

(* Build a satellite from J2000 state vectors; pass it to Globe_webgl.Scene in
   browser code. *)
let satellite ~pos ~vel ~t0 =
  Globe.Satellite.of_state_vector ~pos ~vel ~color:(Globe.Color.rgb 0.2 0.8 1.0)
    ~epoch_unix:t0 ()

API #

Geometry (Globe) #

  • Satellite: satellite state, with cached orbital elements, full orbit paths and trail positions.
  • Sphere: the dot cloud, laid out on a golden spiral with brighter dots on continents and coasts.
  • Gl_coord: maps positions in kilometres to scene coordinates, where the Earth's radius is 1 and Y points north.
  • Geometry, Raycast, Project and Visibility: spatial computations, picking, screen projection and culling.
  • Heatmap: orbital density over the globe.
  • Math and Color: vectors, matrices and RGBA colours.

Rendering (Globe_webgl) #

  • Scene: canvas set-up, the satellites shown, layer compositing and interaction.
  • Camera: the orbit camera, with smooth zoom and pan.
  • Earth, Stars, Grid, Orbit, Coverage, Density and Label: the layers.
  • Shader: WebGL2 shader compilation.

License #

ISC. See LICENSE.md.