diff --git a/docs/assets/camera_geometry/Iss_WAC_ema_figure.png b/docs/assets/camera_geometry/Iss_WAC_ema_figure.png new file mode 100644 index 0000000000000000000000000000000000000000..85037e5dbf4bed755dcb490d338263b7b2fa9b72 Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_ema_figure.png differ diff --git a/docs/assets/camera_geometry/Iss_WAC_enceladus_sm2.png b/docs/assets/camera_geometry/Iss_WAC_enceladus_sm2.png new file mode 100644 index 0000000000000000000000000000000000000000..d80e1f77394d2a3190c904ea4a09a5759ccea0ec Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_enceladus_sm2.png differ diff --git a/docs/assets/camera_geometry/Iss_WAC_inc_figure.png b/docs/assets/camera_geometry/Iss_WAC_inc_figure.png new file mode 100644 index 0000000000000000000000000000000000000000..7292d9a5e541e3c3f3221b9ae9e4c41d3a9f3846 Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_inc_figure.png differ diff --git a/docs/assets/camera_geometry/Iss_WAC_lat_figure.png b/docs/assets/camera_geometry/Iss_WAC_lat_figure.png new file mode 100644 index 0000000000000000000000000000000000000000..7fa74034229de813583bb3a7f1ee043de930a748 Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_lat_figure.png differ diff --git a/docs/assets/camera_geometry/Iss_WAC_lon_figure.png b/docs/assets/camera_geometry/Iss_WAC_lon_figure.png new file mode 100644 index 0000000000000000000000000000000000000000..9f66384180d502e8f9afb505161cbb65735868fa Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_lon_figure.png differ diff --git a/docs/assets/camera_geometry/Iss_WAC_phase_figure.png b/docs/assets/camera_geometry/Iss_WAC_phase_figure.png new file mode 100644 index 0000000000000000000000000000000000000000..876c171d20167fc55832935a1e7024aa2421871e Binary files /dev/null and b/docs/assets/camera_geometry/Iss_WAC_phase_figure.png differ diff --git a/docs/assets/map_projections/180_domain_correct.png b/docs/assets/map_projections/180_domain_correct.png new file mode 100644 index 0000000000000000000000000000000000000000..bf3137ca08b65a79e8eb9c5802edad0f2c2596e0 Binary files /dev/null and b/docs/assets/map_projections/180_domain_correct.png differ diff --git a/docs/assets/map_projections/360_domain_incorrect.png b/docs/assets/map_projections/360_domain_incorrect.png new file mode 100644 index 0000000000000000000000000000000000000000..e8ae58101f33e66302267c7f3b0f51346633fb49 Binary files /dev/null and b/docs/assets/map_projections/360_domain_incorrect.png differ diff --git a/docs/assets/map_projections/Blue_right_arrow.gif b/docs/assets/map_projections/Blue_right_arrow.gif new file mode 100644 index 0000000000000000000000000000000000000000..6cd82435cac9d483a81a36e45ffdfbb23bfeaf49 Binary files /dev/null and b/docs/assets/map_projections/Blue_right_arrow.gif differ diff --git a/docs/assets/map_projections/Cam2map_screenshot.jpeg b/docs/assets/map_projections/Cam2map_screenshot.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..3a07e6d67aff6ed159bef6e85a7dc61fcf3ba28e Binary files /dev/null and b/docs/assets/map_projections/Cam2map_screenshot.jpeg differ diff --git a/docs/assets/map_projections/MOC1.jpeg b/docs/assets/map_projections/MOC1.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..3a01164dbca4bd050c6c5365b312b0a7ea834891 Binary files /dev/null and b/docs/assets/map_projections/MOC1.jpeg differ diff --git a/docs/assets/map_projections/Mars_sphere_illustration.png b/docs/assets/map_projections/Mars_sphere_illustration.png new file mode 100644 index 0000000000000000000000000000000000000000..f811a4296dc9dbda0c9061db71888b174c6856ae Binary files /dev/null and b/docs/assets/map_projections/Mars_sphere_illustration.png differ diff --git a/docs/assets/map_projections/Mercator.gif b/docs/assets/map_projections/Mercator.gif new file mode 100644 index 0000000000000000000000000000000000000000..442cc4dbfb6ca1022f36984860a91daab5d98175 Binary files /dev/null and b/docs/assets/map_projections/Mercator.gif differ diff --git a/docs/assets/map_projections/Mola_of_sheet2a_thumb.jpeg b/docs/assets/map_projections/Mola_of_sheet2a_thumb.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..0faa7017ae1eb2d36897d794685ace02b2350016 Binary files /dev/null and b/docs/assets/map_projections/Mola_of_sheet2a_thumb.jpeg differ diff --git a/docs/assets/map_projections/Mosaic_after.jpeg b/docs/assets/map_projections/Mosaic_after.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..dd8dba6a09ad99ab0eb9926c59b2d5492a057894 Binary files /dev/null and b/docs/assets/map_projections/Mosaic_after.jpeg differ diff --git a/docs/assets/map_projections/Mosaic_sinus.jpeg b/docs/assets/map_projections/Mosaic_sinus.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..1c26ebbe5ce7e01a07f2d156acde30837c59a232 Binary files /dev/null and b/docs/assets/map_projections/Mosaic_sinus.jpeg differ diff --git a/docs/assets/map_projections/Sample_mosaic_themis.jpeg b/docs/assets/map_projections/Sample_mosaic_themis.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..80e7ad95cfd2e06d1147b9f1ba631e0446a00d9e Binary files /dev/null and b/docs/assets/map_projections/Sample_mosaic_themis.jpeg differ diff --git a/docs/assets/map_projections/SimpleCylindrical.jpeg b/docs/assets/map_projections/SimpleCylindrical.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..865c8b6498571ce87b7c71748ffcec166af98fd6 Binary files /dev/null and b/docs/assets/map_projections/SimpleCylindrical.jpeg differ diff --git a/docs/assets/map_projections/Simple_135-110.jpeg b/docs/assets/map_projections/Simple_135-110.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..74d070ba72fa40e848124b0e5fa217b665c3f6a7 Binary files /dev/null and b/docs/assets/map_projections/Simple_135-110.jpeg differ diff --git a/docs/assets/map_projections/SinuMOC1.jpeg b/docs/assets/map_projections/SinuMOC1.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..6d852a4d795c2de44f4e24a76dbbf1bccd4d7c31 Binary files /dev/null and b/docs/assets/map_projections/SinuMOC1.jpeg differ diff --git a/docs/assets/map_projections/SinusodialProjection.jpeg b/docs/assets/map_projections/SinusodialProjection.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..32dace70a128e4b10c1512dfc0f662eb346d7a18 Binary files /dev/null and b/docs/assets/map_projections/SinusodialProjection.jpeg differ diff --git a/docs/assets/map_projections/Sinusodial_135-110.jpeg b/docs/assets/map_projections/Sinusodial_135-110.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..1b8fed229608522d83bb58e447c965eb9a13fee2 Binary files /dev/null and b/docs/assets/map_projections/Sinusodial_135-110.jpeg differ diff --git a/docs/concepts/Camera Geometry.md b/docs/concepts/Camera Geometry.md new file mode 100644 index 0000000000000000000000000000000000000000..a361c1107d4b249dfdb942905c68cb1d75a9714e --- /dev/null +++ b/docs/concepts/Camera Geometry.md @@ -0,0 +1,232 @@ +## 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> + {: style="width:225px;height:225px"} + <figcaption>Enceladus</figcaption> +</figure> + +<figure class="inline" markdown> + {: style="width:225px;height:225px"} + <figcaption>Phocube: Emission Angle Band</figcaption> +</figure> + +<figure markdown> + {: style="width:225px;height:225px"} + <figcaption>Phocube: Incidence Angle Band</figcaption> +</figure> + + +<figure class="inline" markdown> + {: style="width:225px;height:225px"} + <figcaption>Phocube: Phase Angle Band</figcaption> +</figure> + +<figure class="inline" markdown> + {: style="width:225px;height:225px"} + <figcaption>Phocube: Latitude Band</figcaption> +</figure> + +<figure markdown> + {: style="width:225px;height:225px"} + <figcaption>Phocube: Longitude Band</figcaption> +</figure> diff --git a/docs/concepts/Learning About Map Projections.md b/docs/concepts/Learning About Map Projections.md new file mode 100644 index 0000000000000000000000000000000000000000..acaca4bb4f974d50b8dcbe7da868bf1bc00c83b8 --- /dev/null +++ b/docs/concepts/Learning About Map Projections.md @@ -0,0 +1,643 @@ +# Learning About Map Projections + + +## What is a Map? + +----- + +A map is a two dimensional representation of a three dimensional object +such as a sphere, ellipsoid (egg-shape), or an irregular shaped body. +For planetary maps, these 3-D objects are the planets, their moons, and +irregular bodies such as asteroids. Maps allow scientists and +researchers to analyze and measure characteristics of features on the +body such as area, distance, and direction. See [Map +(Wikipedia)](http://en.wikipedia.org/wiki/Map) for a detailed +description of maps. + +<figure markdown> + "){ width="100%" } +</figure> + + +## What is a Map Projection? + +----- + +A projection is an algorithm or equation for mapping a three dimensional +body onto a two dimensional surface such as paper, a computer screen, or +in our case, a digital image. There are many different types of +projections. + +<figure markdown> + {width="100%"} + <figcaption> Mercator Projection: The classic Mercator projection places a cylinder (rolled piece of paper) tangent to the equator. </figcaption> +</figure> + + + +For additional information on types and properties of map projections +see [Map Projection +(USGS)](http://egsc.usgs.gov/isb//pubs/MapProjections/projections.html) +. + + +## ISIS3 Supported Projections + +----- + +**ISIS3 currently supports the following projections:** + + - Equirectangular + - Lambert Azimuthal Equal Area + - Lambert Conformal + - Lunar Azimuthal Equal Area + - Mercator + - Mollweide + - Oblique Cylindrical + - Orthographic + - Planar + - Point Perspective + - Polar Stereographic + - Ring Cylindrical + - Robinson + - Simple Cylindrical + - Sinusoidal + - Transverse Mercator + - Upturned Ellipsoid Transverse Azimuthal + +**Related Resources** + + - [USGS: Map + Projections](http://egsc.usgs.gov/isb//pubs/MapProjections/projections.html) + - descriptions and comparisons of several map projections + + +## What is a Planetary Image Map? + +----- + +A primary capability of ISIS3 is to create map projected images of raw +instrument data. This allows researchers to make fundamental +measurements on and observations about the images. + +The following is an example of a single Mars Global Surveyor (MGS) Mars +Orbital Camera (MOC) instrument image that has been transformed to a +planetary image map using the Sinusoidal projection. + +| {: style="width:300px;height:300px"} | {: style="width:300px;height:300px"} | +| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| MOC image before transformation | MOC image after sinusoidal transformation | + + +## What is a Planetary Image Mosaic? + +----- + +Equally as important, ISIS3 allows a collection of raw instrument images +to be projected and stitched together (mosaicked) into large regional or +global maps. + + + +<figure markdown> + {: style="width:100%"} + <figcaption> Five Mars Odyssey THEMIS instrument images that have been projected and mosaicked to generate\n a regional planetary image map using the Sinusoidal projection </figcaption> +</figure> + + + +## Defining a Map in ISIS3 + +----- + +In order to project an image, characteristics of the map must be +established. They include the latitude/longitude coverage or ground +range, the pixel resolution, the target body radii, latitude and +longitude definitions, and the projection. In ISIS3 we record all of +this information in a Parameter Value Language (PVL) formatted map file. +For example this MGS MOC image was projected using the following: + +``` + 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 +``` +<figure markdown> + {: style="width:100%"} + <figcaption> Image projected using the above mapfile </figcaption> +</figure> + + +## Target Shape Definition + +----- + +The target shape must be defined in order to project an image. The shape +is characterized by the equatorial and polar radii of the body. +Depending on the projection, one or both of these values will be used. +The chart below shows which projections are for a sphere only (use only +the equatorial radius) and which work for ellipsoids: + +Marked below are the PVL keywords used to define the target radii, which +must be given in units of meters. + +``` + 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 +``` + +| Projection | Sphere | Ellipsoid | +| ------------------- | ------ | --------- | +| Sinusoidal | X | | +| Simple Cylindrical | X | | +| Equirectangular | X | | +| Polar Stereographic | X | X | +| Orthographic | X | | +| Mercator | X | X | +| Transverse Mercator | X | X | +| Lambert Conformal | X | X | + + +### Interactive Planetary Radii Demonstration + + +## Latitude Type + +----- + +Latitudes can be represented either in **planetocentric** or +**planetographic** form. The planetocentric latitude is the angle +between the equatorial plane and a line from the center of the body. The +**planetographic latitude** is the angle between the equatorial plane +and a line that is normal to the body. In a quick summary, both +latitudes are equivalent on a sphere (i.e., equatorial radius equal to +polar radius); however, they differ on an ellipsoid (e.g., Mars, Earth). + +``` + 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 +``` + + +### Quick Tips + + - The latitude type will affect how other PVL keywords such as + MinimumLatitude, CenterLatitude are interpreted. + - Projections such as Sinusoidal, Simple Cylindrical, and + Equirectangular will place pixels differently in the image depending + on the latitude type. Pixel placement for other projections is not + affected. The LatitudeType keyword must be either **Planetocentric** + or **Planetographic** . + + +### Interactive Planetocentric and Planetographic Demonstration + +**PLACE INTERACTIVE DEMO HERE** + + +## Longitude Direction and Domain + +----- + +Two keywords indicate how longitude is defined on the target body and +must be specified. The LongitudeDirection keyword indicates whether +longitude increases to the east or west, that is, positive to the east +or positive to the west. The LongitudeDomain keyword specifies how +longitudes should be interpreted 0° to 360° or -180° to 180°. In both +cases, these specifications affect other keywords and the interpretation +of other keywords, such as MinimumLongitude and CenterLongitude. + +The LongitudeDirection keyword must be either PositiveEast or +PositiveWest, while the LongitudeDomain keyword must be 180 or 360. +These keywords are marked in the example below. + +``` + 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 +``` + + +### Interactive Longitude Direction of Domain Demonstration + +**PLACE INTERACTIVE DEMO HERE** + + +## Ground Range + +----- + +The ground range defines the extent of the map. That is, the minimum and +maximum latitude/longitude values. Recall that these are in terms of the +latitude system, longitude direction, and longitude domain. In the +keywords below, the keywords marked define the ground range of the map. + +``` + 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 +``` + + +### Interactive Ground range demonstration + +**PLACE INTERACTIVE DEMO HERE** + + +## Pixel Resolution + +----- + +The pixel resolution defines the size of pixels in a map projected image +in either meters per pixel, or pixels per degree. In the example below +is the marked keyword used to define the pixel resolution in meters per +pixel. + +``` + 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 +``` + +Alternatively, the resolution can be defined as pixels per degree. For +example + +``` + 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 + + **Scale = 138.85641255722 <pixels/degree>** + End_Group +``` + + +### Interactive Exle of pixel resolutions + +**PLACE INTERACTIVE DEMONSTRATION HERE** + + +## Projection and Parameters + +----- + +The final information required in the map file is the projection for +mapping the body to a two dimensional surface. In addition to the +projection name, projection-specific parameters must be provided. For +example, Sinusoidal requires the CenterLongitude. The following table +outlines the keywords required for each projection: + +| ProjectionName | CenterLongitude | CenterLatitude | FirstStandardParallel | SecondStandardParallel | ScaleFactor | CenterAzimuth | Distance | CenterRadius | +| ------------------------------------ | --------------- | -------------- | --------------------- | ---------------------- | ----------- | ------------- | -------- | ------------ | +| Equirectangular | X | X | | | | | | | +| LambertAzimuthalEqualArea | X | X | | | | | | | +| LambertConformal | X | X | X | X | | | | | +| LunarAzimuthalEqualArea | | | | | | | | | +| Mercator | X | X | | | | | | | +| Mollweide | X | | | | | | | | +| ObliqueCylindrical | X | | | | | | | | +| Orthographic | X | X | | | | | | | +| Planar | | | | | | X | | | +| PointPerspective | X | X | | | | | X | | +| PolarStereographic | X | X | | | | | | | +| RingCylindrical | | | | | | X | | X | +| Robinson | X | | | | | | | | +| SimpleCylindrical | X | | | | | | | | +| Sinusoidal | X | | | | | | | | +| TransverseMercator | X | X | | | X | | | | +| UpturnedEllipsoidTransverseAzimuthal | X | | | | | | | | + + +## Projecting a Camera Cube + +----- + +To project a raw instrument (camera) cube to a map projected image you +must use the ISIS3 program +[**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html) +. The program allows you to enter a map file to specify the projection, +ground range, resolution, and target definition. If a map file is not +supplied the program will provide the following defaults: + +| Parameters | Default Value | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | +| MinimumLatitude, MaximumLatitude, MinimumLongitude, MaximumLongitude | Automatically computed using information from the camera model | +| PixelResolution | Automatically computed using information from the camera model | +| EquatorialRadius, PolarRadius, LatitudeSystem, LongitudeRange, LongitudeDomain | Automatically computed using the TargetName from the cube labels. | +| CenterLatitude, CenterLongitude, and other projection specific parameters | Automatically computed using the middle of the ground range | + + +<figure markdown> + {: style="width:400px"} + <figcaption>A screenshot of the cam2map application</figcaption> +</figure> + + +### Quick Tips + + - [**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html) + requires the input to be a camera cube and therefore ISIS3 must + support the camera model in order for this program to be successful. + - [**spiceinit**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html) + must be run on the input cube as well. + + +## Problems at the Longitude Seams + +----- + +Problems can occur when working on images that cross the longitude seam. +For example, choosing a map file with: + +``` + LongitudeDomain = 360 +``` + +A map file combined with an image that was viewed over the 0°/360° seam +will visually look like the following example. + +When a camera acquires image data it is stored in a certain domain: + +<figure markdown> + {: style="width:400px"} + <figcaption>An illustration of the martian sphere at the 0-360 boundary</figcaption> +</figure> + + +When an image is created from the acquired data using the same domain, +the correct image is generated: + +<figure markdown> + {: style="width:400px"} + <figcaption>An image acquisition at the boundary using the same domain </figcaption> +</figure> + + +When an image is created in a different longitude domain, the resulting +image is incorrect (below, this image was scaled down to fit on the +screen): + +<figure markdown> + {: style="width:400px"} + <figcaption>An image acquisition at the boundary using a different domain </figcaption> +</figure> + + +These illustrate the problems that can arise when working with images +that cross the longitude seam. + +The +[**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html) +program has an option which automatically changes the longitude domain +if it detects the image crossing the seam. If you turn this option off, +be aware you can generate large images with mostly NULL data. Note that +a similar problem occurs at the -180°/180° longitude boundary if +LongitudeDomain = 180. + + +## Power Tip: Reprojecting an Image Map + +----- + +Occasionally the need arises to reproject an image map. For example, +converting from a Simple Cylindrical to Sinusoidal projection: + + +{: style="width:40%"} +{: style="width:10%"} +{: style="width:40%"} + + +Another purpose for reprojecting an image map is to get all the images +with the same projection, parameters, resolution, latitude system, etc +in order to mosaic. For example, + +<figure class="inline" markdown> + {: style="width:250px;height:150px"} + <figcaption>Simple Cylindrical</figcaption> +</figure> + +<figure class="inline" markdown> + {: style="width:250px;height:150px"} + <figcaption>Sinusoidal</figcaption> +</figure> + + +<figure markdown> + {: style="width:250px;height:150px"} + <figcaption>Sinusoidal Martian Mosaic</figcaption> +</figure> + +----- + + +The program for reprojecting an image map is +[**map2map**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2map/map2map.html) +. + + +## Power Tip: Making Mosaics + +----- + +In order to mosaic a set of cubes they must all be projected in +[**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html) +or +[**map2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2map/map2map.html) +using the SAME pixel resolution, target definition, and projection and +parameters (e.g., center longitude, etc). Note the ground range does not +need to be the same. This is fairly straight-forward as you can project +all the images with the same map file, just leave out the +MinimumLatitude, MinimumLongitude, MaximumLatitude, MaximumLongitude +parameters. + +In the example below, we see the mapping file used to project the five +images in the THEMIS mosaic below + +``` + Group = Mapping + LatitudeType = Planetocentric + LongitudeDirection = PositiveEast + LongitudeDomain = 360 + + ProjectionName = Sinusoidal + CenterLongitude = 354.0 + + PixelResolution = 100.0 <meters/pixel> + End_Group + End +``` + +<figure markdown> + {: style="width:250px"} + <figcaption>THEMIS Mosaic</figcaption> +</figure> + + +## Creating a mosaic + +----- + + - The most convenient way to mosaic a number of map projected images + is to use the + [**automos**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/automos/automos.html) + application. Automos reads a list of input images, computes the + latitude and longitude coverage of all the images and creates the + output mosaic. + + - The + [**mapmos**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/mapmos/mapmos.html) + application mosaics one image at a time. Remember to set create=true + the first time mapmos is run with the first image in order to create + the output mosaic file. + + - It is possible to mosaic images together by specifying the output + pixel coordinate placement using the + [**handmos**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/handmos/handmos.html) + application. This would be for any ISIS3 image cubes that do not + have a camera model or cartographic mapping information that is + required by mapmos and automos. + + +## Other Hints and Tips + +----- + + - In lieu of using a standard text editor, the programs + [**maptemplate**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/maptemplate/maptemplate.html) + or + [**mosrange**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/mosrange/mosrange.html) + can be used to assist in the building of map files. + + - A map projected image can be used as a map file. For example, a + Viking and MOC image taken of the same area can be projected by + running + [**cam2map**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cam2map/cam2map.html) + on the Viking image using the defaults and then the MOC image + projected using the Viking image as the map file. The MOC image will + have the same projection, target definition, resolution, and ground + range so that the images can be easily compared. + + - In general, the pixel resolution of the image map is only accurate + in certain portions of the image; however, this is entirely + dependent upon the projection you select. The labels of the output + cube will have a keyword called TrueScaleLatitude and/or + TrueScaleLongitude and these represent where the resolution is + accurate. The accuracy may be true along that meridian or parallel + or point. Again this depends upon the projection. + + - The output map image size will vary depending on ground range and + pixel resolution. Care should be taken to ensure your output image + is not too large. You can check the size of image that will produced + with a fully-defined map file by using the + [**mapsize**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/mapsize/mapsize.html) + program. + +</div> + + + diff --git a/docs/how-to-guides/Image Processing/Map Projecting Images.md b/docs/how-to-guides/Image Processing/Map Projecting Images.md new file mode 100644 index 0000000000000000000000000000000000000000..97540fc32c7c0904727a866edae878460a3dfa96 --- /dev/null +++ b/docs/how-to-guides/Image Processing/Map Projecting Images.md @@ -0,0 +1,168 @@ + + +# 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 + + diff --git a/mkdocs.yml b/mkdocs.yml index c9ad4e5e4c53989596906a5baf7045a061ce735a..04eb1670fd5d28ba1a7fff2268b9d2743569b0b6 100644 --- a/mkdocs.yml +++ b/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: