Drawing Earth satellite groundtracks

What are orbit groundtracks?

By definition, a groundtrack is just the projection of the position left by a satellite over its attractor. They are usually applied to Earth orbiting spacecraft and thus, have been implemented within the hapsira.earth.plotting sub-package.

Something interesting about these kind of figures is that they take the Earth’s rotation into account. Therefore, it is possible to predict over which locations in the planet will the spacecraft be within the next hours or days.

In this notebook, we will show all the possibilities that the GrountrackPlotter class offers to hapsira’s users. Let us start by importing some useful modules!

# Useful for defining quantities
from astropy import units as u

# Earth focused modules, ISS example orbit and time span generator
from hapsira.earth import EarthSatellite
from hapsira.earth.plotting import GroundtrackPlotter
from hapsira.examples import iss
from hapsira.util import time_range

EarthSatellite instance and desired time span

As said before, groundtrack figures are usually related with Earth capabilities. Because of this, the plotter requires an EarthSatellite object to be passed and not a simple Orbit one. Main differences among them are that the first one is a combination of Orbit+ Spacecraft, including not only orbital data but also other one related with aerodynamic properties, for example. For more information, please refer to official API documentation.

Let us build an EarthSatellite instance but without any associated Spacecraft data, since for this notebook they will not be useful at all. Furthermore, we will generate a desired time span for the next three hours since actual ISS epoch. Notice that the periods parameter controls the resolution of the time vector and thus, the amount of values:

# Build spacecraft instance
iss_spacecraft = EarthSatellite(iss, None)
t_span = time_range(
    iss.epoch - 1.5 * u.h, num_values=150, end=iss.epoch + 1.5 * u.h

Using the plotter

Because of its interactive nature, lots of possibilities are offered by GroundtrackPlotter. It can provide lots of different map projections, customization parameters… This utility is based on plotly.layout.geo, please refer to the official documentation for more information about it. Let us create a simple instance and start plotting:

# Generate an instance of the plotter, add title and show latlon grid
gp = GroundtrackPlotter()
gp.update_layout(title="International Space Station groundtrack")

# Plot previously defined EarthSatellite object
        "size": 10,
        "symbol": "triangle-right",
        "line": {"width": 1, "color": "black"},