Skip to content
Snippets Groups Projects
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
No related merge requests found
# 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)
# 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
...@@ -69,6 +69,9 @@ nav: ...@@ -69,6 +69,9 @@ nav:
- Camera Geometry and Projections: - Camera Geometry and Projections:
- Camera Geometry: concepts/Camera Geometry and Projections/Camera Geometry.md - Camera Geometry: concepts/Camera Geometry and Projections/Camera Geometry.md
- Learning About Map Projections: concepts/Camera Geometry and Projections/Learning About Map Projections.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: - Image Processing:
- The Power of Spatial Filters: concepts/Image Processing/The Power of Spatial Filters.md - 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 - Overview of Noise and Artifacts: concepts/Image Processing/Overview of Noise and Artifacts.md
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment