ISIS 2

jigsaw

Description

The jigsaw application performs a bundle adjustment on a group of overlapping Isis 3,
level 1, cubes from framing and/or line-scan cameras. The adjustment
simultaneously defines the selected image geometry information (camera pointing, spacecraft
position) and control point coordinates (x,y,z or lat,lon,radius) to reduce
boundary mismatches in mosaics of the images.

This functionality is demonstrated below in a zoomed-in area of a mosaic of a
pair of overlapping Messenger images. In the before jigsaw mosaic on the left
(uncontrolled), the features on the edges of the images do not match. In the after
jigsaw mosaic on the right (controlled), the crater edges meet correctly and the
seam between the two images is no longer visible.

The jigsaw application assumes spiceinit has been run on the input cubes so that
SPICE is included in the Isis 3 cube labels in the Kernels group. In order to
run the program, the user must provide a list of input cubes, an input control
net, the name of an output control net, and the adjustment parameters.
jigsaw outputs a new control net that includes the initial state of the
points in the network and their final state after the adjustment. The initial states of
the points are tagged as a priori in the control net, and their final
states are tagged as adjusted. The measured sample/line positions
associated with the control points in the net are not changed. SPICE
in the cube labels is updated at the end of the adjustment only
if the bundle converges and the UPDATE parameter is selected.

Optional output files can be selected to provide more information for analyzing the
results. BUNDLEOUT_TXT provides an overall summary of the bundle adjustment.
It lists the user input parameters selected and tables of statistics for both the
images and the points. The image statistics can also be written to a separate
CSV file and likewise for the point statistics with the OUTPUT_CSV
option selected. RESIDUALS_CSV provides a table of the measured image
coordinates and the final sample, line, and overall residuals
in both millimeters and pixels.

The functional model for the bundle adjustment is the collinearity
condition. It stipulates that the camera perspective center, a ground
point, and its associated image point measurement be collinear. The diagram
below demonstrates the collinear condition in a bundle adjustment.
The vectors formed by connecting each object space point (target surface x,y,z)
and its corresponding image space points (sample,line) form
a bundle of light rays.

Known Issues

Running jigsaw with a control net containing JigsawRejected
flags may result in bundle failure

When running jigsaw with Outlier Rejection turned on,
control points and/or control measures may be flagged as
JigsawRejected in the output control net file. If this output net
file is then used in a subsequent jigsaw run, these points and
measures will be erroneously ignored, potentially causing the bundle
adjustment to fail.

--Workarounds

Run jigsaw with Outlier Rejectionoff.

Do not use the output control net file in subsequent jigsaw runs.

Convert the output control net file from binary to PVL and back using
cnetbin2pvl and cnetpvl2bin. This will
clear the JigsawRejected flags.

Added minimums to parameters, corrected SOLVEDEGREE description, and
added to the camsolve option descriptions in response to Mantis
issue #514.

Ken Edmundson

2011-12-20

Added REJECTION_MULTIPLIER to interface, part of Mantis issue #637.

Ken Edmundson

2012-01-19

Added SPKDEGREE and SPKSOLVEDEGREE; changed name of SOLVEDEGREE to
CKSOLVEDEGREE.

Ken Edmundson

2014-02-13

Added separate group for Error Propagation with option to write inverse matrix to binary
file. For extremely large networks where memory/time for error propagation is limited.

Ken Edmundson

2014-07-09

Added USEPVL and SC_PARAMETERS parameters.

Jeannie Backer

2014-07-14

Modified appTests to use SPARSE method only. Commented out bundleout_images.csv references.
Created observationSolveSettings() method to create an observation settings object from the user
entered values.

Added a connection to allow jigsaw to surface exceptions from BundleAdjust. Fixes #2302

Jeannie Backer

2016-08-18

Removed the user parameter called METHOD (i.e. the method used for solving the bundle matrix).
This solve method is no longer user-selected. The program will now use what was called the SPARSE option
for the METHOD parameter (i.e. solve with CholMod sparse decomposition). This method should give
the same results as the other options and should run faster. So the other options were no longer needed.
References #4162.

