Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation

cnetref

Printer Friendly View | TOC | Home

The application cnetref finds the best reference for a Control Point based on criteria like Emission Angle or Incidence Angle or Resolution or Interest

Overview Parameters

Description

The application cnetref finds the best reference for a Control Point based on user specified Criteria.

Application takes in as input the Control Net CNET and its corresponding images list FROMLIST. FROMLIST contains the filenames of all the images that are part of the input Control Net.

The resulting output Control Net is placed in the user specified file ONET. The Id and Description for the output Control Net can be specified in NETWORKID and DESCRIPTION parameters respectively. If the values are not entered then the information is taken from the input Control Net.

Best Reference for the Control Point can be chosen based on the following four CRITERIAs. For all the criterias, picking the best Reference is skipped if the Control Point is not Free or if either the Control Point or the Reference is EditLocked.

1. EMISSION : Of all the valid Control Measures in a Control Point, the Control Measure with the least Emission Angle will be chosen as the Reference.

2. INCIDENCE: Of all the valid Control Measures in a Control Point, the Control Measure with the least Incidence Angle will be chosen as the Reference.

3. RESOLUTION: Of all the valid Control Measures in a Control Point, the Control Measure with the best Resolution TYPE will be chosen as the Reference. All the images in the Control Net must have the resolution in the same units.
The best Resolution can be chosen from the following TYPEs:
a. HIGH - The Control Measure with the Highest Resolution will be chosen as the Reference.
b. LOW - The Control Measure with the Least Resolution will be chosen as the Reference.
c. MEAN - The Mean Resolution is calculated from the Resolution all the images within each Control Point. The Control Measure closest to the Mean Resolution will be chosen as the Reference.
d. NEAREST - The Control Measure with the Resolution closest to this user specified value in RESVALUE will be chosen as the Reference.
e. RANGE - The first Control Measure in the MINRES - MAXRES Range will be chosen as the Reference.

4. INTEREST: Of all the valid Control Measures in a Control Point, the Control Measure with the best Interest will be chosen as the Reference. This option uses an interest operator to find the most interesting point in the area near each Control Point of a Control Net. The area is defined by the keywords DeltaLine and DeltaSample. The application starts by finding the best Interest for each valid Control Measure in a Control Point. Then the Control Measure with the best Interest among all the valid Control Measures in the Control Point is chosen as the Reference. After the new Reference is chosen, all the Control Measures are aligned to the new Reference's location. The movement of the Control Point can be limited to the Overlaps by enabling LIMIT and entering the list in OVERLAPLIST. The Overlaplist contains the Serial Number and their intersections. The intersections information can be got from the application findimageoverlaps. If an exact match of the Control Measure's Serial Number in the overlaplist fails then this option finds image overlaps by getting intersection of the individual image footprints. If the overlapslist is not specified, then the Point can be moved in the area defined by DeltaLine and DeltaSample.

The Interest operator reads in a chip of size Delta Samples and Lines from each Control Measure(Cube) in a point. If the Overlap list is included then the overlap polygon is taken into consideration when the chip reads the cube. For each pixel in the chip, it extracts a sub chip of box size (Samples, Lines) around the pixel. It first checks the pixel for validity as specified in the DEFFILE. If the pixel passes the above tests, then the Interest is calculated for the box around the pixel using the chosen algorithm. This way it calculates the interest for all the pixels in the chosen area (chip) around the Control Measure and the best Interest (highest value) is chosen among them. The best Interest is calculated for all the Control Measures in a Control Point.
The application then selects the best Interest of all the valid Control Measures in the Control Point and chooses it as the Reference. It then moves all the other valid Control Measures to the chosen Reference by mapping the Reference Lat/Lon to a sample, line in the Control Measure. It then creates a new Control Net using these new "more interesting" Control Points. If the BestReferenceIndex is not calculated because no Interest was calculated for all the Control Measures or if the BestReferenceIndex's Interest is invalid(less than the threshold Interest) then the Control Point is set to be ignored.

Interest Algorithm could be:
1. Standard Deviation
2. Gradient

The options for the Interest Operator is defined in PVL group in the DEFFILE. The DEFFILE should have the Operator Group relevant for the Interest Operator plugin. It defines the algorithm(Name) to be used to calculate the interest, the box size (Samples, Lines) and the distance (DeltaSamp, DeltaLine) the algorithm is allowed to move the point from the current position. It defines the minimum interest (MinimumInterest) value for the interest to be considered a best interest. If the point must be static then set the DeltaSamp and DeltaLine to zero.
All the keywords in the Operator Group are required for this Criteria.
Example:

Group = Operator
Name = StandardDeviation
Samples = Positive Integer
Lines = Positive Integer
DeltaLine = Positive Integer
DeltaSample = Positive Integer
MinimumInterest = Double
EndGroup

Note:
1.If Control Measures with no camera is encountered, then the application is halted and no ouput Control Net is generated.
2. The values Samples, Lines, DeltaLine, DeltaSamp, MinimumInterest for the Operator are entirely dependent on the images in the Control Net. Recommended preprocessing would be to run "gradient" filter or "svfilter" and run "hist" to get the image stats and set the values for the Operator accordingly.

For all the criterias except Interest, the application first validates each measure for the properties specified in the "ValidMeasure" PvlGroup in DEFFILE. The Validity test is optional for all the Criterias.

Validation is little different if using the Interest Critera. The Interest Operator while finding Interest for a Valid Control Measure, first Validates each Sample, Line location in the DeltaSample, DeltaLine area of the Control Measure and then calculates the Interest for that location. This way the expensive Interest calculation is bypassed for an invalid Sample, Line location. Validity test is also performed after moving the Control Measure to the new location of the BestReference chosen after the Interest operation for all the Control Measures in the Control Point. If the moved Control Measure fails the Validity test, then it is set to be Ignored.

Following is the format for the Pvl DEFFILE file with the defaults for Control Measure validation:

Group=ValidMeasure
MinDN = Default is Min DN value (depends on the pixel size of the image)
MaxDN = Default is Max DN value (depends on the pixel size of the image)
MinEmission = 0 (Default)
MaxEmission = 135 (Default)
MinIncidence = 0 (Default)
MaxIncidence = 135 (Default)
MinResolution = 0 (Default)
MaxResolution = Max Double
PixelsFromEdge = 0 (Default) OR
MetersFromEdge = 0 (Default)
EndGroup

If the Control Measure does not pass the validity test, then it will be be Ignored. If the number of Valid Control Measures in a Control Point is less than 2, then the Control Point is Ignored.

If the "Required" parameters are not entered or misspelled, then the application will throw an error. If "Optional" parameters are not entered then the Control Measure will not be validated against that option.

The entire Control Net processing can be logged in an output LOG file. Log information such as Control Point and Control Measure details and change statistics are placed in LOG file if specified in PVL. Following is the format of the Log File:

Object = PointDetails
PointId =

Group = MeasureDetails
SerialNum =
EmissionAngle =
IncidenceAngle =
Resolution=
DNValue =
SampleResidual =
LineResidual =
ResidualMagnitude=
SampleShift =
LineShift =
PixelShift =
Reference =
EndGroup

Group = MeasureDetails
SerialNum =
OriginalLocation =
EmissionAngle =
IncidenceAngle =
Resolution =
DNValue =
SampleResidual =
LineResidual =
ResidualMagnitude =
SampleShift =
LineShift =
PixelShift =
EndGroup

Group = ReferenceChangeDetails
PrevSerialNumber =
PrevIncAngle =
PrevLocation =
NewSerialNumber =
NewLeastIncAngle =
NewLocation =
EndGroup

EndObject

Categories

History

Stuart Sides2005-08-20 Original version
Steven Koechle2008-09-25 Tweaked to compile and run with current version of Isis
Steven Lambright2008-11-04 Added support for image overlap files, new optional parameter "OVERLAPLIST"
Steven Lambright2008-11-14 "OVERLAPLIST" is now a required parameter.
Steven Koechle2009-01-20 Fixed Memory Leaks, Changed Deletion of cubes to use an iterator
Steven Koechle2009-04-24 If a control measure fails SetUniversalGround it is now ignored.
Travis Addair2009-08-11 Interest operator parameters are now placed into the print file.
Sharmila Prasad2010-03-30 Added Emission Angle criteria in the interest operator plugin for the best interest point to be considered. Also Check that the best interest point has DN value in the Valid Min and Max DN range.
Sharmila Prasad2010-04-20 Logging and documentation-specify output log file for the results to be sent to else printed to print.prt. If images with no camera is encountered, the application is closed.
Sharmila Prasad2010-05-04 Make the overlap list optional incase a control network has no overlap list. Added a checkbox to indicate whether the overlap list is available or not and modified the app accordingly
Sharmila Prasad2010-05-10 Renamed to cnetref
Sharmila Prasad2010-05-11 Calculate interest for Control Points with no Reference point and Control Points with Measures less than 2. Include Min and Max Incidence Angle filter and make parameters NETWORKID and DESCRIPTION optional..
Steven Lambright2010-05-27 Using an overlap list should be much more accurate and restrictive now. Added MINRES and MAXRES parameters. Fixed potential segmentation fault. Restored program's history.
Sharmila Prasad2010-06-10 Find reference based on Emission, Incidence angles or interest or Resolution. Added new parameters to accomodate the new options
Sharmila Prasad2010-06-11 Added documentation and tests
Sharmila Prasad2010-06-18 Added documentation, display error for Interest option with no DefFile.
Sharmila Prasad2010-06-18 Use Standard Options Pixels/Meters from Edge
Sharmila Prasad2010-10-06 Made changes for binary control net
Sharmila Prasad2010-10-15 Use single copy of Control Net
Sharmila Prasad2010-10-18 Input DefFile Validation before any processing
Sharmila Prasad2010-10-22 Reset apriori for source==Reference
Sharmila Prasad2010-10-27 Log, if Reference changed and apriorisource==Reference
Sharmila Prasad2010-11-09 Update documentation regarding Template DefFile
Sharmila Prasad2010-12-29 Updated for binary control net and fixed the app tests accordingly
Christopher Austin2011-01-19 Altered to compile with the new Control redesign.
Sharmila Prasad2011-02-24 Fixed the app tests
Sharmila Prasad2011-05-14 Added ability to validate Measure by Sample/Line Residuals and Residual Magnitude
Sharmila Prasad2011-05-24 Helper function to edit DefFile
Debbie A. Cook and Tracie Sucharski2011-06-07 Changed point types "Ground" to "Fixed" and "Tie" to "Free"
Sharmila Prasad2011-07-29 Improved the Log messages
Sharmila Prasad2011-08-03 Fixed the statistics
Sharmila Prasad, Bonnie Redding, Mark Rosiek2011-10-06 Updated the documentation and added missing tests for criteria resolution
Sharmila Prasad2011-11-23 Updated the documentation. Edited to work for control nets with Reference not set. Fixes #589 and #584
Debbie A. Cook2013-02-11 Changed selection of reference by mean resolution to use the first measure for points with only 2 measures. References #775.
Kimberly Oyama and Steven Lambright2013-02-25 Changed error handling such that, when an error occurs, this program will not choose that measure as reference instead of throwing an error and stopping. References #825.

Parameter Groups

Files

Name Description
FROMLIST List of Input cubes in the Control Net
CNET Input Control Net
ONET Output Control Net
LOGOptional output log file

Information

Name Description
NETWORKID Output Control Net ID
DESCRIPTION The description of the Output Control Net.

Reference

Name Description
CRITERIACriteria in choosing the best Reference in a Control Point
DEFFILE PVL file containing the options for which a Control Measure has to be validated and/or operator plugin if Interest criteria is chosen.

Interest

Name Description
LIMIT Limit the movement of all Control Measures to be within their overlaps
OVERLAPLISTThis is the list of image overlaps corresponding to this Control Net

Resolution

Name Description
TYPEChoose the Resolution type
RESVALUEResolution Number
MINRESMinimum Image Resolution
MAXRESMaximum Image Resolution
X

Files: FROMLIST

Description

This file contains all the the cube filenames which are associated with the input Control Net.

Type filename
File Mode input
Filter *.lis
Close Window
X

Files: CNET

Description

This file must contain Control Net with valid Control Points and Control Measures

Type filename
File Mode input
Filter *.net
Close Window
X

Files: ONET

Description

This file will contain the new adjusted Control Net

Type filename
File Mode output
Close Window
X

Files: LOG

Description

This file stores log information such as Control Point and Control Measure details and change statistics in PVL.

Type filename
File Mode output
Internal Default None
Filter *.*
Close Window
X

Information: NETWORKID

Description

The ID or name of the output Control Net. This string should be unique. If not specified, the ID is taken from the input Control Net.

Type string
Internal Default None
Close Window
X

Information: DESCRIPTION

Description

A string describing purpose of this Output Control Net. If not specified, the ID is taken from the input Control Net.

