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, science models, and observation configuration.

Automatic SPICE Kernel setup based on meta-kernels.

Load individual CKs.

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 all platforms:

Mac-OSX (64 bits)

Linux (64 bits)

Windows (64 bits)

Please note that Cosmo Plugin versions prior to v1.0.0 are not compatible with Windows and require Cosmographia v4.1 or lower.

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.

Cosmo Plugin Installation

Download the plugin: Download the last version of the Cosmographia Juice plugin.

Extract the plugin: Extract the Juice plugin zip content within the main Cosmographia Folder cosmographia-4.x (e.g.: 4.2).

Run the plugin: Run the plugin by opening Cosmographia. In the menu select: File > Run Script.... Search for the directory: cosmographia-4.2/juice_plugin/plugin/. Select the file: juice.py

Additional info: Cosmographia Plugin JUICE SOC page

Working with the Plugin

To use the visualization plugin, after installing it: Start Cosmographia, in the top menu select File > Run Scripts. Navigate to the cosmographia-4.x/juice_plugin/plugin. Select the juice.py script.

The juice.py is the plugin that allows the creation/visualisation of Cosmographia scenarios. The tool shows a dialog that allows to configure the scenario creation.

The dialogue has three tabs:

Basic: The tab that we are interested the most with the Plugin’s basic usage.

Advanced: See Advanced Usage.

Help: Provides a brief description of the Plugin and a link to this documentation.

For most of the documentation we discuss the Basic functionality of the Plugin.

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 Generate Scenario 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 a Window, that can always be recovered from the JUICE Plugin option of the Cosmographia application top horizontal bar.

The GUI has different panels, from left to right and top to bottom:

UI Controls: Provides Time and Camera controls. With the camera control you can lock the view to the S/C +Z axis and center the camera in the S/C. With the time control, you can start/pause time, and choose a calendar date (will not visually work properly if OS is set in the so-called “Night Mode”).

Science Models: Allows to load some science models for PR/Visualization purposes, e.g.: Jupiter Main Aurora and Inner, Middle, and Outer Magnetosphere belts.

Sensors: Allows to show and hide the sensor models for each instruments as defined in the SPICE Instrument Kernels. There are some models not available in SPICE for PEP that contain DOME in their names. There is a tab for each instrument and you can also select and deselect all the sensors of one instrument at a time.

Jupiter Minor 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 (fk/juice_sci_vNN.tf)

Jupiter Rings: Allows to activate/deactivate the Jupiter Digital Shape Kernel (DSK) model as defined in the JUICE DSK surfaces definitions kernel (fk/juice_dsk_surfaces_vNN.tf). It also includes a legend and brief description of the rings model as described in the JUICE-specific Planetary Constants Kernel (PCK, pck/juice_jupVVV.tpc).

Info display: Displays the scenario generation time and other information of interest.

Note

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

Loading CK attitude files

The JUICE Plugin option of the Cosmographia application top horizontal bar has the Load CK 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.

Advanced Usage

The Advance tab of the Plugin initialization allows you to visualize instrument/sensor specific observations. After specifying a sensor, a date, and a duration, the tool will show the instrument boresight and its frustrum. For MAPPS users, a convenient way to generate Cosmographia observations out of ITLs and EVFs is provided.

Note

Please note that a detailed explanation on how to use the advanced mode 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 JUICE Plugin should be conisdered as a prototype and is developed by the JUICE SOC on a best effor 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.