Cosmographia Plugin

SPICE-Enhanced Cosmographia is a visualization program rendering the solar system and its bodies in 3D to create a freely navigable map of the solar system. The program allows manipulation of time and camera (observer) position. It can use SPICE data to visualize trajectory, orientation, and sensors flown on and observations taken by interplanetary spacecraft, to support scientific or engineering analysis, and perhaps even public outreach.

The Cosmographia JUICE plugin is a software that adds extra features to the SPICE-Enhanced Cosmographia tool allowing easy 3D visualization of the JUICE spacecraft manoeuvres and instrument pointing.

Overview

The package deals with the tedious build-up of Cosmographia catalog files, hiding the low level details and providing a turn-key solution for quick and easy visualization of JUICE pointing.

The Plugin feature the following functionalities:

Creation of complete Cosmographia scenes.

JUICE Spacecraft 3D Models integrated.

Sensor and observation configuration.

Automatic SPICE Kernel setup based on metakernels.

Load of external custom CKs not included in a metakernel.

Pointing request simulation and timeline visualization.

Jupiter specific science structures (Main Aurora, Rings, Magnetosphere belts, Minor Moons).

Customized star database.

Cosmographia includes a Python-based scripting interface, providing access to many of the program’s elementary visualization functions and allowing users to create visualization sequences using these functions. The plugin uses this capability to get access to the Cosmographia resources.

Installation

In order to use the Cosmographia Plugin you will need to install first Cosmographia and to setup the SPICE kernels. Some schematic instructions are provided hereunder.

Warning

The plugin is now available for the following platforms:

Mac-OSX (64 bits)

Linux (64 bits)

Cosmographia Installation

In order to run the Cosmo Plugin you need to have Cosmographia installed in advance a quick summary is provided hereunder:

Download the Tool: Download the Cosmographia Tool from the ESA SPICE Service.

Install the Tool: Follow the installation instructions provided by the tool’s installer.

Open Cosmographia: You should see a Cosmographia icon in your Desktop please click it to open Cosmographia.

Additional info: Additional information on Cosmographia is available in the on-line Cosmoguide.

Warning

The latest version of the plugin will only work with Cosmographia v4.2 or higher.

Setup SPICE (optional)

You do not need to install and setup SPICE to use Cosmographia, but we will do so for many other tasks. So far we recommend to use SpiceyPy the Python wrapper of SPICE. You can install it as any other Python library.

Install SpiceyPy with pip install spiceypy.

This will install CSPICE with the wrapper. Alternative methods available from the SpiceyPy GitHub repository.

If you wish to install SPICE for other languages follow the instructions under the NAIF Toolkit page.

Warning

If you have the SPICE Toolkit already installed, make sure is version N67 or a latest one.

SPICE Kernels Setup

The SPICE Kernels can be setup in a plethora of ways. Here we provide the one that is recommended by the JUICE SOC and by the ESA SPICE Service.

Install Git: You can see the instruction on the following page.
Clone the SPICE Kernels: Clone the JUICE SPICE kernel data set from BitBucket. Clone it from the terminal with:
git clone --depth 1 https://s2e2.cosmos.esa.int/bitbucket/scm/spice_kernels/juice.git
Please be aware that due to the large history of the repository and the large size of some binary kernels, timeout errors may occur if the --depth option is not used for performing a shallow clone.

ALTERNATIVELY download the kernels from the ESA SPICE FTP, you should do so by downloading the kernels listed in any Meta-kernel. Good luck with that.
Update the meta-kernel for local usage: In order to use the kernels with the Meta-kernels in SPICE outside of the Meta-kernel directory of the Git repository the user needs to modify the following the PATH_VALUE variable of the meta-kernel from:
PATH_VALUES       = ( '..' )
to:
PATH_VALUES = ( '<Absolute Path to 'kernels' directory>' )
The meta-kernel can be found in the directory juice/kernels/mk/

It is recommended for users to make a local copy of the meta-kernel and modify the value of the PATH_VALUES keyword to point to the actual location of the JUICE SPICE data set’s data directory on their system. Replacing / with \ and converting line terminators to the format native to the user’s system may also be required if this meta-kernel is to be used on a non-UNIX workstation.
Test the kernels: Download the BRIEF utility from NAIF utilites page Put it under your system PATH or directly in the directory juice/kernels/mk/. Run it from the command line with ./brief <name of the metakernel>, you should see something like:
brief juice_crema_5_0_local.tm

BRIEF -- Version 4.1.0, September 17, 2021 -- Toolkit Version N0067

Summary for: /Users/marc.costa/spice/juice/kernels/spk/juice_sci_v02.bsp
Bodies: JUICE_JUP_HALO_RING (-28941)*
        JUICE_JUP_MAIN_RING (-28942)*
        JUICE_JUP_AMA_GOS_RING (-28943)*
        JUICE_JUP_THE_GOS_RING (-28944)*
        JUICE_JUP_THE_RING_EXR (-28945)*
        JUICE_IO_PLASMA_TORUS (-28968)*
        JUICE_EUROPA_PLASMA_TORUS (-28988)*
        Start of Interval (ET)              End of Interval (ET)
        -----------------------------       -----------------------------
        1950 JAN 01 00:00:00.000            2050 JAN 01 00:00:00.000
(...)

Note

A very practical alternative to the SPICE Kernel setup is to use the planetary-coverage Python package to obtain and manage the SPICE Kernels. Full instructions available in its Documentation.

ESS Cosmo Plugin Installation

The installation procedure has made more flexible from previous versions. The local clone of the repository does not need an specific location in the file system.

Clone the ESS plugin repository

git clone https://s2e2.cosmos.esa.int/bitbucket/scm/spice/ess-plugin.git

