Merge branch 'geometry' into 'main'

Added docs and assets for camera geometry and projection

Closes #22

See merge request astrogeology/asc-public-docs!11

docs/concepts/Camera Geometry.md

+## Introduction 
+
+-----
+
+In order to access and view the geometry for an ISIS image cube \[raw
+instrument camera cube, (i.e., PDS-EDR)\], the application
+[**spiceinit**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html)
+must be **successfully** applied to the cube. Once **spiceinit** has
+been applied, there are a number of applications that will be able to
+compute and output statistics about your image based on the raw **Camera
+Geometry** .
+
+
+## Camera Geometry 
+
+-----
+
+**Camera Geometry** refers to the viewing geometry of an observation. It
+also implies a 'non-projected' cube (sometimes referred to as a Level1,
+though it does not require radiometric calibration). 
+
+!!! Note "Within the ISIS environment, unless otherwise specified, **ALL** applications default (for input and output) to the following geometric reference (regardless of target body):"
+
+      - **Longitude\_Domain = 360** \[Longitudes will be reported in the
+        range of 0 to 360 degrees (not -180 to 180)\]
+      - **Latitude\_System = Ocentric** \[Versus Ographic; Note: there is
+        not difference for a spherical body\]
+      - **Longitude Direction = East** \[Longitude values increase to the
+        east\]
+
+Definitions for the geometric reference terms can be found in [Learning
+About Map Projections](concepts/Learning About Map Projections)
+
+
+## Camera Information Applications 
+
+-----
+
+
+### **Camstats** 
+
+For a given image cube, the application
+[**camstats**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/camstats/camstats.html)
+will report Minimum, Maximum, Average and Standard Deviation for the
+following:
+
+**Geometric Information**
+
+  - Latitude
+  - Longitude
+  - Resolution, LineResolution, SampleResolution
+  - AspectRatio
+
+**Photometric Information**
+
+  - Phase Angle
+  - Emission Angle
+  - Incidence Angle
+  - LocalSolarTime
+  - NorthAzimuth
+
+Example (not all parameters shown):
+
+    camstats from=xxxx.cub linc=1 sinc=1
+
+!!! Note " The *linc* and *sinc* parameters default to 1. For larger pixel size images, such as HiRISE or CTX data, setting the *linc* and *sinc* values to higher values (10, 100) would help the application to run faster. Set with care knowing that the application is literally skipping line/sample data to retrieve SPICE information."
+
+  - **camstats** supplies useful information that can be considered and
+    applied when map projecting images (Level2 processing).
+
+
+### **Mosrange** 
+
+Given a list of multiple raw image cubes, the application
+[**mosrange**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/mosrange/mosrange.html)
+computes the range of latitude/longitude and resolution statistics for
+all images given.
+
+Example (not all parameters shown):
+
+    mosrange fromlist=list_of_lev0_w_spice.lis to=output_map_information.map projection=Equirectangular
+
+  - This is one application that allows the user to specify output
+    latitude type, longitude direction and longitude domain.
+
+  - Knowing the information about your set of images at this point is
+    useful, especially if the goal is to generate a mosaic. The output
+    can be used later in defining the desired output map projection in
+    Level 2 processing.
+
+
+### **Campt** 
+
+The application
+[**campt**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/campt/campt.html)
+will supply geometric and photometric information based on a *single*
+latitude/longitude value (remember the raw camera geometry defaults when
+entering values) or a *single* line/sample coordinate of an image cube.
+
+**Geometric Information**
+
+  - Latitude
+  - Longitude
+  - Resolution
+
+**Photometric Information**
+
+  - Phase Angle
+  - Emission Angle
+  - Incidence Angle
+
+**In addition** , this application will return a list of other
+spacecraft, sun and instrument related information such as:
+
+  - SpacecraftPosition
+  - SpacecraftAzimuth
+  - SubSpacecraftLongitude
+  - SubSolarLatitude
+  - SubSolarLongitude
+  - Time information (EphemerisTime, UTC)
+
+Example (not all parameters shown):  
+*Enter lat- [](fixit.wr.usgs.gov)* [*Ocentric* **](fixit.wr.usgs.gov)
+*/long- [](fixit.wr.usgs.gov)* [*360* **](fixit.wr.usgs.gov) *point
+location*
+
+    campt from=xxxx.cub latitude=0.0 longitude=270.0 type=ground
+
+or
+
+Example (not all parameters shown):  
+*Enter line/sample pixel location-current default of application*
+
+    campt from=xxxx.cub line=512 sample=512 type=image
+
+
+### **Phocube** 
+
+[**phocube**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/phocube/phocube.html)
+will compute and generate a separate output [multi-band ISIS
+cube](https://DOI-USGS.github.io/ISIS3/gh-pages/ISIS_Cube_Format.html) where each band will represent the selected
+(parameter=TRUE) geometric and photometric elements. The bands are named
+appropriately in the output cube labels: **Group=BandBin** .
+
+``` 
+ Object = IsisCube
+     Object = Core
+     StartByte   = 65537
+     Format      = Tile
+     TileSamples = 128
+     TileLines   = 128
+     Group = Dimensions
+       Samples = 1024
+       Lines   = 1024
+       Bands   = 6
+     End_Group
+     Group = Pixels
+       Type       = Real
+       ByteOrder  = Lsb
+       Base       = 0.0
+       Multiplier = 1.0
+     End_Group
+   End_Object
+    Group = BandBin
+    Name = ("Phase Angle", "Emission Angle", "Incidence Angle", "Latitude", "Longitude")
+  End_Group
+```
+
+  - **phocube** requires a successful **spiceinit** execution
+  - **phocube** can be applied to an unprojected "Level1" image cube or
+    an individual map projected "Level2" image.
+  - **phocube** will not work on a mosaic cube, the photometric
+    information for each input file is eliminated from the mosaic output
+    file.
+
+Example:  
+Run **phocube** on a fly-by Cassini ISS-Wide Angle Camera image of
+Enceladus. In this example, **phocube** will generate a 6-band output
+cube.
+
+!!! Note "The image used in this example has been processed through Level1 \[ingestion, spiceinit and radiometric calibration\]. Refer to: [Working with Cassini ISS Data](Working_with_Cassini_ISS_Data)"
+
+Each band will contain the information asked for (parameters set to
+true) in the following command:
+
+    phocube from=W1487302209_2.lev1.cub to=W1487302209_2_pho.cub 
+            phase=true  emission=true  incidence=true  latitude=true  longitude=true 
+
+  - All bands of the phocube output can be displayed in qview
+  - To access a selected band in an application, use the cube-attribute
+    syntax.  
+
+For example, calculate and report the average values of the Incidence
+Angle (Band 3).  
+The command line for the **stats** applications is as follows:
+
+    stats from=W1487302209_2_pho.cub+3  to=W1487302209_2_inc_stats.pvl 
+
+The Example ISS Wide-Angle Camera image of Enceladus and the output of
+**phocube** :
+
+
+<figure class="inline" markdown>
+  ![Cassini ISS WA-camera Enceladus](/assets/camera_geometry/Iss_WAC_enceladus_sm2.png){: style="width:225px;height:225px"}
+  <figcaption>Enceladus</figcaption>
+</figure>
+
+<figure class="inline" markdown>
+  ![Iss\_WAC\_ema\_figure](/assets/camera_geometry/Iss_WAC_ema_figure.png "Phocube-Emission Angle Band"){: style="width:225px;height:225px"}
+  <figcaption>Phocube: Emission Angle Band</figcaption>
+</figure>
+
+<figure markdown>
+  ![Iss\_WAC\_inc\_figure](/assets/camera_geometry/Iss_WAC_inc_figure.png "Phocube Incidence Angle Band"){: style="width:225px;height:225px"}
+  <figcaption>Phocube: Incidence Angle Band</figcaption>
+</figure>
+
+
+<figure class="inline" markdown>
+  ![Iss\_WAC\_phase\_figure](/assets/camera_geometry/Iss_WAC_phase_figure.png "Phocube-Phase Angle Band"){: style="width:225px;height:225px"}
+  <figcaption>Phocube: Phase Angle Band</figcaption>
+</figure>
+
+<figure class="inline" markdown>
+  ![Iss\_WAC\_lat\_figure](/assets/camera_geometry/Iss_WAC_lat_figure.png "Phocube-Latitude Band"){: style="width:225px;height:225px"}
+  <figcaption>Phocube: Latitude Band</figcaption>
+</figure>
+
+<figure markdown>
+  ![Iss\_WAC\_lon\_figure](/assets/camera_geometry/Iss_WAC_lon_figure.png "Phocube-Longitude Band"){: style="width:225px;height:225px"}
+  <figcaption>Phocube: Longitude Band</figcaption>
+</figure>

docs/how-to-guides/Image Processing/Map Projecting Images.md

+
+
+# Overview of Map Projecting Images 
+
+## Introduction 
+
+Converting a raw instrument/camera cube (Level1) to a map projected
+image (Level2) is a fundamental capability of ISIS.  
+The default transformation is based on the original viewing geometry of
+the observation, relative position of the target body and the definition
+of the output map projection.
+
+The main application to project an image is
+[**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html)
+.
+
+``` 
+ cam2map from=camera_cube_level1.cub to=level2_cube.cub
+```
+
+
+## ISIS Requirements 
+
+-----
+
+  - The image data must be part of a mission instrument 'camera model'
+    that is supported within ISIS
+  - Proper ingestion of the image data into ISIS ( [**Importing Mission
+    Data**](Locating_and_Ingesting_Image_Data) )
+  - Available [**SPICE**](SPICE_Information) information for every
+    individual image
+  - A [**map template**](/concepts/Learning About Map Projections) to define an
+    output map projection
+
+
+## Supported Map Projections 
+
+-----
+
+[**ISIS Supported Projections**](/concepts/Learning About Map Projections)
+
+  - For detailed information about Map Projections within ISIS refer to
+    [Learning About Map Projections](/concepts/Learning About Map Projections) .
+
+
+## Defining an Output Map 
+
+-----
+
+
+### ISIS Defaults 
+
+ISIS supplies 'basic' map templates that set the ProjectionName
+parameter to a supported map projection.
+
+  - The map templates can be found in: $ISISDATA/base/templates/maps/  
+
+  - These map templates can be selected through the MAP parameter in
+    'cam2map' (current default is sinusoidal).
+
+  - In conjunction with the supplied map templates; the default for an
+    output map are as follows:
+    
+      - The original [**raw camera geometry**](/concepts/Camera Geometry)
+      - [**Computed parameters**](/concepts/Learning About Map Projections)
+      - The target body is defined in the system defaults which can be
+        found in $ISISDATA/base/templates/targets/.
+
+
+### When to Generate A Custom Defined Map Template 
+
+  - The viewing geometry of an image(s) are important details to
+    consider when defining an output map projection.
+      - There are a number of applications that report relevant
+        [**camera geometry**](/concepts/Camera Geometry) information for a given
+        image or a list of images.
+      - Does your input cover the north or south pole of the body?
+      - Do you want your output map to be centered at a specific
+        latitude/longitude?
+      - Do you plan on mosaicking your images together?
+      - An output mosaic (digital image map-DIM) is a major
+        consideration before projecting multiple images. Refer to
+        [**Making Mosaics**](/concepts/Learning About Map Projections).
+
+
+#### The Custom Map Template 
+
+In order to project an image to a specific map projection, you'll need
+to set up a list of parameters based on the projection you wish to use.
+Use the
+[**maptemplate**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/maptemplate/maptemplate.html)
+application program (or your favorite text editor) to set up a **map
+template** file defining the mapping parameters for the projection. The
+following is a an example of a map template file for defining the
+projection of an image of Mars to the sinusoidal projection:
+
+``` 
+ Group = Mapping
+  TargetName         = Mars
+  EquatorialRadius   = 3396190.0 <meters>
+  PolarRadius        = 3376200.0 <meters>
+  LatitudeType       = Planetocentric
+  LongitudeDirection = PositiveEast
+  LongitudeDomain    = 360
+
+  ProjectionName     = Sinusoidal
+  CenterLongitude    = 227.95679808356
+
+  MinimumLatitude    = 10.766902750622
+  MaximumLatitude    = 34.44419678224
+  MinimumLongitude   = 219.7240455337
+  MaximumLongitude   = 236.18955063342
+
+  PixelResolution    = 426.87763879023 <meters/pixel>
+ End_Group
+```
+
+!!! Note "A separate map or map-projected image can be used as a map template file in cam2map. These files are required to have the ISIS Mapping Group keyword labels."
+
+
+## Camera Distortion Correction 
+
+-----
+
+Within ISIS, the map projection software includes correcting modeled
+camera distortions for each supported instrument. When map projecting an
+image, the camera distortion correction and geometric transformation are
+performed simultaneously so that resampling is performed only once and
+pixel resolution loss is minimal.
+
+
+## Projecting the Image 
+
+-----
+
+The
+[**cam2map**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html)
+application converts a camera (instrument) image to a map projected
+image. cam2map will automatically compute defaults for most of the
+mapping parameters, so you only need to define a subset of the
+parameters in your map template (e.g. ProjectionName).
+
+  - If you are projecting several images with the same projection
+    parameters, **you can apply the same map template** for all of your
+    images simply by removing the latitude longitude range parameters
+    (MinimumLatitude, MaximumLatitude, MinimumLongitude, and
+    MaximumLongitude) from your map template.
+  - **cam2map will automatically calculate parameter values for you** --
+    all you *really* need is the projection name in your map template.
+  - If you are planning on mosaicking your projected images, make sure
+    the **PixelResolution** , **CenterLongitude** and **CenterLatitude**
+    is the **same** for all images.
+
+
+## Related ISIS Applications 
+
+-----
+
+See the following ISIS documentation for information about the
+applications you will need to use to perform this procedure:
+
+  - [**maptemplate**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/maptemplate/maptemplate.html)
+    : set up a map projection parameter template for map projecting
+    cubes
+  - [**cam2map**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html)
+    : project a cube to a map projection
+
+

mkdocs.yml

@@ -42,6 +42,8 @@ nav:
       - Generating an ISD, creating a CSM model, and converting coordinates: getting-started/CSM Stack/ImageToGroundTutorial.ipynb
   - How-To Guides: 
     - Home: how-to-guides/index.md
+    - Image Processing:
+      - Map Projecting Images: how-to-guides/Image Processing/Map Projecting Images.md
     - Software Management: 
       - ISIS Public Release Process: how-to-guides/Software Management/Public Release Process.md
       - Software Support: how-to-guides/Software Management/Software Support.md
@@ -49,7 +51,11 @@ nav:
       - How To Write ISIS Tests with CTest and GTest: "how-to-guides/ISIS Developer Guides/Writing ISIS Tests with CTest and GTest.md"
       - App Testing CookBook: "how-to-guides/ISIS Developer Guides/App Testing Cookbook.md"
       - Class Requirements For Using Doxygen Tags: "how-to-guides/ISIS Developer Guides/Class Requirements For Using Doxygen Tags.md"
-  - Concepts: concepts/index.md
+  - Concepts: 
+    - Home: concepts/index.md
+    - Camera Geometry and Projections:
+      - Camera Geometry: concepts/Camera Geometry.md
+      - Learning About Map Projections: concepts/Learning About Map Projections.md
   - Manuals: manuals/index.md
 
 extra_css: