User Installation Guide

This guide will cover the installation of OMINAS and common issues with configuration, as well as present some common errors and possible solutions. Please see the section entitled Troubleshooting for more information regarding installation issues with OMINAS.

Requirements

Currently OMINAS requires IDL 8.2.3 or above, and a bash shell, on Linux or Mac OS.

To process images from a particular mission, that mission's kernels will need to be available. The OMINAS installer can automatically download sets of kernels for several missions (Cassini, Galileo, Voyager, Dawn).

OMINAS makes use of the NAIF Icy Toolkit to process SPICE kernels. The Icy toolkit may optionally be obtained manually from NAIF. However, the installer utility provided with OMINAS can download and compile Icy automatically. Installation of Icy is somewhat platform-dependent, so troubleshooting information can be found in Troubleshooting.

Procedure

1. Please ensure that OMINAS has been properly downloaded from the Github repository by entering the following command at the terminal:

A local copy of the OMINAS source will be cloned automatically.

2. Configuration of OMINAS should be performed using the configuration script, configure.sh, which is located in the top-level ominas directory. This script can be run from the command line with:

3. A prompt will appear asking which packages should be installed. The user should type the numbers of the desired packages separated by spaces. We recomend, at a minimum, setting up packages 1, 2 and 3 (OMINAS Core, Demo and Icy). To automatically download and setup all the packages, use the all option.

4. When setting up an individual kernel or data package (selections 4-13), one can either provide a path for an existing directory containing the required files, or tell the installer to download them.

5. Test the install of OMINAS has been completed correctly by running the the following example scripts:

6. A successful Icy installation can be tested with the following IDL command from within an OMINAS IDL session: Some text on the installed version of Icy should be displayed. Additionally, use the following command: The version of Icy should be printed. If both of these functions return successfully, then Icy has been installed correctly.

Example installation walkthrough

From a fresh account (that never had OMINAS, Icy or any IDL libraries setup before), for the 3 main packages (Core, Demo and Icy):

At this point, a copy of OMINAS will be in a newly-created directory called ominas, under the current directory. Note that if a non-empty ominas directory was already present, git would notice it and refuse to download OMINAS into that directory.

Now, getting into the ominas directory and running the installer:

At this point, one can run a few tests of the enviroment: Which shows both ominas and ominasde are defined. Use ominas to start and IDL session in which to use OMINAS, and ominasde to start an IDL DE session in which to use OMINAS.

Now, to check on the ominas_setup file, which sets the environment for the OMINAS core and all currently set packages (in this example, only Core, Demo and Icy are set):

Now, to check that the right environment is see from an OMINAS session: Now, to check that the OMINAS paths show up inside an OMINAS IDL session: With this environment, one can run some demo scripts, such as:

Testing the environment with ominas_env_info

OMINAS includes a utilty script that prints out the most commonly relevant about your OMINAS environment, which can be useful for debugging (both for yourself, and when you send us questions). It can be run by calling ominas_env_info, from an ominas/ominasde session. If an argument is provided, it will be the filename where the output will be saved into (as opposed to printing it to the console). One example:

Which produces:

Troubleshooting

This section outlines several common sources of error which are due to OMINAS not being configured correctly.

One of the most common configuration problems manifests as this error:

This error comes from the Icy toolkit. It specifically refers to the Leap Second Kernel file, however, as the lsk is usually the first kernel which is loaded, this error generally means that no kernels are being loaded.

You can check which kernels have been loaded by entering the following IDL commands:

A list will be populated with the currently loaded SPICE kernels, and their load order. If no kernels are loaded, then it is likely that a bad path was supplied to the kernel pools. Ensure that the kernel pool was successfully entered into the environemnt by using the "env" command at the terminal prompt. The kernel pool variable names follow a convention like so: <MIS>_SPICE_<*K>, where <MIS> is the abbreviated mission name, and <*K> is the type of kernel. Therefore, for Cassini, the IDL command: will list the path to directories containing each type of Cassini kernel. If the variables are not present, the easiest fix might be to run the OMINAS installer again

source configure.sh

From the ominas directory. Then, if the Cassini package shows as installed, select that option at the menu (4), to uninstall it. You will be presented with the possibility of preserving files the OMINAS installer previously downloaded, or deleting them. After the uninstallation is complete, you will be returned to the installer menu, and Cassini should show as not configured. Then select the Cassini option to set it up again.

In some cases, a demo script will run and no error will appear to occur, but no pointing will be overlayed on the image. This error generally occurs due to the PCK kernels not being loaded or the CK kernels not being loaded in the correct order.

When the frame kernel (FK) is not being loaded correctly for an image, Icy will return the following error:

If Icy is not installed, and a script is run, something similar to the following error may occur: In general, the undefined procudure may have any cspice prefix. Icy is either not configured correctly, or not installed. In IDL, check that the Icy path has been added to the IDL path as follows: The path variable should appear as a colon-separated list with <IDL_DEFAULT> as the first entry. Check that both Icy and OMINAS directories are added to the IDL_PATH, and that Icy is added to the IDL_DLM_PATH. If either Icy or OMINAS are not present, the best way to fix it probably is to get back into the OMINAS directory and run the configure.sh script to uninstall/install the Core, Demo or Icy packages again.