Working with the Plugin

The plugin includes several entry points accessing different functionalities.

juice_mk.py: Allows to create a basic scene, based on a metakernel and selecting a date. Specific Jupiter science structures and dedicated sensor selectors are made available to the user.

juice_ptr.py: Allows to create a scene based on a pointing request. The tool process the provided PTR using a embeded OSVE tool and allows the visualisation and the navigation on the resultant timeline. Specific Juice sensors and structures are also available.

stardb_conf.py: Auxiliary script that allows to add custom stars/fields that are not displayed by default in Cosmographia.

To use the visualization plugin, after installing it: Start Cosmographia, in the top menu select File > Run Scripts. Navigate to the repository root. Select the entry point script.

The plugin needs as mandatory input a valid SPICE meta-kernel with JUICE configuration (e.g. juice_plan_v341.tm). The meta-kernel must have a local absolute path, as described in SPICE Kernels Setup. More details on JUICE kernels available can be found in the ESA SPICE Service JUICE page.

Clicking in the ‘visualize’ button, will create the scenario with the information contained in the meta-kernel. The tool will setup the camera near to JUICE and the user can start the spatial/temporal navigations with the Graphical User Interface (GUI) as described in Plugin Graphical User Interface.

Plugin Graphical User Interface

After generating the scenario, the Plugin GUI will appear. The GUI consists of several dialog windows, that can always be recovered from the options of the Cosmographia application top horizontal bar.

The GUI has different menu entries, from left to right:

Scenes: Provides access to the main dialogs of the two scenario creations. They can be invoked several times, reseting the visualisations. The detailed usage will be explained in the next sections:

Metakernel Loader: Allows the basic scene generation based on metakernel load.

PTR Simulation: Allows the scene generation based on a pointing requests timeline.

Runtime

Console: Allows the execution of comosgraphia scripting commands [Advanced]

Catalog: Allows to manage the cosmographia catalogues [Advanced]

Tool version: Shows the current version of the plugin, linking to the repository with the code.

Jupiter structures: Allows to load JUICE science models in the jovian system for visualization purposes:

Jovian Moons: Allows to activate/deactivate the Jupiter Minor Moons. When activated the trajectory will also be shown. The Moons are classified in different groups: inner group, ananke group, carme group, pasiphae group, and prograde group according to the latest version of the JUICE Science Frames SPICE kernel.

Rings and Torus: Allows to activate/deactivate the Jupiter Digital Shape Kernel (DSK) model as defined in the JUICE DSK surfaces definitions kernel

Jupiter Main Aurora

Jupiter Inner, Middle, and Outer Magnetosphere belts

Navigation

Sensors: Allows to show and hide the sensor models for each instruments as defined in the SPICE Instrument Kernels. There is a tab for each instrument and you can also select and deselect all the sensors of one instrument at a time and remove the sensor frustrum. With the camera control you can lock the view to the sensor boresights or center the camera in the S/C. With the time control, you can start/pause time, and choose the time step to be applied in the visualisation.

Observations: Allows the on-the-fly creation of observations using the available sensors.

Juice Help: Displays documentation, links and information of interest.

Science Models

SPICE Data for JUICE

OSVE version

Pointing: Only available after the PTR Simulation

Timeline: Allows the review and time navigation of the block timeline included in the pointing request.

Note

More information and references for the Science Models is available at Science Models

Loading CK attitude files

The Scenes option of the Cosmographia application top horizontal bar has the Metakernel Load option. This option opens a menu that allows you to load an applicable Attitude CK file (needs to be designed for the JUICE_SPACECRAFT reference frame).

Once the CK is loaded the scenario is re-generated accordingly preserving the previously selected options of the plugin. This option is extremely useful for the analysis of pointing design during the science planning and operations processes.

PTR Simulation

The Scenes option of the top horizontal menu bar has the PTR Simulation option. This option opens a menu that allows you to load a metakernel and a Pointing Request file. The request is processed by the embeded OSVE tool, producing a CK kernel that is loaded as part of the kernel bundle.

Once the PTR is processed (please, note that it could take some time depending on the lenght of the request period), a new Timeline dialog appears for the visualisation of the blocks that build-up the request. The UI allows to move along the blocks, reviewing its duration, contents and driving the time navigation of the scene.

Note

Please note that a detailed explanation on how to design pointing requests is out of the scope of this documentation, for more information please contact the JUICE SOC.

Working with the SPICE Kernel Data set Cosmographia Configuration

Altough the Cosmo Plugin provides a very convenient way to manage and setup JUICE for Cosmographia, you can still load JUICE for Cosmographia by “simply” loading the Cosmographia Configuration files provided in the SPICE Kernel data set. You can load the configuration independently or on top of the Cosmo Plugin.

To do so, navigate the Cosmographia top level bar and select File > Open Catalogue and load any configuration file as desired. The Cosmographia configuration files are available in the BitBucket SPICE Kernel data set under juice/misc/cosmo this is also true for the ESA SPICE FTP JUICE directory.

Note

The Cosmo plugin generates the Cosmographia configuration files that it loads on the fly and as temporary files based on templates that it incorporates.

If you want to have a log of what the plugin does, start Cosmographia from a Terminal.

Known Issues

The Cosmopraphia ESS Plugin should be considered as a prototype and is developed by the ESA Spice Service on a best effort basis. The plugin is good enough but is certainly not tested by the highest standards due to lack of resources. Feedback is always welcome. A list of known features is provided hereunder:

OS Dark Mode Display: When using the Dark Mode Display for the MacOS, the numbers in the Calendar option are not visible.

Models cannot be unloaded: There are several science models that cannot be unloaded once loaded. This is due to a limitation of Cosmographia.