Fix findfeatures matrix inversion issues and improve FastGeom performance

CHANGELOG.md

@@ -34,6 +34,19 @@ release.
 -->
 
 ## [Unreleased]
+- Bug fixes and improvements have been made to <i>findfeatures</i>.
+  - Fix matrix inversion errors due to bad FASTGEOM matrix transforms using a more robust implementation to detect these errors and throw exceptions. Images with these errors are captured and logged to the <b>TONOTMATCHED</b> file. Fixes [#4639](https://github.com/DOI-USGS/ISIS3/issues/4639)
+  - Fixed use of projected mosaics with correct check for <b>TargetName</b> in the Mapping labels.
+  - Add new program optiom <b>TONOGEOM</b> that logs captures geometry errors in the FASTGEOM algorithm and records them to the file provided in this parameter. These images are excluded from the matching process. References [#4772](https://github.com/DOI-USGS/ISIS3/issues/4772)
+  - Added a new Radial FASTGEOM transform mapping algorithm to address performance problems with the Grid algorithm. This is now the default algorithm none are selected by the user (see the new <b>GLOBALS</b> parameter to specify the algorithm)
+  - Added new parameter <b>GLOBALS</b> to make parameterization of <i>findfeatures</i> behavior significantly easier and convenient. Wrote significant documentation for the parameter and provide several examples showing its use.
+  - Significantly refactored FASTGEOM processing to accomodate stabilility and functionality. The scope of the algorithm was taken out of the ImageSource class and isolated to support this feature.
+  - Added new gtests for <i>findfeatures</i> that replaces all the old application tests. These tests are <i>FunctionalTestFindfeaturesFastGeomDefault</i>, <i>FunctionalTestFindfeaturesFastGeomRadialConfig</i>, <i>FunctionalTestFindfeaturesFastGeomGridDefault</i> and <i>FunctionalTestFindfeaturesFastGeomGridConfig</i>.
+  - Fixed a bug in the <i>cnetwinnow</i> test that did not clean/remove it during test runs.
+  - Added new option <b>GEOMSOURCE=BOTH</b> to check both the MATCH and FROM/FROMLIST images for valid control measure geometry to produce better networks and prevent downstream processing errors. Ignore points that end up with no valid measures (but can retained with use of <b>PreserveIgnoredControl</b> via GLOBALS parameterization).
+  - Report better information regarding the behavior of <i>findfeatures</i>, FASTGEOM algorithms, and creation of the output network.
+  - Added two new examples demonstrating/documenting the use of FASTGEOM algorithm, parameterization using <b>GLOBALS</b> and how to produce a regional mosaic using <i>findfeatures</i> with batch scripts.
+
 
 ### Changed
 - Removed the `.py` extention from the _isisdataeval_ tool `isisdata_mockup` for consistency and install it in $ISISROOT/bin; added the `--tojson` and `--hasher` option to _isisdata_mockup_ tool improve utility; updated the tool `README.md` documentation to reflect this change, removed help output and trimmed example results;  fixed paths to test data in `make_isisdata_mockup.sh`. [#5163](https://github.com/DOI-USGS/ISIS3/pull/5163)

isis/CMakeLists.txt

@@ -441,6 +441,7 @@ file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/appdata/translations
                     ${CMAKE_BINARY_DIR}/appdata/templates/hidtmgen
                     ${CMAKE_BINARY_DIR}/appdata/import
                     ${CMAKE_BINARY_DIR}/appdata/templates/findfeatures
+                    ${CMAKE_BINARY_DIR}/appdata/templates/findfeatures/mosaics
                     ${CMAKE_BINARY_DIR}/appdata/templates/fullcnetdiff
                     ${CMAKE_BINARY_DIR}/appdata/templates/jigsaw
                     ${CMAKE_BINARY_DIR}/appdata/templates/kernels
@@ -524,7 +525,8 @@ add_custom_target(controlnetworks ALL COMMAND ${CMAKE_COMMAND} -E copy_if_differ
 add_dependencies(isis controlnetworks)
 
 add_custom_target(findfeatures ALL COMMAND ${CMAKE_COMMAND} -E copy_if_different
-  ${CMAKE_SOURCE_DIR}/appdata/templates/findfeatures/* ${CMAKE_BINARY_DIR}/appdata/templates/findfeatures/)
+  ${CMAKE_SOURCE_DIR}/appdata/templates/findfeatures/* ${CMAKE_BINARY_DIR}/appdata/templates/findfeatures/
+  ${CMAKE_SOURCE_DIR}/appdata/templates/findfeatures/mosaics/* ${CMAKE_BINARY_DIR}/appdata/templates/findfeatures/mosaics/)
 add_dependencies(isis findfeatures)
 
 add_custom_target(fullcnetdiff ALL COMMAND ${CMAKE_COMMAND} -E copy_if_different

isis/appdata/templates/findfeatures/findfeatures_fastgeom_defaults.pvl

@@ -0,0 +1,40 @@
+Group = FastGeomCommonParameters
+  # Defaults used for findfeatures FastGeom Algorithms
+
+  # FastGeomAlgorithm           = radial
+  FastGeomPoints               = 25
+  FastGeomTolerance            = 3
+  # GeomType                    = camera
+
+  FastGeomQuerySampleTolerance = 0
+  FastGeomQueryLineTolerance   = 0
+  FastGeomTrainSampleTolerance = 0
+  FastGeomTrainLineTolerance   = 0
+
+  FastGeomDumpMapping = false
+EndGroup = FastGeomCommonParameters
+
+
+Group = FastGeomGridParameters
+  # FastGeomAlgorithm            =  grid
+
+  FastGeomGridStartIteration   = 0
+  # FastGeomGridStopIteration    = 1 to N
+  FastGeomGridIterationStep    = 1
+
+  FastGeomTotalGridIterations  = 1
+
+  FastGeomGridSaveAllPoints    = false
+EndGroup = FastGeomGridParameters
+
+
+Group = FastGeomRadialParameters
+  # FastGeomAlgorithm           = radial
+
+  FastGeomRadialSegmentLength  = 25
+  FastGeomRadialPointCount     = 5
+  FastGeomRadialPointFactor    = 1.0
+
+  # FastGeomRadialSegments       = N
+EndGroup = FastGeomRadialParameters
+End

isis/appdata/templates/findfeatures/mosaics/00_basic_proc.sh

@@ -0,0 +1,188 @@
+#!/bin/bash
+#set -o pipefail
+###############################################################################
+#
+# Applies basic ISIS processing for control preparation
+#
+# Prerequisites:
+#   ISIS3        - must have an appropriate version of system initilized
+#
+# Defaults;
+#   Current directory set to processing root dir
+#
+# @author  2021-03-02 Kris Becker Original Version
+###############################################################################
+usage() { echo "Usage: $0 [-0 {invokes dryrun}] [-h] [-v]  \
+[-S {do not run spiceinit}] [-l] [-p] [-e {error list}] \
+ *.IMG | *.cub  \
+" 1>&2; exit 1; }
+
+dryrun=0
+verbose=0
+
+run_spice=1   # run spiceinit by default, disable with -S
+pwddir='$PWD'
+lev0dir='$PWD/Lev0'
+lev1dir='$PWD/Lev1'
+lev2dir='$PWD/Lev2'
+prtfile=""
+errlist=""
+
+##################################################################
+#  finesse_isis_command - Adds additional components to ISIS commmand
+#
+#  This function will add logging and preference files to an ISIS
+#  command that will be executed within this script.
+#
+# Should be called as:
+#    newcmd=$(finesse_isis_command "cmd")
+#
+# @author Kris Becker 2018-05-23
+##################################################################
+function finesse_isis_command() {
+command="$1"
+
+# Check for logging
+logger=""
+if [ -n "${prtfile}" ]; then
+  logger="-log=${prtfile}"
+else
+  logger="-log=/dev/null"
+fi
+
+echo "${command} ${logger}"
+}
+
+##################################################################
+#  execute - Executes a command as a subshell
+#
+#  This function will execute a command to the users shell and
+#  return status. If the variable $dryurn is set, it will only
+#  print out the command and not execute
+#
+# @author Kris Becker 2018-05-23
+##################################################################
+function execute() {  # (command)
+  command="$1"
+  echo "$command"
+  if [ $dryrun -eq 1 ]; then
+    status=0
+  else
+    eval $command
+    status=$?
+  fi
+  return $status
+}
+
+###################################################################
+# MAIN script section
+# Accumulate the parameters
+###################################################################
+while getopts ":0hvSlpe:" o; do
+    case "${o}" in
+        0)
+            dryrun=1
+            verbose=1
+            ;;
+        h)
+            usage
+            ;;
+        v)
+            verbose=1
+            ;;
+        S)
+            run_spice=0
+            ;;
+        l)
+            maklog=1
+            ;;
+        p)
+            prtfile="print.prt"
+            ;;
+        e)
+            errlist="${OPTARG}"
+            ;;
+        *)
+            usage
+            ;;
+    esac
+done
+shift $((OPTIND-1))
+
+declare -a fromfiles=( "$@" )
+
+# Check to see if the input file list exists
+# I. Variable definition
+if [ ${#fromfiles[@]} -le 0 ]; then
+  echo ""
+  echo "ERROR: No files provided!"
+  usage
+  exit 1
+fi
+
+
+###############################################################################
+#  Main processing loop. Process all give files checking for errors along
+#  the way.
+###############################################################################
+
+for from in "${fromfiles[@]}"; do
+
+    ifile="${from##*/}"
+    base="${ifile%%.*}"
+    ext="${ifile#*.}"
+
+    (
+
+# If given a cube, it is assumed import and radiometric calibration has
+# been applied
+      edrfile="${from}"
+      lev0file="${from}"
+      lev1file="${from}"
+
+# Level0 DATA IMPORT processing
+# Run import and apply radiometric calibrated images
+      if [ "${ext}" != "cub" ]; then
+        execute "mkdir -p ${lev0dir}"
+        lev0file="${lev0dir}/${base}.cub"
+        cmd="mdis2isis from=${from} to=${lev0file}"
+        execute "$(finesse_isis_command "$cmd")" ||  exit $?
+      fi
+
+# Apply a prior SPICE kernels
+      if [[ $run_spice -eq 1 ]]; then
+        cmd="spiceinit from=${lev0file}"
+        execute "$(finesse_isis_command "$cmd")" || exit $?
+      fi
+
+# Level1 - radiometric calibration processing
+      if [ "${ext}" != "cub" ]; then
+        execute "mkdir -p ${lev1dir}"
+        lev1file="${lev1dir}/${base}.cal.cub"
+        cmd="mdiscal from=${lev0file} to=${lev1file}"
+        execute "$(finesse_isis_command "$cmd")" || exit $?
+      fi
+
+# Know Your Data!
+      cmd="camstats from=${lev1file} attach=true linc=10 sinc=10"
+      execute "$(finesse_isis_command "$cmd")" || exit $?
+
+      cmd="footprintinit from=${lev1file} linc=10 sinc=10 maxemission=89 maxincidence=89 increaseprecision=true"
+      execute "$(finesse_isis_command "$cmd")" || exit $?
+
+    )
+
+    # Subshell exist status and testing
+    err=$?
+    if [ $err != 0 ]; then
+    #  If errlist file given, append this file to the list
+      if [ -n "$errlist" ]; then
+        [ -f "$errlist" ] || execute "touch $errlist"
+        execute "echo ${from} >> $errlist"
+      fi
+      echo "Error encountered with file ${from}"
+    fi
+done
+
+exit 0
+

isis/appdata/templates/findfeatures/mosaics/clean_restart.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+/bin/rm -f *.lis *.cub *.net *.png *_Island.* *.csv *.txt *.log print.prt
+/bin/rm -rf ./Lev0 ./Lev1 ./Lev2 ./Phot ./Updated_Lev1
+
+exit 0

isis/appdata/templates/findfeatures/mosaics/equi_clon180_PosEast_200m.map

@@ -0,0 +1,12 @@
+Group = Mapping
+ ProjectionName = Equirectangular
+ TargetName = Mercury
+ EquatorialRadius  = 2440000.0
+ PolarRadius = 2440000.0
+ CenterLatitude  = 0.0
+ CenterLongitude = 180.0
+ LatitudeType = Planetocentric
+ LongitudeDirection = PositiveEast
+ LongitudeDomain = 360
+ PixelResolution = 200
+End_Group

isis/appdata/templates/findfeatures/mosaics/fetch_edrs.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2008_014/EN0108828436M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2008_014/EN0108828483M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2008_014/EN0108828488M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_179/EN0217733143M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_179/EN0217733334M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_183/EN0218118182M.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_154/EW0215590428G.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_183/EW0218075871G.IMG
+wget -P . https://pds-imaging.jpl.nasa.gov/data/messenger/MDIS/MDIS/msgrmds_1001/DATA/2011_183/EW0218118239G.IMG
+
+exit 0

isis/appdata/templates/findfeatures/mosaics/pointreg_P31x31_S51x51.def

@@ -0,0 +1,23 @@
+Object = AutoRegistration
+  Group = Algorithm
+    Name            = MaximumCorrelation
+    Tolerance       = 0.9
+  End_Group
+
+  Group = PatternChip
+    Samples       = 31
+    Lines         = 31
+  End_Group
+
+  Group = SearchChip
+    Samples = 51
+    Lines   = 51
+  End_Group
+
+  Group = SurfaceModel
+    DistanceTolerance = 1.5
+    WindowSize        = 7
+  End_Group
+End_Object
+End
+