diff --git a/ale/base/data_naif.py b/ale/base/data_naif.py index 98d07805e76d9d40085343bf5c2987df872cb467..70499578e5cf9d69c47ce1fdea87866f89f31e3a 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 bf6fcab3d2c9b831ddd984f58675596a095af0eb..e25e36df2ccc01c4b54dba8d161f763a994636a4 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 16f743d1b4563d7554bc5036fdfefaca9b0910e0..8743697bc12a1316a2bf0e172ec491dae5adb36c 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 0814700b4069194fa5d5196de3da643e83ce8c75..1a5388a257a024c06475a53c86c2eadd9955d5d1 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 f2eea5b4288993a73a202ab0640cd06f865fbce8..16e7e0b994d2ee0ec0b6c054602f9defafb4e3cf 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 d739e564bd6204f94b66eec1f487e796dbcfcfcb..d47d9e9711d47cfdde8b055d32c58a015f39c9bc 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 8e2ad1cc2225bd803d36aa83fdf1402b889a3682..169d34ec15754de0d073fecb7bacd29606e2af4b 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 0000000000000000000000000000000000000000..1221866d5ac710573f3209d8ccebd84f5991e65c --- /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 9cc7d93db24eba472b41d8f5bf31eb3b3b4f7bf6..e667fc347e7fb3e6e54db9d3fc78129010e76649 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 0000000000000000000000000000000000000000..9c1b6450a1f38de6047a077f8c6bf8ba66dcb704 --- /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 0000000000000000000000000000000000000000..cf32561307c499786f33c51d51a3a740f5a52dcc --- /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 0000000000000000000000000000000000000000..6a60d71687506a2377ee32a292725a3153997d05 --- /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 0000000000000000000000000000000000000000..9f7ee4e62ea7e70e6069fb5ae817c7eb20f626aa --- /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 0000000000000000000000000000000000000000..a74797d84162bc22ae62df713a3a4c524f3f28a7 --- /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 0000000000000000000000000000000000000000..0dbef76baf8c752ea2b1d43f9b1fca00bea553d3 --- /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 0000000000000000000000000000000000000000..d152487425d0d904f8c5352cc0620321f9f010e1 --- /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 0000000000000000000000000000000000000000..bdcfc1a6738b08bca961dcfe5e7b990793afc216 --- /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 0000000000000000000000000000000000000000..3072eaa956e29d896d6697a66313c5b86cd2e3b4 --- /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)