Added the IMAGES_CSV parameter to the "Output Options" group
so that the user can now request the bundleout_images.csv file
in addition to the other output files such as bundleout.txt. Fixes #4314.

Ian Humphrey

2016-10-13

Implemented HELDLIST functionality for non-overlapping held images. Any control points that
intersect the held images are fixed, and a priori surface points for these control points are
set to the held images' measures' surface points. Disabled USEPVL/SC_PARAMETERS. Fixes #4293.

The bundleout.txt output file will record default values for unsolved parameters. The default
position will be the instrument position's center coordinate, and the default pointing will
be the pointing's (rotation's) center angles. The bundleout_images.csv file will also have
these defaults provided. Fixes #4464.

Makayla Shepherd

2016-10-26

Removed the underscores from the new parameters IMAGESCSV and TBPARAMETERS.

Ian Humphrey

2016-11-16

Exceptions that occur during the solving of the bundle adjustment will now pop up as
message boxes when running jigsaw in GUI mode. Fixes #4483.

Ken Edmundson

2016-11-17

Output control net will be now be written regardless of whether bundle converges. Fixes #4533.

Ken Edmundson

2017-01-17

Updated description and brief for SOLVETARGETBODY and TBPARAMETERS.

Summer Stapleton

2017-08-09

Fixed bug where an invalid control net was not throwing exception. Fixes #5068.

Ken Edmundson

2018-05-23

Modifed call to bundleAdjustment->solveCholeskyBR() to return a raw pointer to a
BundleSolutionInfo object. Am also deleting this pointer because jigsaw.cpp takes
ownership from BundleAdjust.

Files:
FROMLIST

Description

Files:
HELDLIST

Description

This file contains a list of all cubes whose orientation and position
will be held in the adjustment. These images will still be included
in the solution, but their camera orientation and spacecraft position
will be constrained to keep the values from changing. This is an
optional parameter and the default is to not hold any of the images.
Note that held images must not overlap each other to work properly.

Files:
ONET

Description

Solve Options:
OBSERVATIONS

Description

This option will solve for SPICE on all cubes with a matching
observation number as though they were a single observation. For
most missions, the default observation number is equivalent to the
serial number of the cube, and a single cube
is an observation. However, for the Lunar Orbiter mission, an image has a defined
observation number that is a substring of its serial number. This
feature allows the three subframes of a Lunar Orbiter High
Resolution frame to be treated as a single observation when this
option is used; otherwise, each subframe is adjusted independently.

Solve Options:
UPDATE

Description

When this option is selected, the application will update the labels
of the individual cubes in the FROMLIST with the final values
from the solution if the adjustment converges. The results are written
to the SPICE blobs attached to the cube, overwriting the previous
values. If this option is not selected, the cube files are not
changed. All other output files are still created.

Exclusions

Huber: approximates the L2 norm near 0, and the L1 norm thereafter. Has one continuous derivative.

A highly recommended model that works well in many situations.

HUBER_MODIFIED

Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives.

An adaptation of the highly recommended Huber model that has two continuous derivatives.

WELSCH

Welsch: approximates the L2 norm near 0, but then decays exponentially to zero.

This model reduces the significance of large residuals more aggressively than Huber. Large residuals will have less influence than small residuals,
and they approach negligibility as they approach infinity. Measures can be effectively 'removed' by this method, which may cause singularities and/or islands.

CHEN

Chen: a highly aggressive method that intentionally removes the largest few percent of residuals.

This method dramatically increases the influence of smaller residuals (beyond the L2 norm) while simultaneously totally ignoring the largest few
percent of the residuals.

Exclusions

Huber: approximates the L2 norm near 0, and the L1 norm thereafter. Has one continuous derivative.

A highly recommended model that works well in many situations.

HUBER_MODIFIED

Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives.

An adaptation of the highly recommended Huber model that has two continuous derivatives.

WELSCH

Welsch: approximates the L2 norm near 0, but then decays exponentially to zero.

This model reduces the significance of large residuals more aggressively than Huber. Large residuals will have less influence than small residuals,
and they approach negligibility as they approach infinity. Measures can be effectively 'removed' by this method, which may cause singularities and/or islands.

