From bc3f2368d57ed4ffa0d27c1f45e59cda3630ede2 Mon Sep 17 00:00:00 2001 From: Jesse Mapel <jmapel@usgs.gov> Date: Tue, 7 Jul 2020 15:02:53 -0700 Subject: [PATCH] Added a quick start guide to the docs & restructured Pythong docs (#378) * Added loads docs * Added other base driver mix-ins * Simple quick start guide * minor clean up * Added quick start and cleaned up * Combined mix-in files * Fixed label data name * Restructured Python docs * Added Python rotation docs * PR review updates * Updated label_data description --- ale/base/data_naif.py | 28 ++++++++ ale/base/label_isis.py | 3 + ale/base/label_pds3.py | 3 + ale/base/type_distortion.py | 12 +++- ale/base/type_sensor.py | 15 +++- ale/drivers/__init__.py | 41 +++++++++-- docs/source/index.rst | 1 + .../{ => concrete_drivers}/co_driver.rst | 0 .../{ => concrete_drivers}/dawn_driver.rst | 0 .../hayabusa2_driver.rst | 0 .../library/python/concrete_drivers/index.rst | 23 +++++++ .../isis_ideal_driver.rst | 0 .../{ => concrete_drivers}/juno_driver.rst | 0 .../{ => concrete_drivers}/lro_driver.rst | 0 .../{ => concrete_drivers}/mess_driver.rst | 0 .../{ => concrete_drivers}/mex_driver.rst | 0 .../{ => concrete_drivers}/mro_driver.rst | 0 .../{ => concrete_drivers}/nh_driver.rst | 0 .../{ => concrete_drivers}/ody_driver.rst | 0 .../{ => concrete_drivers}/selene_driver.rst | 0 .../{ => concrete_drivers}/tgo_driver.rst | 0 .../{ => concrete_drivers}/viking_driver.rst | 0 .../{ => concrete_drivers}/voyager_driver.rst | 0 docs/source/library/python/index.rst | 20 ++---- .../python/mix_ins/distortion_model.rst | 13 ++++ docs/source/library/python/mix_ins/index.rst | 12 ++++ .../library/python/mix_ins/label_data.rst | 18 +++++ .../library/python/mix_ins/sensor_type.rst | 11 +++ .../python/mix_ins/supplementary_data.rst | 18 +++++ docs/source/library/python/rotation.rst | 10 +++ docs/source/library/python/transformation.rst | 10 +++ docs/source/tutorials/index.rst | 13 ++++ docs/source/tutorials/quick_start.rst | 68 +++++++++++++++++++ 33 files changed, 294 insertions(+), 25 deletions(-) rename docs/source/library/python/{ => concrete_drivers}/co_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/dawn_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/hayabusa2_driver.rst (100%) create mode 100644 docs/source/library/python/concrete_drivers/index.rst rename docs/source/library/python/{ => concrete_drivers}/isis_ideal_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/juno_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/lro_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/mess_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/mex_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/mro_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/nh_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/ody_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/selene_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/tgo_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/viking_driver.rst (100%) rename docs/source/library/python/{ => concrete_drivers}/voyager_driver.rst (100%) create mode 100644 docs/source/library/python/mix_ins/distortion_model.rst create mode 100644 docs/source/library/python/mix_ins/index.rst create mode 100644 docs/source/library/python/mix_ins/label_data.rst create mode 100644 docs/source/library/python/mix_ins/sensor_type.rst create mode 100644 docs/source/library/python/mix_ins/supplementary_data.rst create mode 100644 docs/source/library/python/rotation.rst create mode 100644 docs/source/library/python/transformation.rst create mode 100644 docs/source/tutorials/index.rst create mode 100644 docs/source/tutorials/quick_start.rst diff --git a/ale/base/data_naif.py b/ale/base/data_naif.py index 98d0780..7049957 100644 --- a/ale/base/data_naif.py +++ b/ale/base/data_naif.py @@ -9,6 +9,10 @@ from ale.rotation import TimeDependentRotation from ale import util class NaifSpice(): + """ + Mix-in for reading data from NAIF SPICE Kernels. + """ + def __enter__(self): """ Called when the context is created. This is used @@ -29,6 +33,30 @@ class NaifSpice(): @property def kernels(self): + """ + Get the NAIF SPICE Kernels to furnish + + There are two ways to specify which kernels a driver will use: + + 1. Passing the 'kernels' property into load(s) or at instantiation. + This can be either a straight iterable or a dictionary that specifies + the kernels in ISIS style ('TargetPosition', 'InstrumentPosition', etc). + 2. Set the ALESPICEROOT environment variable. This variable should be + the path to a directory that contains directories whose naming + convention matches the PDS Kernel Archives format, + `shortMissionName-versionInfo`. The directory corresponding to the + driver's mission will be searched for the approriate meta kernel to + load. + + See Also + -------- + ale.util.get_kernels_from_isis_pvl : Function used to parse ISIS style dict + ale.util.get_metakernels : Function that searches ALESPICEROOT for meta kernels + ale.util.generate_kernels_from_cube : Helper function to get an ISIS style dict + from an ISIS cube that has been through + spiceinit + + """ if not hasattr(self, '_kernels'): if 'kernels' in self._props.keys(): try: diff --git a/ale/base/label_isis.py b/ale/base/label_isis.py index bf6fcab..e25e36d 100644 --- a/ale/base/label_isis.py +++ b/ale/base/label_isis.py @@ -1,6 +1,9 @@ import pvl class IsisLabel(): + """ + Mix-in for parsing ISIS Cube labels. + """ @property def label(self): diff --git a/ale/base/label_pds3.py b/ale/base/label_pds3.py index 16f743d..8743697 100644 --- a/ale/base/label_pds3.py +++ b/ale/base/label_pds3.py @@ -1,6 +1,9 @@ import pvl class Pds3Label(): + """ + Mix-in for parsing PDS3 PVL labels. + """ @property def label(self): diff --git a/ale/base/type_distortion.py b/ale/base/type_distortion.py index 0814700..1a5388a 100644 --- a/ale/base/type_distortion.py +++ b/ale/base/type_distortion.py @@ -1,9 +1,13 @@ class RadialDistortion(): + """ + Mix-in for sensors that use a radial distortion model. + """ + @property def usgscsm_distortion_model(self): """ Expects odtk to be defined. This should be a list containing - the radial distortion coefficients + the radial distortion coefficients Returns ------- @@ -18,11 +22,15 @@ class RadialDistortion(): class NoDistortion(): + """ + Mix-in for sensors and data sets that do not have a distortion model. + """ + @property def usgscsm_distortion_model(self): """ Returns the specification for no distortion in usgscsm. - + Returns ------- : dict diff --git a/ale/base/type_sensor.py b/ale/base/type_sensor.py index f2eea5b..16e7e0b 100644 --- a/ale/base/type_sensor.py +++ b/ale/base/type_sensor.py @@ -1,6 +1,9 @@ import numpy as np class LineScanner(): + """ + Mix-in for line scan sensors. + """ @property def name_model(self): @@ -70,6 +73,10 @@ class LineScanner(): return self.ephemeris_start_time + (self.image_lines * self.exposure_duration) class Framer(): + """ + Mix-in for framing sensors. + """ + @property def name_model(self): """ @@ -114,6 +121,10 @@ class Framer(): return self.ephemeris_start_time + self.exposure_duration class Radar(): + """ + Mix-in for synthetic aperture radar sensors. + """ + @property def name_model(self): """ @@ -148,7 +159,7 @@ class Radar(): @property def wavelength(self): """ - Returns the wavelength used for image acquistion. + Returns the wavelength used for image acquistion. Returns ------- @@ -168,7 +179,7 @@ class Radar(): Exposure duration for a line """ raise NotImplmentedError - + @property def scaled_pixel_width(self): diff --git a/ale/drivers/__init__.py b/ale/drivers/__init__.py index d739e56..d47d9e9 100644 --- a/ale/drivers/__init__.py +++ b/ale/drivers/__init__.py @@ -55,22 +55,37 @@ class AleJsonEncoder(json.JSONEncoder): def load(label, props={}, formatter='ale', verbose=False): """ - Attempt to load a given label from all possible drivers + Attempt to load a given label from all possible drivers. + + This function opens up the label file and attempts to produce an ISD in the + format specified using the supplied properties. Drivers are tried sequentially + until an ISD is successfully created. Drivers that use external ephemeris + data are tested before drivers that use attached epehemeris data. Parameters ---------- label : str - String path to the given label file + String path to the given label file props : dict A dictionary of optional keywords/parameters for use in driver - loading + loading. Each driver specifies its own set of properties to use. + For example, Drivers that use the NaifSpice mix-in use the 'kernels' + property to specify an explicit set of kernels and load order. - formatter : str - Formatted output to expect from the driver + formatter : {'ale', 'isis', 'usgscsm'} + Output format for the ISD. As of 0.8.0, it is recommended that + the `ale` formatter is used. The `isis` and `usgscsm` formatters + are retrained for backwards compatability. verbose : bool - If True, displays error messages from driver loading + If True, displays debug output specifying which drivers were + attempted and why they failed. + + Returns + ------- + dict + The ISD as a dictionary """ if isinstance(formatter, str): formatter = __formatters__[formatter] @@ -99,5 +114,19 @@ def load(label, props={}, formatter='ale', verbose=False): raise Exception('No Such Driver for Label') def loads(label, props='', formatter='ale', verbose=False): + """ + Attempt to load a given label from all possible drivers. + + This function is the same as load, except it returns a JSON formatted string. + + Returns + ------- + str + The ISD as a JSON formatted string + + See Also + -------- + load + """ res = load(label, props, formatter, verbose=verbose) return json.dumps(res, cls=AleJsonEncoder) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8e2ad1c..169d34e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,3 +9,4 @@ Ephemeris Abstraction Library :maxdepth: 3 library/index + tutorials/index diff --git a/docs/source/library/python/co_driver.rst b/docs/source/library/python/concrete_drivers/co_driver.rst similarity index 100% rename from docs/source/library/python/co_driver.rst rename to docs/source/library/python/concrete_drivers/co_driver.rst diff --git a/docs/source/library/python/dawn_driver.rst b/docs/source/library/python/concrete_drivers/dawn_driver.rst similarity index 100% rename from docs/source/library/python/dawn_driver.rst rename to docs/source/library/python/concrete_drivers/dawn_driver.rst diff --git a/docs/source/library/python/hayabusa2_driver.rst b/docs/source/library/python/concrete_drivers/hayabusa2_driver.rst similarity index 100% rename from docs/source/library/python/hayabusa2_driver.rst rename to docs/source/library/python/concrete_drivers/hayabusa2_driver.rst diff --git a/docs/source/library/python/concrete_drivers/index.rst b/docs/source/library/python/concrete_drivers/index.rst new file mode 100644 index 0000000..1221866 --- /dev/null +++ b/docs/source/library/python/concrete_drivers/index.rst @@ -0,0 +1,23 @@ +:mod:`concrete-drivers` --- Concrete Sensor Driver +================================================== + +The classes in these modules are the concrete drivers that are composed from +the base :py:class:`ale.base.base.Driver` class and various mix-ins classes. + +.. toctree:: + + co_driver + dawn_driver + hayabusa2_driver + isis_ideal_driver + juno_driver + lro_driver + mess_driver + mex_driver + mro_driver + nh_driver + ody_driver + selene_driver + tgo_driver + viking_driver + voyager_driver diff --git a/docs/source/library/python/isis_ideal_driver.rst b/docs/source/library/python/concrete_drivers/isis_ideal_driver.rst similarity index 100% rename from docs/source/library/python/isis_ideal_driver.rst rename to docs/source/library/python/concrete_drivers/isis_ideal_driver.rst diff --git a/docs/source/library/python/juno_driver.rst b/docs/source/library/python/concrete_drivers/juno_driver.rst similarity index 100% rename from docs/source/library/python/juno_driver.rst rename to docs/source/library/python/concrete_drivers/juno_driver.rst diff --git a/docs/source/library/python/lro_driver.rst b/docs/source/library/python/concrete_drivers/lro_driver.rst similarity index 100% rename from docs/source/library/python/lro_driver.rst rename to docs/source/library/python/concrete_drivers/lro_driver.rst diff --git a/docs/source/library/python/mess_driver.rst b/docs/source/library/python/concrete_drivers/mess_driver.rst similarity index 100% rename from docs/source/library/python/mess_driver.rst rename to docs/source/library/python/concrete_drivers/mess_driver.rst diff --git a/docs/source/library/python/mex_driver.rst b/docs/source/library/python/concrete_drivers/mex_driver.rst similarity index 100% rename from docs/source/library/python/mex_driver.rst rename to docs/source/library/python/concrete_drivers/mex_driver.rst diff --git a/docs/source/library/python/mro_driver.rst b/docs/source/library/python/concrete_drivers/mro_driver.rst similarity index 100% rename from docs/source/library/python/mro_driver.rst rename to docs/source/library/python/concrete_drivers/mro_driver.rst diff --git a/docs/source/library/python/nh_driver.rst b/docs/source/library/python/concrete_drivers/nh_driver.rst similarity index 100% rename from docs/source/library/python/nh_driver.rst rename to docs/source/library/python/concrete_drivers/nh_driver.rst diff --git a/docs/source/library/python/ody_driver.rst b/docs/source/library/python/concrete_drivers/ody_driver.rst similarity index 100% rename from docs/source/library/python/ody_driver.rst rename to docs/source/library/python/concrete_drivers/ody_driver.rst diff --git a/docs/source/library/python/selene_driver.rst b/docs/source/library/python/concrete_drivers/selene_driver.rst similarity index 100% rename from docs/source/library/python/selene_driver.rst rename to docs/source/library/python/concrete_drivers/selene_driver.rst diff --git a/docs/source/library/python/tgo_driver.rst b/docs/source/library/python/concrete_drivers/tgo_driver.rst similarity index 100% rename from docs/source/library/python/tgo_driver.rst rename to docs/source/library/python/concrete_drivers/tgo_driver.rst diff --git a/docs/source/library/python/viking_driver.rst b/docs/source/library/python/concrete_drivers/viking_driver.rst similarity index 100% rename from docs/source/library/python/viking_driver.rst rename to docs/source/library/python/concrete_drivers/viking_driver.rst diff --git a/docs/source/library/python/voyager_driver.rst b/docs/source/library/python/concrete_drivers/voyager_driver.rst similarity index 100% rename from docs/source/library/python/voyager_driver.rst rename to docs/source/library/python/concrete_drivers/voyager_driver.rst diff --git a/docs/source/library/python/index.rst b/docs/source/library/python/index.rst index 9cc7d93..e667fc3 100644 --- a/docs/source/library/python/index.rst +++ b/docs/source/library/python/index.rst @@ -2,24 +2,14 @@ =================================== .. autofunction:: ale.drivers.load +.. autofunction:: ale.drivers.loads .. toctree:: base - co_driver - dawn_driver - hayabusa2_driver - isis_ideal_driver - juno_driver - lro_driver - mess_driver - mex_driver - mro_driver - nh_driver - ody_driver - selene_driver - tgo_driver - viking_driver - voyager_driver util + rotation + transformation + mix_ins/index + concrete_drivers/index diff --git a/docs/source/library/python/mix_ins/distortion_model.rst b/docs/source/library/python/mix_ins/distortion_model.rst new file mode 100644 index 0000000..9c1b645 --- /dev/null +++ b/docs/source/library/python/mix_ins/distortion_model.rst @@ -0,0 +1,13 @@ +:mod:`Distortion Model` --- Distortion Model Type Mix-ins +========================================================= + +The mix-ins in this module are for common distortion models that are shared +between multiple sensors. Distortion models that are unique to a sensor or +mission are kept in the driver module for that mission. + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.type_distortion + :synopsis: + :members: + :show-inheritance: diff --git a/docs/source/library/python/mix_ins/index.rst b/docs/source/library/python/mix_ins/index.rst new file mode 100644 index 0000000..cf32561 --- /dev/null +++ b/docs/source/library/python/mix_ins/index.rst @@ -0,0 +1,12 @@ +:mod:`mix-ins` --- Mix-in Classes +================================= + +The classes in these modules are mix-ins that combined with the base +:py:class:`ale.base.base.Driver` class create the concrete drivers. + +.. toctree:: + + supplementary_data + label_data + sensor_type + distortion_model diff --git a/docs/source/library/python/mix_ins/label_data.rst b/docs/source/library/python/mix_ins/label_data.rst new file mode 100644 index 0000000..6a60d71 --- /dev/null +++ b/docs/source/library/python/mix_ins/label_data.rst @@ -0,0 +1,18 @@ +:mod:`Label Data` --- Label Data Mix-ins +======================================== + +Modules for accessing label data. + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.label_isis + :synopsis: + :members: + :show-inheritance: + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.label_pds3 + :synopsis: + :members: + :show-inheritance: diff --git a/docs/source/library/python/mix_ins/sensor_type.rst b/docs/source/library/python/mix_ins/sensor_type.rst new file mode 100644 index 0000000..9f7ee4e --- /dev/null +++ b/docs/source/library/python/mix_ins/sensor_type.rst @@ -0,0 +1,11 @@ +:mod:`Sensor Type` --- Sensor Type Mix-ins +========================================== + +The mix-ins in this module are for different types of imaging sensors. + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.type_sensor + :synopsis: + :members: + :show-inheritance: diff --git a/docs/source/library/python/mix_ins/supplementary_data.rst b/docs/source/library/python/mix_ins/supplementary_data.rst new file mode 100644 index 0000000..a74797d --- /dev/null +++ b/docs/source/library/python/mix_ins/supplementary_data.rst @@ -0,0 +1,18 @@ +:mod:`Supplementary Data` --- Supplementary Data Mix-ins +======================================================== + +Modules for accessing supplementary data when computing exterior orientation. + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.data_naif + :synopsis: + :members: + :show-inheritance: + +.. versionadded:: 0.1.0 + +.. automodule:: ale.base.data_isis + :synopsis: + :members: + :show-inheritance: diff --git a/docs/source/library/python/rotation.rst b/docs/source/library/python/rotation.rst new file mode 100644 index 0000000..0dbef76 --- /dev/null +++ b/docs/source/library/python/rotation.rst @@ -0,0 +1,10 @@ +:mod:`rotation` --- Python Rotations +==================================== + +The :mod:`ale.rotation` module + +.. versionadded:: 0.1.0 + + .. automodule:: ale.rotation + :synopsis: + :members: diff --git a/docs/source/library/python/transformation.rst b/docs/source/library/python/transformation.rst new file mode 100644 index 0000000..d152487 --- /dev/null +++ b/docs/source/library/python/transformation.rst @@ -0,0 +1,10 @@ +:mod:`transformation` --- Python Frame Transformations +====================================================== + +The :mod:`ale.transformation` module + +.. versionadded:: 0.1.0 + + .. automodule:: ale.transformation + :synopsis: + :members: diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst new file mode 100644 index 0000000..bdcfc1a --- /dev/null +++ b/docs/source/tutorials/index.rst @@ -0,0 +1,13 @@ +######### +Tutorials +######### + +:Release: |version| +:Date: |today| + +----------------------------------------- + +.. toctree:: + :maxdepth: 2 + + quick_start diff --git a/docs/source/tutorials/quick_start.rst b/docs/source/tutorials/quick_start.rst new file mode 100644 index 0000000..3072eaa --- /dev/null +++ b/docs/source/tutorials/quick_start.rst @@ -0,0 +1,68 @@ +=============== +ALE Quick Start +=============== + +This document provides a set of steps to get setup for generating Image Support +Data (ISD) for an image. + +Installation +============ + +The easiest way to setup ALE is using Anaconda. Once you have +`Anaconda <https://www.anaconda.com/products/individual>`_ or +`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ installed install +ALE from conda-forge by running + +.. code-block:: + + conda install -c conda-forge ale + +.. note:: + It is highly recommended that you use + `environments <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_ + to manage the packages you install with Anaconda. + +Data +==== + +Planetary imagery is not archived with sufficient data to generate an ISD +from only the image and its label. ALE currently supports two supplementary data +sources: ISIS cubes with attached SPICE, and NAIF SPICE Kernels. + + +If you are working with ISIS cubes that have attached SPICE (the +`spiceinit <https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html>`_ +application has been run on them) then ALE will use the data embedded in the +cube file. + + +If you are working with PDS3 images or ISIS cubes that do not have attached +SPICE, then you will need to download the required NAIF SPICE Kernels for your +image. It is recommended that you use the metakernels provided in the +`PDS kernel archives <https://naif.jpl.nasa.gov/naif/data_archived.html>`_. +You can specify the path for ALE to search for metakernels via the +``ALESPICEROOT`` environment variable. This should be set to the directory where +you have the PDS kernel archives downloaded. An example structure would be + +* $ALESPICEROOT + + * mro-m-spice-6-v1.0 + * dawn-m_a-spice-6-v1.0 + * mess-e_v_h-spice-6-v1.0 + +See :py:attr:`ale.base.data_naif.NaifSpice.kernels` for more information about how to +specify NAIF SPICE kernels. + +Load/Loads +========== + +The :py:meth:`ale.drivers.load` and :py:meth:`ale.drivers.loads` functions are +the main interface for generating ISDs. Simply pass them the path to your image +file/label and they will attempt to generate an ISD for it. + +.. code-block:: python + + import ale + + image_label_path = "/path/to/my/image.lbl" + isd_string = ale.loads(image_label_path) -- GitLab