Skip to content
Snippets Groups Projects
Unverified Commit d1ba0228 authored by Amy Stamile's avatar Amy Stamile Committed by GitHub
Browse files

Isis Fundamental Docs (#28)


* isis-introduction

* Added isis fundamental docs

* fix typos

* fixed dark mode css

* autoseed relative link

* faq relative links, more descriptive links, grammar

* Revisions to ISIS fundamentals docs

* title change, link correction, typos

* resort isis-fundamentals into concepts and getting-started

* updated link to isis intro from autoseed

* link corrections

* collapseable faq questions

* updated links

* formatting, -flags in `code` on intro to isis

* textures... link correction, commas

* Describe examples instead of linking to interactives, clean resc and code

* Removed reference to Bundle Adjusted BodyRotation Table TODO

---------

Co-authored-by: default avatarJacob Cain <jrcain@usgs.gov>
parent ecd1150c
No related branches found
No related tags found
No related merge requests found
Showing
with 757 additions and 228 deletions
{% extends "base.html" %} {% extends "base.html" %}
{% block scripts %} {% block scripts %}
<script async type="text/javascript" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=DOI" id="_fed_an_ua_tag"></script> <script async type="text/javascript" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=DOI" id="_fed_an_ua_tag"></script>
<script type="text/javascript" src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/js/uswds-init.min.js"></script>
{{super()}} {{super()}}
{% endblock %} {% endblock %}
{% block header %} {% block header %}
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<script type="text/javascript" src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/js/uswds-init.min.js"></script>
<script type="text/javascript" src="https://asc-public-docs.s3.us-west-2.amazonaws.com/common/uswds/3.6.0/js/uswds.min.js"></script>
</body>
<section class="usa-banner" aria-label="Official government website"> <section class="usa-banner" aria-label="Official government website">
<div class="usa-accordion"> <div class="usa-accordion">
<header class="usa-banner__header"> <header class="usa-banner__header">
......
...@@ -3,6 +3,7 @@ ...@@ -3,6 +3,7 @@
*[Bit]: Short for binary digit, which in a computer is the smallest unit of storage. Bits are either "0" or "1". *[Bit]: Short for binary digit, which in a computer is the smallest unit of storage. Bits are either "0" or "1".
*[Byte]: Short for binary term. A byte is a collection of computer bits. On most modern computers, a byte is a group of eight bits. Typically, computers handle and store information in binary (base-2), and a group of eight bits represents an eight digit binary number. *[Byte]: Short for binary term. A byte is a collection of computer bits. On most modern computers, a byte is a group of eight bits. Typically, computers handle and store information in binary (base-2), and a group of eight bits represents an eight digit binary number.
*[CSM]: Community Sensor Model. A standard for sensor models USGS uses for interoperability. *[CSM]: Community Sensor Model. A standard for sensor models USGS uses for interoperability.
*[DN]: Digital Number. The numeric value of a single pixel in an image. The value can represent a measurement in various units, such as reflectance (I/F), radiance, elevation, or radius. Digital Numbers can be discrete integers or floating point values.
*[EMCAscript]: A standard for scripting languages. C++'s standard library uses the EMCAscript standard for regular expressions. *[EMCAscript]: A standard for scripting languages. C++'s standard library uses the EMCAscript standard for regular expressions.
*[SPICE]: Spacecraft & Planetary ephemerides, Instrument C-matrix and Event kernels. SPICE refers to all the information required by ISIS in order to compute and map each image pixel onto a surface with reference to spacecraft position, sun position, instrument, and mission activities. ISIS uses software (ToolKit) supplied by the Navigation and Ancillary Information Facility (NAIF) for SPICE access and kernel management (Refer to spiceinit). *[SPICE]: Spacecraft & Planetary ephemerides, Instrument C-matrix and Event kernels. SPICE refers to all the information required by ISIS in order to compute and map each image pixel onto a surface with reference to spacecraft position, sun position, instrument, and mission activities. ISIS uses software (ToolKit) supplied by the Navigation and Ancillary Information Facility (NAIF) for SPICE access and kernel management (Refer to spiceinit).
*[NAIF]: Navigation and Ancillary Information Facility. They engineered and support the SPICE observation geometry information system. *[NAIF]: Navigation and Ancillary Information Facility. They engineered and support the SPICE observation geometry information system.
......
File added
File added
File added
docs/assets/isis-fundamentals/Bit-byte-word.jpg

70.6 KiB

docs/assets/isis-fundamentals/Cube.png

44.8 KiB

File added
docs/assets/isis-fundamentals/LowpassScreenShot1.png

26 KiB

docs/assets/isis-fundamentals/LowpassScreenShot2.png

26.8 KiB

docs/assets/isis-fundamentals/LowpassScreenShot3.png

20.7 KiB

docs/assets/isis-fundamentals/Mars_hemi.gif

40.8 KiB

docs/assets/isis-fundamentals/QviewTwoCubes.png

85 KiB

docs/assets/isis-fundamentals/Qview_vims_bandrgb.png

147 KiB

docs/assets/isis-fundamentals/Qview_vims_singleband.png

90.9 KiB

...@@ -297,11 +297,7 @@ program. The following is an example of the **qview** measurement tool, ...@@ -297,11 +297,7 @@ program. The following is an example of the **qview** measurement tool,
depicted as a ruler on the right side, to measure the distance of the depicted as a ruler on the right side, to measure the distance of the
widest overlap area: widest overlap area:
!!! danger "TODO - Update link" See [Using Qview to view cubes](../../getting-started/using-isis-first-steps/introduction-to-isis.md#using-qview-to-view-cubes) for more
TODO: Update **Using Qview to view cubes** link once that page is migrated.
See [Using Qview to view cubes](https://github.com/DOI-USGS/ISIS3/wiki/Introduction_to_Isis) for more
information about **qview**. information about **qview**.
![Measurement tool on two side-by-side Clementine images to show the overlap area]( ![Measurement tool on two side-by-side Clementine images to show the overlap area](
......
This diff is collapsed.
# Bit-Type
## Bit-Type Basics
-----
Computers store values in base-2 or binary, ones and zeros.
Values are stored in chunks of 8, 16, or 32 binary digits, or bits. The number
of bits per pixel (8-bit, 16-bit, 32-bit) is called **Bit-Depth**. A **Data Type** (Unsigned Byte, Signed Word, Real) is a unit of information.
In ISIS, each data type has a corresponding bit-depth, and together these are called the **Bit-Type**. Bit-type is a term unique to ISIS.
The a cube's bit-type affects the file size, and determines the
range and number of values that can be stored in each pixel of a cube. Larger bit-types (those with higher bit-depths) allow each pixel to represent its data with greater precision.
There are three bit-types supported in ISIS:
<table>
<thead>
<tr>
<th>Bit-Depth</th>
<th>Data Type</th>
<th>Bytes per Value</th>
<th>Range</th>
</tr>
</thead>
<tbody>
<tr>
<td>8-bit</td>
<td>Unsigned Byte</td>
<td>1</td>
<td>0 to 255</td>
</tr>
<tr>
<td>16-bit</td>
<td>Signed Word</td>
<td>2</td>
<td>-32768 to 32767</td>
</tr>
<tr>
<td>32-bit</td>
<td>Real</td>
<td>4</td>
<td>-3.40282E+38 to 3.04282E+38</td>
</tr>
</tbody>
</table>
[![Bit-byte-word.jpg](../../assets/isis-fundamentals/Bit-byte-word.jpg)](../../assets/isis-fundamentals/Bit-byte-word.jpg "Dimensions of an ISIS3 Cube")
There are 8 bits in 1 byte, and 16 bits in 2 bytes, as shown above. A word in ISIS is a 16-bit value.
!!! note
In ISIS, the data type and bit-depth will always correspond as follows: Unsigned Byte (8-bit), Signed Word (16-bit), and Real (32-bit). Therefore, ISIS's Bit-Type can refer to Bit-Depth or Data Type. (Outside of ISIS, it is possible for bytes, words and reals to be different bit-depths. But within ISIS, you don't have to worry about that.)
There are 256 possible values (called digital numbers, or DNs) that can
be represented in an 8-bit pixel. If all the bits above are set to 1, the
output DN value would be 255. The values 0 to 255 are derived by setting
different bit positions to 0 or 1. The table below shows the binary
number stored by the computer, and the corresponding DN value the user
would see on a computer monitor.
<table>
<thead>
<tr>
<th>Binary Number</th>
<th>DN Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>00000000</td>
<td>0</td>
</tr>
<tr>
<td>00000001</td>
<td>1</td>
</tr>
<tr>
<td>00000010</td>
<td>2</td>
</tr>
<tr>
<td>...</td>
<td>...</td>
</tr>
<tr>
<td>11111110</td>
<td>254</td>
</tr>
<tr>
<td>11111111</td>
<td>255</td>
</tr>
</tbody>
</table>
When the number of bits is increased to 16 or 32, the number of possible DN values
that can be represented also increases.
### Glossary & Review
* **Binary** : A base-2 numeral system. [Binary Number on Wikipedia](http://en.wikipedia.org/wiki/Binary_number).
* **Bit** : Short for binary digit, the smallest unit of digital storage. Bits are either "0" or "1".
* **Byte** : Short for binary term. In ISIS (and in most places), a byte is a group of eight bits. These 8 bits together can represent an 8-digit binary number from 00000000 (0) to 11111111 (255).
* **Bit-Type** : Refers to bit-depth or data type, representing how many bits there are per single pixel in a cube.
* **DN** : An abbreviation of digital number. For images, particularly ISIS cubes, a DN is also referred to as a pixel.
## What's the bit-type of my image?
-----
The **Type** keyword in the Pixels group of an image label will be set
to `UnsignedByte` for 8-bit cubes, `SignedWord` for 16-bit cubes, or `Real`
for 32-bit cubes.
!!! abstract "Portion of ISIS Cube Label Showing the Data Type or Bit-Type"
The **Type** keyword here is `UnsignedByte`, meaning this is an 8-bit cube. Type is a keyword in the **Pixels** group.
```
Object = IsisCube
Object = Core
...
Group = Pixels
Type = UnsignedByte
ByteOrder = Lsb
Base = -128.00395256917
Multiplier = 1.00395256917
End_Group
End_Object
End_Object
```
## How does the bit-type affect my file?
-----
The file size for the output file increases as the bit-type increases.
With larger bit-types, each pixel in the data portion of the file requires
a larger number of bytes to hold the value of that pixel, regardless
of what that value is. While the data portion of the cube usually takes the
biggest share of the file size, the text portions of a cube (the labels and
history) can add to the file size as well. The minimum label size
is 64 kilobytes. The following sizes are for a file that is 100 samples
by 100 lines:
<table>
<thead>
<tr>
<th>Bit-Type</th>
<th>Data Size (bytes)</th>
<th>Label &amp; History Size (bytes)</th>
<th>File size (bytes)</th>
<th>Possible Discrete DNs</th>
<th>DN Range</th>
</tr>
</thead>
<tbody>
<tr>
<td>8-bit.cub</td>
<td>10,000</td>
<td>72,348</td>
<td>82,348</td>
<td>256</td>
<td>0 to 255</td>
</tr>
<tr>
<td>16-bit.cub</td>
<td>20,000</td>
<td>78,736</td>
<td>98,736</td>
<td>65,535</td>
<td>-32768 to 32767</td>
</tr>
<tr>
<td>32-bit.cub</td>
<td>40,000</td>
<td>91,507</td>
<td>131,507</td>
<td>about 4 billion</td>
<td>-3.40282E+38 to 3.40282E+38</td>
</tr>
</tbody>
</table>
## How do I set the bit-type?
-----
Many of the ISIS3 programs allow the user to set the bit-type by setting
the bit-type attribute for an output file.
!!! example "Sample Cubes"
Try converting the bit-types of these cubes with ISIS as described below.
| Bytes per Value | Output Bit-Type | Sample Cube |
| --------------- | --------------- | ----------- |
| 1 | 8-bit | [8-bit.cub](../../assets/isis-fundamentals/8-bit.cub) (80.4 KB) Ian Humphrey, 2016-06-01 10:41 AM |
| 2 | 16-bit | [16-bit.cub](../../assets/isis-fundamentals/16-bit.cub) (96.4 KB) Ian Humphrey, 2016-06-01 10:41 AM |
| 4 | 32-bit | [32-bit.cub](../../assets/isis-fundamentals/32-bit.cub) (128 KB) Ian Humphrey, 2016-06-01 10:41 AM |
### Increasing the Bit-Type of a Cube
Increasing the bit-type of a cube is a fairly straightforward matter
because the range of data in a smaller bit-type cube fits easily in the
increased range offered by the larger bit-type. Increasing the bit-type
of a cube will not increase the accuracy of the data in the cube, but
could allow the results of future operations to be recorded with more precision.
Example - create a 16-bit (signed word) cube from an 8-bit (unsigned byte) cube using
[cubeatt](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cubeatt/cubeatt.html)
by appending the attributes you wish to change to the file name:
```
cubeatt from=8bit.cub to=16bit.cub+SignedWord
OR
cubeatt from=8bit.cub to=16bit.cub+16-bit
```
In the
[cubeatt](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cubeatt/cubeatt.html)
graphical user interface (GUI), simply hit the ATT (attributes) button
next to the output file selection box and select the desired bit-type in
the Attributes dialog. Notice when you change the attributes through the
ATT dialog, the attributes are appended to the output filename in the
main application window in the same fashion as the command line. Most
ISIS3 applications allow you to change key cube attributes through the
Attributes dialog.
!!! tip
Increasing the Bit-Type of a cube will increase the file size.
### Decreasing the Bit-Type of a Cube
Decreasing the bit-type of a cube is a bit trickier because the range of
data in a larger bit-type cube probably does not fit easily in the
decreased range of the smaller bit-type. In this case, you must supply
the minimum and maximum values of the input file to convert to valid DNs
in the output file. The values will then be stretched (scaled) as
necessary to fit into the reduced data range. To perform this operation,
you must know the range of the input data and provide that information
to the application that is used to reduce the bit-type.
1. Get statistics for your image: Run **stats** to get the data range:
```
stats from=32bit.cub
```
stats produces:
```
Group = Results
From = 32bit.cub
Average = 3386367.6610505
StandardDeviation = 7446.038790893
Variance = 55443493.675484
Median = 3385719.8387097
Mode = 3382280.056696
Skew = 0.26100683557387
Minimum = 3372788.0
Maximum = 3417331.0
TotalPixels = 265420800
ValidPixels = 265420800
NullPixels = 0
LisPixels = 0
LrsPixels = 0
HisPixels = 0
HrsPixels = 0
End_Group
```
1. **Change the bit-type attribute of your image** : Run **cubeatt** ,
using the minimum and maximum values from stats (refer to the output
from stats above) for the data range attribute. Append the attribute
**3372788.0:3417331.0** to the output filename create the 16-bit
cube:
```
cubeatt from=32bit.cub to=16bit.cub+UnsignedWord+3372788.0:3417331.0
OR
cubeatt from=32bit.cub to=16bit.cub+16-bit+3372788.0:3417331.0
```
1. **Voila\!** The resulting output cube will have the values from
3372788.0 to 3417331.0 from the original cube scaled to the range of
-32752 to 32767. Note the use of -32752 instead of -32768. This is
because the values below -32752 to -32768 are reserved for special
pixels in ISIS3
!!! tip
When reducing the bit-type, the original values may be stretched
(scaled) to fit in the range of the target bit-type. This may not
only shift the DN values to the new range, but may actually merge
ranges of DNs into a single value if the number of distinct values
in the original file is greater than the range of the output bit-type.
# ISIS Cube Format
## What Is A Cube?
---------------
![Three axes from the top left front corner of a cube, showing lines in the Y dimension, samples in the X dimension, and bands in the Z dimension.](../../assets/isis-fundamentals/Cube.png "Dimensions of an ISIS Cube"){ align=right }
A cube is a 3-dimensional image with axis: samples, lines, and bands. The physical dimensions of a cube are called the number of samples (NS), number of lines (NL), and number of bands (NB). Typically, the sample and line dimensions are used to represent spatial information while the band dimension represents spectral information. See the table below for examples of the line, sample, and band dimensions of a few data sets from planetary missions.
> Illustration of an ISIS3 image cube, showing the three dimensions of an ISIS3 image: width (samples), height (lines), and depth (bands)
<table>
<thead>
<tr>
<th>Instrument/Camera</th>
<th># Lines</th>
<th># Samples</th>
<th># Bands</th>
<th>Bands</th>
</tr>
</thead>
<tbody>
<tr>
<td>Mars Odyssey - Thermal Emission Imaging System, Infrared (THEMIS-IR)</td>
<td>240</td>
<td>320</td>
<td>10</td>
<td>All 10 are Infrared, ranging from 6.78 to 14.88 microns</td>
</tr>
<tr>
<td>Mars Odyssey - Thermal Emission Imaging System, Visible Imaging Subsystem (THEMIS-VIS)</td>
<td>1024</td>
<td>1024</td>
<td>5</td>
<td>visible</td>
</tr>
<tr>
<td>Viking Orbiter</td>
<td>1056</td>
<td>1204</td>
<td>1 ?</td>
<td>blue, minus-blue, violet, green, red, clear</td>
</tr>
<tr>
<td>Mars Global Surveyor - Mars Oribiter Camera Wide Angle (MOC-WA)</td>
<td>*</td>
<td>3456</td>
<td>1</td>
<td>bandwidth encompasses visible and near-infrared</td>
</tr>
<tr>
<td>Galileo Near-Infrared Mapping Spectrometer (NIMS)</td>
<td>*</td>
<td>20</td>
<td>408</td>
<td>visible to infrared</td>
</tr>
</tbody>
</table>
## What Are Pixels?
----------------
The individual cells within a cube are called pixels. Each pixel in a cube has a location, which is similar to rectangular coordinates (i.e.., (samples, lines, bands)). A cube can be as small as one sample, by one line, by one band (1,1,1). If we had a cube of this size, it would contain only one pixel. A cube can be as large as thousands of samples, by thousands of lines, by thousands of bands. A cube with dimensions (1000, 1000, 1000) would contain one billion pixels. See the [ISIS Cube Demo](https://doi-usgs.github.io/ISIS3/ISIS_Cube_Format.html#Cube-Demo) for an interactive visual of samples, lines, and bands.
!!! tip
Notice sample 1 is on the left edge of the image and line 1 is on the top edge. Therefore, to figure out the coordinates of a pixel, count lines and samples staring with 1,1 in the upper left corner and move down and to the right.
## Bit-Depth (aka Bit-Type)
For more info about the amount of data stored per-pixel, or range of DNs, see [Bit-Type](../../concepts/isis-fundamentals/bit-types.md)
## Pixel Values: Digital Numbers
-----------------------------
Each pixel contains a numerical value, often referred to as the digital number, or DN. Low DNs typically show up as black in the image and high DN as white. DNs represent a measurement in units such as:
* Radiance - A measurement describing the amount of electromagnetic energy emitted from an area of a planet
* Reflectance - The ratio of reflected energy to incoming energy
* Elevation - The height above or below a fixed point on the surface of a body
* Emissivity - A measure describing a substances ability to absorb and radiate electromagnetic energy
## Core Base and Multiplier Basics
-------------------------------
An 8-bit cube needs to represent elevations in meters. Unfortunately, 8-bit pixels have a range of 0 to 255, which is very restrictive for elevation. ISIS3 deals with this problem by using a **Core Base** and **Multiplier**. Each DN is really treated as a kind of floating point number in all ISIS3 programs. A multiplier of 100 on an 8-bit cube would make the DN range from 0 to 25500. A base of 30 with a multiplier of 100 would make that range from 30 to 25530.
*Base + Multiplier * DN = True DN*
## Sub-Pixel Positioning
--------------------
ISIS3 programs and users often need to interact at the sub-pixel level. That is, fractional pixel positions. The integral sample/line position is defined to be the center of a pixel.
Take a pixel centered at (5, 5) for example. The upper left of the pixel contains the point (4.75, 4.75), and the lower right of the pixel contains the point (5.25, 5.25). The threshold between pixels is a value ending in .5
## Summary
-------
Cubes are made up of individual pixels. Each pixel usually represents some area of a planet, moon, asteroid or other body. Pixels hold a DN (digital number). That number can be one, two or four bytes long depending on the accuracy necessary to represent the data. DNs can be modified by a "Base" and "Multiplier". The columns of a cube are called samples, the rows are called lines and a plane of samples and lines is called a band.
\ No newline at end of file
# ISIS Kernel Load Selection
ISIS selects the SPICE kernels to be used with an ISIS cube as part of running the spiceinit application.
The user can enter kernels they would like to load via `spiceinit` (either by hand, or with a parameter file) or use the spice server, but that is not covered by this write up. This documents what happens when `spiceinit` selects kernels from the default location (`$ISIS3DATA/mission/kernels` or a different location specified by the `IsisPreferences` file) using the ISIS kernel databases.
In spiceinit, the `KernelDb` class is used to select which kernels to load. This class can be called directly to query the ISIS kernel databases if desired.
## Kernel Types
First, the allowed kernel “types” are specified for both cks and spks:
- **Nadir** : The worst quality kernel. Used as a last resort because it assumes the spacecraft is always nadir-looking.
- **Predicted** : Preliminary kernels produced by a mission with best-estimates of where the spacecraft will be.
- **Reconstructed** : Typically produced by a mission a few weeks after the target has been reached.
- **Smithed** : The best quality kernel, will be used first when selected. Smithed kernels have been improved or adjusted for accuracy by a mission team or for the purpose of a cartographic product. Consider the source, content and completeness of Smithed kernels when selecting this level of quality.
Kernels of a non-allowed type will not be selected, and the highest quality kernel that meets the other selection criteria will be returned.
Above, the types are in order of lowest to highest quality kernel category. For more information about these kernel quality categories, and the spiceinit application, please see [spiceinit documentation](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html).
## Kernel Selection
1. The location of the correct kernel database file to use is determined using the mission name, the cube’s label (to get the `InstrumentID`), and the user's `IsisPreferences` file. There is one kernel.db file for each "type" of kernel needed by the image (ck, spk, fk, ik, iak...) but these are simple files for all but the cks and spks (TODO: Add more detail here).
1. The most recent kernel database file in the appropriate directory is loaded (unless there is a kernel configuration file, see *Kernel Configuration File* below). Kernel databases are updated when new kernels become available or there is a change to which kernels need to be loaded communicated from the team.
1. The `StartTime` and `StopTime` keywords from the `Instrument` group in the input cube label are used to search through the available kernels as specified by PVL groups in the kernel database file and determine the best match. `StopTime` is an optional keyword in ISIS cubes, so if it is not available, it is set equal to the `StartTime`
!!! info "Kernel Configuration File"
A kernel configuration file is a file of the form `kernels.????.conf` that contains information about which kernel database files to load in which cases.
## Kernel Distribution Infrastructure
In the ISIS data area, shell scripts within each ck and spk directory that receive new kernels from an automated download script are run to re-generate kernel database files when new kernels are downloaded. These scripts are usually named `makedb` and call the ISIS application makedb. After update, in most cases, these new kernels and kernel database files are immediately pushed to the rsync server.
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment