ISIS 3 Application Documentation
Improves camera pointing and a whole lot more!
Description
jigsaw performs a bundle adjustment on a group of overlapping Isis 3, level
1, cubes from framing and/or line-scan cameras. The adjustment simultaneously
refines 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.
jigsaw 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 state of
the points are tagged as a priori in the control net, and their final
state 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.
Kraus, Karl., 1993. Photogrammetry Vol. I., Fundamentals and Standard
Processes, Der. Dümmler Verlag, Bonn, Germany, ISBN 3-427-78684-6, 397
pages.
Known Issues
Running jigsaw with a control net containing JigsawRejected
flags may result in bundle failure
When running jigsaw with Outlier Retection 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 Rejection off.
- 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.
Categories
Applications
History
| Jeff Anderson | 2007-04-27 |
Original version
|
| Steven Lambright | 2007-07-23 |
Changed category to Control Networks and corrected XML bugs
|
| Debbie A. Cook | 2007-10-05 |
Revised iteration report to list the errors and sigmas from the same iteration. Previous version reported errors from previous iteration and sigmas from current iteration.
|
| Christopher Austin | 2008-07-03 |
Cleaned the Bundle Adjust memory leak and fixed the app tests.
|
| Tracie Sucharski | 2009-04-08 |
Added date to the Jigged comment in the spice tables.
|
| Tracie Sucharski | 2009-04-22 |
If updating pointing, delete the CameraStatistics table from labels.
|
| Mackenzie Boyd | 2009-07-23 |
Modified program to write history to input cubes.
|
| Debbie A. Cook | 2010-08-12 |
Commented out Heldlist until mechanism in place to enter individual
image parameter constraints.
|
| Debbie A. Cook | 2010-08-12 |
Merged Ken Edmundson version with system and binary control net.
|
| Debbie A. Cook | 2011-06-14 |
Modified code to prevent updates to cube files in held list.
|
| Debbie A. Cook | 2011-09-28 |
Removed SC_SIGMAS from user parameter list because it is not
fully implemented; changed method name SPARSE to OLDSPARSE
and CHOLMOD to SPARSE; and improved the documentation for
the Isis3.3.0 release.
|
| Debbie A. Cook, Ken Edmundson, and Orrin Thomas | 2011-10-03 |
Added images showing before and after to demonstrate the
program. Added Krause's collinearity diagram and
a brief explanation on the output options. Also added
a lien for example(s) to be added later.
|
| Debbie A. Cook | 2011-10-06 |
Corrected previous history entry and added references to glossary. Also
changed application names to bold type.
|
| Debbie A. Cook and Ken Edmundson | 2011-10-07 |
Removed glossary references from briefs. Also changed the definition
of angles to state right ascension and declination to be consistent
with the output.
|
| Ken Edmundson | 2011-10-14 |
Added internal default and minimum inclusive tags to global apriori
uncertainties.
|
| Ken Edmundson | 2011-10-18 |
Added Known Issues section and JigsawRejected flag issue.
|
| Debbie A. Cook | 2011-11-04 |
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.
|
|
Parameter Groups
Files
Solve Options
Maximum Likelihood Estimation
|
Name
|
Description
|
| MODEL1 | A maximum likelihood estimation model selection. |
| MAX_MODEL1_C_QUANTILE | Quantile of the |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model. |
| MODEL2 | A maximum likelihood estimation model selection. |
| MAX_MODEL2_C_QUANTILE | Quantile of the |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model. |
| MODEL3 | A maximum likelihood estimation model selection. |
| MAX_MODEL3_C_QUANTILE | Quantile of the |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model. |
Convergence Criteria
|
Name
|
Description
|
| SIGMA0 | standard deviation of unit weight
|
| MAXITS | iterations
|
Camera Pointing Options
|
Name
|
Description
|
| CKDEGREE |
Degree of polynomial fit to original camera angles
|
| CKSOLVEDEGREE |
The degree of the polynomial being fit to in the bundle adjustment
|
| CAMSOLVE | Camera pointing parameters to include in the bundle adjustment |
| TWIST | Solve for twist |
| OVEREXISTING | Fit polynomial over the existing pointing |
Spacecraft Options
|
Name
|
Description
|
| SPKDEGREE |
Degree of polynomial fit to original camera position
|
| SPKSOLVEDEGREE |
The degree of the camera position polynomial being fit to in the bundle
adjustment.
|
| SPSOLVE | Spacecraft position parameters to include in the adjustment |
| OVERHERMITE | Fit polynomial over the existing Hermite spline |
Parameter Uncertainties
Output Options
|
Name
|
Description
|
| FILE_PREFIX | output file prefix |
| BUNDLEOUT_TXT | Standard bundle output file - bundleout.txt
|
| OUTPUT_CSV | Outputs point and image data (body-fixed) to csv file - bundleout_points.csv
|
| RESIDUALS_CSV | Outputs image coordinate residuals to csv file - residuals.csv |
|
Files:
FROMLIST
Description
This file contains a list of all cubes in the control network
|
Type
| filename |
|
File Mode
| input |
|
Filter
|
*.txt *.lis
|
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.
|
Type
| filename |
|
File Mode
| input |
|
Internal Default
| none |
|
Filter
|
*.txt *.lis
|
Files:
CNET
Description
This file is a control network generated from programs such as
autoseed or qnet. It contains the control points
and associated measures.
|
Type
| filename |
|
File Mode
| input |
|
Filter
|
*.net
|
Files:
ONET
Description
This output file contains the updated control network with
the final coordinates of the control points and residuals for each
measurement.
|
Type
| filename |
|
File Mode
| output |
|
Filter
|
*.net
|
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:
RADIUS
Description
Select this option to solve for the local radius of each control
point. If this button is not turned on, the radii of the points
will not change from the cube's shape model.
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.
Solve Options:
METHOD
Description
Enter the desired method to use to solve the matrix. Methods will
vary in speed and accuracy. The default, SPARSE, is the preferred
method because of speed and memory usage.
|
Type
| string |
|
Default
|
SPARSE
|
|
Option List:
|
|
Option |
Brief |
Description |
| SPARSE | CholMod |
Solve with CholMod sparse decomposition.
|
| SPECIALK | SpecialK (dense) |
Solve with Cholesky dense decomposition.
|
| OLDSPARSE | Sparse matrix solver |
Solve the matrix using a sparse matrix solver.
Note: Sparse solver will not work on Sun/Solaris, QRD will be
used.
Exclusions
- MODEL1
- MODEL2
- MODEL3
- MAX_MODEL1_C_QUANTILE
- MAX_MODEL2_C_QUANTILE
- MAX_MODEL3_C_QUANTILE
|
|
Solve Options:
OUTLIER_REJECTION
Description
Select this option to perform automatic outlier detection and rejection.
Solve Options:
REJECTION_MULTIPLIER
Description
Rejection multiplier
Solve Options:
ERRORPROPAGATION
Description
Select this option to compute the variance-covariance matrix of the
parameters. The parameter uncertainties can be computed from this
matrix.
Maximum Likelihood Estimation:
MODEL1
Description
A maximum likelihood estimation model selection.
|
Type
| string |
|
Default
| NONE |
|
Option List:
|
|
Option |
Brief |
Description |
| NONE | None: no tier one maximumlikelihood estimation |
None: no tier one maximumlikelihood estimation
Exclusions
- MODEL2
- MODEL3
- MAX_MODEL1_C_QUANTILE
- MAX_MODEL2_C_QUANTILE
- MAX_MODEL3_C_QUANTILE
|
| HUBER | Huber: aproximates the L2 norm near 0, and the L1 norm therafter. Has one continuous derivative. |
A highly recommend model, that works well in many situations.
Exclusions
- REJECTION_MULTIPLIER
- OUTLIER_REJECTION
- ERRORPROPAGATION
|
| HUBER_MODIFIED | Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives. |
An adaptation of the hignly recomended Huber model that has two continuous derviatives.
Exclusions
- REJECTION_MULTIPLIER
- OUTLIER_REJECTION
- ERRORPROPAGATION
|
|
Maximum Likelihood Estimation:
MAX_MODEL1_C_QUANTILE
Description
The tweaking constant has differenct meaning depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recomended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recomended quantile: 0.7
Chen model: Residuals whose absolute values is greater than the tweaking constant are total ignored. Recomend quantile: > 0.9
|
Type
| double |
|
Default
|
0.5
|
|
Minimum
| 0
(exclusive)
|
|
Maximum
| 1
(exclusive)
|
Maximum Likelihood Estimation:
MODEL2
Description
A maximum likelihood estimation model selection.
|
Type
| string |
|
Default
| NONE |
|
Option List:
|
|
Option |
Brief |
Description |
| NONE | None: no tier two maximumlikelihood estimation |
None: no tier two maximumlikelihood estimation
Exclusions
- MODEL3
- MAX_MODEL2_C_QUANTILE
- MAX_MODEL3_C_QUANTILE
|
| HUBER | Huber: aproximates the L2 norm near 0, and the L1 norm therafter. Has one continuous derivative. |
A highly recommend 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 hignly recomended Huber model that has two continuous derviatives.
|
| WELSCH | Welsch: aprroximates the L2 norm near 0, but then decays exponentially to zero. |
This model reduces the significance of large residuals more agressively 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 aggresive method that intentionally removes the largest few percent of residuals |
This mehtod dramatically increases the influence of smaller residuals (beyond the L2 norm), while at the same time totally ignoring the largest few
percent of the residuals.
|
|
Maximum Likelihood Estimation:
MAX_MODEL2_C_QUANTILE
Description
The tweaking constant has differenct meaning depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recomended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recomended quantile: 0.7
Chen model: Residuals whose absolute values is greater than the tweaking constant are total ignored. Recomend quantile: > 0.9
|
Type
| double |
|
Default
|
0.5
|
|
Minimum
| 0
(exclusive)
|
|
Maximum
| 1
(exclusive)
|
Maximum Likelihood Estimation:
MODEL3
Description
A maximum likelihood estimation model selection.
|
Type
| string |
|
Default
| NONE |
|
Option List:
|
|
Option |
Brief |
Description |
| NONE | None: no tier three maximumlikelihood estimation |
None: no tier three maximumlikelihood estimation
Exclusions
|
| HUBER | Huber: aproximates the L2 norm near 0, and the L1 norm therafter. Has one continuous derivative. |
A highly recommend 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 hignly recomended Huber model that has two continuous derviatives.
|
| WELSCH | Welsch: aprroximates the L2 norm near 0, but then decays exponentially to zero. |
This model reduces the significance of large residuals more agressively 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 aggresive method that intentionally removes the largest few percent of residuals |
This mehtod dramatically increases the influence of smaller residuals (beyond the L2 norm), while at the same time totally ignoring the largest residuals.
|
|
Maximum Likelihood Estimation:
MAX_MODEL3_C_QUANTILE
Description
The tweaking constant has differenct meaning depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recomended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recomended quantile: 0.7
Chen model: Residuals whose absolute values is greater than the tweaking constant are total ignored. Recomend quantile: > 0.9
|
Type
| double |
|
Default
|
0.5
|
|
Minimum
| 0
(exclusive)
|
|
Maximum
| 1
(exclusive)
|
Convergence Criteria:
SIGMA0
Description
Converges on stabilization of Sigma0. Convergence occurs when the change
in sigma0 between iterations is less than or equal to Sigma0.
|
Type
| double |
|
Default
|
1.0e-10
|
|
Minimum
| 0
(exclusive)
|
Convergence Criteria:
MAXITS
Description
Maximum number of times to iterate. The application stops iterating at
MAXIT, or when convergence is reached.
|
Type
| integer |
|
Default
|
50
|
|
Minimum
| 1
(inclusive)
|
Camera Pointing Options:
CKDEGREE
Description
The degree of the polynomial fit to the original camera angles
and used to generate a priori camera angles for the first
iteration.
|
Type
| integer |
|
Default
|
2
|
|
Minimum
| 0
(inclusive)
|
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.
|
Type
| integer |
|
Default
|
2
|
|
Minimum
| 0
(inclusive)
|
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.
|
| 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.
|
| 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.
|
| 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
If this option is selected, the twist angle will be adjusted in the
bundle adjustment solution.
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
The degree of the polynomial fit to the original camera position
and used to generate a priori camera positions for the
first iteration.
|
Type
| integer |
|
Default
|
2
|
|
Minimum
| 0
(inclusive)
|
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.
|
Type
| integer |
|
Default
|
2
|
|
Minimum
| 0
(inclusive)
|
Spacecraft Options:
SPSOLVE
Description
This parameter is used to specify which, if any, spacecraft
position parameters to include in the adjustment.
|
Type
| string |
|
Default
|
NONE
|
|
Option List:
|
|
Option |
Brief |
Description |
| NONE | Don't solve for any spacecraft position parameters |
No spacecraft position parameters will be adjusted.
Exclusions
- SPKDEGREE
- SPKSOLVEDEGREE
- OVERHERMITE
|
| POSITION | Solve for the spacecraft positions |
Spacecraft positions will be adjusted in the solution, but
not the velocity or the acceleration.
|
| VELOCITIES | Solve for the spacecraft positions and velocities |
Spacecraft positions will be adjusted in the solution, as
well as the velocities of the spacecraft at each instance.
|
| ACCELERATIONS | Solve for the spacecraft positions, velocities, and accelerations |
Spacecraft positions will be adjusted in the solution, as well
as the velocities and accelerations of the spacecraft at each
instance.
|
| ALL | Solve for all coefficients in the polynomials fit to the camera position. |
If this option is selected, all coefficients of the solve
equation will be adjusted in the solution (SPKSOLVEDEGREE+1
coefficients)
|
|
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.
Parameter Uncertainties:
POINT_LATITUDE_SIGMA
Description
This optional value will be used as the global latitude
uncertainty for all points. Units are meters.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
POINT_LONGITUDE_SIGMA
Description
This optional value will be used as the global longitude
uncertainty for all points. Units are meters.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
POINT_RADIUS_SIGMA
Description
This value will be used as the global radius uncertainty for
all points. Units are meters.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
SPACECRAFT_POSITION_SIGMA
Description
This value will be used as the global uncertainty for spacecraft
coordinates. Units are meters.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
SPACECRAFT_VELOCITY_SIGMA
Description
This value will be used as the global uncertainty for spacecraft
velocity. Units are meters/second.
(meters)
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
SPACECRAFT_ACCELERATION_SIGMA
Description
This value will be used as the global uncertainty for
spacecraft acceleration. Units are meters/second/second.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
CAMERA_ANGLES_SIGMA
Description
This value will be used as the global uncertainty for camera
angles. Units are decimal degrees.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
CAMERA_ANGULAR_VELOCITY_SIGMA
Description
This value will be used as the global uncertainty for camera
angular velocity. Units are decimal degrees/second.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Parameter Uncertainties:
CAMERA_ANGULAR_ACCELERATION_SIGMA
Description
This value will be used as the global uncertainty for camera
angular acceleration. Units are decimal degrees/second/second.
|
Type
| double |
|
Internal Default
| none |
|
Minimum
| 0
(inclusive)
|
Output Options:
FILE_PREFIX
Description
output file prefix
|
Type
| string |
|
Internal Default
| none |
Output Options:
BUNDLEOUT_TXT
Description
Selection of this parameter flags generation of the standard
bundle output file
Output Options:
OUTPUT_CSV
Description
Selection of this parameter flags output of point and image data
(in body-fixed coordinates) to csv file.
Output Options:
RESIDUALS_CSV
Description
Selection of this parameter flags output of image coordinate
residuals to a csv file