Type string
Internal Default None
Close Window
X

Reference: CRITERIA

Description

This parameter lets the user choose one of the four ways to choose the best Reference in a Control Point.

Type string
Default EMISSION
Option List:
Option Brief Description
EMISSIONReference is chosen based on the Best Emission Angle This option chooses a valid Control Measure with the least Emission Angle (closer to zero) among all the other Control Measures in a Control Point as the best Reference.

Exclusions

  • LIMIT
  • OVERLAPLIST
  • TYPE
  • RESVALUE
  • MINRES
  • MAXRES
INCIDENCEReference is chosen based on the Best Incidence Angle This option chooses a valid Control Measure with the least Incidence Angle (closer to zero) among all the other Control Measures in a Control Point as the best Reference.

Exclusions

  • LIMIT
  • OVERLAPLIST
  • TYPE
  • RESVALUE
  • MINRES
  • MAXRES
INTERESTReference is chosen based on the Best Interest This option finds the most interesting area near each Control Point of a Control Net depending on the best Interest. The Control Measure with the best Interest (highest value) among all other Control Measures in a Control Point will be chosen as the Reference. Interest is calculated by an interest algorithm Standard Deviation or Gradient.

Exclusions

  • TYPE
  • RESVALUE
  • MINRES
  • MAXRES
RESOLUTION Reference is chosen based on the Resolution This option chooses the Reference based on the Control Measure's Resolution. There are different ways as to how the Resolution will be chosen as the best value.

Exclusions

  • LIMIT
  • OVERLAPLIST

Inclusions

  • TYPE
Close Window
X

Reference: DEFFILE

Description

PVL file containing the options for which a Control Measure has to be validated and/or operator plugin if Interest criteria is chosen. Refer to documentation for DEFFILE format.

Type filename
File Mode input
Internal Default None
Filter *
Close Window
X

Interest: LIMIT

Description

Limit the movement of all Control Measures to be within their overlaps. The application makes sure that when enabled, even if the point moves it will be within the defined overlap area. Uncheck LIMIT if there is no overlap list for example Control Net from seedgrid application or if it is ok if the point moves beyond the overlap area.

Type boolean
Internal Default false
Inclusions
  • OVERLAPLIST
Close Window
X

Interest: OVERLAPLIST

Description

Use this parameter to select the filename which contains the overlap list. You can obtain this file by running the application "findimageoverlaps."

Type filename
File Mode input
Internal Default None
Filter *
Close Window
X

Resolution: TYPE

Description

This parameter lets the user choose the different Resolution choices available

Type string
Default HIGH
Option List:
Option Brief Description
HIGHReference is chosen based on Highest Resolution This option chooses a valid Control Measure with the highest Resolution

Exclusions

  • RESVALUE
  • MINRES
  • MAXRES
LOWReference is chosen based on Least Resolution This option chooses a valid Control Measure with the lowest Resolution

Exclusions

  • RESVALUE
  • MINRES
  • MAXRES
MEANReference is chosen based on Mean of all the Resolutions This option first calculates the Mean of the Resolution of all the Control Measures in a Control Point and then chooses the Control Measure with the Resolution closest to the Mean on the higher Resolution side as Control Point Reference.

Exclusions

  • RESVALUE
  • MINRES
  • MAXRES
NEARESTReference is chosen based on Nearness to RESVALUE This option chooses the Control Measure whose Resolution is closest to the user specified value in RESVALUE as Control Point Reference.

Exclusions

  • MINRES
  • MAXRES
RANGEReference is chosen if within MINRES, MAXRES Range This option chooses the first Control Measure whose Resolution is within the specified Resolution Range MINRES, MAXRES as Control Point Reference.

Exclusions

  • RESVALUE
Close Window
X

Resolution: RESVALUE

Description

This parameter is associated with the parameter NEAREST and holds the Resolution value. The Control Measure closest to this value is chosen as the Control Point Reference.

Type double
Internal Default 0
Close Window
X

Resolution: MINRES

Description

This parameter is associated with parameters RANGE and MAXRES and represents the Minimum Resolution for a Control Measure to be considered to be a Control Point Reference.

Type double
Internal Default 0
Close Window
X

Resolution: MAXRES

Description

This parameter is associated with parameters RANGE and MINRES and represents the Maximum Resolution for a Control Measure to be considered to be a Control Point Reference.

Type double
Internal Default 0
Close Window