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

Public Release
8.1.0
8.0.0
7.2.0
7.1.0
7.0.0
6.0.0
3.9.0
3.5.0

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Documentation

Control Networks

Control Network format and keyword definitions in ISIS

Home

Introduction

Control Network

A Control Network in ISIS is a structure which holds a network of image correspondances, also known as tie points or control points, which identify common ground points across multiple images of the same body. A Control Network is made up of Control Points (the common tie point) and a Control Point has one or more Control Measures (measurements in image space of the common point in a particular image). There are two file formats for Control Networks in ISIS -- a binary google protocol buffer format and a human-readable pvl format. Both contain the same contents and information. This document describes the keywords present in the PVL format for convenience.

Control Network

This section describes the keywords associated with the main Control Network object.

  Object = ControlNetwork
  NetworkId    = ExampleNetwork1
  TargetName   = Template
  UserName     = aexample
  Created      = 2012-01-04T12:09:57
  LastModified = 2012-01-04T12:09:57
  Description  = "Example PvlV0005 ControlNetwork template."
  Version      = 5
Keyword Required Default Description
NetworkId Yes No Default A user defined single-word identifier assigned to the control network file.
TargetName Yes "" The planetary body to which the control network file applies. This Target Name should appear in all cubes used in the control network. Possible example values are Moon, or Mars.
UserName No No Default Name of the user that created the control network file.
Created No Set automatically Initial creation date and time of control net file. Once this is set it should not be modified.
LastModified No None Date and time on which the control net file was last modified. All programs which modify the contents of this network must set this keyword.
Description No None Brief description of the control network file. This is free-form text normally supplied by the person running the application.
Version No Set to current version on output. The Version of the Control Network file. The most recent version is 5.

Control Point

A control point is one or more measurements that identify the same feature or location in different images. This section contains the information describing a Control Point.

  Object = ControlPoint
    PointType                = "Fixed    # (Fixed, Constrained, Free)"
    PointId                  = I00826010RDR_ex_1_ID
    ChooserName              = aexample
    DateTime                 = 2012-01-04T17:01:32
    EditLock                 = True
    Ignore                   = True
    AprioriXYZSource         = "User # (None, User, AverageOfMeasures, Reference, Basemap, BundleSolution)"
    AprioriXYZSourceFile     = /home/temp/xyzSource.cub
    AprioriRadiusSource      = "User   # (AverageOfMeasures, BundleSolution, Ellipsoid, DEM)"
    AprioriRadiusSourceFile  = /home/temp/radiusSource.cub

    # AprioriLatitude = 1.1 <degrees>
    AprioriX                 = 100 <meters>

    # AprioriLongitude = 2.2 <degrees>
    AprioriY                 = 100 <meters>

    # AprioriRadius = 3.3 <meters>
    AprioriZ                 = 100 <meters>
    AprioriCovarianceMatrix  = (1.1, 2.2, 3.3, 4.4, 5.5, 6.6)
    LatitudeConstrained      = True
    LongitudeConstrained     = True
    RadiusConstrained        = True

    # AdjustedLatitude = 1.1 <degrees>
    AdjustedX                = 100 <meters>

    # AdjustedLongitude = 2.2 <degrees>
    AdjustedY                = 100 <meters>

    # AdjustedRadius = 3.3 <meters>
    AdjustedZ                = 100 <meters>
    AdjustedCovarianceMatrix = (1.1, 2.2, 3.3, 4.4, 5.5, 6.6)
Keyword Required Default Description
PointType Yes No Default?
  • Fixed - A Fixed point is a Control Point whose lat/lon is well established and should not be changed. Some people will refer to this as a truth (i.e., ground truth).
  • Constrained - A Constrained point is a Control Point whose lat/lon/radius is somewhat established and should not be changed.
  • Free - A Free point is a Control Point that identifies common measurements between two or more cubes. While it could have a lat/lon, it is not necessarily correct and is subject to change. This is the most common type of control point. This point type floats freely in a bundle adjustment.
