diff --git a/.gitignore b/.gitignore index 496ee2ca6a2f08396a4076fe43dedf3dc0da8b6d..cce739c5056f4849f6b5356e6dc484e2909e6133 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -.DS_Store \ No newline at end of file +.DS_Store +site/* \ No newline at end of file diff --git a/README.md b/README.md index 186debbb27b01cd77825819bfb018d0441419ad1..d04949e0acac89ad56df88360aedc8c4d4124020 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ We use these four categories to cover the range of potential docs while clarifyi | **Has the Goal of** | Enabling Beginners | Showing How To Solve A Problem | Give Detailed Written Explanations | Give Dry Descriptions of Libraries, Services and Apps | | **Example** | Jupyter notebook with toy data on how to ingest and project images | A breakdown of quirks working with Themis Images | Write-up on how ISIS defines projections | ISIS library Doxygen reference | -This website structure borrows from the [Divio documentation system](https://documentation.divio.com/), except adapted to more specifically adhere to how our software is already structured, renamed the categories to be more specific, and have more focus on the composition (or mode of writing) of the docs to reduce ambiguity. One can't expect any categorical structure for software documentation to be orthogonal to eachother. There will always exist some degree of overlap between categories as the quantity of documentation grows. Documentation in one category can easily have overlapping information with those in others. However, composition of the doc (e.g., jupyter notebook with an explicit starting and end point, short how-to guide with code examples but ambigious starting point and end point, written explanation without code, doxygen API reference) is less ambigious that whether or not your docs can be considered a guide or a tutorial. +This website structure borrows from the [Divio documentation system](https://documentation.divio.com/), except adapted to more specifically adhere to how our software is already structured, renamed the categories to be more specific, and have more focus on the composition (or mode of writing) of the docs to reduce ambiguity. One can't expect any categorical structure for software documentation to be orthogonal to each other. There will always exist some degree of overlap between categories as the quantity of documentation grows. Documentation in one category can easily have overlapping information with those in others. However, composition of the doc (e.g., jupyter notebook with an explicit starting and end point, short how-to guide with code examples but ambiguous starting point and end point, written explanation without code, doxygen API reference) is less ambiguous that whether or not your docs can be considered a guide or a tutorial. ### Getting Started Tutorials @@ -89,7 +89,7 @@ Good getting started docs should: Concrete things your tutorial needs: - If your tutorial requires installing software, list what software and their versions and clear instructions on how to install them. Feel free to point to other points of the doc that already have boilerplate info like "Go here to read on how to set up a custom ISISPreferences file". -- If your tutorial has data, use generative data or data that is in the repo. Avoid external data dependencies. Before data is committed into the repo, check if [existing data can be re-used](./data/). If new data needs to be committed, make sure it is small so as not to increase the data burden. +- If your tutorial has data, use generative data or data that is in the repo. Avoid external data dependencies. Before data is committed into the repo, check if [existing data can be reused](./data/). If new data needs to be committed, make sure it is small so as not to increase the data burden. - Make sure to make the lesson clear in the title. Also, make it clear in the tutorial with something like "Lessons learned in this tutorial:". @@ -105,7 +105,7 @@ How-to guides are much like recipes in a recipe book. Write how-to docs to solve Similar to getting started guides in that they explain to users how to perform some valuable tasks with the software, but distinct in that they: 1. Solve practical problems for more experienced users -1. Offer more ambiguous starting points; they should be re-usable in many different contexts +1. Offer more ambiguous starting points; they should be reusable in many different contexts 1. Can be much shorter than getting started docs Examples: @@ -136,5 +136,5 @@ Examples: Software manuals centered on the code of the library. These are generally links to the library's programmatically generated API docs. Think Sphinx docs and/or Doxygen-generated docs. Examples: -* Programatically Generated Python/C++ API docs from inline doc strings +* Programmatically Generated Python/C++ API docs from inline doc strings * RESTful API docs from an OpenAPI spec file diff --git a/docs/assets/control-networks/autoseed-gui-2012.png b/docs/assets/control-networks/autoseed-gui-2012.png new file mode 100644 index 0000000000000000000000000000000000000000..d33b50ffc8e1e26944e8904553229e7e91ed5953 Binary files /dev/null and b/docs/assets/control-networks/autoseed-gui-2012.png differ diff --git a/docs/assets/control-networks/clem-footprint-plot.png b/docs/assets/control-networks/clem-footprint-plot.png new file mode 100644 index 0000000000000000000000000000000000000000..4356da78aea4ef844c37348c4f06fbd1ca6221df Binary files /dev/null and b/docs/assets/control-networks/clem-footprint-plot.png differ diff --git a/docs/assets/control-networks/clem-grid1-autoseed.png b/docs/assets/control-networks/clem-grid1-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..154adf93a627c03e08247024d57e29bd0c6de0b3 Binary files /dev/null and b/docs/assets/control-networks/clem-grid1-autoseed.png differ diff --git a/docs/assets/control-networks/clem-grid2-autoseed.png b/docs/assets/control-networks/clem-grid2-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..96abc54919f86ed1ea2d57db33c5ce6c9e3c17e9 Binary files /dev/null and b/docs/assets/control-networks/clem-grid2-autoseed.png differ diff --git a/docs/assets/control-networks/clem-limit1-autoseed.png b/docs/assets/control-networks/clem-limit1-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..61380f91198ee7867067c1505e649223bf6ca10d Binary files /dev/null and b/docs/assets/control-networks/clem-limit1-autoseed.png differ diff --git a/docs/assets/control-networks/clem-limit2-autoseed.png b/docs/assets/control-networks/clem-limit2-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..dc4958e1efdf10571ea9cf040c8400b915be6371 Binary files /dev/null and b/docs/assets/control-networks/clem-limit2-autoseed.png differ diff --git a/docs/assets/control-networks/clem-limit3-autoseed.png b/docs/assets/control-networks/clem-limit3-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..d24d11beb25eedb767f673e2ba4f64d5c9d1bcd9 Binary files /dev/null and b/docs/assets/control-networks/clem-limit3-autoseed.png differ diff --git a/docs/assets/control-networks/clem-limit4-autoseed.png b/docs/assets/control-networks/clem-limit4-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..beec98a2adc4c00dfa25b707e938e0ba8e10c9b6 Binary files /dev/null and b/docs/assets/control-networks/clem-limit4-autoseed.png differ diff --git a/docs/assets/control-networks/clem-limit5-autoseed.png b/docs/assets/control-networks/clem-limit5-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..92e5fcce7e49d81c424cd7db8022c266d0c160ea Binary files /dev/null and b/docs/assets/control-networks/clem-limit5-autoseed.png differ diff --git a/docs/assets/control-networks/clem-polar-footprints.png b/docs/assets/control-networks/clem-polar-footprints.png new file mode 100644 index 0000000000000000000000000000000000000000..7f2243c2a6e12c06ca57ef5b9f86ea2ae0dfbbaf Binary files /dev/null and b/docs/assets/control-networks/clem-polar-footprints.png differ diff --git a/docs/assets/control-networks/clem-strip1-autoseed.png b/docs/assets/control-networks/clem-strip1-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..202935b77d20aa1b9fdf77e373248b8c3c1aeaf1 Binary files /dev/null and b/docs/assets/control-networks/clem-strip1-autoseed.png differ diff --git a/docs/assets/control-networks/clem-strip2-autoseed.png b/docs/assets/control-networks/clem-strip2-autoseed.png new file mode 100644 index 0000000000000000000000000000000000000000..415caada5a098bc53c29afb133c8f90608fd50d0 Binary files /dev/null and b/docs/assets/control-networks/clem-strip2-autoseed.png differ diff --git a/docs/assets/control-networks/cneteditor-2012.png b/docs/assets/control-networks/cneteditor-2012.png new file mode 100644 index 0000000000000000000000000000000000000000..04687da6f6c29bc110f16658fd03acddda835320 Binary files /dev/null and b/docs/assets/control-networks/cneteditor-2012.png differ diff --git a/docs/assets/control-networks/ctx-footprint-plot-cropped-demo.png b/docs/assets/control-networks/ctx-footprint-plot-cropped-demo.png new file mode 100644 index 0000000000000000000000000000000000000000..7c7bc6f9781f6eacd4ca9460062faf0dfb91b4c6 Binary files /dev/null and b/docs/assets/control-networks/ctx-footprint-plot-cropped-demo.png differ diff --git a/docs/assets/control-networks/ctx-footprint-plot.png b/docs/assets/control-networks/ctx-footprint-plot.png new file mode 100644 index 0000000000000000000000000000000000000000..df9133aab93475615731fb7dd31c71aa44bb9e0a Binary files /dev/null and b/docs/assets/control-networks/ctx-footprint-plot.png differ diff --git a/docs/assets/control-networks/ctx-high-res.png b/docs/assets/control-networks/ctx-high-res.png new file mode 100644 index 0000000000000000000000000000000000000000..6bf92538b3aeec8d3232356139392cfe4f0a9ca8 Binary files /dev/null and b/docs/assets/control-networks/ctx-high-res.png differ diff --git a/docs/assets/control-networks/ctx-hirise-blink.gif b/docs/assets/control-networks/ctx-hirise-blink.gif new file mode 100644 index 0000000000000000000000000000000000000000..97b96c0bcb0fb06da8e4cd65c8e19dbb6cc56534 Binary files /dev/null and b/docs/assets/control-networks/ctx-hirise-blink.gif differ diff --git a/docs/assets/control-networks/moc-hirise-blink.gif b/docs/assets/control-networks/moc-hirise-blink.gif new file mode 100644 index 0000000000000000000000000000000000000000..519436019a8e99e29068948d012d76120827cf68 Binary files /dev/null and b/docs/assets/control-networks/moc-hirise-blink.gif differ diff --git a/docs/assets/control-networks/moc-hirise-zoomedin-blink.gif b/docs/assets/control-networks/moc-hirise-zoomedin-blink.gif new file mode 100644 index 0000000000000000000000000000000000000000..40129fc3afe7e823dbe3e96e3f79b7aa1463c673 Binary files /dev/null and b/docs/assets/control-networks/moc-hirise-zoomedin-blink.gif differ diff --git a/docs/assets/control-networks/mola-low-res.png b/docs/assets/control-networks/mola-low-res.png new file mode 100644 index 0000000000000000000000000000000000000000..1b0bdf571b37f269a0390315d1c4aea575da7fd5 Binary files /dev/null and b/docs/assets/control-networks/mola-low-res.png differ diff --git a/docs/assets/control-networks/narrow-sliver-polygon-example.png b/docs/assets/control-networks/narrow-sliver-polygon-example.png new file mode 100644 index 0000000000000000000000000000000000000000..86795cd839ccd92e1e5f5f642c8834a49ead0de8 Binary files /dev/null and b/docs/assets/control-networks/narrow-sliver-polygon-example.png differ diff --git a/docs/assets/control-networks/overlap-polygon-example.png b/docs/assets/control-networks/overlap-polygon-example.png new file mode 100644 index 0000000000000000000000000000000000000000..f28343dd9c6e5c0ac5df026852049783556b393c Binary files /dev/null and b/docs/assets/control-networks/overlap-polygon-example.png differ diff --git a/docs/assets/control-networks/qview-measure-for-spacing-calculation-indexcolor.png b/docs/assets/control-networks/qview-measure-for-spacing-calculation-indexcolor.png new file mode 100644 index 0000000000000000000000000000000000000000..c13bae1129788259492392a65f5ca2b4f3e48598 Binary files /dev/null and b/docs/assets/control-networks/qview-measure-for-spacing-calculation-indexcolor.png differ diff --git a/docs/assets/control-networks/qview-moreoverlap-measure-for-spacing-calculation.png b/docs/assets/control-networks/qview-moreoverlap-measure-for-spacing-calculation.png new file mode 100644 index 0000000000000000000000000000000000000000..87158e7dd1e2560ebecca9b4c97b58f0cade3b87 Binary files /dev/null and b/docs/assets/control-networks/qview-moreoverlap-measure-for-spacing-calculation.png differ diff --git a/docs/assets/control-networks/upc-ctx-search-for-footprint-reduced.png b/docs/assets/control-networks/upc-ctx-search-for-footprint-reduced.png new file mode 100644 index 0000000000000000000000000000000000000000..fab2a4e3b96494a6c8ad739e6eb6852c1f9b1523 Binary files /dev/null and b/docs/assets/control-networks/upc-ctx-search-for-footprint-reduced.png differ diff --git a/docs/concepts/control-networks/automatic-registration.md b/docs/concepts/control-networks/automatic-registration.md new file mode 100644 index 0000000000000000000000000000000000000000..7584431ee1a9bcd6e91c73ddb0798521ded8b2ff --- /dev/null +++ b/docs/concepts/control-networks/automatic-registration.md @@ -0,0 +1,389 @@ + +# Automatic Registration + +## Introduction + +Automatic registration is the attempt to match a pattern in an image +cube. Pattern matching has many different purposes. + +Examples: + +1. Register an entire image to a second image. The registration of an + image is performed by moving (rubber-sheet) the pixels to output + pixel locations that result in pattern matching directly to a second + 'fixed' or 'truth' image. + + - Use: [coreg](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/coreg/coreg.html) + +2. Relative cartographic registration between a number of overlapping + images. Pattern matching is used to build a control point network + across a number of overlapping images for solving and adjusting the + camera pointing that are then applied to map project the images. + + - Use: [pointreg](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/pointreg/pointreg.html) or [jigsaw](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/jigsaw/jigsaw.html) + +3. Find and record the pixel location(s) of a camera reference mark + (e.g., Vidicon reseau mark) across an image + + - Use: [findrx](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/findrx/findrx.html) + + +## Match Algorithm Definition Files (PVL) + +Registration of images can be an advanced and complicated process. ISIS3 +is designed to supply a choice of match/registration algorithms to +handle a variety of image data conditions. An ISIS3 "plugin" algorithm +expects all match algorithms to supply parameter information through a +Parameter Value Language (PVL) definition file. Examples of match +algorithm PVL's can be found in + + $ISIS3DATA/base/templates/autoreg/coreg*.def + +Registration applications (such as coreg) will allow the user to choose +from this collection of PVL files in the user interface gui. + +A PVL file can be generated for a selected match algorithm with +[autoregtemplate](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/autoregtemplate/autoregtemplate.html). + +## Match Algorithms + +### Maximum Correlation + +The Maximum Correlation match algorithm is most commonly used. The +algorithm computes a +correlation coefficient that will range from no correlation (zero) to +perfect correlation (one). + +Example templates for Maximum Correlation can be found in: + + + $ISIS3DATA/base/templates/autoreg/coreg.maxcor.p*.s*.def. + + +An example PVL for the Maximum Correlation follows: + + Object = AutoRegistration + + Group = Algorithm + Name = MaximumCorrelation + Tolerance = 0.7 + End_Group + + End_Object + +!!! tip + + A successful correlation is met if the **Goodness of Fit** is **Greater Than** + the Tolerance parameter value for the Maximum Correlation Algorithm. + +### Minimum Difference + +The Minimum Difference match algorithm performs a subtraction of the +Pattern Chip and the sub-region of the Search Chip. The **Goodness of +Fit** will range from zero for a perfect match, while larger values +indicate a less likely match. The **Goodness of Fit** is measured as an +absolute value and will never be negative. + +Example templates for Minimum Difference can be found in: + + $ISIS3DATA/base/templates/autoreg/coreg.mindif.p*.s*.def. + +An example PVL for the Minimum Difference follows: + + Object = AutoRegistration + + Group = Algorithm + Name = MinimumDifference + Tolerance = 100 + End_Group + + End_Object + +!!! tip + + A successful correlation is met if the **Goodness of Fit** is **Less + Than** the Tolerance parameter value for the Minimum Difference Algorithm. + +## Tolerance + +The Tolerance parameter is used by both Maximum +Correlation and Minimum +Difference. Each correlation coefficient result +(**Goodness of Fit**) is tested against the Tolerance. Tolerance is set +within the PVL file along with the chosen +registration algorithm. + +Points that fail the Tolerance test are reported by the autoreg +applications as: + +- `FitChipToleranceNotMet` + +- `SurfaceModelToleranceNotMet` + +## Chips + +There are two chips used in automatic registration, the Pattern +Chip and the Search Chip. The +two chips are nothing more than sub-areas of the input image cubes, +generally small in size. An NxM Chip is defined to be an N-Sample by +M-Line region of an image. Basic elements of a chip are: + + - N and M are natural numbers (1, 2, 3...,50) + - Like image cubes, chip coordinates are sample/line and 1-band based + - The center of the chips is (N - 1)/2 + 1 and (M - 1)/2 + 1 + +### Pattern Chip + +A Pattern Chip will contain the data you would like to match. This +Pattern Chip is basically extracted from the 'Reference' image (it is +also referred to as the 'Truth' image). The Pattern Chip is then walked +across the Search Chip that has been extracted from +the other image that is to be modified. + +The PVL for a Pattern Chip defined as 25 Samples x 25 Lines (625 pixels) +is: + + Object = AutoRegistration + + Group = PatternChip + Samples = 25 + Lines = 25 + End_Group + + End_Object + +**Pattern Chip Size Requirement:** + +N + M \>= 3. This ensures that the pattern is not a single pixel. + +???+ tip "Tips" + + 1. The feature to match included in the Pattern Chip does not have to + be in the center. + 2. The more "bland" the data is within the input images, the larger the + Pattern Chip box should be. A larger box will allow for more pixel + DN variance. + 3. In general, avoid very small box sizes less than 11 Samples X 11 + Lines + 4. The smaller the size of the Pattern Chip, the greater the chance of + matching too many areas in the search chip and returning a 'false + positive' match. + +### Search Chip + +A Search Chip is the sub-area of the image cube that the pattern might +be found in. The Pattern Chip is walked through the +Search Chip looking for the best match. The Search Chip must be larger +than the Pattern Chip (at least one pixel bigger on line/sample size). + +The PVL for a Search Chip defined as 45 Samples x 45 Lines (2025 pixels) +is: + + Object = AutoRegistration + + Group = PatternChip + Samples = 25 + Lines = 25 + End_Group + + Group = SearchChip + Samples = 45 + Lines = 45 + End_Group + + End_Object + +**Search Chip Size Requirement:** + +!!! danger "TODO - Update Link" + + TODO: Update **Sub-Pixel Definition** links to new docs once those pages are migrated. + +N(search) \>= N(pattern) + 2 and similarly for M. This ensures that the +Pattern Chip spans at least a 3x3 window within the Search Chip. An +important requirement for surface fitting in order to compute sub-pixel +accuracy. (Refer to: [Sub-Pixel Definition](https://DOI-USGS.github.io/ISIS3/gh-pages/ISIS_Cube_Format)). + +???+ tip "Tips" + + - The Search Chip must be larger than the Pattern Chip (at least one + pixel bigger on line/sample size). + - The Search Chip needs to be large enough to allow a 'best guess' or + predicted line and sample mis-registration offset between the images + that are to be correlated. + - **SearchChipSize = PatternChipSize + (OffsetPixelEstimate * + 2)** + - BUT, the Search Chip shouldn't be too much larger than the Pattern + Chip. + - The difference in size could greatly affect how long the + registration application would run. + - Refer to PVL example above: + - An estimated offset between two input images of 10 Lines by 10 + Samples will need a Search Chip size (10 Line offset * 2) by + (10 Sample offset * 2). The Search Chip size in this example + needs to be at least 20*20 Lines/Samples bigger than the pattern + chip. + - PatternChipSize = 25 * 25 + - SearchLineDimention = 25 + (10 * 2) = 45 * SearchSampleDimention = 25 + (10 * 2) = 45 + - SearchChipSize= 45 * 45 + +## Restricting Input Pixel Ranges + +!!! danger "TODO - Update Link" + + TODO: Update **Input Pixels** and **Special Pixel** links to new docs once those pages are migrated. + +The validity of the [input pixels](https://DOI-USGS.github.io/ISIS3/gh-pages/ISIS_Cube_Format) +of the Pattern Chip is the very first test +performed. Prior to the match algorithm being invoked during the walk +process, a simple test is performed to ensure there are enough pixels to +work with. Pixels are deemed valid if they are in the minimum/maximum +range and/or they are not [special pixel](https://DOI-USGS.github.io/ISIS3/gh-pages/Special_Pixels.html) values. + +The Pattern Chip is only checked once. If it does not contain enough +valid pixels, the match is deemed to fail. Otherwise, the walk through +occurs and the sub-area is extracted from the Search +Chip. If this sub-area does not have enough valid +pixels a match will be deemed to fail at that search location. + +Points that fail the default or specified Valid Minimum/Maximum and/or +ValidPercent tests are reported by the autoreg applications as: + +- `PatternNotEnoughValidData` + +- `FitChipNoData` + +- `SurfaceModelToleranceNotMet` + +### Valid Minimum/Maximum + +Input image pixels (DN) values may be excluded from the match +algorithm if they fall outside of a specific range. The ranges can be +specified independently for the Search Chip and Pattern Chip. While this +might not be necessary for a successful registration, excluding pixel +data could improve the chances depending on the characteristics of the +input images. (i.e., Eliminating the DN range of deep shadow areas in an +image). + +The ranges are handled via the PVL as follows: + + Object = AutoRegistration + + Group = PatternChip + Samples = 20 + Lines = 20 + ValidMinimum = 0.1 + ValidMaximum = 0.4 + End_Group + + Group = SearchChip + Samples = 55 + Lines = 55 + ValidMinimum = 2.5 + ValidMaximum = 10.5 + End_Group + + End_Group + +### Valid Pixel Count (ValidPercent) + +`ValidPercent` defines the percentage of valid data that is required +within the Pattern Chip or Search Chip. The parameter can be set in +conjunction with Valid Minimum/Maximum. + +The Valid Percent would be handled via the PVL as follows: + + Object = AutoRegistration + + Group = PatternChip + Samples = 20 + Lines = 20 + ValidPercent = 80 + End_Group + End_Group + +Default for `ValidPercent`: `AutoRegDefaults` + +!!! tip + + `ValidPercent` is specified in the Pattern Chip, as the sub-area + chip of the search area will use the same value. + +## Fit Chip + +As the Pattern Chip walks through the sub-regions +of the Search Chip , a third chip is generated +called a Fit Chip. The Fit Chip will have the same line and sample +dimensions as the Search Chip. The Fit Chip is filled with the resulting +**Goodness of Fit** values at every position that the Pattern Chip is walked +across the Search Chip computing a fit correlation value. + +The highest or lowest **Goodness of Fit** values within the Fit Chip +generally represent the position that best matched between the Pattern +and Search areas. It is only good to a maximum of **ONE pixel accuracy**. + +The Fit Chip can be interactively generated and viewed using the image +display application +[qnet](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/qnet/qnet.html). + + +## Sub-Pixel Accuracy + +!!! danger "TODO - Update Link" + + TODO: Update **Sub-Pixel Definition** links to new docs once those pages are migrated. + +The attempt to reach a registration of sub-pixel accuracy is performed +on the Fit Chip. The Fit Chip is created as the +Pattern Chip is walked through Search +Chip. The Fit Chip contains the resulting +correlation position between the two chips of a maximum of ONE pixel +accuracy. In many cases, the actual, ultimate registration may lie +somewhere between two pixels. (Refer to: +[Sub-Pixel Definition](https://DOI-USGS.github.io/ISIS3/gh-pages/ISIS_Cube_Format)). + +The sub-pixel accuracy can be turned off through the PVL settings as +follows: + + Group = Algorithm + Name = MaximumCorrelation + SubPixelAccuracy = False + End_Group + +When the sub-pixel accuracy is turned off, the whole pixel with the best +fit is returned. +Default for SubPixelAccuracy: AutoRegDefaults + +!!! tip + + By default, if an ideal **Goodness of Fit** is found (e.g. Zero (0.0) for + Minimum Difference or One (1.0) for Maximum Correlation), we have a perfect + fit and assume that it is the best position. In this case, the sub-pixel + accuracy phase is omitted. + +### Surface Modeling + +A continuous mathematical surface is modeled based on the data within +the Fit Chip. A 2nd degree 2-dimensional +polynomial is calculated given an NxN window of points extracted from +the Fit Chip surrounding the correlation peak (highest value)-which +represents the whole pixel registration. An estimate of the true +sub-pixel registration position of the chip can be reached based on this +surface model. + +A perfect 3D linear fit (global maximum) would be represented by a +spherical surface with a single high peak. + +## AutoRegDefaults + +(As of May 20, 2009) + + ValidPercent = 50.0 + MinimumZScore = 1.0 + Tolerance = Null (no default) + ReductionFactor = 1.0 + + SubPixelAccuracy = True + SurfaceModelDistanceTolerance = 1.5 + SurfaceModelWindows = 5 + SurfaceModelEccentricityRatio = 2 (2:1) diff --git a/docs/concepts/control-networks/autoseed.md b/docs/concepts/control-networks/autoseed.md new file mode 100644 index 0000000000000000000000000000000000000000..44450c4fae5c9201f23c9cbe6d9d7179b530aa8b --- /dev/null +++ b/docs/concepts/control-networks/autoseed.md @@ -0,0 +1,798 @@ + +# Autoseed + +See Also: [autoseed Application +Documentation](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/autoseed/autoseed.html) + +## Introduction + +[Autoseed](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/autoseed/autoseed.html) +is a program that will automatically build a gridded network of evenly +distributed tiepoints across overlapping polygons. The distance between +the tiepoints is defined in meters, or number of points along the major +axis and minor axis. Autoseed requires the success of ISIS3's +[spiceinit](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html), +[footprintinit](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/footprintinit/footprintinit.html) +and +[findimageoverlaps](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/findimageoverlaps/findimageoverlaps.html) +applications. The collection of tiepoints are further refined with other +ISIS3 programs, and used to improve the geometric accuracy of the input +images. + +## Overlap Polygons + +{ align=right width=300 } + +The automatic seeding program is dependent on the information about how +all the images to be combined into a single output overlap each other. +The polygons can be different shapes and sizes. A separate program +(**findimageoverlaps**) attempts to find all the polygons and saves the +information to an output file. This output file is defined as the +*overlap* parameter in **autoseed**. This image shows the +overlap polygons in different shades of color. + + + +## Available Algorithms + +| Algorithm | Best for: | +|-----------|-------------------------------------------------------------------------------| +| **Grid** | different shapes and sizes of overlap polygon | +| **Limit** | limiting the number of seeded tiepoints per polygon | +| **Strip** | rectangular shaped overlap polygons such as those for adjacent line scan data | + +The standard autoseed templates for the three algorithms are in +`$ISIS3DATA/base/templates/autoseed/` + +## Required Parameters for each Algorithm + +The required parameters for each algorithm are provided through a +separate **Parameter Value Language** (PVL) definition file. + +??? abstract "Grid Algorithm PVL File" + + Object = AutoSeed + Group = PolygonSeederAlgorithm + Name = Grid + Minimum Thickness = 0.0 + MinimumArea = 100000000 + XSpacing = 10000 + YSpacing = 10000 + EndGroup + EndObject + + +??? abstract "Limit Algorithm PVL File" + + Object = AutoSeed + Group = PolygonSeederAlgorithm + Name = Limit + Minimum Thickness = 0.0 + MinimumArea = 100000000 + MajorAxisPoints = 6 + MinorAxisPoints = 3 + EndGroup + EndObject + + +??? abstract "Strip Algorithm PVL File" + + Object = AutoSeed + Group = PolygonSeederAlgorithm + Name = Strip + Minimum Thickness = 0.0 + MinimumArea = 100000000 + XSpacing = 10000 + YSpacing = 10000 + EndGroup + EndObject + + +???+ example "Using keywords to specify a set of valid parameters to seed tie points" + + Object = AutoSeed + Group = PolygonSeederAlgorithm + Name = Grid + MinimumThickness = 0.0 + MinimumArea = 1000 <meters> + XSpacing = 20000 <meters> + YSpacing = 10000 <meters> + PixelsFromEdge = 20.0 + MinEmission = 20.0 + MaxEmission = 75.0 + MinIncidence = 25.0 + MaxIncidecne = 80.0 + MinResolution = 255.0 + MaxResolution = 259.0 + # MinDN and MaxDN are costly checks + MinDN = 0.145 + MaxDN = 0.175 + EndGroup + EndObject + + +### MinimumThickness + +{ width=250 align=left } + +!!! tip + + Setting the **MinimumThickness** parameter will most likely work better + for these polygons. If boxes were drawn around the polygons they would be + similar to the shape of the original polygons. + +The MinimumThickness is used to exclude seeding tiepoints within +polygons that are narrow slivers. If the thickness value is below the +defined minimum thickness, then no tiepoints are seeded within the +polygon. The valid values are between 0.0 and 1.0, and the default value +is 0.0 if nothing is entered. The thickness value is derived by drawing +a box around the polygon, and calculating the ratio of the short side by +the long side of the box. The MinimumThickness option works best if the +polygons are rectangular or square shapes. Use this parameter with +caution because the calculated value for thickness may not be accurate. + +----- + +### MinimumArea + +{ width=300 align=left } + +The MinimumArea is used to specify what the smallest calculated value +for the minimum area of an overlap polygon must be in order to seed +tiepoints. The default value is 0.0 if nothing is entered for +MinimumArea. This parameter is useful for excluding small and skinny +overlap polygons from being seeded with tiepoints. + +!!! tip + + 1. Set the **MinimumArea** to avoid seeding tiepoints in polygons + formed by narrow slivers overlapping. + + 1. **MinimumThickness** might be misleading for these polygons; + its estimate would be too large. + +----- + +### *XSpacing* & *YSpacing* + +The *grid* and *strip* algorithms require the user to define XSpacing +and YSpacing, and if nothing is entered the program will report an error +and fail. The XSpacing and YSpacing parameters are defined in meters, +and determine how the tiepoints will be distributed within each polygon. +The tiepoints are seeded starting at the center of each polygon, and +spaced every XSpacing increment along the X-axis, and YSpacing increment +along the Y-axis. The resolution of the input images will contribute to +how dense the tiepoints are seeded. See Examples. + +### *MajorAxisPoints* & *MinorAxisPoints* + +These two parameters are only used for the *Limit* algorithm. The +MajorAxisPoints is used to specify how many tiepoints to seed along the +longer side of a box drawn around the polygon. The MinorAxisPoints is +used to specify how many tiepoints to seed along the shorter side of a +box drawn around a polygon. So, if you set MajorAxisPoints = 10 and +MinorAxisPoints = 3, then you would have 30 equally spaced tiepoints (10 +rows by 3 columns or 3 rows by 10 columns) within each of the overlap +polygons. + + +## Preparing for autoseed (run these programs first) +#### These must be run on individual input images: + +| | Program | Purpose | +|---|-------------------|------------------------------------------------------------------| +| 1 | **spiceinit** | attaches SPICE data to the ISIS3 cube | +| 2 | **footprintinit** | adds image footprint information to ISIS3 cube labels | +| 3 | **camstats** | attaches geometric and image statistics to the ISIS3 cube labels | + +#### *findimageoverlaps* needs a list of images as input: + +| | | +|-----------------------|----------------------------------------------------------------------------| +| **findimageoverlaps** | determines all the overlap polygons among all the images in the input list | + +## Deciding which algorithm to use + +The first step is to display the images you have selected to see how +they overlap each other using either PILOT, qmos, or some other display +method. The overlap polygons are areas where a unique set of images +overlap each other. The complexity of the polygons across your mosaic +area will determine which algorithm is the most appropriate to use. + +### Examples: + +{ align=left width=300 } + +#### Non-uniform order and size → *Grid* + +The image footprints are not in a uniform order, and the size of the images +varies. The `Grid` algorithm would be the best to use for this data. + +(This image shows rendered footprints in [PILOT](http://pilot.wr.usgs.gov/).) + +----- + +{ align=left width=300 } + +#### Same resolution but different sizes → *Limit* or maybe *Strip* + +The resolution of the images are about the same, but +the ground area that was imaged varies in size. The strips of CTX +linescan data are adjacent to each other, and the overlap polygons are +simple and easily identified. The `Limit` algorithm would be the easiest +to use. You would need to decide how many points to seed along the +longest side of the overlap polygon and how many points across the +shorter side. The `Strip` algorithm will provide more evenly distributed +set of tiepoints, but you will need to figure out the most appropriate X +and Y spacing. + +----- + +{ align=left width=300 } + +#### Same resolution and size, varying overlaps → *MinimumArea* + *Grid* or *Strip* + +The resolution of the images are about the same. The +size of the overlap polygons vary in shape, orientation, and sizes. It +would be best to specify the `MinimumArea` to eliminate many of the +smaller polygons from getting seeded. The best option would be to use +either `Grid` or `Strip` algorithm to avoid clustered points in the smaller +polygons. The `MinimumArea` can be increased if there are too many points +clustered together in the smaller polygons, and the spacing can also be +increased to put a greater distance between the seeded tiepoints. + +----- + +{ align=left } + +#### Complex overlaps → Manual Approach with *seedgrid* + +The overlap polygons here are so complex that +`findimageoverlaps` will fail, and `autoseed` cannot be run. In this +case, the only option is to use the program `seedgrid` to generate a +network of seeded tiepoints. The `seedgrid` program does not require +prior knowledge of the overlap polygons, but does require latitude +range, longitude range, and a map template. + +----- + +## Determining XSpacing and YSpacing + +It is important to know the range of resolutions for the images you wish +to include. Decide how many tiepoints you want to seed across the longer +side and shorter side of the overlap polygons. For example, let’s say +most of the polygons have 50 pixels of overlap along the shortest width +and 5000 pixels along the longest length and the median resolution is 6 +meters/pixel, and you have decided to seed 3 points across the shorter +side and 10 points along the longer side of the polygons. The +calculation for the spacing would be the following: + + X-spacing = (50/(3 + 1)) * 6 = 75m + y-spacing = (5000/(10 + 1)) * 6 = ~2727m (round up to 2800m) + +The second option is to display two images whose overlap pattern is +representative of most of the images in the mosaic using ISIS3 **qview** +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 +widest overlap area: + +!!! danger "TODO - Update link" + + 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**. + + + +The tool measured approximately 278 pixels. The resolution of these two +images are around 190 meters/pixel. So, the calculation for XSpacing +would be ((278 pixels/6) \* 190 m/pixel) resulting in 8803.3 meters. You +could start with XSpacing and YSpacing equal to 8800 meters as a +starting point, and then increase or decrease the number based on +whether you want to increase or decrease the distance between the seeded +tiepoints. + + + +This example shows the measurement for the shorter side of the polygon, +which is about 86 pixels. Sometimes the spacing increments you select +may need to be different in the x and y directions, especially for line +scan data where the image has a lot more lines than samples. If the +desire is to seed only two tiepoints along the shorter side then your +calculation would be ((86 pixels/3) \* 190 m/pixel) giving an xspacing +of 5446 meters. You could use 5500 meters for x-spacing and 8800 meters +for y-spacing. + +## Required Parameters + +Autoseed parameters: + +| Parameter | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------| +| `fromlist` | List of all the filenames to be included in a control solution | +| `deffile` | PVL file containing the seeding algorithm and spacing between the tiepoints | +| `overlaplist` | Output file from **findimageoverlaps** program | +| `cnet` | Filename of existing control network to add to (optional) | +| `onet` | Output filename for control network generated by **autoseed** | +| `errors` | Output filename for error tracking | +| `networkid` | ID name assigned to the control network file | +| `pointid` | Starting string to be assigned to the **PointId**s, with question </br>marks for the number of digits needed (like "`C?????`") | +| `description` | Description of the contents of the output control net file | + +## Running Autoseed + +!!! example "Command Line Interface" + + In your terminal, type `autoseed` followed by `parameter=value` for each parameter as shown: + ```sh + autoseed fromlist=lev1.lis deffile=clem_grid2_autoseed.def overlaplist=overlaps.lis onet=autoseed_grid.net errors=autoseed_grid.err networkid=Clementine1 pointid=C?????? description="Clementine grid1" + ``` + +??? example "Graphical Interface" + +  + +## Output + +The output file is a binary control network (cnet) file that contains +the control pointids and control measurements of all the images that +overlap each seeded tiepoint. The program **qmos** can be used to +display the images, image footprints, and the control network to see how +the tiepoints are distributed. If the distribution of tiepoints is too +dense, increase the spacing between the tie points to spread them apart +and to reduce the number of tiepoints. If the tiepoints are too sparse +then decrease the spacing to add more tiepoints. Rerun **autoseed** each +time the parameters in the PVL definition file are changed. When you +have reached an acceptable solution then use the program **qnet** to +evaluate and refine the tiepoints by loading the control network file. + +The output network can no longer be viewed by a text editor unless the +network file has been converted to a PVL format with **cnetbin2pvl** , +but use caution if the file size is large. The second option is to use +**cneteditor** to view the network file in the binary format. + +**Converting binary control network to PVL format:** + +```sh +cnetbin2pvl from=hirise_set1_autoseed.net to=hirise_set1_autoseed_pvl.net +``` + +??? abstract "Contents of an example HiRISE cnet file (first 66 lines)" + + Object = ControlNetwork + NetworkId = Hirise_set1 + TargetName = Mars + UserName = elee + Created = 2012-05-08T10:38:21 + LastModified = 2012-05-08T10:38:21 + Description = "HiRise set1 images autoseed with hirise_ccd_sets_seed.def" + Version = 3 + + Object = ControlPoint + PointType = Free + PointId = hirise_set1_00001 + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + + Group = ControlMeasure + SerialNumber = MRO/HIRISE/867676384:40724/RED0/2 + MeasureType = Candidate + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + Sample = 2040.423603891 + Line = 20.242382897271 + AprioriSample = 2040.423603891 + AprioriLine = 20.242382897271 + End_Group + + Group = ControlMeasure + SerialNumber = MRO/HIRISE/867676384:40724/RED1/2 + MeasureType = Candidate + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + Sample = 43.186441092459 + Line = 13.357872143126 + AprioriSample = 43.186441092459 + AprioriLine = 13.357872143126 + End_Group + End_Object + + Object = ControlPoint + PointType = Free + PointId = hirise_set1_00002 + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + + Group = ControlMeasure + SerialNumber = MRO/HIRISE/867676384:40724/RED0/2 + MeasureType = Candidate + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + Sample = 2011.1452341621 + Line = 16.380977898313 + AprioriSample = 2011.1452341621 + AprioriLine = 16.380977898313 + End_Group + + Group = ControlMeasure + SerialNumber = MRO/HIRISE/867676384:40724/RED1/2 + MeasureType = Candidate + ChooserName = autoseed + DateTime = 2012-05-08T10:38:45 + Sample = 13.917053834296 + Line = 9.5400377909342 + AprioriSample = 13.917053834296 + AprioriLine = 9.5400377909342 + End_Group + End_Object + + +**Run this command to display the control network with cneteditor:** + +```sh +cneteditor hirise_set1_autoseed.net +``` + +??? info "A control network in cneteditor" + +  + +## Examples + +Examples of image footprint and tiepoints plotted with different parameter settings. + +??? example "Coarse *Grid*" + + { align=right width=450 } + + **Autoseed PVL definition file for *Grid* algorithm** + + Name = Grid + MinimumThickness = 0.0 + MinimumArea = 10000000 + XSpacing = 10000 + YSpacing = 10000 + + The spacing increment for both X and Y directions are the same due to + the similar shapes of the overlap polygons. The `MinimumArea` was defined + to limit clustered tiepoints. + +??? example "Fine *Grid*" + + { align=right width=450 } + + **Autoseed PVL definition file for *Grid* algorithm** + + Name = Grid + MinimumThickness = 0.0 + MinimumArea = 10000000 + XSpacing = 5000 + YSpacing = 5000 + + The spacing increment decreased by a factor of two so more tiepoints can + be automatically seeded. It was desirable to have more tiepoints due to + the fact that we are working with data near the South Pole where there + are more areas in shadows than normal. + +??? example "Coarse *Strip*" + + { align=right width=450 } + + **Autoseed PVL definition file for *Strip* algorithm** + + Name = Strip + MinimumThickness = 0.0 + MinimumArea = 10000000 + XSpacing = 10000 + YSpacing = 10000 + + The spacing increment for both X and Y directions are the same due to + the similar shapes of the overlap polygons. The `MinimumArea` was defined + to limit clustered tiepoints. The result is very similar to the grid + algorithm and some of the tiepoints are seeded in difference locations. + +??? example "Fine *Strip*" + + { align=right width=450} + + **Autoseed PVL definition file for *Strip* algorithm** + + Name = Strip + MinimumThickness = 0.0 + MinimumArea = 10000000 + XSpacing = 5000 + YSpacing = 5000 + + The spacing increment decreased by a factor of two so more tiepoints can + be automatically seeded. It was desirable to have more tiepoints due to + the fact that we are working with data near the South Pole where there + are more areas in shadows than normal. There are more tiepoints + clustered along polygon boundaries for this test. + +??? example "Limit example" + + #### Starting Point + + {align=right width=450 } + + MinimumThickness = 0.0 + MinimumArea = 10000000 + MajorAxisPoints = 6 + MinorAxisPoints = 3 + + ----- + + #### Step 1 + + { align=right width=450 } + + MinimumThickness = 0.0 + MinimumArea = 10000000 + MajorAxisPoints = 3 + MinorAxisPoints = 1 + + The number of points for the major and minor axis were reduced to seed + fewer tiepoints. + + ----- + + #### Step 2 + + { align=right width=450 } + + MinimumThickness = 0.0 + MinimumArea = 20000000 + MajorAxisPoints = 3 + MinorAxisPoints = 1 + + The MinimumArea was doubled to eliminate tiepoints in the small + polygons. + + ----- + + #### Step 3 + + { align=right width=450 } + + MinimumThickness = 0.0 + MinimumArea = 50000000 + MajorAxisPoints = 3 + MinorAxisPoints = 1 + + The MinimumArea was increased again to remove more tiepoints from the + small polygons. + + ----- + + #### Step 4 + + { align=right width=450 } + + MinimumThickness = 0.0 + MinimumArea = 75000000 + MajorAxisPoints = 3 + MinorAxisPoints = 1 + + The MinimumArea was increased even further to eliminate tiepoints that + were still too close together especially along the polygon boundaries. + +## Seedgrid + +The last option is to utilize **seedgrid** instead of **autoseed** if +**findimageoverlaps** fails. This method seeds tiepoints without relying +on the overlap polygons. The program will seed tiepoints across a +specified area based solely on the spacing provided by the user, either +in x/y spacing or lat/lon increment. The output file will contain the +PointId and the latitude and longitude coordinate associated with each +pointid. This option is also useful if your data set includes images +with a wide range of resolutions, or if the limb or terminator in the +image. + +!!! example "Running seedgrid on the command line" + + ``` + seedgrid target=Mars minlat=0 maxlat=5 minlon=0 maxlon=6 spacing=latlon latstep=1 lonstep=1 networkid=Seedgrid1 pointid=Mars_seedgrid_??? onet=seedgrid.net description="Seedgrid latinc=1 loninc=1" + cnetbin2pvl from=seedgrid.net to=seedgrid_pvl.net + ``` + + +??? abstract "Partial contents of seedgrid control network file" + + Object = ControlNetwork + NetworkId = Seedgrid1 + TargetName = Mars + UserName = elee + Created = 2012-06-01T11:07:49 + LastModified = 2012-06-01T11:07:49 + Description = "Seedgrid latinc=1 loninc=1" + Version = 3 + + Object = ControlPoint + PointType = Free + PointId = Mars_seedgrid_001 + ChooserName = seedgrid + DateTime = 2012-06-01T11:07:49 + Ignore = True + + # AprioriLatitude = 0.0 <degrees> + AprioriX = 3396190.0 <meters> + + # AprioriLongitude = 0.0 <degrees> + AprioriY = 0.0 <meters> + + # AprioriRadius = 3396190.0 <meters> + AprioriZ = 0.0 <meters> + End_Object + + Object = ControlPoint + PointType = Free + PointId = Mars_seedgrid_002 + ChooserName = seedgrid + DateTime = 2012-06-01T11:07:49 + Ignore = True + + # AprioriLatitude = 1.0 <degrees> + AprioriX = 3395672.7438132 <meters> + + # AprioriLongitude = 0.0 <degrees> + AprioriY = 0.0 <meters> + + # AprioriRadius = 3396190.0 <meters> + AprioriZ = 59271.688218238 <meters> + End_Object + +The next step would be to run **cnetadd** to add new control measurement +for the images in your input list. + + ls *lev1.cub > lev1.lis + cnetadd cnet=seedgrid.net addlist=lev1.lis onet=seedgrid_cnetadd.net tolist=cnetadd_output.lis log=seedgrid_cnetadd.log modifiedpoints=modified.lis polygon=yes retrieval=point + +Continue with control registration with **pointreg** or other cnet +programs. + +----- + +??? quote "Images on this page" + + [autoseed-gui-2012.png](../../assets/control-networks/autoseed-gui-2012.png) + [View](../../assets/control-networks/autoseed-gui-2012.png "View") + (79.3 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-grid1-autoseed.png](../../assets/control-networks/clem-grid1-autoseed.png) + [View](../../assets/control-networks/clem-grid1-autoseed.png "View") + (83.8 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-grid2-autoseed.png](../../assets/control-networks/clem-grid2-autoseed.png) + [View](../../assets/control-networks/clem-grid2-autoseed.png "View") + (104 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-footprint-plot.png](../../assets/control-networks/clem-footprint-plot.png) + [View](../../assets/control-networks/clem-footprint-plot.png "View") + (141 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-limit1-autoseed.png](../../assets/control-networks/clem-limit1-autoseed.png) + [View](../../assets/control-networks/clem-limit1-autoseed.png "View") + (115 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-limit3-autoseed.png](../../assets/control-networks/clem-limit3-autoseed.png) + [View](../../assets/control-networks/clem-limit3-autoseed.png "View") + (67.7 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-limit2-autoseed.png](../../assets/control-networks/clem-limit2-autoseed.png) + [View](../../assets/control-networks/clem-limit2-autoseed.png "View") + (68.7 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-limit4-autoseed.png](../../assets/control-networks/clem-limit4-autoseed.png) + [View](../../assets/control-networks/clem-limit4-autoseed.png "View") + (82.4 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-polar-footprints.png](../../assets/control-networks/clem-polar-footprints.png) + [View](../../assets/control-networks/clem-polar-footprints.png "View") + (148 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-strip1-autoseed.png](../../assets/control-networks/clem-strip1-autoseed.png) + [View](../../assets/control-networks/clem-strip1-autoseed.png "View") + (82.6 KB) Jesse Mapel, + 2016-05-31 12:58 PM + + [clem-strip2-autoseed.png](../../assets/control-networks/clem-strip2-autoseed.png) + [View](../../assets/control-networks/clem-strip2-autoseed.png "View") + (108 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [cneteditor-2012.png](../../assets/control-networks/cneteditor-2012.png) + [View](../../assets/control-networks/cneteditor-2012.png "View") + (77.5 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [ctx-footprint-plot.png](../../assets/control-networks/ctx-footprint-plot.png) + [View](../../assets/control-networks/ctx-footprint-plot.png "View") + (114 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [ctx-footprint-plot-cropped-demo.png](../../assets/control-networks/ctx-footprint-plot-cropped-demo.png) + [View](../../assets/control-networks/ctx-footprint-plot-cropped-demo.png "View") + (47 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [overlap-polygon-example.png](../../assets/control-networks/overlap-polygon-example.png) + [View](../../assets/control-networks/overlap-polygon-example.png "View") + (22.9 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [narrow-sliver-polygon-example.png](../../assets/control-networks/narrow-sliver-polygon-example.png) + [View](../../assets/control-networks/narrow-sliver-polygon-example.png "View") + (84.4 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [qview-measure-for-spacing-calculation-indexcolor.png](../../assets/control-networks/qview-measure-for-spacing-calculation-indexcolor.png) + [View](../../assets/control-networks/qview-measure-for-spacing-calculation-indexcolor.png "View") + (94.5 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [qview-moreoverlap-measure-for-spacing-calculation.png](../../assets/control-networks/qview-moreoverlap-measure-for-spacing-calculation.png) + [View](../../assets/control-networks/qview-moreoverlap-measure-for-spacing-calculation.png "View") + (126 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [upc-ctx-search-for-footprint-reduced.png](../../assets/control-networks/upc-ctx-search-for-footprint-reduced.png) + [View](../../assets/control-networks/upc-ctx-search-for-footprint-reduced.png "View") + (170 KB) Jesse Mapel, + 2016-05-31 01:00 PM + + [clem-limit5-autoseed.png](../../assets/control-networks/clem-limit5-autoseed.png) + [View](../../assets/control-networks/clem-limit5-autoseed.png "View") + (79 KB) Jesse Mapel, + 2016-05-31 02:25 PM diff --git a/docs/concepts/control-networks/image-registration.md b/docs/concepts/control-networks/image-registration.md new file mode 100644 index 0000000000000000000000000000000000000000..c881898724f74e2beda8c32a6781f2752ae88897 --- /dev/null +++ b/docs/concepts/control-networks/image-registration.md @@ -0,0 +1,40 @@ + +# Image Registration + +There two alternative paths to automatically creating a tie-point +control network. + +1. **Autoseed Path** + - This path will distribute and establish tie-points based on + polygon overlaps of a collection of images. + - The image coordinates for each point are immediately measured + with the **autoseed** application. + - The **footprintinit** and **findimageoverlaps** are required by + **autoseed** +1. **Seedgrid Path** + - A gridded pattern of tie-points are established based on + specified latitude/longitude values and spacing. + - The image coordinates for each "seeded" point are measured with + the **cnetadd** application. + +## Creating a Tie-Point Control Network + +| autoseed Path | seedgrid Path | +| ----------------- | ------------- | +| spiceinit | spiceinit | +| footprintinit | | +| findimageoverlaps | seedgrid | +| autoseed | cnetadd | +| cnetref | cnetref | +| pointreg | pointreg | + +## Related ISIS3 Applications + +[**spiceinit**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/spiceinit/spiceinit.html) +[**footprintinit**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/footprintinit/footprintinit.html) +[**findimageoverlaps**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/findimageoverlaps/findimageoverlaps.html) +[**autoseed**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/autoseed/autoseed.html) +[**seedgrid**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/seedgrid/seedgrid.html) +[**cnetadd**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cnetadd/cnetadd.html) +[**cnetref**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/cnetref/cnetref.html) +[**pointreg**](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/pointreg/pointreg.html) diff --git a/docs/concepts/control-networks/multi-instrument-registration.md b/docs/concepts/control-networks/multi-instrument-registration.md new file mode 100644 index 0000000000000000000000000000000000000000..3c8dda3dc7e74b16ed48eaed7272cc8bf4ac9081 --- /dev/null +++ b/docs/concepts/control-networks/multi-instrument-registration.md @@ -0,0 +1,226 @@ + +# Multi-Instrument Registration + +## Reasons for merging datasets + +List of useful reasons: + + - Change detection + - Spatial / Spectral merges + - Understanding instrument calibration (optical distortion, + radiometric similarities) + - Multivariate statistical analysis + - Principal component analysis + - Etc., etc., etc. + +## Choosing the "truth" + +Datasets from different instruments often do not register using the raw, +native pointing. In order to merge these datasets, they must be brought +together by selecting one dataset as having the correct pointing or +“truth”. The pointing for the other datasets is then adjusted to match +the truth. + +Choosing the truth is dependent on the datasets being merged. First, the +data with the known best pointing could be chosen, such as the Mars +Global Surveyor’s MOLA. Or if simply merging HiRISE and CTX, HiRISE +pointing is considered to be more accurate than CTX pointing. + +The differing resolution of the datasets is something to keep in mind. +You will not want to attempt to register HiRISE directly to MOLA as the +difference in resolution is too large to find a common point. In +general, you will want to build up in resolution. + + +| Resolution: | Lowest | - | - | - | - | Highest | +| ---------- |:------:|:------:|:------:|:------:|:---:|:-------:| +| Dataset: | MOLA | MOC WA | Themis | MOC NA | CTX | HiRISE | + +Registering to MOLA can be difficult. Using a shaded relief version of +MOLA (program – **shade**), and running either +[map2map](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2map/map2map.html) +or +[map2cam](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2cam/map2cam.html) +to bring MOLA into the local ground area will help. + +| CTX | MOLA | +| ---------------------------------------------------------------------------- | -----------------------------------------------------------------------------| +| { width=200 } | { width=200 } | + +### Registration Tools + +[**deltack**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/deltack/deltack.html) + + - Updates camera pointing for a single image + - Tie one image to another + - THEMIS to MOLA, HiRISE to MOC NA, HiRISE to CTX, etc. + +[**jigsaw**](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/jigsaw/jigsaw.html) + + - Simultaneously updates camera pointing for multiple images + - Typically used for regional or global mosaics + +### Initial Datasets + +Start with Experiment Data Records (EDRs) if possible to ensure +consistency among the datasets for SPICE and mapping parameters such as +planetocentric vs planetographic and positive longitude east vs west. + +## Merging THEMIS / CTX / HiRISE (controlled to MOLA) + +### Controlling THEMIS to MOLA + +Start with the lowest resolution dataset, which in this case is THEMIS. +Pick a matching point between THEMIS and MOLA using qview. (Hint: It is +easier to use a crater as a match point.) +Write down the latitude / longitude of the point on MOLA and the sample +/ line of the point on the THEMIS image. Update the THEMIS pointing by +running the ISIS3 program `deltack`. + + deltack from=themis.cub lat1=molaLat lon1=molaLon samp1=themisSamp line1=themisLine + +This will update the themis pointing to the MOLA. + +### Controlling CTX to THEMIS + +Next, control the CTX image to the THEMIS image by picking a match point +the same as was done between the MOLA and THEMIS. Use the THEMIS image +that has the updated pointing (after +[deltack](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/deltack/deltack.html)). + + deltack from=ctx.cub lat1=themisLat lon1=themisLon samp1=ctxSamp line1=ctxLine + +### Controlling HiRISE to CTX + +{ align=right width=350 } + +[Image: CTX/HiRISE Misregistration. Errors: ~40 samples, ~20 lines] + +First, control the HiRISE red ccds locally by running the ISIS3 program, +[autoseed](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/autoseed/autoseed.html), +which will automatically pick match points among the red ccd’s. Then run the ISIS3 program, +[pointreg](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/pointreg/pointreg.html), +which will sub-pixel register the points that autoseed picked. + +Next, pick a matching point between HiRISE RED5 and the CTX image with +the updated pointing (after deltack). Record the CTX latitude / +longitude and the red5 sample / line. This will be used as a ground +point when running jigsaw on the red CCDs to adjust the pointing. +In order to use this point as a ground point, the radius is needed. Run +the ISIS3 program, +[campt](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/campt/campt.html) +to get this radius. + + campt from=ctx.cub lat=cxtLat lon=ctxLon type=ground + +This ground point can now be added to the control net file that was +output from pointreg using any editor. + + Object = ControlPoint + PointType = Ground + PointId = Ground_1 + Latitude = -5.3320739040534 + Longitude = 213.71209674872 + Radius = 3394090.9408245 + + Group = ControlMeasure + SerialNumber = MRO/HIRISE/RED5/848376111:51904/2 + MeasureType = Automatic + Sample = 1131.92 + Line = 18555.3 + ErrorLine = 0 + ErrorSample = 0 + ErrorMagnitude = 0 + DateTime = 2007-05-25T09:24:50 + ChooserName = "TLS" + GoodnessOfFit = 0 + Reference = True + End_Group + End_Object + +Finally, run +[jigsaw](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/jigsaw/jigsaw.html) +on the HiRISE red cubes. + +See Also: + + - controlled mosaics + - [jigsaw](https://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/jigsaw/jigsaw.html) + +| MOC Registered with HiRISE Red CCDs | MOC Registered with HiRISE Red CCDs (zoomed) | +| ------------------------------------------------------- | ---------------------------------------------------------------- | +|  |  | + +## Projecting all + +Project the THEMIS, CTX and HiRISE red images using the CTX resolution +and latitude/longitude range. + + cam2map from=ctx.cub to=ctx.equi.cub pixres=mpp resolution=5.0 + map=$base/templates/maps/equirectangular.map + + cam2map from=themis.cub to=themis.equi.cub map=ctx.equi.cub pixres=map defaultrange=map + + /bin/ls *RED* | sed s/.balance.cub// > red.lis + + cam2map from=\$1.balance.cub to=\$1.equi.cub map=ctx.equi.cub pixres=map defaultrange=map + -batch=res.lis + + /bin/ls *RED*.equi.cub > redEqui.lis + + automos fromlist=redEqui.lis mosaic=redMos.cub match=no + +More Information: [Learning About Map Projections](../camera-geometry-and-projections/learning-about-map-projections.md) + +## Problems and Issues + + - Registering to MOLA can be difficult: + + - Use shaded relief if possible ([shade](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/shade/shade.html)) + - Use + [map2cam](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2cam/map2cam.html) + or + [map2map](http://isis.astrogeology.usgs.gov/Application/presentation/Tabbed/map2map/map2map.html) + to bring MOLA image into local ground area to help with the + smaller MOLA image size + + - Simultaneous CTX and HiRISE observations do not register + + - Inconsistent sample/line offsets + - Probably have timing issues + - Maybe some boresight misalignment + - Will research this problem as more CTX data becomes available + + - MOC Narrow Angle does not align with HiRISE or CTX + + - Update the MOC NA focal length + - MOC NA camera model has no distortion model + - More research needed in this area + + - MRO CRISM + + - Unable to fully decipher the PDS IMAGE_PROJECTION_OBJECT + - No CRISM camera model in ISIS3 + - Unable to compare HiRISE, MOC, and THEMIS to CRISM + +## Images on this page + +[mola-low-res.png](../../assets/control-networks/mola-low-res.png) +(31.9 KB) Jesse Mapel, +2016-05-31 02:59 PM + +[ctx-high-res.png](../../assets/control-networks/ctx-high-res.png) +(243 KB) Jesse Mapel, +2016-05-31 02:59 PM + +[ctx-hirise-blink.gif](../../assets/control-networks/ctx-hirise-blink.gif) +(213 KB) Jesse Mapel, +2016-05-31 03:06 PM + +[moc-hirise-zoomedin-blink.gif](../../assets/control-networks/moc-hirise-zoomedin-blink.gif) +(118 KB) Jesse Mapel, +2016-05-31 03:12 PM + +[moc-hirise-blink.gif](../../assets/control-networks/moc-hirise-blink.gif) +(39.9 KB) Jesse Mapel, +2016-05-31 03:12 PM \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index b5a0a3337f2c9b7220dc85791fc394afa09c3565..e2af981b07b5c852e85925549f95503118ec1884 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,11 @@ nav: - 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 Radiometric Calibration: concepts/image-processing/overview-of-radiometric-calibration.md + - Control Networks: + - Automatic Registration: concepts/control-networks/automatic-registration.md + - Autoseed: concepts/control-networks/autoseed.md + - Image Registration: concepts/control-networks/image-registration.md + - Multi-Instrument Registration: concepts/control-networks/multi-instrument-registration.md - Manuals: manuals/index.md extra_css: