Added Mro isd generation notebook (#203)

%% Cell type:markdown id: tags:

# Writing out a USGSCSM ISD from a PDS3 LRO LROC NAC image

%% Cell type:code id: tags:

``` python

import os

import json

import ale

from ale.drivers.mro_drivers import MroCtxPds3LabelNaifSpiceDriver

from ale.formatters.usgscsm_formatter import to_usgscsm

```

%% Cell type:markdown id: tags:

## Instantiating an ALE driver

ALE drivers are objects that define how to acquire common ISD keys from an input image format, in this case we are reading in a PDS3 image using NAIF SPICE kernels for exterior orientation data. If the driver utilizes NAIF SPICE kernels, it is implemented as a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers) and will furnish metakernels when entering the context (i.e. when entering the `with` block) and free the metakernels on exit. This maintains the integrity of spicelib's internal data structures. These driver objects are short-lived and are input to a formatter function that consumes the API to create a serializable file format. `ale.formatters` contains available formatter functions.

The default config file is located at `ale/config.yml` and is copied into your home directory at `.ale/config.yml` on first use of the library. The config file can be modified using a text editor. `ale.config` is loaded into memory as a dictionary. It is used to find metakernels for different missions. For example, there is an entry for MRO that points to `/usgs/cpkgs/isis3/data/mro/kernels/mk/` by default. If you want to use your own metakernels, you will need to udpate this path. For example, if the metakernels are located in `/data/ctxmro/mk/` the MRO entry should be updated with this path. If you are using the default metakernels, then you do not need to update the path.

ALE has a two step process for writing out an ISD: 1. Instantiate your driver (in this case `MroCtxPds3LabelNaifSpiceDriver`) within a context and 2. pass the driver object into a formatter (in this case, `to_usgscsm`).

Requirements:

 * A PDS3 CTX MRO image

 * NAIF metakernels installed

 * Config file path for MRO (ale.config.mro) pointing to MRO NAIF metakernel directory

 * A conda environment with ALE installed into it usisng the `conda install` command or created using the environment.yml file at the base of ALE.

%% Cell type:code id: tags:

``` python

# printing config displays the yaml formatted string

print(ale.config)

# config object is a dictionary so it has the same access patterns

print('MRO spice directory:', ale.config['mro'])

# updating config for new LRO path in this notebook

# Note: this will not change the path in `.ale/config.yml`. This change only lives in the notebook.

# ale.config['lro'] = '/data/lrolrocnac/mk/'

```

%% Output

    cassini: /usgs/cpkgs/isis3/data/cassini/kernels/mk/

    dawn: /data/spice/dawn-m_a-spice-6-v1.0/dawnsp_1000/extras/mk

    kaguya: /data/spice/SELENE/kernels/mk/

    lro: /scratch/jlaura/spice/lro-l-spice-6-v1.0/lrosp_1000/extras/mk/

    mdis: /data/spice/mess-e_v_h-spice-6-v1.0/messsp_1000/extras/mk

    mro: /data/spice/mro-m-spice-6-v1.0/mrosp_1000/extras/mk

    spice_root: /data/spice/

    MRO spice directory: /data/spice/mro-m-spice-6-v1.0/mrosp_1000/extras/mk

%% Cell type:code id: tags:

``` python

# change to desired PDS3 image path

file_name = '/home/acpaquette/F03_037064_1857_XN_05N218W.IMG'

# metakernels are furnsh-ed when entering the context (with block) with a driver instance

# most driver constructors simply accept an image path

with MroCtxPds3LabelNaifSpiceDriver(file_name) as driver:

    # pass driver instance into formatter function

    usgscsmString = to_usgscsm(driver)

```

%% Cell type:markdown id: tags:

### Write ISD to disk

ALE formatter functions generally return bytes or a string that can be written out to disk. ALE's USGSCSM formatter function returns a JSON encoded string that can be written out using any JSON library.

USGSCSM requires the ISD to be colocated with the image file with a `.json` extension in place of the image extension.

%% Cell type:code id: tags:

``` python

# Load the json string into a dict

usgscsm_dict = json.loads(usgscsmString)

# Write the dict out to the associated file

json_file = os.path.splitext(file_name)[0] + '.json'

# Save off the json and read it back in to check if

# the json exists and was formatted correctly

with open(json_file, 'w') as fp:

    json.dump(usgscsm_dict, fp)

with open(json_file, 'r') as fp:

    usgscsm_dict = json.load(fp)

usgscsm_dict.keys()

```

%% Output

    dict_keys(['radii', 'sensor_position', 'sun_position', 'sensor_orientation', 'detector_sample_summing', 'detector_line_summing', 'focal_length_model', 'detector_center', 'starting_detector_line', 'starting_detector_sample', 'focal2pixel_lines', 'focal2pixel_samples', 'optical_distortion', 'image_lines', 'image_samples', 'name_platform', 'name_sensor', 'reference_height', 'name_model', 'interpolation_method', 'line_scan_rate', 'starting_ephemeris_time', 'center_ephemeris_time', 't0_ephemeris', 'dt_ephemeris', 't0_quaternion', 'dt_quaternion'])

%% Cell type:code id: tags:

``` python

```