CHEN

Chen: a highly aggressive method that intentionally removes the largest few percent of residuals.

This method dramatically increases the influence of smaller residuals (beyond the L2 norm) while simultaneously totally ignoring the largest residuals.

Camera Pointing Options:
CKDEGREE

Description

Camera Pointing Options:
CKSOLVEDEGREE

Description

The degree of the polynomial being fit to in the bundle adjust
solution. This polynomial can be different from the one used to
generate the a priori camera angles used in the first
iteration. In the case of an instrument with a jitter problem, a
higher degree polynomial fit to each of the camera angles might
provide a better solution (smaller errors). For framing cameras,
the application automatically sets degree to 0.

Camera Pointing Options:
CAMSOLVE

Description

This parameter is used to specify which, if any, camera
pointing parameters to include in the adjustment.

Type

string

Default

ANGLES

Option List:

Option

Brief

Description

NONE

Don't solve for any camera pointing factors

If this option is selected, no camera pointing parameters
will be adjusted.

Exclusions

CKDEGREE

CKSOLVEDEGREE

TWIST

OVEREXISTING

ANGLES

Solve for camera angles: right ascension, declination and optionally twist

Camera angles in each cube will be adjusted in the solution,
but not angular velocities or accelerations. Solving for the first two
camera angles translates images in sample and line. Adding the third
angle to the solution (TWIST option) allows for rotation corrections.
Adjustments are not applied unless the solution converges and UPDATE is
selected. Solving for angles only is equivalent to using CKSOLVEDEGREE=0.

Exclusions

CKDEGREE

CKSOLVEDEGREE

VELOCITIES

Solve for camera angles AND their angular velocities

Camera angles and their angular velocities will be adjusted in the
solution. Solving for angles and velocities is equivalent to using
CKSOLVEDEGREE=1.

Exclusions

CKDEGREE

CKSOLVEDEGREE

ACCELERATIONS

Solve for camera angles, their angular velocities and accelerations

Camera angles, their angular velocities, and accelerations will be
adjusted in the solution. Solving for angles, angular velocities, and
accelerations is equivalent to using CKSOLVEDEGREE=2.

Exclusions

CKDEGREE

CKSOLVEDEGREE

ALL

Solve for all coefficients in the polynomials fit to the camera angles.

If this option is selected, all coefficients of the solve
equation will be adjusted in the solution (CKSOLVEDEGREE+1
coefficients)

Camera Pointing Options:
TWIST

Description

Camera Pointing Options:
OVEREXISTING

Description

This option will fit a polynomial over the existing pointing data.
This data is held constant in the adjustment, and the
initial value for the each of the coefficients in the polynomials
is 0.
When this option is used, the current pointing is used as a priori
in the adjustment.

Spacecraft Options:
SPKDEGREE

Description

Spacecraft Options:
SPKSOLVEDEGREE

Description

The degree of the polynomial being fit to in the bundle adjust
solution. This polynomial can be different from the one used to
generate the a priori camera positions used in the first
iteration. In the case of an instrument with a jitter problem, a
higher degree polynomial fit for the camera position might provide
a better solution (smaller errors). For framing cameras, the
application automatically sets degree to 0.

Spacecraft Options:
OVERHERMITE

Description

This option will fit a polynomial over the existing Hermite cubic
spline used to interpolate the coordinates of the spacecraft
position. The spline is held constant in the adjustment, and the
initial value for the each of the coefficients in the polynomials
is 0.
When this option is used, the current positions are used as a priori
in the adjustment.

Target Body:
SOLVETARGETBODY

Description

Solve for target body parameters. The parameters, their a priori values, and uncertainties are input
using a PVL file specified by TBPARAMETERS below. An example template PVL file is located at
$base/templates/jigsaw/TargetBodyParameters.pvl.

Target Body:
TBPARAMETERS

Description

This file contains target body parameters to solve for in the bundle adjustment, their
a priori values, and uncertainties. The file must be in PVL format. An example template
PVL file is located at $base/templates/jigsaw/TargetBodyParameters.pvl. Instructions for the PVL
structure are given in the template.