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


cnetextract

Standard View | TOC | Home

Extracts portions of an existing Control Network

Description
Categories
Groups
Examples
History


Description

Extracts Control Points into a new Control Network from a specified Control Network in accordance to specified filters.

Currently, the filters are divided into four categories: Exclusive Filters, Inclusive Filters, Cube Filters, and Lat/Lon Filters.

Exclusive Filters prevent extraction. They are taken into consideration last and have the highest priority. This means that if any other filter creates a selected Exclusive Filter condition during processing, that Exclusive Filter will prevent the extraction. For example, if the Cube Filters CUBES, CUBELIST, and CUBEMEASURES are used along with the Exclusive Filter NOSINGLEMEASURES, then an input Control Point which contains only one cube in the CUBELIST will not be extracted, regardless of the number of Control Measures it had on input. This is because NOSINGLEMEASURES will see it as a Control Point with exactly one Control Measure and prevent its extraction. If only Exclusive Filters are used, all Control Points/Measures that do not have an exclusive property will be extracted.

Inclusive Filters allow extraction. They only extract Control Points and/or Measures that are included in the Inclusive Filter. In addition, each Inclusive Filter is associated with an explicit property of the Control Point/Measure. If more than one Inclusive Filter is selected, only Control Points/Measures that contain all inclusive properties will be extracted.

Cube Filters also allow extraction, however, they pertain to the cubes contained within the Control Points/Measures. Option RETAIN_REFERENCE will extract the Reference even if not in the Cube List.

Lat/Lon Filters allow extraction as well, however, they only extract Control Points/Measures that lie in the lat/lon bounding box.

A summary of the Control Points not extracted, listed by the filter which prevented them from being extracted, can be included in optional report files. See the PREFIX and filter keywords for more details. The following table lists the output file names, the corresponding filter for the output file, and a description of the contents of the output file. These output files will only be generated if PREFIX has been defined.

OutputReport Filter Reason for not extracting the points/measures in this report
[PREFIX]IgnoredPoints.txt NOIGNORE These points are set to ignored.
[PREFIX]IgnoredMeasures.txt NOIGNORE These measures are set to ignored. Ignored reference measures are always extracted, however they are still listed in this report with the note: Ignored measure but extracted since it is Reference.
[PREFIX]SingleMeasurePoints.txt NOSINGLEMEASURES These points have only one measure.
[PREFIX]MeasurelessPoints.txt NOMEASURELESS and REFERENCE These points have no measures.
[PREFIX]NonReferenceMeasures.txt REFERENCE These measures are not reference measures.
[PREFIX]NonFixedPoints.txt FIXED These points are not fixed.
[PREFIX]NonConstrainedPoints.txt CONSTRAINED These points are not constrained.
[PREFIX]NonEditLockedPoints.txt EDITLOCKED These points are not editlocked.
[PREFIX]TolerancePoints.txt TOLERANCE These points have line and/or sample less than the given PIXELTOLERANCE.
[PREFIX]NonListedPoints.txt POINTSLIST These points are not in the given POINTLIST.
[PREFIX]NonCubePoints.txt CUBES These points have no measures corresponding to the given CUBELIST.
[PREFIX]NonCubeMeasures.txt CUBES, CUBEMEASURES, and RETAIN_REFERENCE These are measures for extracted points that do not correspond to cubes in the given CUBELIST. If RETAIN_REFERENCE is true, all reference measures for extracted points will be extracted, however any reference measure that does not correspond to cubes in the cubelist will still be listed in this report with the note: Reference not in the cubelist but extracted since RETAIN_REFERENCE=true.
[PREFIX]LatLonOutOfRange.txt LATLON These points have a latitude and/or longitude that is not in the given MINLAT/MAXLAT or MINLON/MAXLON range.
[PREFIX]NoLatLonPoints.txt LATLON These points do not have a determineable latitude and/or longitude value.


Categories


Parameter Groups

Input Files

Name Description
FROMLIST List of ISIS cubes in the input Control Network
CNET Input Control Network filename

Output

Name Description
PREFIX A string used to enable output of optional report file(s) of excluded information
TOLIST List of ISIS cubes in the output Control Network file
ONET Output Control Network filename
NETWORKID Set Networkid keyword to this value in the extracted Control Network
DESCRIPTION Set Description keyword to this value in the extracted Control Network.

Exclusive Filters

Name Description
NOIGNORE Do not extract ignored Control Points and non-referernce ignored Control Measures
NOMEASURELESS Do not extract Control Points with exactly zero Control Measures
NOSINGLEMEASURES Do not extract Control Points with exactly one Control Measure

Inclusive Filters

Name Description
REFERENCE Only extract reference Control Measures
FIXED Only extract fixed Control Points
CONSTRAINED Only extract constrained Control Points
EDITLOCKED Only extract editlocked Control Points
TOLERANCE Only extract Control Points with line or sample residual greater than PIXELTOLERANCE
PIXELTOLERANCE Only extract Control Points with a line or sample residual greater than this value
POINTLIST File containing Control Point Ids which will be extracted

Cube Filters

Name Description
CUBES Enable extraction of Control Points/Measures based on listed cubes
CUBELIST Only extract Control Points containing the listed cubes
CUBEMEASURES Only extract Control Measures containing a cube in CUBELIST
RETAIN_REFERENCE Retain Reference even if not in the CUBELIST

Lat/Lon Filters

Name Description
LATLON Only extract Control Points in the lat/lon range
MINLAT Minimum Control Point Latitude
MAXLAT Maximum Control Point Latitude
MINLON Minimum Control Point Longitude
MAXLON Maximum Control Point Longitude

Input Files: FROMLIST

Description

A text file containing one column of ISIS cube file names. Every cube used in the input control network should be contained in this list.

Type filename
File Mode input
Internal Default No input cube list
Filter *.txt *.lis *.list

Input Files: CNET

Description

A filename containing control network points and measures to extract the ONET from.

Type filename
File Mode input
Filter *.net

Output: PREFIX

Description

A short single word string used as a prefix on output report file(s) generated based on extraction criteria entered by the user. If a PREFIX is provided, the Control Points and Control Measures not extracted will be placed into output report files with the given PREFIX. If a PREFIX is not entered, no report files will be output. See each option in the "Filter" groups to see which report files are created for each given filter.

Type string
File Mode output
Internal Default Prefix of NO results reports

Output: TOLIST

Description

This optional output text file contains one column of ISIS cube file names associated with the ONET. This list can only include cubes that were provided in the FROMLIST.

Type filename
File Mode output
Internal Default No output cube list
Filter *.txt *.lis *.list

Output: ONET

Description

The resultant Control Network file extracted from CNET.

Type filename
File Mode output
Filter *.net

Output: NETWORKID

Description

The Networkid keyword of the extracted Control Network will be set to this string value. The Networkid is a single word identifier or name assigned to a Control Network. This string should be unique.

Type string
Internal Default Parent Network Id

Output: DESCRIPTION

Description

The Description keyword of the extracted Control Network will be set to this string value. This should be a brief description of the purpose of the extracted control network.

Type string
Default cnetextracted

Exclusive Filters: NOIGNORE

Description

When selected, no ignored Control Points in the input Control Net will be included in the output Control Network. Furthermore, any ignored Control Measures that are not reference measures will also be excluded from the output Control Network.

When option PREFIX is used, two report files will be created, [PREFIX]IgnoredPoints.txt and [PREFIX]IgnoredMeasures.txt. These files list all Control Points and Control Measures from the input Control Network that were not extracted due to this filter. **Note** The [PREFIX]IgnoredMeasures.txt will include ignored control measures that are reference measures even though they will be extracted.

Type boolean
Default False

Exclusive Filters: NOMEASURELESS

Description

When selected, all Control Points that are reduced to zero Control Measures (from other selected filters or have zero measures on input) will not be included in the output Control Network.

When option PREFIX is used, report file [PREFIX]MeasurelessPoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False

Exclusive Filters: NOSINGLEMEASURES

Description

When selected, all Control Points that are reduced to one Control Measure (from other selected filters or only have one measure on input) will not be included in the output Control Network.

When option PREFIX is used, report file [PREFIX]SingleMeasurePoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False
Exclusions
  • REFERENCE

Inclusive Filters: REFERENCE

Description

