Initial user and instrument docs. (#396)

* Initial user and instrument docs.

Instrument docs will be populated with examples as they become
available.

* Tweaked Juno language

* Updated MEX SRC info

* change THEMIS VIS to pushframe

* Update Voyager.rst

Co-authored-by: Jesse Mapel <[email protected]>

docs/source/sensors/Cassini.rst

@@ -0,0 +1,39 @@
+Cassini ISS
+===========
+The Cassini Imaging Subsystem comprises two instruments -- a narrow angle camera
+and a wide angle camera.  The narrow angle camera contains 24 filters, and the
+wide angle camera contains 18 filters.
+
+Processing Cassini ISS Images
+-----------------------------
+    import ale, json, os
+    from ale.drivers.cassini_drivers import CassiniIssPds3LabelNaifSpiceDriver
+    from ale.drivers import JsonEncoder
+
+    # Use the images to generate ISDs and create CSM cameras
+    # Assume images are in current directory
+
+    nac_stereo_1 = 'N1702360370_1.LBL'
+    nac_stereo_2 = 'N1702360308_1.LBL'
+
+    def generate_isd(filename):
+        driver = CassiniIssPds3LabelNaifSpiceDriver(filename)
+
+        # SPICE kernels are furnished inside this with
+        with driver as d:
+            # this is the information for the ISD in a python dict
+            aledict = d.to_dict()
+
+            # Export python dictionary ISD to external json file to be used by CSM
+            alelabel = os.path.splitext(filename)[0]+".json"
+            with open (alelabel, "w") as file:
+              json.dump(aledict, file, cls=JsonEncoder)
+            return aledict
+
+    # Generate ISD and export to a json file
+    nac1_dict = generate_isd(nac_stereo_1)
+    nac2_dict = generate_isd(nac_stereo_2)
+
+    # Construct a camera
+    camera1 = csm.create_csm(nac_stereo_1)
+    camera2 = csm.create_csm(nac_stereo_2)

docs/source/sensors/Dawn.rst

@@ -0,0 +1,7 @@
+Dawn FC
+=======
+The Dawn Framing Camera is a frame camera with a resolution of up to 25 meters
+per pixel.  This instrument contains a clear filter and 7 band-pass filters.
+
+Processing Dawn FC Images
+-------------------------

docs/source/sensors/Galileo.rst

@@ -0,0 +1,8 @@
+Galileo SSI
+===========
+The Galileo Solid State Imager is a modified form of the Voyager Narrow Angle
+Camera.  Galileo SSI has 8 band filters and is capable of capturing imagery with
+a spatial resolution up to 1 kilometer per pixel.
+
+Processing Galileo SSI Images
+-----------------------------

docs/source/sensors/Hayabusa.rst

@@ -0,0 +1,9 @@
+Hayabusa ONC
+============
+The Hayabusa Optical Navigation Camera is suite of three instruments (two wide
+angle and one telescopic imager), and is primarily used for navigation.  The
+wide angle cameras employ clear filters, and the telescopic imager uses 7
+color filters and one clear filter.
+
+Processing Hayabusa ONC Images
+------------------------------

docs/source/sensors/Juno.rst

@@ -0,0 +1,8 @@
+JunoCam
+=======
+JunoCam is a push frame camera attached to the Juno spacecraft.  This camera
+uses four filters and has an intended spatial resolution between 3 and 15
+kilometers per pixel.
+
+Processing JunoCam Images
+-------------------------

docs/source/sensors/LunarReconnaissanceOrbiter.rst

@@ -0,0 +1,81 @@
+MiniRF
+======
+MiniRF is the Lunar Reconnaissance Orbiter's Miniature Radio Frequency instrument.
+This instrument features two wavelength bands, and has a resolution of 30 meters
+per pixel.
+
+
+Processing MiniRF Images
+------------------------
+
+LRO NAC
+=======
+LRO NAC is the Lunar Reconnaissance Orbiter's Narrow Angle Camera.  It is a
+panchromatic linescan imager with a resolution of .5 meters per pixel over a 5km
+swath.
+
+Processing LRO NAC Images
+-------------------------
+
+LRO WAC
+=======
+LRO WAC is the Lunar Reconnaissance Orbiter's Wide Angle Camera.  This is a
+pushframe camera with a resolution of 100 meters per pixel over a 65km swath.
+This instrument captures data in 7 bands.
+
+Processing LRO WAC Images
+-------------------------
+LRO WAC uses a pushframe camera model, and an overview of the processing steps
+for this sensor is as follows:
+
+1. Use ISIS to ingest, calibrate, and spiceinit your cubes
+2. (Optional) photometrically correct the images
+3. Use framestitch to re-combine your even and odd frames
+4. Use ale to generate ISDs for your images, the framestitch application will
+   strip the ISIS camera model info off the cubes, so you'll need to pass ALE
+   your un-stitched images. It doesn't matter if you use even or odd´.
+5. Load your generated ISDs and stitched cubes into your CSM SET
+
+
+This example uses M119929852ME.IMG, which can be easily downloaded from the
+terminal via
+
+    $ curl http://pds.lroc.asu.edu/data/LRO-L-LROC-2-EDR-V1.0/LROLRC_0002/DATA/MAP/2010035/WAC/M119929852ME.IMG -o M119929852ME.IMG
+
+
+Ingesting, calibrating, and spiceinitting cubes
+-----------------------------------------------
+Ingesting, calibrating, and spiceinitting files results in an ISIS´-formatted
+image file that has been dark-field, flat-field, radiometric, and temperature
+corrected and initialized with spice kernels.  These processes can be completed
+in a terminal with the following ISIS commands:
+
+    $ lrowac2isis from= M119929852ME.IMG to = M119929852ME.cub
+    $ lrowaccal from= M119929852ME.vis.even.cub to= M119929852ME.vis.even.cal.cub
+    $ lrowaccal from= M119929852ME.vis.odd.cub to= M119929852ME.vis.odd.cal.cub
+    $ spiceinit from= M119929852ME.vis.even.cal.cub
+    $ spiceinit from= M119929852ME.vis.odd.cal.cub
+
+Photometrically correcting cubes (optional)
+-------------------------------------------
+Further research is necessary before ASC developers can recommend specific
+parameters for photometric correction.  While the following call is used to
+perform the correction, the determination of the specific values used in the
+input PVL is left to the user.
+
+    $ photomet from= M119929852ME.vis.even.cal.cub to= M119929852ME.vis.even.cal.cor.cub
+    $ photomet from= M119929852ME.vis.odd.cal.cub to= M119929852ME.vis.odd.cal.cor.cub
+
+
+Using framestitch to stitch even and odd frames together
+---------------------------------------------------------
+Framestitch is responsible for combining the even and odd framelets into a single
+image.  Note that the resulting, stitched image will not include camera model
+information.
+
+    $ framestitch even= M119929852ME.vis.even.cal.cor.cub odd= M119929852ME.vis.odd.cal.cub to= M119929852ME.vis.stitched.cal.cor.cub
+
+
+Generating ISDs
+---------------
+For information on generating an ISD, review the section on :ref:`isd_generation`.

docs/source/sensors/MarsExpress.rst

@@ -0,0 +1,21 @@
+MEX HRSC
+========
+* HRSC has 9 different filters. Each has it's own instrument id, as well as
+  the main/"HEAD" camera composing those filters. There is also another
+  "SRC" channel, making-up a total of 11 distinct sensors. It is very
+  important to understand which code is needed when/where.
+
+* HRSC is a variable rate line scanner, and so does not maintain one exposure
+  duration, but rather differing exposure durations per line. This
+  information is stored within the individual records in the image data
+  itself, with the the first 8 bytes making up the double presicion
+  ephemeris time that the line exposure was started, and the next 4 bytes
+  making up the float containing that line's exposure duration.
+
+* The SRC channel is a high resolution framing sensor.
+
+Processing HRSC Images
+----------------------
+
+Processing SRC Images
+---------------------

docs/source/sensors/MarsReconnaissanceOrbiter.rst

@@ -0,0 +1,9 @@
+MRO CTX
+=======
+The Mars Reconnaissance Orbiter Context Camera (CTX) is a high resolution linescan
+imager that is capable of capturing grayscale images with a resolution of up to
+6 meters per pixel.
+
+
+Processing MRO CTX Images
+-------------------------

docs/source/sensors/Messenger.rst

@@ -0,0 +1,10 @@
+Messenger MDIS
+==============
+The Messenger Mercury Dual Imaging System (MDIS) is a suite of two framing
+cameras-- a wide angle camera (WAC) and a narrow angle camera (NAC).  The wide
+angle camera captures multispectral information, and the narrow angle camera
+captures data in monochrome format. The combined cameras result in global mosaics
+with an average spatial resolution of 200 meters per pixel.
+
+Processing MDIS Images
+----------------------

docs/source/sensors/NewHorizons.rst

@@ -0,0 +1,9 @@
+New Horizons LORRI
+==================
+New Horizons Long Range Reconnaissance Imager is a fixed, narrow angle frame
+camera with a field of view of .29 degrees.  LORRI is a panchromatic imaging
+system, and it offers a maximum spatial resolution of roughly 33 meters per
+pixel.
+
+Processing New Horizons LORRI Images
+------------------------------------

docs/source/sensors/Odyssey.rst

@@ -0,0 +1,18 @@
+Odyssey THEMIS IR
+=================
+The Thermal Emission Imaging System Infrared sensor is a linescan camera
+responsible for capturing 10 infrared bands at a spatial resolution of 100
+meters per pixel.
+
+
+Processing THEMIS IR Images
+---------------------------
+
+Odyssey THEMIS VIS
+==================
+The Thermal Emission Imaging System Visible sensor is a push frame camera
+responsible for capturing 5 color bands at a spatial resolution of 18 meters
+per pixel.
+
+Processing THEMIS VIS Images
+----------------------------

docs/source/sensors/Selene.rst

@@ -0,0 +1,47 @@
+Kaguya TC
+=========
+The Kaguya Terrain Camera is a dual-band, stereo, linescan camera with a spatial
+resolution of 20 meters per pixel.  This set of sensors uses two telescopic
+imaging instruments, one pointed forward, and one pointed backward. Together,
+these instruments provide data necessary to create stereoscopic imagery.
+
+Processing Kaguya TC Images
+---------------------------
+Begin by generating an ISD as described in the section on :ref:`isd_generation`.
+
+    import json
+    import os
+    import csmapi
+    import ale
+    import pvl
+    from ale.drivers import JsonEncoder
+    from ale.drivers.kaguya_drivers import KaguyaTcPds3NaifSpiceDriver
+
+    image = "images/TC2W2B0_01_00366S490E1640.img"
+    alelabel = os.path.splitext(image)[0]+".json"
+
+    label = pvl.load(image)
+    driver = KaguyaTcPds3NaifSpiceDriver(image)
+
+    with driver as d:
+        aledict = d.to_dict()
+
+    json.dump(aledict, open(alelabel, "w"), cls=JsonEncoder)
+
+    nlines, nsamples = aledict["image_lines"], aledict["image_samples"]
+
+    model="USGS_ASTRO_LINE_SCANNER_SENSOR_MODEL"
+    plugin = csmapi.Plugin.getList()[0]
+    isd = csmapi.Isd(alelabel)
+    camera = plugin.constructModelFromISD(isd, model)
+
+Kaguya MI
+=========
+The Kaguya Multiband Imagery platform comprises two different instruments -- a
+visible light sensor (VIS) and a near infrared sensor (NIR).  The visible light
+sensor has a spatial resolution of 20 meters per pixel, and collects 5 bands of
+data via a bandpass filter.  The near infrared sensor is responsible for
+collecting 4 bands of data at a resolution of 62 meters per pixel.
+
+Processing Kaguya MI Images
+---------------------------

docs/source/sensors/TraceGasOrbiter.rst

@@ -0,0 +1,9 @@
+TGO CaSSIS
+==========
+The Trace Gas Orbiter's Color and Stereo Surface Imaging System is a 4 filter
+frame camera capable of capturing data at a resolution of 4.6 meters per pixel.
+The camera is mounted on a rotating mechanism, and it is able to capture stereo
+imagery in a single pass.
+
+Processing TGO CaSSIS Images
+----------------------------

docs/source/sensors/Viking.rst

@@ -0,0 +1,8 @@
+Viking
+======
+The Viking visual imaging subsystem comprises two high-resolution framing
+cameras.  These cameras are identical, and each camera contains 6 color imaging
+filters and one clear filter.
+
+Processing Viking Images
+------------------------

docs/source/sensors/Voyager.rst

@@ -0,0 +1,9 @@
+Voyager
+=======
+The voyager imaging system is a set of two instruments -- a wide angle camera
+(WAC) and a narrow angle camera (NAC).  The wide angle camera contains 8 filters
+and has a field of view of 3.2 degrees.  The narrow angle camera also contains 8
+filters, and has a field of view of .4 degrees.
+
+Processing Voyager Images
+-------------------------

docs/source/user/creating_an_environment.rst

@@ -0,0 +1,11 @@
+Creating an environment
+-----------------------
+Due to version incompatibilities, setting up a full environment can be somewhat
+difficult to navigate, and it is recommended that you follow these steps.  This
+guide assumes that you already have anaconda set up on your computer.  If you do
+not, please follow `these instructions <https://www.anaconda.com/products/distribution>`_.
+
+    conda create -n csm python=3.6
+    conda activate csm
+    conda install -c conda-forge csmapi
+    conda env update -n csm -f environment.yml

docs/source/user/isd_generation.rst

@@ -0,0 +1,69 @@
+.. _isd_generation:
+
+Creating and testing an ISD
+===
+
+This tutorial assumes that the user has created a conda environment with ale, usgscsm,
+and csmapi installed.
+
+Generating an ISD with ALE
+-----------------
+ISD generation is the first step in processing an image with the models provided
+by USGSCSM.  ISDs can be easily generated with the use of
+`ALE <https://github.com/USGS-Astrogeology/ale>`_, which generates ISDs through
+the use of the "load" and "loads" functions  After installing the library
+(as described on the repository), one can generate an ISD using the image's label
+in the following fashion::
+
+    import ale
+
+    image_label_path = "/path/to/my/image.lbl"
+    isd_string = ale.loads(image_label_path)
+
+Under some circumstances, ALE fails to identify a set of kernels to properly
+generate an ISD, and users will receive the message
+
+    "No Such Driver for Label."
+
+Under these circumstances, the user must explicitly pass the desired kernel set
+to the loads function.  This kernel set can be generated from a spiceinit'd cub
+and passed to ale as follows:
+
+    kernels = ale.util.generate_kernels_from_cube(spice_initted_cub, expand=True)
+    isd = ale.loads(img_file, props={'kernels': kernels})
+
+After generating the ISD in Python, it is necessary to save it to disc. This is
+accomplished via Python builtin functions such as:
+
+    with open('out.json', 'w') as f:
+        f.write(isd)
+
+Generating an ISD with Pfeffernusse
+-------------
+Alternatively, ISDs can be generated via web service through the API exposed by
+`Pfeffernusse <https://app.swaggerhub.com/apis/USGS-Astro/pfeffernusse2/0.1.4-oas3>`_.
+While the web service is not yet publicly hosted, a public version of the service
+is under development.  Individuals or organizations may choose to host their own
+service, and it can be accessed as follows::
+
+    curl -X POST "http://<servername>:<port>/v1/pds/" -H \
+    "accept: application/json" -H "Content-Type: application/json" \
+    -d @EN1040199536M_tmp.json
+
+where EN1040199536M_tmp.json is a file containing a JSON representation of an
+image label.
+
+Testing the ISD
+---------------
+USGSCSM includes a test utility that can be used to verify the integrity of an
+ISD by loading a camera model and performing basic tests.  This utility is
+located in the USGSCSM build directory, and requires only the path to the ISD
+from the previous step.
+
+    ./usgscsm_cam_test --model /Path/to/isd.json
+
+A successful test will result in output similar to the following:
+
+    Detected CSM plugin: UsgsAstroPluginCSM
+    Number of models for this plugin: 4
+    Loaded a CSM model of type USGS_ASTRO_LINE_SCANNER_SENSOR_MODEL from ISD file ...