From fadcb0b8ef474fab10abf9d96f275d7d962c7c13 Mon Sep 17 00:00:00 2001 From: AustinSanders Date: Tue, 17 May 2022 14:02:57 -0700 Subject: [PATCH] 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 --- docs/source/sensors/Cassini.rst | 39 +++++++++ docs/source/sensors/Dawn.rst | 7 ++ docs/source/sensors/Galileo.rst | 8 ++ docs/source/sensors/Hayabusa.rst | 9 +++ docs/source/sensors/Juno.rst | 8 ++ .../sensors/LunarReconnaissanceOrbiter.rst | 81 +++++++++++++++++++ docs/source/sensors/MarsExpress.rst | 21 +++++ .../sensors/MarsReconnaissanceOrbiter.rst | 9 +++ docs/source/sensors/Messenger.rst | 10 +++ docs/source/sensors/NewHorizons.rst | 9 +++ docs/source/sensors/Odyssey.rst | 18 +++++ docs/source/sensors/Selene.rst | 47 +++++++++++ docs/source/sensors/TraceGasOrbiter.rst | 9 +++ docs/source/sensors/Viking.rst | 8 ++ docs/source/sensors/Voyager.rst | 9 +++ docs/source/user/creating_an_environment.rst | 11 +++ docs/source/user/isd_generation.rst | 69 ++++++++++++++++ 17 files changed, 372 insertions(+) create mode 100644 docs/source/sensors/Cassini.rst create mode 100644 docs/source/sensors/Dawn.rst create mode 100644 docs/source/sensors/Galileo.rst create mode 100644 docs/source/sensors/Hayabusa.rst create mode 100644 docs/source/sensors/Juno.rst create mode 100644 docs/source/sensors/LunarReconnaissanceOrbiter.rst create mode 100644 docs/source/sensors/MarsExpress.rst create mode 100644 docs/source/sensors/MarsReconnaissanceOrbiter.rst create mode 100644 docs/source/sensors/Messenger.rst create mode 100644 docs/source/sensors/NewHorizons.rst create mode 100644 docs/source/sensors/Odyssey.rst create mode 100644 docs/source/sensors/Selene.rst create mode 100644 docs/source/sensors/TraceGasOrbiter.rst create mode 100644 docs/source/sensors/Viking.rst create mode 100644 docs/source/sensors/Voyager.rst create mode 100644 docs/source/user/creating_an_environment.rst create mode 100644 docs/source/user/isd_generation.rst diff --git a/docs/source/sensors/Cassini.rst b/docs/source/sensors/Cassini.rst new file mode 100644 index 000000000..a673b498f --- /dev/null +++ b/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) diff --git a/docs/source/sensors/Dawn.rst b/docs/source/sensors/Dawn.rst new file mode 100644 index 000000000..51cde4b63 --- /dev/null +++ b/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 +------------------------- diff --git a/docs/source/sensors/Galileo.rst b/docs/source/sensors/Galileo.rst new file mode 100644 index 000000000..9de137cb8 --- /dev/null +++ b/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 +----------------------------- diff --git a/docs/source/sensors/Hayabusa.rst b/docs/source/sensors/Hayabusa.rst new file mode 100644 index 000000000..d6d8d4bd3 --- /dev/null +++ b/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 +------------------------------ diff --git a/docs/source/sensors/Juno.rst b/docs/source/sensors/Juno.rst new file mode 100644 index 000000000..9a22d2701 --- /dev/null +++ b/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 +------------------------- diff --git a/docs/source/sensors/LunarReconnaissanceOrbiter.rst b/docs/source/sensors/LunarReconnaissanceOrbiter.rst new file mode 100644 index 000000000..168e9df21 --- /dev/null +++ b/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`. diff --git a/docs/source/sensors/MarsExpress.rst b/docs/source/sensors/MarsExpress.rst new file mode 100644 index 000000000..96e037f99 --- /dev/null +++ b/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 +--------------------- diff --git a/docs/source/sensors/MarsReconnaissanceOrbiter.rst b/docs/source/sensors/MarsReconnaissanceOrbiter.rst new file mode 100644 index 000000000..41b35096a --- /dev/null +++ b/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 +------------------------- diff --git a/docs/source/sensors/Messenger.rst b/docs/source/sensors/Messenger.rst new file mode 100644 index 000000000..a59f668dd --- /dev/null +++ b/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 +---------------------- diff --git a/docs/source/sensors/NewHorizons.rst b/docs/source/sensors/NewHorizons.rst new file mode 100644 index 000000000..2a443439f --- /dev/null +++ b/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 +------------------------------------ diff --git a/docs/source/sensors/Odyssey.rst b/docs/source/sensors/Odyssey.rst new file mode 100644 index 000000000..cf74fd36f --- /dev/null +++ b/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 +---------------------------- diff --git a/docs/source/sensors/Selene.rst b/docs/source/sensors/Selene.rst new file mode 100644 index 000000000..9b58192a0 --- /dev/null +++ b/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 +--------------------------- diff --git a/docs/source/sensors/TraceGasOrbiter.rst b/docs/source/sensors/TraceGasOrbiter.rst new file mode 100644 index 000000000..147fb5b29 --- /dev/null +++ b/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 +---------------------------- diff --git a/docs/source/sensors/Viking.rst b/docs/source/sensors/Viking.rst new file mode 100644 index 000000000..f0c400321 --- /dev/null +++ b/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 +------------------------ diff --git a/docs/source/sensors/Voyager.rst b/docs/source/sensors/Voyager.rst new file mode 100644 index 000000000..3407df33d --- /dev/null +++ b/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 +------------------------- diff --git a/docs/source/user/creating_an_environment.rst b/docs/source/user/creating_an_environment.rst new file mode 100644 index 000000000..132a5e55b --- /dev/null +++ b/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 `_. + + conda create -n csm python=3.6 + conda activate csm + conda install -c conda-forge csmapi + conda env update -n csm -f environment.yml diff --git a/docs/source/user/isd_generation.rst b/docs/source/user/isd_generation.rst new file mode 100644 index 000000000..55f8b75c0 --- /dev/null +++ b/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 `_, 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 `_. +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://:/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 ...