When selected, only reference Control Measures will be extracted into the output Control Network.

When this filter is used, NOMEASURELESS will be selected automatically, and NOSINGLEMEASURES will be disabled.

When option PREFIX is used, report files with the names [PREFIX]NonReferenceMeasures.txt and [PREFIX]MeasurelessPoints.txt will also be created. The first file will contain each Control Measure that was not extracted due to this filter and the latter will list all measurless points not extracted due to this filter.

Type boolean
Default False
Exclusions
  • NOSINGLEMEASURES

Inclusive Filters: FIXED

Description

When selected, only fixed Control Points will be extracted into the output Control Network file.

When option PREFIX is used, report file [PREFIX]NonFixedPoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False

Inclusive Filters: CONSTRAINED

Description

When selected, only constrained Control Points will be extracted into the output Control Network file.

When option PREFIX is used, report file [PREFIX]NonConstrainedPoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False

Inclusive Filters: EDITLOCKED

Description

When selected, only editlocked Control Points will be extracted into the output Control Network file.

When option PREFIX is used, report file [PREFIX]NonEditLockedPoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False

Inclusive Filters: TOLERANCE

Description

When selected, extract all Control Points which have a line or a sample residual greater than or equal to the PIXELTOLERANCE value.

The PIXELTOLERANCE is compared to the keywords LineResidual and SampleResidual in the input Control Network.

When option PREFIX is used, report file [PREFIX]TolerancePoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type boolean
Default False
Inclusions
  • PIXELTOLERANCE

Inclusive Filters: PIXELTOLERANCE

Description

Control Points which contain at least one Control Measure with a line or a sample residual error greater than or equal to this value will be extracted.

Type double
Default 10.0

Inclusive Filters: POINTLIST

Description

Use this parameter to select a text file that contains a list of Control Point Ids. All the Control Points with matching Ids will be extracted as long as another selected filter does not exclude the Control Point.

When option PREFIX is used, report file [PREFIX]NonListedPoints.txt will also be created. Each Control Point it contains was not extracted due to this filter.

Type filename
File Mode input
Internal Default None
Filter *.lis

Cube Filters: CUBES

Description

When selected, only Control Points which contain the cubes listed in CUBELIST will be extracted.

Type boolean
Default False
Inclusions
  • CUBELIST
  • CUBEMEASURES

Cube Filters: CUBELIST

Description

Use this parameter to select a text file that contains a list of ISIS cubes. All the Control Points which contain at least one of these cubes will be extracted.

When option PREFIX is used, report file [PREFIX]NonCubePoints.txt will also be created. Each Control Point it lists was not extracted due to this filter.

Type filename
File Mode input
Filter *.lis

Cube Filters: CUBEMEASURES

Description

When selected, extract all Control Measures from extracted Control Points that contain a cube in the CUBELIST list. This option can only be used when a file has been provided for CUBELIST.

When this filter is used, NOMEASURELESS will be selected automatically.

When option PREFIX is used with this filter, the report file [PREFIX]NonCubeMeasures.txt will also be created. Each Control Measure it lists was not extracted due to this filter.

Type boolean
Default False
Inclusions
  • RETAIN_REFERENCE

Cube Filters: RETAIN_REFERENCE

Description

When selected, retain the Reference in the extracted Control Points even if it is not in the the CUBELIST list.

When this filter is used, NOMEASURELESS will be selected automatically.

When option PREFIX is used with the CUBEMEASURES filter, the report file [PREFIX]NonCubeMeasures.txt will also be created. This file will list the measures that are not extracted. This will include non-reference measures that do not correspond to the cubelist. When RETAIN_REFERENCE is true, reference measures will be listed in this file, even though they will be extracted.

Type boolean
Default False

Lat/Lon Filters: LATLON

Description

When selected, all Control Points that are inside of the provided latitude and longitude ranges will be extracted. Control Points whose latitude and/or longitude cannot be computed will not be extracted.

Fixed Points will use the lat/lon values provided in the input control network, while Free Points will calculate the lat/lon from the images provided by the FROMLIST. These calculated lat/lon values will be added to Free Points in the output control network for reference purposes. However, no Isis application will use these lat/lons that are added to Free Points.

When option PREFIX is used, report files [PREFIX]LatLonOutOfRange.txt and [PREFIX]NoLatLonPoint.txt will also be created. Each Control Point they list was not extracted due to this filter.

Control Points in [PREFIX]LatLonOutOfRange.txt did not fall within the provided lat/lon bound. Each Control Points listed in [PREFIX]NoLatLonPoint.txt do not have a determinable Latitude or Longitude.

Note: This option is expensive.

Type boolean
Default False
Inclusions
  • MINLAT
  • MAXLAT
  • MINLON
  • MAXLON

Lat/Lon Filters: MINLAT

Description

Any Control Point with a latitude less than MINLAT will be removed.

Type double
Default -90.0
Minimum -90.0 (inclusive)
Maximum 90.0 (inclusive)

Lat/Lon Filters: MAXLAT

Description

Any Control Point with a latitude greater than MAXLAT will be removed.

Type double
Default 90.0
Minimum -90.0 (inclusive)
Maximum 90.0 (inclusive)
Greater Than or Equal
  • MINLAT

Lat/Lon Filters: MINLON

Description

Any Control Point with a longitude less than MINLON will be removed.

If MINLON is greater than MAXLON than the longitude range is assumed to cross the 0/360 longitude boundry, where points with longitude greater than MINLON or less than MAXLON will be included.

Type double
Default 0.0
Minimum 0.0 (inclusive)
Maximum 360.0 (inclusive)

Lat/Lon Filters: MAXLON

Description

Any Control Point with a longitude greater than MAXLON will be removed.

If MAXLON is less than MINLON than the longitude range is assumed to cross the 0/360 longitude boundry, where points with longitude greater than MINLON or less than MAXLON will be included.

Type double
Default 360.0
Minimum 0.0 (inclusive)
Maximum 360.0 (inclusive)

Examples


Example 1

Example of cnetextract using the CUBES parameters.

Description

This example shows how to use cnetextract to extract points using Cube filters. This will extract all points that contain at least one measure corresponding to the given cubes in the file list.lis (CUBES=true CUBELIST=list.lis). From these points, the only measures that are extracted will correspond to the cubelist (CUBEMEASURES=true). All reference measures will be extracted, whether they correspond to the cubelist or not (RETAIN_REFERENCE=true). Note that the RETAIN_REFERENCE option overrides the CUBEMEASURES option with respect to reference measures.

Command Line

cnetextract fromlist=list.lis cnet=cnet.net prefix=new tolist=newList.lis onet=newNet.net networkid=new description=new cubes=true cubelist=list.lis cubemeasures=true retain_reference=true
An example of how to run this program from the command line.

GUI Screenshot

Example of GUI command

Example GUI

An example of how to run this program using the GUI. Note that the results summary can be seen in the log window.

Data Files

FROMLIST = list.lis This is the input list containing cubes that can be found in the input control network.
CNET = cnet.net The input control network contains 18 points and a total of 37 measures.
TOLIST = newList.lis This is the list of cubes contained in the FROMLIST that can be found in the output control network. Notice that one of the cubes listed in the FROMLIST is not included in the output TOLIST.
ONET = newNet.net The output control network contains 13 of the original 18 points. Five points were extracted (test0135 to test0139) since they did not contain either measures from any of the three cubes in the cubelist (see list.lis). Also, notice that 19 of the original 37 measures have been extracted. Each of these measures can be matched to a cube in the cubelist or is reference measure for one of the 13 output points.
CUBELIST = list.lis This is a list of cubes from which we will filter.
newNonCubePoints.txt, created since PREFIX=new and CUBES=true The output report for the CUBES filter lists the 5 points that were not extracted since they have no measures that correspond to cubes in the given cubelist. Notice the prefix of the file name "new" is taken from the value passed into the PREFIX parameter. Also, note that this file would not be created if the PREFIX parameter was left blank.
newNonCubeMeasures.txt, created since PREFIX=new, CUBEMEASURES=true, RETAIN_REFERENCE=true Output report for CUBEMEASURES filter The output report for the CUBEMEASURES and RETAIN_REFERENCE filters lists the 24 measures from extracted points that don't correspond to cubes in the given cubelist. Notice that, since RETAIN_REFERENCE is selected, the reference measures listed in this report indicate that they are extracted. Also, notice the prefix of the file name "new" is taken from the value passed into the PREFIX parameter. This file would not be created if the PREFIX parameter was left blank.
Standard output results summary. If run command line, this summary will be printed in the terminal window. If run in GUI, this summary will be printed in the log area. Notice that the report shows MeasurelessPoints even though the NOMEASURELESS parameter was not selected. However, this parameter is automatically selected when CUBEMEASURES is selected.

History

Christopher Austin2009-07-22 Original version
Christopher Austin2009-07-31 Refactored for readability, added parameter defaults, and added detail to the application log.
Christopher Austin2009-08-11 Added an additional output progress bar.
Christopher Austin2009-08-21 Added the points kept to the print file.
Christopher Austin2009-08-28 Fixed TOLIST blank lines, added the POINTLIST option, and changed the CUBEPOINTS parameter to take a filename instead of a boolean.
Christopher Austin2009-09-29 Added the TOLERANCE parameter.
Christopher Austin2009-10-02 Changed the TOLERANCE keyword to extract points with an error greater than or equal to the TOLERANCE, instead of less than or eqaul to.
Christopher Austin2009-10-15 Fixed the TOLERANCE code.
Christopher Austin2009-11-02 Fixed the interface to be more clear.
Christopher Austin2009-11-09 Added the GROUND parameter.
Christopher Austin2010-01-20 Added the USENETWORK parameter to avoid the need for spiceinit prior to knowing which cubes are necessary for the extracted control network.
Christopher Austin2010-02-01 FROMLIST is now an option parameter, however, to be able to generate a TOLIST, the FROMLIST must be provided. Also did some code cleanup.
Christopher Austin2010-03-01 Changed NOSINGLEMEASURES to NOMEASURELESS and fixed a simple progress bug.
Christopher Austin2010-03-03 Fixed min/max lat/lon bounding issues.
Christopher Austin2010-03-08 Brought back NOSINGLEMEASURES while leaving NOMEASURELESS as is.
Christopher Austin2010-06-18 Added PREFIX and moved all detailed output from the print.prt to the PREFIX files for each filter parameter.
Christopher Austin2010-06-30 Rewrote documentation and reorganized keywords into groups.
Christopher Austin2010-11-08 Fixed for binary cnet conversion.
Christopher Austin2011-01-18 Altered to compile with the new Control redesign.
Jai Rideout2011-04-12 Changed OUTNET to ONET for consistency.
Sharmila Prasad2011-05-27 Added an option RETAIN_REFERENCE to extract the Reference measure even if it is not in the CUBELIST
Debbie A. Cook and Tracie Sucharski2011-06-07 Change point types "Ground" to "Fixed" and "Tie" to "Free".
Stuart Sides2011-10-07 Added documentation with Annie Howington-Kraus and Ella Lee.
Jeannie Backer2012-06-22 Added and modified documentation for filters and PREFIX report files to better reflect how the program filters work. References #927.
Jeannie Backer2012-07-11 Modified application to not create empty output files. If a file is not created, a comment will be printed in the results log. Fixes #253. Fixed bug in NOMEASURELESS and POINTLIST filters. These were not being properly handled by the program. Replaced summary keyword NoCubeMeasure with NonCubeMeasures for consitency with NonCubePoints. Modified and added new appTests to reflect changes. Fixes #955. Added webpage example. Added documentation to Makefiles. Updated xml documentation and clarified output reports for [PREFIX]IgnoredMeasures.txt and [PREFIX]NonCubeMeasures.txt Fixes #927.
Debbie A. Cook2012-11-30 Changed to use TProjection instead of Projection. References #775.
Moses P. Milazzo2014-11-13 Added EditLocked and Constrained filters. References #255.
Kelvin Rodriguez2016-08-16 removed redundant boolean statement (len == 0) which caused warnings in clang. Part of porting to OS X 10.11.
Ian Humphrey2016-09-29 When using LATLON=true, control points that are out of the specified latitude and longitude ranges will now be properly recorded into the approriate output text files. See the internal history for cnetextract.cpp's ExtractLatLonRange() for more detailed change information.