PointId Yes No Default String to identify an individual Control Point. This is a required keyword for all points and must be unique within a single Control Network. This keyword is often generated automatically by applications which create Control Points.
ChooserName No No Default The name of the user who manually created a point or the name of the application which automatically created a point.
DateTime No No Default Indicates the date/time a ground Control Point's coordinate was last changed
EditLock No False Indicator to applications that edit the contents of Control Points that all information about this point (e.g. Latitude, Longitude, Radius) should not be modified. This does not include adding or removing measurements or the contents of existing measurements, as long as those measures are not locked.
Ignore No False Flag (True/False) to indicate whether this Control Point should be Ignored. When a point is ignored, no data within the point should be used by a program unless the program is explicitly working with ignored points.
AprioriXYZSource No None Set to one of the values below:
  • User - The a priori coordinates for this point were entered by the user.
  • AverageOfMeasures - The a priori coordinates for this point were calculated by averaging the coordinates for all measures (e.g., Average lat/lon or x/y/z for all measures).
  • Reference - The a priori coordinates for this point were obtained from the camera associated with the Control Measure marked as "REFERENCE".
  • Basemap - The a priori coordinates for this point were obtained from either a controlled mosaic or a single projected image used for a priori coordinates.
  • BundleSolution - The a priori coordinates for this point were obtained from a previous run of jigsaw.
AprioriXYZSourceFile No "" A string containing the file name of the AprioriLatitude and AprioriLongitude source. This keyword will only be used if AprioriLatLonSource == Basemap.
AprioriRadiusSource No Doesn't exist in net Set to one of the values below:
  • User - The a priori radius was hand entered by the user.
  • AverageOfMeasures - The a priori radius was calculated as the average radius for all measures.
  • Ellipsoid - The a priori radius was calculated using the Naif PCK body radii. The number of radii used depends on the IAU definition of the target body.
  • DEM - Digital Elevation Model used for a priori radius.
  • BundleSolution - Radius output from a previous run of jigsaw.
AprioriRadiusSourceFile No "" A string containing the file name of the AprioriRadius source.
If AprioriiRadiusSource = Ellipsoid, this keyword will be set to the Naif PCK file.
If AprioriRadiusSource = DEM, this keyword will be set to the file name of the DEM.
AprioriX No False Internal storage of the '''initial''' position of the point on the target. Always stored in body fixed x,y,z coordinates.
AprioriY No False Internal storage of the '''initial''' position of the point on the target. Always stored in body fixed x,y,z coordinates.
AprioriZ No False Internal storage of the '''initial''' position of the point on the target. Always stored in body fixed x,y,z coordinates.
AprioriSigmaX No None Pre-adjustment standard deviation of XXXXXXX. An indicator of accuracy that may be used in the weighting of the XXXXXX point coordinate in the bundle adjustment. May originate from a variety of sources; for example a base-map, a previous bundle adjustment, or from the assumed or estimated quality of a sensor measurement such as GPS (in the case of terrestrial mapping) or lidar. Or for other planets accuracy of the MOLA solution. Units are meters.
AprioriSigmaY No None Pre-adjustment standard deviation of XXXXXXX. An indicator of accuracy that may be used in the weighting of the XXXXXX point coordinate in the bundle adjustment. May originate from a variety of sources; for example a base-map, a previous bundle adjustment, or from the assumed or estimated quality of a sensor measurement such as GPS (in the case of terrestrial mapping) or lidar. Or for other planets accuracy of the MOLA solution. Units are meters.
AprioriSigmaZ No None Pre-adjustment standard deviation of XXXXXXX. An indicator of accuracy that may be used in the weighting of the XXXXXX point coordinate in the bundle adjustment. May originate from a variety of sources; for example a base-map, a previous bundle adjustment, or from the assumed or estimated quality of a sensor measurement such as GPS (in the case of terrestrial mapping) or lidar. Or for other planets accuracy of the MOLA solution. Units are meters.
LatitudeConstrained No False Flag that indicates if the Latitude is constrained.
LongitudeConstrained No False Flag that indicates if the longitude is constrained.
RadiusConstrained No False Flag that indicates if the radius is constrained.
AdjustedX No None Adjusted X coordinate of the Control Point location. Units are decimal meters.
AdjustedY No None Adjusted Y coordinate of the Control Point location. Units are decimal meters.
AdjustedZ No None Adjusted Z coordinate of the Control Point location. Units are decimal meters.

Control Measure

A Control Measure is a measurement in image space (sample and line coordinates) of a point in one cube that has been associated with a Control Point and other overlapping image cubes. Each ControlMeasure group in a PVL-formatted Control Network contains all information concerning a control measurement. An example follows:

    Group = ControlMeasure
      SerialNumber       = Example/Measure/111.000
      MeasureType        = "Candidate   # (Candidate, Manual, RegisteredPixel, RegisteredSubPixel)"
      ChooserName        = aexample
      DateTime           = 2012-01-04T17:01:32
      EditLock           = True
      Ignore             = True
      Sample             = 180.0
      Line               = 270.0
      Diameter           = 10.0
      AprioriSample      = 50
      AprioriLine        = 50
      SampleSigma        = 10 <pixels>
      LineSigma          = 10 <pixels>
      SampleResidual     = 10 <pixels>
      LineResidual       = -10 <pixels>
      JigsawRejected     = Yes
      MinimumPixelZScore = -6.9339878963865
      MaximumPixelZScore = 7.8509687345151
      GoodnessOfFit      = 0.7774975693515
      Reference          = True
      End_Group
