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

cnetmerge

Standard View | TOC | Home

Merges multiple Control Networks into one

Description
Categories
Groups
History

Description

This program attempts to merge a set of (two or more) Control Networks into a single network. The merging process starts with a "base" network into which each successive "add" network is added. When conflicts arise between the base network and the network being added, a set of user-selected options are used to determine how the conflicts are resolved.

When more than two Control Networks are merged, note that the "base" network is updated iteratively when each successive network is added. So the definition of the "base" network is dynamic in this case.

For any point or measure that is edit locked in the base network, that point or measure will never be modified regardless of the OVERWRITE options set. When a point is edit locked, the reference measure is locked implicitly. So, for example, if OVERWRITEREFERENCE is selected, and a control point is edit locked, that point's reference will not be overwritten.

Note: Each network must share the same target.

Categories

Parameter Groups

Input

Name Description
INPUTTYPEHow the program should retrieve its input
CLIST List of Control Networks to be merged
BASE "Base" Control Network
CNET2 Control Network to be "added"

Output

Name Description
ONET Merged Control Network
NETWORKIDThe NetworkId keyword value for the merged ControlNet
DESCRIPTIONThe Description keyword value for the merged ControlNet
LOG Reports Control Points that conflicted

Conflict Resolution

Name Description
DUPLICATEPOINTS How to handle Control Points appearing in both base and add networks
OVERWRITEPOINTSReplace conflicting Control Points as networks are added
OVERWRITEMEASURES Replace conflicting Control Measures as networks are added
OVERWRITEREFERENCE Replace Reference Measures in conflicting Control Points
OVERWRITEMISSING Omit Control Measures missing in network(s) added to the base network

Input: INPUTTYPE

Description

This parameter specifies whether the program should take its input from a list of Control Networks to be merged (LIST) or directly from a pair of parameters specifying a base and add network (CNETS).

Type string
Default LIST
Option List:
Option Brief Description
LISTMerge a list of networks

This option will have the program retrieve its input from a list of Control Networks (one per line), and merge them one by one. The first network in the list acts as the initial "base" network into which each successive network is "added". The last network in the file is the last network to be added to the network, and thus will have either highest or lowest priority in certain conflict resolutions depending on the option(s) specified in the "Conflict Resolution" parameter group.

If a value is provided for the BASE parameter, then that network will become the new, explicit base. This will effectively place the explicit base at the front of the input list. If the explicit base appears elsewhere in the list, it will be ignored there to avoid adding it to the output twice.

Exclusions

  • CNET2
CNETSMerge a pair of networks Selecting this option is like providing a list of networks to be merged with only two networks. The first network (BASE) will act as the base network, and the second network (CNET2) will act as the network being "added".

Exclusions

  • CLIST

Inclusions

  • BASE

Input: CLIST

Description

Starting from the first network in the list as the "base", the program will "add" each following network in the order specified by this list to produce the output. When conflicts arise, they are resolved in accordance with the options in the "Conflict Resolution" group.

If a value is provided for the BASE parameter, then that network will effectively be added to the front of this list, becoming the new base network into which all the networks in this list are added. If the BASE filename also appears elsewhere in this list, it will be ignored in the list to avoid adding it twice.

Type filename
File Mode input
Filter *.txt *.lis *.list *.lst

Input: BASE

Description

The "base" Control Network into which all other control networks will be "added". When no overwrite option(s) from the "Conflict Resolution" group are selected, any conflicts will be resolved by retaining the values from this network.

This parameter is required for the INPUTTYPE of CNETS, and is optional for LIST. When INPUTTYPE=LIST and an explicit BASE is provided, the value of this parameter will act as the first network in the list, making it the base network into which all other networks are added. If a network with the same filename appears in the input list, it will be ignored in the list to avoid adding it twice.

Type filename
File Mode input
Internal Default Automatic
Filter *.ctl *.pvl *.net

Input: CNET2

Description

The Control Network to be "added" into the base network. When an overwrite option(s) in the "Conflict Resolution" group is selected, the conflicting value from this network will replace the existing value in the base network.

Type filename
File Mode input
Filter *.ctl *.pvl *.net

Output: ONET

Description

The output Control Network, which is the merged result of the input networks.

Type filename
File Mode output
Filter *.ctl *.pvl *.net

Output: NETWORKID

Description

The NetworkId keyword for the newly merged ControlNet will be set to this given value. The Networkid is a single word identifier or name assigned to a Control Network.

Type string

Output: DESCRIPTION

Description

The Description keyword for the newly merged ControlNet will be set to this given value. This should be a brief description of the purpose of the merged control network.

Type string

Output: LOG

Description

This file will contain a report that reveals all Control Points that were conflicted during the merging process. If no Control Points conflicted, then this file will be empty.

Type filename
File Mode output
Internal Default None

Conflict Resolution: DUPLICATEPOINTS

Description

This parameter specifies how conflicting Control Points between two networks are handled when merging. The current options are to report an error and abort the program when a Control Point appears in both the base and add networks (ERROR), or to attempt to merge the conflicts in the duplicated point (MERGE).

Type string
Default ERROR
Option List:
Option Brief Description
ERRORDisallow merging networks with duplicate points This option will check for conflicting Control Points in the Control Networks and report an error and abort the program when a conflict occurs. If no conflict occurs, all Control Points will be added without changing any existing points in the base network. For the purposes of this option, a conflict can be as simple as two Control Points sharing the same ID. In such a case, an error will be reported and the program aborted, even if nothing else is different between them.

Exclusions

  • OVERWRITEPOINTS
  • OVERWRITEMEASURES
  • OVERWRITEREFERENCE
  • OVERWRITEMISSING
MERGEMerge duplicate points and resolve their conflicts This option will attempt to merge duplicate points between the base network and the successive networks being added to it. When conflicts arise, they will be resolved in accordance with the various overwrite options. By default (i.e., when no overwrite option is selected), values in the base network will take priority over those in the networks added to it, but this can be changed when selecting an overwrite option(s). For example, if OVERWRITEMEASURES is selected, then Line/Sample measurements in the last network added will take precedence over all the Line/Sample measurements for conflicting measures in the base network and the networks that were added prior.

Conflict Resolution: OVERWRITEPOINTS

Description

When this option is SELECTED, whenever a Control Point conflicts between the base network and the network being added, the Control Point values in the base network will be replaced with the values from the added network. When this option is NOT SELECTED, the conflict will be noted in the LOG file (if provided), but the values from the base network will be retained in the output network.

Note that Control Point values being retained or overwritten include the point type (fixed, constrained or free), ignore status, editlock status, apriori and/or adjusted ground coordinates, apriori and/or adjusted ground coordinate sigma values, constrained coordinate flags.

It should also be noted that even when this options is NOT SELECTED, measures can still be added and, depending on the OVERWRITE options selected, modified and deleted from points. This options therefore applies only to control point data values, not items contained within control points.

Type boolean
Default False

Conflict Resolution: OVERWRITEMEASURES

Description

When this option is SELECTED, whenever a Control Measure conflicts between the base network and the network being added, the Control Measure in the base network will be replaced with that from the added network. When this options is NOT SELECTED, the conflict will be noted in the LOG file (if provided), but the Control Measure from the base network will be retained in the output network.

Type boolean
Default False

Conflict Resolution: OVERWRITEREFERENCE

Description

If a Control Point in the current "base" network and the current network being added to it have different Reference Measures, there is ambiguity about which Control Measure should be defined as the one and only Reference Measure in the output Control Network. When this option is SELECTED, the Reference Measure in the network being added will overwrite the existing reference status of the Reference Measure in the base network. If this option is NOT SELECTED, the base Reference Measure will be retained. In both cases, both Control Measures make it into the merged network, but only one will be listed as the Reference Measure for that Control Point.

Regardless of the other OVERWRITE options selected, a reference measure will NEVER be modified unless this option is SELECTED. So, for example, if OVERWRITEMEASURES is selected, and the reference measure exists in the new network with a different line/sample, the base's line/sample will be retained if OVERWRITEREFERENCE is not selected. If this options is selected, however, the reference is subject to modification or removal like any other measure.

Type boolean
Default False

Conflict Resolution: OVERWRITEMISSING

Description

When this option is SELECTED, if a Control Measure exists in a conflicting Control Point in the base network, but not the network being added to it, then the missing Control Measure will not be included in the output merged Control Network for that Control Point. If this option is NOT SELECTED (the default), and a Control Measure exists in either the base or the "add" network, it will be included in the ouput network.

Type boolean
Default False

History

Christpher Austin2008-04-04 Original version
Christopher Austin2008-06-24 Clarified error messages and added documentation. (Removed netmerge from the system, because it did the same thing, just not quite as clean)
Christopher Austin2008-08-05 Fix xml app name error
Christopher Austin2008-11-13 Rebuilt for more Control Point Id control, including a REPLACE option. Only FORCE prefixes the original Control Network Id to the new Control Point Ids, then logs the number of duplicate Control Points. NORMAL and REPLACE leave the Control Point Ids alone.
Christopher Austin2009-01-09 Added the FROMLIST input option.
Christopher Austin2009-01-13 Changed MERGETYPE param name and options to be more clear. Changed MODE to INPUTTYPE. Added the REPORT param which reveals any Control Points that have been renamed or replaced durring the merge.
Christopher Austin2009-01-15 Added Filename expansion to the listed nets and a few other minor readability changes.
Christopher Austin2009-11-19 Multiple changes based on user request, including removal of RENAME, replacing REPLACE with MERGE while merging at the Control Measure level.
Christopher Austin2010-03-15 Changed an outdated error message.
Steven Lambright2010-10-19 Updated to work with recent control network changes
Christopher Austin2011-01-19 Altered to compile with the new Control redesign.
Christopher Austin2011-02-25 Fixed a simple pointer ownership issue.
Steven Lambright2011-04-11 Updated parameter names
Travis Addair2011-05-26 Separated reference resolution control out of OVERWRITEMEASURES and into new parameter OVERWRITEREFERENCE.
Travis Addair2011-05-27 Overhauled documentation to better explain the distinction between the base Control Network and the networks being added into it.
Debbie A. Cook and Tracie Sucharski2011-06-07 Change point type "Ground" to "Fixed"
Travis Addair2011-05-27 Overhauled the application to reflect functional changes to the program, and fix inconsistencies between the documentation and the code. The program now operates without regard for point type, and properly honors all OVERWRITE options in all situations, which fixes #230. A fourth option has been added, OVERWRITEMISSING, which will remove measures that do not appear in newer networks being added to the base, which fixes #228. The log file has been revamped to print out a PVL report for each network, and each conflicting point or measure. Every conflict will be reported along with a reason (based on user parameter options) for the ultimate resolution. This is in reference to issue #229, but more logging will need to be done in order to warn the user of potential pitfalls in their selected options.
Jai Rideout2011-08-04 Made a small modification to the code in mergeNetworks(...) that created a new control network for each file in the file list. FileList's overloaded '[]' operator that was used inside of the call to Filename's constructor confused the compiler on Ubuntu10.04 systems.
Travis Addair, Janet Richie, Elpitha Howington-Kraus2011-10-07 Rewrote large sections of the documentation to make more clear, accessible, and user-friendly.
Travis Addair2012-04-17 Moved duplicate point check for DUPLICATEPOINTS=ERROR to occur before merging is attempted. In this way, errors can be caught before expensive merging begins. Also enabled logging of duplicate points. If the user specifies a LOG file with DUPLICATEPOINTS=ERROR, all duplicate points will be reported to that file before the program terminates.
Travis Addair2011-04-18 Removed the REVERSE option and changed the CNET parameter to BASE. When INPUTTYPE=CNETS, BASE will act exactly as CNET did. However, when INPUTTYPE=LIST, the BASE parameter can now be provided in order to set an explicit base network, effectively adding it to the front of the input list. If the explicit base network also appears in the input list, it will be ignored there to avoid adding it twice. If not value is provided for BASE, the first element in the list is considered the base network.