From 3c90f18d8341a9ee2c80a25db66031bbfc358f39 Mon Sep 17 00:00:00 2001
From: "Sanders, Austin Ray" <arsanders@usgs.gov>
Date: Fri, 20 Oct 2023 20:33:59 +0000
Subject: [PATCH] Added SPICE overview docs

---
 docs/concepts/SPICE/SPICE Overview.md         | 185 ++++++++++++++++++
 ...ICE Position Functions and Requirements.md | 146 ++++++++++++++
 mkdocs.yml                                    |   3 +
 3 files changed, 334 insertions(+)
 create mode 100644 docs/concepts/SPICE/SPICE Overview.md
 create mode 100644 docs/concepts/SPICE/SPICE Position Functions and Requirements.md

diff --git a/docs/concepts/SPICE/SPICE Overview.md b/docs/concepts/SPICE/SPICE Overview.md
new file mode 100644
index 0000000..2b87bec
--- /dev/null
+++ b/docs/concepts/SPICE/SPICE Overview.md	
@@ -0,0 +1,185 @@
+# SPICE 
+
+## Introduction 
+
+-----
+
+Once an image has been correctly ingested into ISIS3 (meaning that the
+ISIS3 cube label contains all required mission-specific keywords ),
+additional navigational and ancillary information (SPICE) is required
+in order to calibrate and geometrically/photometrically process the data.
+ISIS3 utilizes software supplied by the Navigation and Ancillary Information Facility 
+(NAIF).
+
+SPICE ( **S** pacecraft & **P** lanetary ephemerides, **I** nstrument
+**C** -matrix and **E** vent kernels) refers to all the information that
+is required and computed in order for ISIS3 to map each image onto a
+surface with reference to spacecraft position, sun position, instrument
+and mission activities.
+
+
+## SPICEINIT 
+
+-----
+
+The ISIS3 application
+[**spiceinit**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html)
+adds the necessary SPICE information to an image cube. It is important
+to note that if spiceinit is unsuccessful then further cartographic
+processing will not be possible.
+
+
+### Required Mission Keywords 
+
+At a minimum 'spiceinit' requires SpacecraftName, InstrumentId,
+TargetName, StartTime and StopTime. These keywords are loaded at the
+ingestion step ( [Importing Mission Data](../../getting-started/Using%20ISIS:%20First%20Steps/Locating%20and%20Ingesting%20Image%20Data.md) ).
+
+See also: [**Mission Specific
+Programs**](http://isis.astrogeology.usgs.gov/Application/index.html)
+
+
+### ISIS3 SPICE Labels 
+
+  - The information supplied by spiceinit is placed in the
+    **Group=Kernels** and **Group=Instrument** label portion of the
+    ISIS3 image cube.  
+  - Information on the quality of the kernels is added to keywords
+    within the Kernels Group "InstrumentPointingQuality" and "InstrumentPositionQuality"
+  - SPICE computation results can also be attached to the **blob**
+    portion of the ISIS3 image cube (i.e., parameter **ATTACH=TRUE** -
+    the current spiceinit default).
+  - See also in the ISIS3 Documentation: [**Label
+    Dictionary**](http://isis.astrogeology.usgs.gov/documents/LabelDictionary/LabelDictionary.html)
+
+
+## Camera Pointing 
+
+-----
+
+Spiceinit will load the location and filename of the camera pointing
+kernel (CK) in the ISIS3 keyword **InstrumentPointing** .
+
+Which file that is loaded depends on a couple of things:
+
+First, the StartTime of the image must be found within any CK kernel
+
+Secondly, The user can specify what type of CK kernel
+
+  - CKSMITHED - This is considered camera pointing that has been through
+    a bundle-adjustment and most likely the most accurate; this level of
+    pointing is not often available and might not include the entire
+    collection of mission image data.
+  - CKRECON - The default ck kernel for spiceinit. This kernel is the
+    mission actual and is often improved on by NAIF or the mission
+    navigation team.
+  - CKPREDICTED - The least desired, but "better than nothing" kernel
+    that is most available during real-time on newly acquired mission
+    data.
+  - CKNADIR - Nadir pointing is computed if no CK kernels exist
+    (''Requirements...under construction'')
+
+!!! Tip "Tips:"
+    - All parameters above can be set to **=TRUE** and spiceinit will
+      search and load in a hierarchical order from c-smithed first to
+      predicted last. Be aware if processing multiple files and allowing
+      inconsistencies in different ck sources.
+    - The **InstrumentPointingQuality** keyword will be added to the
+      Kernels Group with a value indicating what quality of camera
+      pointing was found and loaded for the input image
+      (InstrumentPointingQuality = Reconstructed or Predicted).
+
+
+## Spacecraft Position 
+
+-----
+
+Spiceinit will load the location and filename of the spacecraft pointing
+kernel (SPK) in the ISIS3 keyword **InstrumentPosition** .
+
+Which file that is loaded depends on a couple of things:
+
+First, the StartTime of the image must be found within any SPK kernel
+
+Secondly, The user can specify what type of SPK kernel
+
+  - SPKSMITHED - This is considered camera pointing that has been
+    through a bundle-adjustment and most likely the most accurate; this
+    level of pointing is not often available and might not include the
+    entire collection of mission image data.
+  - SPKRECON - The default spk kernel for spiceinit. This kernel is the
+    mission actual and is often improved on by NAIF or the mission
+    navigation team.
+  - SPKPREDICTED - The least desired, but "better than nothing" kernel
+    that is most available during real-time on newly acquired mission
+    data.
+
+!!! Tip "Tips:"
+    - All parameters above can be set to **=TRUE** and spiceinit will
+      search and load in a hierarchical order from c-smithed first to
+      predicted last. Be aware if processing multiple files and allowing
+      inconsistencies in different spk sources.
+    - The **InstrumentPositionQuality** keyword will be added to the
+      Kernels Group with a value indicating what quality of camera
+      pointing was found and loaded for the input image
+      (InstrumentPositionQuality = Reconstructed or Predicted).
+
+
+## Shape Model 
+
+-----
+
+Shape Models are what ISIS intersects imaging rays with. When mapping a pixel from an image to a ground point, ISIS generates a look vector using the camera model and then intersects that ray with the surface to generate a ground point.
+
+The ISIS data area and spiceinit are set up to automatically select an appropriate shape model for most data sets. If want more control over which shape model you use or are working with a new data set, here's the different options available in ISIS.
+
+The most basic type of shape model is an ellipsoid shape model. When using an ellipsoid shape model, ISIS intersects imaging rays with a tri-axial ellipsoid. The ellipsoid radii are defined in the PCK. To use an ellipsoid shape model, set `SHAPE=ELLIPSOID` when running spiceinit.
+
+ISIS also supports Digital Elevation Models (DEMs) as shape models. A DEM is a raster image that defines the local radius at each pixel in the image. DEMs can cover a local region or the entirety of a body. When working with a DEM, make sure that it covers the entire ground range of your data set. Some applications use DEMs that define the height or elevation above a reference ellipsoid, but ISIS only supports DEMs that define the radius so that there is no inconsistency between reference ellipsoids. Before using a DEM, it must first be ingested into an ISIS cube file and then run through the demprep application. Once that is complete, set `SHAPE=USER MODEL=<path to your DEM cube>` when running spiceinit.
+
+Some data sets observe irregular surfaces that cannot be represented by a DEM. Surfaces in these situations are now being represented by Digital Shape Kernels (DSKs). You can select a DSK shape model in spiceinit the same way you can select a DEM, set `SHAPE=USER MODEL=<path to your DSK file>`. ISIS supports shape models for DSKs in three different ways: CSPICE, Embree, and Bullet.
+
+By default, ISIS will use the low-level CSPICE routines to intersect imaging rays with the DSK. The CSPICE routines do not load the surface shape into memory, so they use less memory but are limited by your I/O speeds. We recommend having the DSK file on a local, high-speed SSD when using the CSPICE routines.
+
+Both Embree and Bullet load the surface shape from the DSK file into memory and then use ray casting algorithms to intersect imaging rays with the surface. As such, they require more memory, but are significantly faster than the CSPICE routines. Embree performs floating point intersection operations which have between 6 and 9 significant digits of precision. Bullet performs double precision intersection operations  which have between 15 and 18 significant digits of precision. For rapid analysis and to check processing, some users prefer Embree, but for final products and precision analysis we recommend using Bullet. To select the Embree or Bullet shape model you will need to modify the ShapeModel section of your IsisPreference file.
+
+```
+Group = ShapeModel
+  RayTraceEngine = Embree
+  OnError = Continue
+EndGroup
+```
+
+or 
+
+```
+Group = ShapeModel
+  RayTraceEngine = Bullet
+  OnError = Continue
+EndGroup
+```
+
+If you run spiceinit with a DSK shape model and a RayTraceEngine specified in your IsisPreference file, then that will be added to the output cube's label. The cube will use the selected shape model from that point on. This can be overwritten by your current IsisPreference file contents. See the table below for more details:
+
+|IsisPreference at spiceinit | IsisPreference now      | shape model used |
+| -------------------------- | ----------------------- | ---------------- |
+| No ShapeModel Group        | No ShapeModel Group     | CSPICE           |
+| No ShapeModel Group        | RayTraceEngine = Bullet | Bullet           |
+| No ShapeModel Group        | RayTraceEngine = Embree | Embree           |
+| RayTraceEngine = Embree    | No ShapeModel Group     | Embree           |
+| RayTraceEngine = Embree    | RayTraceEngine = CSPICE | CSPICE           |
+| RayTraceEngine = Embree    | RayTraceEngine = Embree | Embree           |
+| RayTraceEngine = Embree    | RayTraceEngine = Bullet | Bullet           |
+| RayTraceEngine = Bullet    | No ShapeModel Group     | Bullet           |
+| RayTraceEngine = Bullet    | RayTraceEngine = CSPICE | CSPICE           |
+| RayTraceEngine = Bullet    | RayTraceEngine = Embree | Embree           |
+| RayTraceEngine = Bullet    | RayTraceEngine = Bullet | Bullet           |
+
+
+## References & Related Resources
+
+-----
+
+1.  About [NAIF](http://naif.jpl.nasa.gov/naif/index.html)
+2.  About [NAIF SPICE](http://naif.jpl.nasa.gov/naif/aboutspice.html)
+3.  [NAIF Software Toolkit](http://naif.jpl.nasa.gov/naif/toolkit.html)
diff --git a/docs/concepts/SPICE/SPICE Position Functions and Requirements.md b/docs/concepts/SPICE/SPICE Position Functions and Requirements.md
new file mode 100644
index 0000000..d39a5e9
--- /dev/null
+++ b/docs/concepts/SPICE/SPICE Position Functions and Requirements.md	
@@ -0,0 +1,146 @@
+# Spice Functions and Requirements
+This document outlines the critical components of the SpicePosition class. This will help guide our refactor efforts by defining the limitations imposed by the rest of the ISIS code base.
+
+## Compute Position and Velocity
+This is the core functionality of SpicePosition. It is a part of the stateful ISIS camera model, so when the position and velocity are computed at a time, all three are stored internally. There are three accessors for the stored values.
+
+### Data sources
+SpicePosition needs to be able to use several different data sources.
+
+#### SPICE Kernels
+SpicePosition is the part of ISIS that reads from SPKs. 99% of the time this only happens during spiceinit because it is immediately cached and saved to the cube file.
+
+#### Position and Velocity Cache
+This is the data source most often used by ISIS. The data is interpolated by either a linear method or a cubic hermite spline.
+
+#### Polynomials
+This is the data source used during and after bundle adjustment.
+
+#### Combination of Cache and Polynomial
+This is used for bundle adjustment of very jittery images. Mechanically, this is the sum of a low degree polynomial and a cubic hermite spline cache.
+### Relevant public methods
+* SetEphemerisTime(double et)
+* EphemerisTime()
+* Coordinate()
+* Velocity()
+
+## Create a Cache from SPICE Data for an Image
+
+This is both a big part of regular ISIS usage and how the spice server works. The spice server creates the cache and then ships it back over the wire.
+
+### Reducing Cache Size
+For large push broom images, a data point for every line can be a huge amount of data to store and work with. So, SpicePosition must able to reduce the cache size based on a given tolerance.
+### Relevant public methods
+* LoadCache(double startTime, double endTime, int size)
+* LoadCache(double time)
+* ReloadCache()
+* Memcache2HermiteCache(double tolerance)
+
+## Write/Read Polynomial or Cached Data From/To a Cube
+Currently this is performed via an ISIS Table object, but it could be a generic BLOB.
+### Relevant public methods
+* LoadCache(Table &table)
+* ReloadCache(Table &table)
+* Cache(const QString &tableName)
+* LineCache(const QString &tableName)
+* LoadHermiteCache(const QString &tableName)
+
+## Fit Polynomial Coefficients over Cached Data
+This is how the polynomial coefficients are initialized at the beginning of bundle adjustment.
+### Relevant public methods
+* SetPolynomial(const Source type)
+
+## Provide Access to Polynomial Coefficients
+The bundle adjustment needs access to these values in order to properly construct the normal equations.
+### Relevant public methods
+* GetPolynomial(std::vector<double>& XC, std::vector<double>& YC, std::vector<double>& ZC)
+
+## Take Adjustments to Polynomial Coefficients
+This is how the BundleAdjust applies its corrects each iteration.
+### Relevant public methods
+* SetPolynomial(const std::vector<double>& XC, const std::vector<double>& YC, const std::vector<double>& ZC, const Source type)
+
+## Compute the Partial Derivatives with Respect to a Polynomial Coefficient
+Mathematically these are something like d/db(at^2 + bt + c). These are needed for the bundle adjustment.
+### Relevant public methods
+* CoordinatePartial(SpicePosition::PartialType partialVar, int coeffIndex)
+* VelocityPartial(SpicePosition::PartialType partialVar, int coeffIndex)
+
+
+## Methods
+
+### Time Bias (**Candidate For Removal**)
+* GetTimeBias() const
+    * Only used within `SpicePosition`! We could potentially eliminate this from the API, as it is only used within `SpicePosition`. 
+
+### LightTime and Aberration Correction
+* SetAberrationCorrection(const QString &correction)
+    * Used by `SpacecraftPosition`, `Spice`, `gllssical/main`, `LoHighCamera`, `LoMediumCamera`, `Mariner10Camera`
+* QString GetAberrationCorrection()
+    * Not used anywhere (`SpacecraftPosition` has something similar and should probably use it but doesn't)
+* GetLightTime()
+    * Not used anywhere (`SpacecraftPosition` has something similar and should probably use it but doesn't)
+
+### GetCenterCoordinate
+* GetCenterCoordinate()
+    * Used by `BundleObservation`
+    * Gets the gets the mid point in time between the start and end of the cached position data, and returns that coordinate
+    * Used to get the center position of the instrument when looking at a section of ephemeris data
+
+### HasVelocity (Candidate For Removal)
+* HasVelocity()
+    * Not used, the private variable is getting accessed directly from within `SpicePosition`
+    * Returns the private variable p_hasVelocity from a SpicePosition object
+    * Doesn't provide any functionality at the moment
+
+### IsCached
+* IsCached()
+    * Used by `Spice`
+    * Checks if there is something stored within the cache
+    * Used to determine whether or not to read/write from and to cache
+
+### SetPolynomialDegree
+* SetPolynomialDegree(int degree)
+    * Used by `BundleObservation`
+    * Sets the degree of the internal polynomial state
+    * Used to set and change the polynomials degree, consequently expanding or reducing the polynomial if the polynomials have been "applied"(?)
+
+### GetSource
+* GetSource()
+    * Used by `Spice`
+    * Returns the private variable p_source from a `SpicePosition` object
+    * Used to determine how the data in `SpicePosition` is stored
+
+### Base Time and Time Scaling
+* ComputeBaseTime()
+    * Only used within `SpicePosition`
+    * Computes the base time based on the private variable p_override
+    * Adjust the p_basetime and p_timescale variables in SpicePosition when SetPolynomial is run or when memcache2hermitecache is run
+* GetBaseTime()
+    * Used in `BundleObservation`
+    * Returns the private variable p_basetime
+    * Used to get the current base time for fit equations
+* SetOverrideBaseTime(double baseTime, double timeScale)
+    * Used in `BundleObservation`
+    * Sets the p_overrideBaseTime to the given baseTime, sets p_overrideTimeScale to the given time scale, and sets p_override to timeScale
+    * Used in LoadCache to set the above variables if p_source is not a PolyFunction
+* GetTimeScale()
+    * Used in `BundleObservation`
+    * Returns the private variable p_timeScale
+    * Used to set a variable in `BundleObservation::initializeExteriorOrientation`
+
+### DPolynomial 
+* DPolynomial(const int coeffIndex)
+    * Only used within `SpicePosition`
+    * Takes the derivative of a polynomial in respect to a given coefficient index
+    * Used to compute partial derivatives in `SpicePosition`
+
+### Extrapolate
+* Extrapolate(double timeEt)
+    * Used in `SpkSegment`
+    * Extrapolate position for a given time assuming a constant velocity (From doc string)
+    * Used to extrapolate a new position based on a known position and assumed constant velocity
+
+### HermiteCoordinate()
+* HermiteCoordinate
+    * Not used
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index fa116d7..4bf94f6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -69,6 +69,9 @@ nav:
     - Camera Geometry and Projections:
       - Camera Geometry: concepts/Camera Geometry and Projections/Camera Geometry.md
       - Learning About Map Projections: concepts/Camera Geometry and Projections/Learning About Map Projections.md
+    - SPICE:
+      - SPICE Overview: concepts/SPICE/SPICE Overview.md
+      - SPICE Position Functions and Requirements: concepts/SPICE/SPICE Position Functions and Requirements.md
     - Image Processing:
       - The Power of Spatial Filters: concepts/Image Processing/The Power of Spatial Filters.md
       - Overview of Noise and Artifacts: concepts/Image Processing/Overview of Noise and Artifacts.md
-- 
GitLab