Generating an ISD with isd_generate¶

Prerequisites¶

Before you can generate an ISD, you will need:

ALE
An image (Locating Image Data) formatted according to your driver type.
SPICE Data according to your driver type.

Driver Types¶

NaifSpice + IsisLabelIsisSpicePds3Label

For NaifSpice + IsisLabel Drivers, you will need:

An image imported into ISIS .cub format with a -2isis app.
NAIF SPICE Kernels (See Setting up NAIF Data).

For IsisSpice Drivers, you will need:

An image imported into ISIS .cub format with a -2isis app,
AND the image must be spiceinited with spiceinit from=<your.cub>.

For Pds3Label Drivers, you will need:

An image in PDS3 format
NAIF SPICE Kernels (See Setting up NAIF Data).

Driver Types: NaifSpice, IsisSpice, IsisLabel, and Pds3Label.

NaifSpice drivers use the NAIF Kernels to look up spice data to an image, while IsisSpice drivers depend on the image already having spice data attached with spiceinit.

IsisLabel drivers use images in the ISIS .cub format, while Pds3Label drivers use images in the PDS format.

NaifSpice + IsisLabel is the most commonly used driver type, but you can check the ALE driver to find out if IsisSpice or Pds3Label drivers are available instead or in addition:

Look at the drivers in the ALE repository.
Click on the drivers for the spacecraft that captured your image.
Find the class for your sensor, and look for NaifSpice, IsisSpice, IsisLabel, or Pds3Label next to the class name.

There may be a class for both NaifSpice and IsisSpice; in that case you can use either, or use the -n or -i argument to specify which one to use. You might use -i for IsisSpice if you want to avoid re-spiceiniting a .cub.

By default, ALE will run through different drivers until either it finds one that works (at which point it will stop), or all drivers fail.

Using isd_generate¶

The basic usage of isd_generate is as follows:

isd_generate [--arguments] [your-image-name]

isd_generate default run, no arguments

To run isd_generate with no arguments on a .cub named B10_013341_1010_XN_79S172W.cub:

isd_generate B10_013341_1010_XN_79S172W.cub

Output¶

Upon a successful run of isd_generate, an uncompressed ISD file will be generated. By default, this is your image's name, with a .json file extension (i.e. B10_013341_1010_XN_79S172W.json).

Specifying Output

Example .cub

To output to a specified filename, use --out or -o. This example outputs a 'MyIsd.json' file:

isd_generate -o MyIsd.json B10_013341_1010_XN_79S172W.cub

To output a brotli-compressed ISD, use --compress or -c. This results in a .br file:

isd_generate -c B10_013341_1010_XN_79S172W.cub

To uncompress an ISD (converts .br to .json):

python -c "import ale.isd_generate as isdg; isdg.decompress_json('B10_013341_1010_XN_79S172W.br')"

Verbosity¶

When using the --verbose (-v) argument, program run information is printed to the console, followed by the text of the ISD. This can be helpful when troubleshooting.

NAIF SPICE Data and Kernels¶

To ensure the use of a NaifSpice Driver (and NAIF SPICE Data) to generate an ISD, use the --only_naif_spice (-n) flag. If you have a spiceinited .cub and you want to avoid re-spiceiniting it or using NAIF SPICE Data, use the --only-isis-spice (-i) flag.

When using an NAIF SPICE Data, you can specify a metakernel using the --kernel (-k) argument, followed by the path to your metakernel.

Using a NaifSpice Driver with a metakernel

Folder with example NAIF Data: [Download as .zip] [View in GitHub]

This folder contains NAIF Data consisting of the various kernels necessary to generate an ISD for the B10_013341_1010_XN_79S172W image. You can open the kernels ending in .t* and view their contents as text files. The kernels ending in .b* are binary kernels; NAIF SPICE Utilities can be used to investigate their contents.

mro_B10_72W.tm is the metakernel file. If you open it, you can see it is a list of other kernels. If you needed to use specific kernels, you could copy a metakernal and edit the list.

To use a NaifSpice Driver and specify a metakernal:

isd_generate -n -k mro_B10_72W.tm B10_013341_1010_XN_79S172W.cub

Troubleshooting¶

Troubleshooting Checklist

Is your image in ISIS format (or PDS format for Pds3Label Drivers)?
- use a -2isis app to convert images to ISIS format.
Do you have spice data...
- If using a NaifSpice Driver:
  - Spice Data Downloaded from NAIF?
  - $ALESPICEROOT set?
  - Metakernel PATH_VALUE set?
- If using an IsisSpice Driver:
  - Spice Data attached to your image by spiceinit?
Check what's wrong with a --verbose run.

Investigating with --verbose¶

Use the --verbose (-v) argument to troubleshoot and see why ALE might not be recognizing your image. Check for info about the failure under Trying <class 'ale.drivers.[X]_drivers...'> where [X] is ALE's abbreviation for the spacecraft/sensor that captured your image.

isd_generate -v B10_013341_1010_XN_79S172W.cub

If requesting assistance, it may be helpful to post what version of ALE you have, shown with:

isd_generate --version

Setting Up NAIF Data¶

For use of NAIF Data with ISIS, see the ISIS Data Area. For use of NAIF data with ALE, continue below.

Downloading NAIF SPICE Data with wget¶

[NAIF SPICE Data Home] [Getting Spice Kernels from the NAIF Server]

If you have enough space, NAIF recommends downloading the entire dataset for your spacecraft, detailed below. Otherwise, you can try subsetting the data as detailed in the NAIF Server tutorial. You will need wget, a common download utility.

Let's download the Clementine archive as a test.

Find your mission on the PDS SPICE Archives and copy the Archive Link.
- The url for the Clementine archive is:
  https://naif.jpl.nasa.gov/pub/naif/pds/data/clem1-l-spice-6-v1.0/clsp_1000
cd into you spice folder, the folder you have or will set as $ALESPICEROOT.
Piece together the wget command.
1. Starting with this base command... (Don't run it yet!)
  wget -m -nH --cut-dirs=5 -R 'index.html*'
2. add the url...
  -nv https://naif.jpl.nasa.gov/pub/naif/pds/data/clem1-l-spice-6-v1.0/
3. then filter by the directory path (last half of url)...
  -I pub/naif/pds/data/clem1-l-spice-6-v1.0/
4. and download into this folder (just the folder at the end of the url).
  -P clem1-l-spice-6-v1.0/

Run the complete wget command:

wget -m -nH --cut-dirs=5 -R 'index.html*' -nv https://naif.jpl.nasa.gov/pub/naif/pds/data/clem1-l-spice-6-v1.0/clsp_1000 -I pub/naif/pds/data/clem1-l-spice-6-v1.0/clsp_1000 -P clem1-l-spice-6-v1.0/

The Mars Reconnaissansce Orbiter (MRO) archive, which corresponds to the B10_013341_1010_XN_79S172W we've been using, is 340 GB. If you will be working with MRO images, and you have the space, you can try downloading the MRO Spice data.

Setting $ALESPICEROOT¶

When you are using a NaifSpice Driver, ALE looks under the $ALESPICEROOT directory for SPICE Kernels. You can echo it to see if it is set.

echo $ALESPICEROOT

To work with MRO images like the example image on this page, you might download the MRO NAIF SPICE Kernels to a data drive. If your directory structure looks like /Volumes/data/spice-data/mro-m-spice-6-v1.0/mrosp_1000, then you should set $ALESPICEROOT like:

export ALESPICEROOT=/Volumes/data/spice-data

Setting the Path Value in a metakernel¶

When you use a NaifSpice Driver, the your $ALESPICEROOT must point to the relevant NAIF SPICE Data, and the metakernel within that data must be set.

isd_generate -n -v B10_013341_1010_XN_79S172W.cub

If the path value in your metakernel has not been set, you may get an error like this:

File B10_013341_1010_XN_79S172W.cub: No Such Driver for Label

Look up further in the verbose data, and if an unset metakernel is causing the problem, you will find something like:

Trying <class 'ale.drivers.mro_drivers.MroCtxIsisLabelNaifSpiceDriver'>
Failed:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(NOSUCHFILE) --

The first file './data/lsk/naif0012.tls' specified by KERNELS_TO_LOAD in the file /Volumes/data/spice-data/mro-m-spice-6-v1.0/mrosp_1000/extras/mk/mro_2009_v14.tm could not be located.

You will need to open that .tm file (mro_2009_v14.tm), and change the PATH_VALUES line to point to your data; the folder containing folders for lsk, pck, sclk, fk, ik, spk, ck, etc...

PATH_VALUES     = ( './data' )

if your $ALESPICEROOT is /Volumes/data/spice-data, and you are working with an MRO image, you might change it to:

PATH_VALUES     = ( '/Volumes/data/spice-data/mro-m-spice-6-v1.0/mrosp_1000/data' )

Now save the metakernel try again, and, if your SPICE Data is correctly configured, you should not see the same error:

isd_generate -n -v B10_013341_1010_XN_79S172W.cub

Arguments¶

Output File¶

-o, --out [filename]: Optional output file. If not specified, this will be set to the input filename with its final suffix replaced with .json. If multiple input files are provided, this option will be ignored and the default strategy of replacing their final suffix with .json will be used to generate the output file paths.
-c, --compress: Output a compressed isd json file with .br file extension. Ale uses the brotli compression algorithm. To decompress an isd file run: python -c "import ale.isd_generate as isdg; isdg.decompress_json('/path/to/isd.br')"

ALE Processing Settings and Info¶

-v, --verbose: Display extra information as program runs.
--version: Shows ALE version number
--max_workers [integer]: If more than one file is provided to work on, this program will engage multiprocessing to parallelize the work. This multiprocessing will default to the number of processors on the machine. If you want to throttle this to use less resources on your machine, indicate the number of processors you want to use.

Spice Data¶

-k, --kernel [filename]: Typically this is an optional metakernel file, care should be taken by the user that it is applicable to all of the input files. It can also be a single ISIS cube, which is sometimes needed if the input file is a label file.
-i, --only_isis_spice: Only use drivers that read from spiceinit'd ISIS cubes.
-n, --only_naif_spice: Only use drivers that generate fresh spice data.

Spatial Settings¶

-l, --local: Generate local spice data, an isd that is unaware of itself relative to target body. This is largely used for landed/rover data.
-N, --nadir: Generate nadir spice pointing, an isd that has pointing directly towards the center of the target body.