Keyword Required Default Description
SerialNumber Yes No Default A serial number is a unique identifier for a cube. This value is usually comprised of a spacecraft name, instrument name, start time, and if needed, other identifying label values from the cube. Serial numbers are used within control networks in conjunction with a cube list to associate cubes and control measures.
MeasureType No Candidate
  • Candidate - This Control Measurement is considered a candidate (i.e., the location is preliminary or not well know).
  • Manual - This Control Measurement was hand measured (eg. qnet).
  • RegisteredPixel - Automatically registered to whole pixel (eg. pointreg).
  • RegisteredSubPixel - Automatically registered to sub-pixel (eg. pointreg, qnet).
ChooserName No Omitted if not set Indicates the name of the user or application that last changed this Control Measure's coordinate.
DateTime No Omitted if not set Indicates the date/time the Control Measure's line/sample coordinates were last changed.
EditLock No False Indicates that the measure is not to be edited. This includes the Ignore and Reference flag for any measure.
Ignore No False Flag (True/False) to indicate whether this Control Measure should be Ignored. When a measurement is ignored it should not be used by a program unless the program is explicitly working with ignored measurements.
Sample No 0.0? Sample coordinate of the Control Measure within the cube. The value of the keyword is a floating point number.
Line No 0.0? Line coordinate of the Control Measure within the cube. The value of the keyword is a floating point number.
Diameter No 0.0 The diameter of the crater in meters, if the control measure is associated with a crater.
AprioriSample No None The first identified sample coordinate of the measure by any application. In this initial state the a priori keyword values are the same as line/sample keyword values.
AprioriLine No None The first identified line coordinate of the measure by any application. In this initial state the a priori keyword values are the same as line/sample keyword values.
SampleSigma No None Standard deviation of sample measurement. An indicator of precision used in the weighting of measurements in the bundle adjustment (i.e. Jigsaw). May be determined from experience (e.g., manual point measurement) or perhaps estimated within an automated point measurement technique (e.g., ellipse fitting of crater edges, or through the use of an interest operator). Units are pixels.
LineSigma No None Standard deviation of line measurement. An indicator of precision used in the weighting of measurements in the bundle adjustment (i.e. Jigsaw). May be determined from experience (e.g., manual point measurement) or perhaps estimated within an automated point measurement technique (e.g., ellipse fitting of crater edges, or through the use of an interest operator). Units are pixels.
SampleResidual No None The difference between the 'estimated' sample measurement (as determined at the end of each iteration of the bundle adjustment) and the original sample measurement. Used in the determination of outliers throughout the bundle. Measurement residuals are used upon convergence to compute the reference variance (σ02) which in turn is used to scale the inverse of the normal equations matrix for error propagation. Units are pixels.
LineResidual No None The difference between the ''estimated'' line measurement (as determined at the end of each iteration of the bundle adjustment) and the original sample measurement. Used in the determination of outliers throughout the bundle. Measurement residuals are used upon convergence to compute the reference variance (σ02) which in turn is used to scale the inverse of the normal equations matrix for error propagation. Units are pixels.
JigsawRejected No False A flag indicating if this measure has been rejected by jigsaw.
MinimumPixelZScore No None Control measures store z-scores in pairs. A pair contains the z-scores of the minimum and maximum pixels in the pattern chip generated for the given measure during point registration. Each z-score indicates how many standard deviations the given pixel value is above or below the mean DN. This is used when using area-based-matching in ISIS.
MaximumPixelZScore No None Control measures store z-scores in pairs. A pair contains the z-scores of the minimum and maximum pixels in the pattern chip generated for the given measure during point registration. Each z-score indicates how many standard deviations the given pixel value is above or below the mean DN. This is used when using area-based-matching in ISIS.
GoodnessOfFit No None This measures how well the computed fit area matches the pattern area when using applications like pointreg.
Reference No False(?) A flag indicating if this measure is the reference measure for its parent Control Point.

Document History

Kristin Berry2018-01-26Original Version. Migrated information from internal wiki, ControlNetVersioner.h, the pvl template file, and many other header files. Actual original authors include most of the ISIS3 team.