Visualize orbital data with Cesium¶
Poliastro allows users to easily convert orbital data to CZML, a JSON format primarily used in applications running Cesium.
Dependencies¶
You will only need poliastro (obviously) and czml3, a library for easily creating and using CZML packets:
pip install poliastro czml3
Our first example: The Molniya orbit¶
We’ll start off by using one of the readily usable poliastro examples. Of course, you can use any poliastro Orbit
object:
[1]:
from poliastro.czml.extract_czml import CZMLExtractor
[2]:
from poliastro.examples import molniya
To initialize the extractor, you’ll only need the starting and ending epoch of the time period you wish to visualize and the number of sample points. The larger the sample point size, the more accurate the trajectory and the bigger your packets. Finding that sweet spot between reasonable package size and visual accuracy depends on the specific orbit. Generally, you’ll need a bigger sample for faster satellites. You could also “break” your orbit into different parts and define the sample size individually (for example, this could be useful when the satellite accelerates within a certain time interval).
For this specific example, we’re only interested in a single orbital period:
[3]:
start_epoch = molniya.epoch
end_epoch = molniya.epoch + molniya.period
N = 80
[4]:
extractor = CZMLExtractor(start_epoch, end_epoch, N)
To add an orbit you can simply call add_orbit
and pass your Orbit
along with an optional precision parameter (rtol
). However, there are also many optional parameters you can pass to the extractor to specify the visual characteristics of your trajectory:
Id parameters:¶
id_name
: The orbit id name
id_description
: The orbit’s description
Path parameters:¶
path_width
: The trajectorie’s width. It’s defined in pixels and defaults to 1.0
path_show
: Whether the trajectorie’s path is visible (true by default)
path_color
: The trajectorie’s color, a simple list with the rgba values (e.g. [45, 30, 50, 255]
)
Label parameters:¶
label_text
: The label text; the text that appears besides the orbit.
label_show
: Whether the label is visible (true by default)
label_fill_color
: The fill color of the label, a simple list with the rgba values
label_outline_color
: The fill color of the label, a simple list with the rgba values
label_font
: The font properties (CSS syntax)
Groundtrack parameters:¶
show_groundtrack
: Whether the groundtrack is visible (true by default)
groundtrack_lead_time
: The time the animation is ahead of the real-time groundtrack
groundtrack_trail_time
: The time the animation is behind the real-time groundtrack
groundtrack_width
: The groundtrack width
groundtrack_color
: The groundtrack color. By default, it is set to the trajectory’s color
[5]:
extractor.add_orbit(
molniya,
id_name="MolniyaOrbit",
path_width=2,
label_text="Molniya",
label_fill_color=[125, 80, 120, 255],
)
You can now export the extractor packets by simply calling extractor.packets
and load it to the Cesium app as described here:
Landing on Mars¶
You can customize the attractor of your orbit by defining any valid ellipsoid with the help of poliastro’s Body
class. For your convenience, poliastro offers a pre-defined list of all the major planetary bodies of the solar system so you can simply import them:
[6]:
from poliastro.bodies import Mars
Of course, when defining a new attractor you want to be able to identify something other than it’s shape. For this reason, the extractor allows you to easily set the UV map by simply providing a valid URL:
[7]:
mars_uv = "https://upload.wikimedia.org/wikipedia/commons/f/fd/Mars_2020_LandingSites_Final_8-full.jpg"
[8]:
extractor = CZMLExtractor(
start_epoch, end_epoch, N, attractor=Mars, pr_map=mars_uv
)
[9]:
extractor.packets
[9]:
[{
"id": "document",
"version": "1.0",
"name": "document_packet",
"clock": {
"interval": "2000-01-01T12:00:00Z/2000-01-01T23:59:35Z",
"currentTime": "2000-01-01T12:00:00Z",
"multiplier": 60,
"range": "LOOP_STOP",
"step": "SYSTEM_CLOCK_MULTIPLIER"
}
},
{
"id": "custom_properties",
"properties": {
"custom_attractor": true,
"ellipsoid": [
{
"array": [
3396190.0,
3396190.0,
3376220.0
]
}
],
"map_url": "https://upload.wikimedia.org/wikipedia/commons/f/fd/Mars_2020_LandingSites_Final_8-full.jpg",
"scene3D": true
}
}]
Return to Flatland¶
Instead of a 3D globe you may want to visualize your orbit as a 2D projection instead. In this case you can simply set scene3D
to false
and Cesium will automatically render the scene’s orthographic projection. This can be of use when plotting animated groundtracks as we’ll see in the next section:
[10]:
extractor = CZMLExtractor(start_epoch, end_epoch, N, scene3D=False)
[11]:
extractor.packets
[11]:
[{
"id": "document",
"version": "1.0",
"name": "document_packet",
"clock": {
"interval": "2000-01-01T12:00:00Z/2000-01-01T23:59:35Z",
"currentTime": "2000-01-01T12:00:00Z",
"multiplier": 60,
"range": "LOOP_STOP",
"step": "SYSTEM_CLOCK_MULTIPLIER"
}
},
{
"id": "custom_properties",
"properties": {
"custom_attractor": true,
"ellipsoid": [
{
"array": [
6378136.6,
6378136.6,
6356751.9
]
}
],
"map_url": [
"https://upload.wikimedia.org/wikipedia/commons/c/c4/Earthmap1000x500compac.jpg"
],
"scene3D": false
}
}]
Ground track plotting¶
Another useful feature the extractor offers, is the ability to plot the ground track of an orbit. You can set the groundtrack by setting the aforementioned groundtrack_show
parameter to true. Note that this also works in 2D view:
[12]:
extractor = CZMLExtractor(start_epoch, end_epoch, N)
[13]:
extractor.add_orbit(
molniya,
groundtrack_show=True,
groundtrack_lead_time=20,
groundtrack_trail_time=20,
)