Commit 4336476f authored by Sanders, Austin Ray's avatar Sanders, Austin Ray
Browse files

Merge branch 'spice' into 'main' 

Added SPICE overview docs

Closes #20

See merge request astrogeology/asc-public-docs!15
parents 793866cd 3c90f18d

docs/concepts/SPICE/SPICE Overview.md

0 → 100644
+185 −0
Original line number Diff line number Diff line 
# 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)

docs/concepts/SPICE/SPICE Position Functions and Requirements.md

0 → 100644
+146 −0
Original line number Diff line number Diff line 
# 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

mkdocs.yml

+3 −0
Original line number Diff line number Diff line
@@ -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