Select Git revision
CHANGELOG.md
-
Christine Kim authored
* Replace affine6p transformation with numpy solution * Remove affine6p dependency * Update changelog and remove pip from conda-recipe
Christine Kim authored* Replace affine6p transformation with numpy solution * Remove affine6p dependency * Update changelog and remove pip from conda-recipe
To find the state of this project's repository at the time of any of these versions, check out the tags.
jigsaw.xml 106.27 KiB
<?xml version="1.0"?>
<application name="jigsaw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Application/application.xsd">
<brief>
Improves image alignment by updating camera geometry attached to cubes.
</brief>
<description>
<h3>Overview</h3>
<p>
The <b>jigsaw</b> application performs a photogrammetric bundle adjustment on a group of
overlapping, level 1 <def>cube</def>s from framing and/or line-scan cameras. The adjustment
simultaneously refines the selected image geometry information (camera pointing, spacecraft
position) and <def>control point</def> coordinates (x,y,z or lat,lon,radius) to reduce
boundary mismatches in mosaics of the images.
</p>
<p>
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.
</p>
<img src='assets/images/mdis2_Uncontrolled.png' alt='Before jigsaw (uncontrolled)' width='306' height='259' />
<img src='assets/images/mdis2_Controlled.png' alt='After jigsaw (controlled)' width='306' height='259' />
<p>
The <b>jigsaw</b> application assumes <b>spiceinit</b> or <b>csminit</b> has been run on the
input <def>cube</def>s so that camera information is included in the Isis <def>cube</def>
labels. In order to run the program, the user must provide a list of input <def>cube</def>s,
an input <def>control net</def>, the name of an output <def>control network</def>, and the
solve settings. The measured <def>sample</def>/<def>line</def> positions associated with the
<def>control measure</def>s in the network are not changed. Instead, the control points and
camera information are adjusted. <b>jigsaw</b> outputs a new <def>control network</def> 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 <def>a priori</def> in the
<def>control network</def>, and their final states are tagged as <def>adjusted</def>.
Updated camera information is only written to the <def>cube</def> labels if the bundle
converges and the <b>UPDATE</b> parameter is selected.
</p>
<p>
In order to apply bundle values using <b>ADJUSTMENT_INPUT</b>, only the option <b>FROMLIST</b>
must be set. If the <b>ADJUSTMENT_INPUT</b> is set to an HDF5 file containing bundle adjustment values
(usually the HDF5 output file from <b>OUTADJUSTMENTH5</b>), those values can be applied to the
<def>cube</def> labels. The adjustment file entails a group of HDF5 datasets where each dataset
contains the instrument pointing and position for each <def>cube</def>. The dataset key is composed
of the <def>cube</def> serial number and the table name, either "InstrumentPointing" or
"InstrumentPosition", separated by a forward slash "/". For example:
</p>
<pre>
SerialNumber: MRO/CTX/1016816309:030
Dataset key for instrument pointing: MRO/CTX/1016816309:030/InstrumentPointing
</pre>
<p>
The input control net may be created by finding each image footprint with <b>footprintinit</b>,
computing the image overlaps with <b>findimageoverlaps</b>, creating guess measurements with
<b>autoseed</b>, then registering them with <b>pointreg</b>.
</p>
<p>
Optional output files can be enabled to provide more information for analyzing the results of
the bundle. <b>BUNDLEOUT_TXT</b> 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 be written to a separate machine readable
file with the <b>IMAGESCSV</b> option and likewise for the point statistics with the
<b>OUTPUT_CSV</b> option. <b>RESIDUALS_CSV</b> provides a table of the measured image
coordinates, the final <def>sample</def>, <def>line</def>, and overall residuals
of every control measure in both millimeters and pixels. <b>OUTADJUSTMENTH5</b> stores bundle
adjustment values in an HDF5 file. Currently, only ISIS adjustment values are saved to file so
if all the cubes in the <b>FROMLIST</b> contain a CSM state blob then the <i>adjustment_out.h5</i>
file will be created but empty.
</p>
<h3>Observation Equations</h3>
<p>
The <b>jigsaw</b> application attempts to minimize the reprojective error within the control network.
For each control measure and its control point in the control network, the reprojective error is
the difference between the control measure's image coordinate (typically determined from image
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Automatic_Registration">registration</a>)
and the image coordinate that the control point projects to through the camera model. We also
refer to the reprojective error as the measure residual. So, for each control measure we can
write an observation equation:
</p>
<pre>
reprojective_error = control_measure - camera(control_point)
</pre>
<p>
The camera models use additional parameters such as the instrument position and pointing to compute
what image coordinate a control point projects to; so, the camera function in our observation
equation can be written more explicitly as:
</p>
<pre>
reprojective_error = control_measure - camera(control_point, camera_parameters)
</pre>
<p>
The primary decision when using the jigsaw application is which parameters to include
as variables in the observation equations. Later sections will cover what parameters can
be included and common considerations when choosing them.
</p>
<p>
By combining all the observation equations for all the control measures in the control network
we can create a system of equations. Then, we can find the camera parameters and control point
coordinates that minimize the sum of the squared reprojective errors using the system of equations.
</p>
<p>
Below is an example system of observation equations for a control network with three images
(A, B, and C) and three control points (1, 2, and 3). Control point 1 has control measures
on images A and B, control point 2 has control measures on images B and C, and control
point 3 has control measures on images A, B, and C. <code>control_point_1</code> is the
ground coordinate of control point 1, <code>camera_parameters_A</code> are the camera
parameters for image A's camera model, <code>camera_A</code> is the projection function
for image A's camera model, and <code>control_measure_1_A</code> is the image coordinate of
control point 1's control measure on image A.
</p>
<img src='assets/images/simple_network.png' alt='Simple control network with 3 images and 3 points' width='400' height='412' />
<pre>
|| control_measure_1_A - camera_A(control_point_1, camera_parameters_A) ||
|| control_measure_1_B - camera_B(control_point_1, camera_parameters_B) ||
|| control_measure_2_B - camera_B(control_point_2, camera_parameters_B) ||
total_error = || control_measure_2_C - camera_C(control_point_3, camera_parameters_C) ||
|| control_measure_3_A - camera_A(control_point_3, camera_parameters_A) ||
|| control_measure_3_B - camera_B(control_point_3, camera_parameters_B) ||
|| control_measure_3_C - camera_C(control_point_3, camera_parameters_C) ||
</pre>
<p>
If the camera projection functions were linear, we could easily minimize this system. Unfortunately,
the camera projection functions are quite non-linear; so, we linearize and
iteratively compute updates that will gradually approach a minimum. The actual
structure of the observation equations is complex and vary significantly
based on the dataset and which parameters are being solved for. If the a-priori parameter
values are sufficiently far away from a minimum, the updates can even diverge. So,
it is important to check your input data set and solve options. Tools like the
<b>cnetcheck</b> application and <b>jigsaw</b> options like <b>OUTLIER_REJECTION</b> can help.
</p>
<p>
As with all iterative methods convergence criteria is important. The default for
the <b>jigsaw</b> application is to converge based on the sigma0 value. This is a
complex value that includes many technical details outside the scope of this
documentation. In a brief, it is a measurement of the remaining error in a typical
observation. The sigma0 value is also a good first estimate of the quality
of the solution. If the only errors in the control network are purely random noise,
then the sigma0 should be 1. So, if the sigma0 value for your solution is
significantly larger than 1, then it is an indication that there is an unusual
source of error in your control network such as poorly registered control measures
or poor a-priori camera parameters.
</p>
<h3>Solve Options</h3>
<p>
Choosing solve options is difficult and often requires experimentation. As a general rule,
the more variation in observation geometry in your dataset and the better distributed your
control measures are across and within images, the more parameters you can solve for.
The following sections describe the different options you can use when running the
<b>jigsaw</b> application. Each section will cover a subset of the options explaining
common situations in which they are used and how to choose values for them.
</p>
<h4>Control Network</h4>
<p>
Control networks can contain a wide variety of information, but the primary
concern for choosing solve options is the presence or lack of ground control.
</p>
<p>
Most control networks are generated by finding matching points between groups
of images. This defines a relative relationship between the images, but it does not
relate those images to the actual planetary surface; so, additional information is needed
to absolutely control the images. In terrestrial work, known points on the ground
are identified in the imagery via special target markers, but this is usually not
possible with planetary data. Instead, we relate the images to an additional dataset such
as a basemap or surface model. This additional relationship is called ground
control. Sometimes, there are not sufficient previous data products to provide accurate
ground control or ground will be done as a secondary step after successfully running jigsaw
on a relatively controlled network. In both these cases, we say that ground
control is not present.
</p>
<p>
If your control network does not have ground control, then we recommended that
you hold the instrument position fixed and only solve for the instrument pointing.
This is because without ground control, the instrument position and pointing can
become correlated and there will be multiple minimums for the observation equations.
We recommend holding the instrument position fixed because a-priori data for it generally is more
accurate than the instrument pointing.
</p>
<h4>Sensor Types</h4>
<h5>Framing</h5>
<p>
Framing sensors are the most basic type or sensor to use with <b>jigsaw</b>. The entire image is exposed at the same
time, so there is only a single position and pointing value for each image. With these datasets
you will want to use the either NONE or POSITIONS for the <b>SPSOLVE</b> parameter and ANGLES
for the <b>CAMSOLVE</b> parameter.
</p>
<h5>Pushbroom</h5>
<p>
Pushbroom sensors require additional consideration because the image is exposed over a period of
time and therefore, position and pointing are time dependent. The <b>jigsaw</b> application handles this
by modeling the position and pointing as polynomial functions of time. Polynomial functions
are fit to the a-priori position and pointing values on each image. Then, each iteration updates
the polynomial coefficients. Setting <b>CAMSOLVE</b> to velocities will use first
degree, linear, polynomials and setting <b>CAMSOLVE</b> to accelerations will use
second degree, quadratic, polynomials for the pointing angles. For most pushbroom observations,
we recommend using second degree polynomials, solving for accelerations.
</p>
<p>
There are also a variety of parameters that allow for more precise control over the polynomials used
and the polynomial fitting process. The <b>OVERHERMITE</b> parameter changes the initial polynomial
setup so that it does not replace the a-priori position values. Instead, the polynomial starts out as a
zero polynomial and is added to the original position values. This effectively adds the noise
from the a-priori position values to the constant term of the polynomial. The <b>OVEREXISTING</b>
parameter does the same thing for pointing values. These two options allow you to preserve complex
variation like jitter. We recommend enabling these options for jittery images and very long
exposure pushbroom images.
</p>
<p>
The <b>SPSOLVE</b> and <b>CAMSOLVE</b> parameters only allow up to a second degree
polynomial. To use a higher degree polynomial for pointing values, set <b>CAMSOLVE</b> to ALL and then set
the <b>CKDEGREE</b> parameter to the degree of the polynomial you want to fit over the original
pointing values and set the <b>CKSOLVEDEGREE</b> parameter to the degree of the polynomial you want
to solve for. Setting the <b>SPSOLVE</b>, <b>SPKDEGREE</b>, and <b>SPKSOLVEDEGREE</b> parameters
in a similar fashion gives fine control over the polynomial for postion values.
For example, if you want to fit a 3rd degree polynomial for the position values
and then solve for a 5th degree polynomial set <b>SPSOLVE</b> to ALL, <b>SPKDEGREE</b> to 3,
and <b>SPKSOLVEDEGREE</b> to 5.
These parameters should only be used when you know the a-priori position and/or pointing values are
well modeled by high degree polynomials. Using high degree polynomials can result in extreme
over-fitting where the solution looks good in areas near control measures and control points but
is poor in areas far from control measures and control points. The end behavior, the solution at
the start and end of images, becomes particularly unstable as the degree of the polynomial used
increases.
</p>
<h5>Synthetic Aperture Radar</h5>
<p>
Running the <b>jigsaw</b> application with synthetic aperture radar (SAR) images is different because
SAR sensors do not have a pointing component. Thus, you can only solve for the sensor position when
working with SAR imagery. SAR imagery also tends to have long duration images which can
necessitate using the <b>OVERHERMITE</b>, <b>SPKDEGREE</b>, and <b>SPKSOLVEDEGREE</b> parameters.
</p>
<h4>Parameter Sigmas</h4>
<p>
The initial, or a-priori, camera parameters and control points all contain error, but it is not equally
distributed. The <b>jigsaw</b> application allows users to input a-priori sigmas for different parameters
that describe how the initial error is distributed. The parameter sigmas are also sometimes
called uncertainties. Parameters with higher a-priori sigma values
are allowed to vary more freely than those with lower a-priori sigma values. The a-priori sigma values
are not hard constraints that limit how much parameters can change, but rather relative accuracy estimates
that adjust how much parameters change relative to each other.
</p>
<p>
The <b>POINT_LATITUDE_SIGMA</b>, <b>POINT_LONGITUDE_SIGMA</b>, and <b>POINT_RADIUS_SIGMA</b>
parameters set the a-priori sigmas for control points <i>that do not already have a ground source</i>.
If a control point already has a ground source, such as a basemap or DEM, then it already has
internal sigma values associated with it or is held completely fixed. The exact behavior depends
on how the control points were created, a topic outside the scope of this documentation.
These sigmas are in meters on the ground, so the latitude
and longitude sigmas are uncertainty in meters in the latitude and longitude directions. Generally, you will
choose values for these parameters based on the resolution of the images and a visual comparison with
other datasets. The radius sigma is also usually higher than the latitude and longitude sigmas
because there is less variation of the viewing geometry with respect to the radius.
</p>
<p>
The <b>CAMERA_ANGLES_SIGMA</b>, <b>CAMERA_ANGULAR_VELOCITY_SIGMA</b>, and
<b>CAMERA_ANGULAR_ACCELERATION_SIGMA</b> parameters set the a-priori sigmas for the instrument pointing.
Similarly, the <b>SPACECRAFT_POSITION_SIGMA</b>, <b>SPACECRAFT_VELOCITY_SIGMA</b>,
and <b>SPACECRAFT_ACCELERATION_SIGMA</b> parameters set the a-priori sigmas for the instrument position.
The sigma for each parameter is only used if you are solving for that parameter. For example,
if you are solving for angular velocities and not solving for any adjustments to the instrument
position you would enter <b>CAMERA_ANGLES_SIGMA</b> and <b>CAMERA_ANGULAR_VELOCITY_SIGMA</b>.
Finding initial values for these sigmas is challenging as SPICE does not have a way to specify them.
Some teams will publish uncertainties for their SPK and CK solutions in separate documentation or
the kernel comments, the
<a href="https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/ug/commnt.html">commnt</a> utility
will read the comments on a kernel file. The velocity
and acceleration sigmas are in meters per second and meters per second squared respectively
(degrees per second and degrees per second squared for angles). So, the velocity sigma will
generally be smaller than the position sigma and the acceleration sigma will be smaller than
the velocity sigma.
</p>
<p>
Coming up with a-priori sigma values can be quite challenging, but the <b>jigsaw</b> application
has the ability to produce updated sigma values for your solution. By enabling the <b>ERRORPROPAGATION</b>
parameter, you will get a-posteriori (updated) sigmas for each control point and camera parameter
in your solution. This information is helpful for analyzing and communicating the quality of
your solution. Computing the updated sigmas, imposes a significant computation and memory
overhead, so it is recommended that you enable <b>ERRORPROPAGATION</b> parameter after you
have run bundle adjustment with all of your other settings and gotten a satisfactory result.
</p>
<h4>Community Sensor Model</h4>
<p>
The <b>jigsaw</b> options that control which parameters to solve for only work with ISIS
camera models. When working with community sensor model (CSM) camera models, you will
need to manually specify the camera parameters to solve for. This is because the
<a href="https://github.com/ngageoint/csm">CSM API</a> only exposes a
generic camera parameter interface that may or may not be related to the physical state of the
sensor when an image was acquired. The <b>CSMSOLVELIST</b> option allows for an explicit list
of model parameters. You can also use the <b>CSMSOLVESET</b> or <b>CSMSOLVEYPE</b> options
to choose your parameters based on how they are labeled in the model.
</p>
<p>
Each CSM plugin library defines its own set of adjustable parameters. See the
documentation for the CSM plugin library you are using for what different adjustable parameters
are and when to solve for them. The sigma values for parameters are also included in the CSM plugin
library and image support data (ISD). So, you do not need to specify camera parameter sigmas when
working with CSM camera models; however, you still need to specify control point coordinate sigmas.
For convenience, the <b>csminit</b> application adds information about all of the adjustable
parameters to the image label.
</p>
<p>
The CSM API natively uses a rectangular coordinate system. So, we recommend that
you have the <b>jigsaw</b> application perform calculations in a rectangular coordinate system
when working with CSM camera models. To do this, set the <b>CONTROL_POINT_COORDINATE_TYPE_BUNDLE</b>
parameter to RECTANGULAR. You can also set the
<b>CONTROL_POINT_COORDINATE_TYPE_REPORTS</b> parameter to RECTANGULAR to see the
results in a rectangular coordinate system, but this is a matter of personal preference
and will not impact the results.
</p>
<h4>Robustness</h4>
<p>
Much of the mathematical underpinning of the <b>jigsaw</b> application expects that the error
in the input data is purely random noise. If there are issues with control measures being
poorly registered or blatantly wrong, it can produce errors in the output solution. Generally,
users should identify and correct these errors before accepting the output of the <b>jigsaw</b>
application, but there are a handful of parameters than can be used to make your solutions more
robust to them.
</p>
<p>
The <b>OUTLIER_REJECTION</b> parameter adds a simple calculation to each iteration that looks
for potential outliers. The median average deviation (MAD) of the measure residuals is computed
and then any control measure whose residual is larger than a multiple of the MAD of the measure residuals
is flagged as rejected. Control measures that are flagged as rejected are removed
from future iterations. The multiplier for the rejection threshold is set by the
<b>REJECTION_MULTIPLIER</b> parameter. The residuals for rejected measures are re-computed
after each iteration and if they fall back below the threshold they are un-flagged
and included again. Enabling this parameter can help eliminate egregious errors in your control
measures, but it is not very sensitive. It is also not selective about what is rejected.
So, it is possible to introduce islands into your control network when the <b>OUTLIER_REJECTION</b>
parameter is enabled. For this reason, always check your output
control network for islands with the <b>cnetcheck</b> application when using the
<b>OUTLIER_REJECTION</b> parameter. Choosing an appropriate value for the <b>REJECTION_MULTIPLIER</b>
is about deciding how aggressively you want to eliminate control measures. The default value
will only remove extreme errors, but lower values will remove control measures that are not
actually errors. It is recommended that you start with the default value and then if you want to remove
more potential outlier, reduce it gradually. If you are seeing too many rejections with the
default value, then your input data is extremely poor and you should investigate other methods
of improving it prior to running the <b>jigsaw</b> application. You can use the <b>qnet</b>
application to examine and improve your control network. You can use the <b>qtie</b> application
to manually adjust your a-priori camera parameters.
</p>
<p>
The <b>jigsaw</b> application also has the ability to set sigmas for individual control
measures. Similar to the sigmas for control points and parameters, these are a measurement
of the relative quality of each control measure. Control measures with a higher sigma have less
impact on the solution than control measures with a lower sigma. Most control networks have
a large number of control measures and it is not realistic to manually set the sigma for
each one. So, the <b>jigsaw</b> application can instead use maximum likelihood estimation (MLE)
to estimate the sigma for each control measure each iteration. There are a variety of models to
choose from, but all of them start each control measure's sigmas at 1. Then, if the control
measure's reprojective error falls beyond a certain quantile the sigma will be increased.
This reduces the impact of poor control measures in a more targeted fashion than simple
outlier rejection. In order to produce good results, though, a high density of control measures
is required to approximate the true reprojective error probability distributions. Some of the
modules used with MLE can set a measure's sigma to infinity, effectively removing it from the
solution. Similar to when using the <b>OUTLIER_REJECTION</b> parameter, this can create islands
in your control network. If you are
working with a large amount of data and want a robustness option that is more targeted and
customizable than outlier rejection, then using the MLE parameters is a good option. See the
<b>MODEL1</b>, <b>MODEL2</b>, <b>MODEL3</b>, <b>MAX_MODEL1_C_QUANTILE</b>,
<b>MAX_MODEL2_C_QUANTILE</b>, and <b>MAX_MODEL3_C_QUANTILE</b> parameter documentation for
more information.
</p>
<h4>Observation Mode</h4>
<p>
Sometimes multiple images are exposed at the same time. They could be exposed by different sensors
on the same spacecraft or they could be read out from different parts of the same sensor. When
this happens, many of the camera parameters for the two images are the same. By default, the
<b>jigsaw</b> application has a different set of camera parameters for each image. To allow
different images that are captured simultaneously to share camera parameters enable the
<b>OBSERVATIONS</b> parameter. This will combine all of the images with the same observation
number into a single set of parameters. By default the observation number for an image is the
same as the serial number. For some instruments, there is an extra keyword in their serial number
translation file called <code>ObservationKeys</code>. This specifies the number of keys from the
serial number to use in the observation number. For example JunoCam serial numbers consist of
<code>SpacecraftName/InstrumentId/StartTime/FrameNumber/FilterName</code> and it has
<code>ObservationKeys = 4</code>. So, the observation number for a JunoCam image is the first
four keys of its serial number, <code>SpacecraftName/InstrumentId/StartTime/FrameNumber</code>.
Thus, if two JunoCam images have the same StartTime and FrameNumber but different FilterNames
and the <b>OBSERVATIONS</b> parameter is enabled, then they will share camera parameters.
To check if observation mode
is setup for use with your data set, check the serial number translation file located in
<code>$ISISROOT/appdata/translations</code>.
</p>
<h3>References</h3>
<p>
For information on what the original <b>jigsaw</b> code was based on checkout
<a href="https://www.rand.org/pubs/notes/N3330.html">Rand Notebook</a>
</p>
<p>
A more technical look at the <b>jigsaw</b> application can be found in
<i>Jigsaw: The ISIS3 bundle adjustment for extraterrestrial photogrammetry</i>
by K. L. Edmundson et al.
</p>
<p>
A rigorous development of how the <b>jigsaw</b> application works can be found
in these
<a href="https://earthsciences.osu.edu/sites/default/files/2019-12/OSU_Adjustment_Notes_Part_1.pdf">lecture notes</a>
from Ohio State University.
</p>
<h3>Known Issues</h3>
<blockquote>
<b>Running jigsaw with a control net containing <i>JigsawRejected</i>
flags may result in bundle failure</b>
<p>When running <b>jigsaw</b> with <i>Outlier Rejection</i> turned on,
control points and/or control measures may be flagged as
<i>JigsawRejected</i> in the output control net file. If this output net
file is then used in a subsequent <b>jigsaw</b> run, these points and
measures will be erroneously ignored, potentially causing the bundle
adjustment to fail.
<blockquote>
<b>--Workarounds</b>
<ol>
<li>Run jigsaw with <i>Outlier Rejection</i> <b>off</b>.</li>
<li>Do not use the output control net file in subsequent jigsaw runs.</li>
<li>Convert the output control net file from binary to PVL and back using
<i><b>cnetbin2pvl</b></i> and <i><b>cnetpvl2bin</b></i>. This will
clear the <i>JigsawRejected</i> flags.</li>
</ol>
</blockquote>
</p>
</blockquote>
<blockquote>
<b>Solving for the target body radii (triaxial or mean) is NOT possible and
likely increases error in the solve.</b>
<p>
With the current jigsaw implementation, it is NOT possible to individually
solve for either the mean or triaxial radii as separate calculations in
the bundle adjustment. More specifically, the target body radii have no
effect when solving for individual points and thus cannot be solved for in the bundle.
A local radii solve is already part of the sequence of equations that <b>jigsaw</b>
uses to compute various partial derivatives to populate the solve matrix.
A separate mean or triaxial radii solve can be applied to the target body
and the partials from this separate application are added to the
solve matrix. This option adds additional computation time to <b>jigsaw</b>
and creates additional uncertainty/error in the bundle adjust. We advise
the mean and triaxial radii solve be avoided.
</p>
<p>
If you are trying to generate a spheroid from a control network there are
other programs that can do this for you. An easier but more naive method
is ingesting the <i>OUTPUT_CSV</i> from your network, gather local radii
information from those points, then generate a spheroid from those local radii.
</p>
</blockquote>
</description>
<category>
<categoryItem>Control Networks</categoryItem>
</category>
<seeAlso>
<applications>
<item>deltack</item>
<item>qnet</item>
</applications>
</seeAlso>
<history>
<change name="Jeff Anderson" date="2007-04-27">
Original version
</change>
<change name="Steven Lambright" date="2007-07-23">
Changed category to Control Networks and corrected XML bugs
</change>
<change name="Debbie A. Cook" date="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.
</change>
<change name="Christopher Austin" date="2008-07-03">
Cleaned the Bundle Adjust memory leak and fixed the app tests.
</change>
<change name="Tracie Sucharski" date="2009-04-08">
Added date to the Jigged comment in the spice tables.
</change>
<change name="Tracie Sucharski" date="2009-04-22">
If updating pointing, delete the CameraStatistics table from labels.
</change>
<change name="Mackenzie Boyd" date="2009-07-23">
Modified program to write history to input cubes.
</change>
<change name="Debbie A. Cook" date="2010-08-12">
Commented out Heldlist until mechanism in place to enter individual
image parameter constraints.
</change>
<change name="Debbie A. Cook" date="2010-08-12">
Merged Ken Edmundson version with system and binary control net.
</change>
<change name="Debbie A. Cook" date="2011-06-14">
Modified code to prevent updates to cube files in held list.
</change>
<change name="Debbie A. Cook" date="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.
</change>
<change name="Debbie A. Cook, Ken Edmundson, and Orrin Thomas" date="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.
</change>
<change name="Debbie A. Cook" date="2011-10-06">
Corrected previous history entry and added references to glossary. Also
changed application names to bold type.
</change>
<change name="Debbie A. Cook and Ken Edmundson" date="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.
</change>
<change name="Ken Edmundson" date="2011-10-14">
Added internal default and minimum inclusive tags to global apriori
uncertainties.
</change>
<change name="Ken Edmundson" date="2011-10-18">
Added Known Issues section and JigsawRejected flag issue.
</change>
<change name="Debbie A. Cook" date="2011-11-04">
Added minimums to parameters, corrected SOLVEDEGREE description, and
added to the camsolve option descriptions in response to Mantis
issue #514.
</change>
<change name="Ken Edmundson" date="2011-12-20">
Added REJECTION_MULTIPLIER to interface, part of Mantis issue #637.
</change>
<change name="Ken Edmundson" date="2012-01-19">
Added SPKDEGREE and SPKSOLVEDEGREE; changed name of SOLVEDEGREE to
CKSOLVEDEGREE.
</change>
<change name="Ken Edmundson" date="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.
</change>
<change name="Ken Edmundson" date="2014-07-09">
Added USEPVL and SC_PARAMETERS parameters.
</change>
<change name="Jeannie Backer" date="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.
</change>
<change name="Ken Edmundson" date="2015-09-05">
Added preliminary target body functionality. Added SOLVETARGETBODY and TB_PARAMETERS.
</change>
<change name="Jesse Mapel" date="2016-08-16">
Added a connection to allow jigsaw to surface exceptions from BundleAdjust. Fixes #2302
</change>
<change name="Jeannie Backer" date="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.
</change>
<change name="Ian Humphrey" date="2016-08-22">
Reviewed documentation and updated small spelling and grammar errors. References #4226.
</change>
<change name="Adam Paquette" date="2016-08-31">
Updated how jigsaw handles its prefix parameter along with a small documentation change. Fixes #4309.
</change>
<change name="Jesse Mapel" date="2016-09-02">
Updated how input parameters are output when using multiple sensor solve settings.
Fixes #4316.
</change>
<change name="Ian Humphrey" date="2016-09-22">
Output from jigsaw will again provide "Validating network" and "Validation complete" messages
to inform user that their control network has been validated. Fixes #4313.
</change>
<change name="Ian Humphrey" date="2016-10-05">
When running jigsaw with error propagation turned on, the correlation matrix file,
inverseMatrix.dat, is no longer generated. Fixes #4315.
</change>
<change name="Tyler Wilson" date="2016-10-06">
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.
</change>
<change name="Ian Humphrey" date="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.
</change>
<change name="Ian Humphrey" date="2016-10-25">
Added the "Generating report files" and Rejected_Measures keyword back to jigsaw's standard
output. Fixes #4461. Fixed spacing in standard output. Fixes #4462, #4463."
</change>
<change name="Ian Humphrey" date="2016-10-26">
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.
</change>
<change name="Makayla Shepherd" date="2016-10-26">
Removed the underscores from the new parameters IMAGESCSV and TBPARAMETERS.
</change>
<change name="Ian Humphrey" date="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.
</change>
<change name="Ken Edmundson" date="2016-11-17">
Output control net will be now be written regardless of whether bundle converges. Fixes #4533.
</change>
<change name="Ken Edmundson" date="2017-01-17">
Updated description and brief for SOLVETARGETBODY and TBPARAMETERS.
</change>
<change name="Summer Stapleton" date="2017-08-09">
Fixed bug where an invalid control net was not throwing exception. Fixes #5068.
</change>
<change name="Ken Edmundson" date="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.
</change>
<change name="Debbie A. Cook" date="2018-06-04">
(BundleXYZ modified on 2017-09-11) Added options for outputting
and/or solving for body-fixed x/y/z instead of lat/lon/radius.
References #501.
</change>
<change name="Debbie A. Cook" date="2018-06-04">
(BundleXYZ modified on 2017-09-17) Fixed a problem in the
xml that was causing the input parameters to be omitted from
the history. References #501.
</change>
<change name="Debbie A. Cook" date="2018-06-04">
(BundleXYZ modified on 2018-03-18) Fixed a problem in the xml
that excluded entry of values for latitudinal point sigmas when the
coordinate type for reports was set to Rectangular and vice versa.
References #501.
</change>
<change name="Tyler Wilson" date="2019-05-17">
Cleaned up the bundleout.txt file and added new information in the header.
Fixes #3267.
</change>
<change name="Ken Edmundson and Debbie A. Cook" date="2019-05-20">
Added initial support for simultaneous LIDAR data. Added LIDARDATA, OLIDARDATA,
and OLIDARFORMAT arguments.
</change>
<change name="Aaron Giroux" date="2019-12-19">
Added SCCONFIG parameter which allows users to pass in a pvl file with different
settings for different instrumentIDs. Added logic into the observationSolveSettings
function to construct BundleObservationSolveSettings objects based off of the settings
in the pvl file.
</change>
<change name="Adam Paquette" date="2020-12-23">
Added a warning when solving for target body radii/radius that is output to
the application log. Updated the documentation to include the original
rand notebook that jigsaw was based on. Also added a section in the documentation
describing the target body radii solve issue.
</change>
<change name="Jesse Mapel and Kristin Berry" date="2021-06-29">
Added the ability to bundle adjust images that use a CSM based model. New parameters
CSMSOLVESET, CSMSOLVELIST, and CSMSOLVEYPE were added to specify which parameters to
solve for. These parameters can also be used as keys in the SCCONFIG file.
Modified images CSV file to generate a separate CSV for each sensor being adjusted.
</change>
<change name="Jesse Mapel" date="2021-11-09">
Fixed measure residual reporting in bundleout.txt file to match the residuals
reported in the residuals CSV file.
</change>
<change name="Ken Edmundson" date="2024-10-21">
Modified xml so that the RADIUS on/off radio button is excluded when the
solution coordinate type is set to Rectangular. Originally added to UofA
code on 2019-07-30.
</change>
</history>
<groups>
<group name="Files">
<parameter name="FROMLIST">
<type>filename</type>
<fileMode>input</fileMode>
<brief>
List of cubes in the input control network
</brief>
<description>
This file contains a list of all <def>cube</def>s in the <def>control network</def>
</description>
<filter>
*.txt *.lis
</filter>
</parameter>
<parameter name="HELDLIST">
<type>filename</type>
<internalDefault>none</internalDefault>
<fileMode>input</fileMode>
<brief>
List of (non-overlapping) cubes to hold in the adjustment
</brief>
<description>
This file contains a list of all <def>cube</def>s 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.
<i>Note that held images must not overlap each other to work properly.</i>
</description>
<filter>
*.txt *.lis
</filter>
</parameter>
<parameter name="CNET">
<type>filename</type>
<fileMode>input</fileMode>
<brief>
Input control network
</brief>
<description>
This file is a <def>control network</def> generated from programs such as
<b>autoseed</b> or <b>qnet</b>. It contains the <def>control point</def>s
and associated measures.
</description>
<exclusions>
<item>ADJUSTMENT_INPUT</item>
</exclusions>
<filter>
*.net
</filter>
</parameter>
<parameter name="ONET">
<type>filename</type>
<fileMode>output</fileMode>
<brief>
Output control network
</brief>
<description>
This output file contains the updated <def>control network</def> with
the final coordinates of the <def>control point</def>s and residuals for each
measurement.
</description>
<exclusions>
<item>ADJUSTMENT_INPUT</item>
</exclusions>
<filter>
*.net
</filter>
</parameter>
<parameter name="LIDARDATA">
<type>filename</type>
<internalDefault>none</internalDefault>
<fileMode>input</fileMode>
<brief>
Input Lidar Point File - requires SPSOLVE to be turned on
</brief>
<description>
This file is a <def>lidar point data</def> generated from <b>lrolola2isis.cpp</b>.
It contains <def>lidar control point</def>s and associated measures for simultaneous images.
If <def>lidar point data</def> are used, SPSOLVE must be turned on (anything besides NONE)
</description>
<exclusions>
</exclusions>
<filter>
*.dat *.json
</filter>
</parameter>
<parameter name="OLIDARDATA">
<type>filename</type>
<internalDefault>none</internalDefault>
<fileMode>output</fileMode>
<brief>
Output lidar data file - requires SPSOLVE to be turned on
</brief>
<description>
This output file contains the adjusted <def>lidar data</def> with
the final coordinates of the <def>lidar point</def>s and residuals for each
measurement.
</description>
<filter>
*.dat *.json
</filter>
</parameter>
<parameter name="OLIDARFORMAT">
<type>string</type>
<brief> Output lidar data file format</brief>
<default>
<item>BINARY</item>
</default>
<description>
Output lidar data file format.
</description>
<list>
<option value="BINARY">
<brief> Output lidar data in binary format</brief>
<description>
Output lidar data in binary format.
</description>
</option>
<option value="JSON">
<brief> Output lidar data in json format </brief>
<description>
Output lidar data in json format.
</description>
</option>
</list>
</parameter>
<parameter name="SCCONFIG">
<exclusions>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
<item>CAMSOLVE</item>
<item>OVEREXISTING</item>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
<item>SPSOLVE</item>
<!-- <item>TWIST</item> -->
<item>OVERHERMITE</item>
<item>CAMERA_ANGLES_SIGMA</item>
<item>CAMERA_ANGULAR_VELOCITY_SIGMA</item>
<item>CAMERA_ANGULAR_ACCELERATION_SIGMA</item>
<item>SPACECRAFT_POSITION_SIGMA</item>
<item>SPACECRAFT_VELOCITY_SIGMA</item>
<item>SPACECRAFT_ACCELERATION_SIGMA</item>
</exclusions>
<type>filename</type>
<fileMode>input</fileMode>
<brief>
File containing Camera/Spacecraft parameters
</brief>
<description>
This file contains the Camera/Spacecraft parameters to use when processing
images from different sensors. This file should be in PVL format. It should
contain an object called SensorParameters with one group per spacecraft/instrument
combination. The SpacecraftName and InstrumentId keywords in the Instrument group
of an image file are used to create the name of each group in the PVL file. The
group pertaining to each spacecraft/instrument should contain the keyword/value
pairs needed to process images taken with that sensor: CKDEGREE, CKSOLVEDEGREE,
CAMSOLVE, TWIST, OVEREXISTING, SPKDEGREE, SPKSOLVEDEGREE, SPSOLVE, OVERHERMITE,
SPACECRAFT_POSITION_SIGMA, SPACECRAFT_VELOCITY_SIGMA, SPACECRAFT_ACCELERATION_SIGMA,
CAMERA_ANGLES_SIGMA, CAMERA_ANGULAR_VELOCITY_SIGMA, CAMERA_ANGULAR_ACCELERATION_SIGMA.
If any of these keywords are missing, then their defaults will be used. There is
an example template at $ISISROOT/appdata/templates/jigsaw/SensorParameters.pvl that can be
used as a guide.
</description>
<filter>
*.pvl
</filter>
</parameter>
</group>
<group name="Solve Options">
<parameter name="OBSERVATIONS">
<brief> Keep instances of the same observation in different cube files the same</brief>
<description>
This option will solve for <def>SPICE</def> 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
<def>serial number</def> of the <def>cube</def>, and a single <def>cube</def>
is an observation. However, for the Lunar Orbiter mission, an image has a defined
observation number that is a substring of its <def>serial number</def>. 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.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
</parameter>
<parameter name="RADIUS">
<brief> Solve for local radii of points</brief>
<description>
Select this option to solve for the local radius of each <def>control
point</def>. If this button is not turned on, the radii of the points
will not change from the <def>cube</def>'s shape model.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
<inclusions>
<item>
POINT_RADIUS_SIGMA
</item>
</inclusions>
<exclusions>
<item>ADJUSTMENT_INPUT</item>
</exclusions>
</parameter>
<parameter name="UPDATE">
<brief> Update cube label</brief>
<description>
When this option is selected, the application will update the labels
of the individual <def>cube</def>s in the FROMLIST with the final values
from the solution if the adjustment converges. The results are written
to the <def>SPICE</def> blobs attached to the cube, overwriting the previous
values. If this option is not selected, the <def>cube</def> files are not
changed. All other output files are still created.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
</parameter>
<parameter name="OUTLIER_REJECTION">
<brief> Auto-rejection of outliers</brief>
<description>
Select this option to perform automatic outlier detection and rejection.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
<exclusions>
<item>MODEL1</item>
<item>MODEL2</item>
<item>MODEL3</item>
<item>MAX_MODEL1_C_QUANTILE</item>
<item>MAX_MODEL2_C_QUANTILE</item>
<item>MAX_MODEL3_C_QUANTILE</item>
</exclusions>
<inclusions>
<item>REJECTION_MULTIPLIER</item>
</inclusions>
</parameter>
<parameter name="REJECTION_MULTIPLIER">
<brief>Rejection multiplier</brief>
<description> Rejection multiplier</description>
<type>double</type>
<default>
<item>3.0</item>
</default>
<inclusions>
<item>OUTLIER_REJECTION</item>
</inclusions>
</parameter>
<parameter name="ERRORPROPAGATION">
<brief> Compute variance-covariance matrix</brief>
<description>
Select this option to compute the variance-covariance matrix of the
parameters. The parameter uncertainties can be computed from this
matrix.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
</parameter>
</group>
<group name="Maximum Likelihood Estimation">
<parameter name="MODEL1">
<type>string</type>
<brief>A maximum likelihood estimation model selection</brief>
<description> A maximum likelihood estimation model selection.
</description>
<default><item>NONE</item></default>
<list>
<option value="NONE">
<brief>None: no tier one maximum likelihood estimation</brief>
<description>
None: no tier one maximum likelihood estimation
</description>
<exclusions>
<item>MODEL2</item>
<item>MODEL3</item>
<item>MAX_MODEL1_C_QUANTILE</item>
<item>MAX_MODEL2_C_QUANTILE</item>
<item>MAX_MODEL3_C_QUANTILE</item>
</exclusions>
</option>
<option value="HUBER">
<brief>Huber: approximates the L2 norm near 0, and the L1 norm thereafter. Has one continuous derivative.</brief>
<description>
A highly recommended model that works well in many situations.
</description>
<exclusions>
<item>REJECTION_MULTIPLIER</item>
<item>OUTLIER_REJECTION</item>
<item>ERRORPROPAGATION</item>
</exclusions>
</option>
<option value="HUBER_MODIFIED">
<brief>Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives.</brief>
<description>
An adaptation of the highly recommended Huber model that has two continuous derivatives.
</description>
<exclusions>
<item>REJECTION_MULTIPLIER</item>
<item>OUTLIER_REJECTION</item>
<item>ERRORPROPAGATION</item>
</exclusions>
</option>
</list>
</parameter>
<parameter name="MAX_MODEL1_C_QUANTILE">
<brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>
<description>
The tweaking constant has different meanings depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recommended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recommended quantile: 0.7
Chen model: Residuals whose absolute value is greater than the tweaking constant are totally ignored. Recommended quantile: > 0.9
</description>
<type>double</type>
<default>
<item>0.5</item>
</default>
<minimum inclusive="no">0</minimum>
<maximum inclusive="no">1</maximum>
</parameter>
<parameter name="MODEL2">
<type>string</type>
<brief>A maximum likelihood estimation model selection</brief>
<description> A maximum likelihood estimation model selection.
</description>
<default><item>NONE</item></default>
<list>
<option value="NONE">
<brief>None: no tier two maximum likelihood estimation</brief>
<description>
None: no tier two maximum likelihood estimation
</description>
<exclusions>
<item>MODEL3</item>
<item>MAX_MODEL2_C_QUANTILE</item>
<item>MAX_MODEL3_C_QUANTILE</item>
</exclusions>
</option>
<option value="HUBER">
<brief>Huber: approximates the L2 norm near 0, and the L1 norm thereafter. Has one continuous derivative.</brief>
<description>
A highly recommended model that works well in many situations.
</description>
</option>
<option value="HUBER_MODIFIED">
<brief>Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives.</brief>
<description>
An adaptation of the highly recommended Huber model that has two continuous derivatives.
</description>
</option>
<option value="WELSCH">
<brief>Welsch: approximates the L2 norm near 0, but then decays exponentially to zero.</brief>
<description>
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.
</description>
</option>
<option value="CHEN">
<brief>Chen: a highly aggressive method that intentionally removes the largest few percent of residuals.</brief>
<description>
This method dramatically increases the influence of smaller residuals (beyond the L2 norm) while simultaneously totally ignoring the largest few
percent of the residuals.
</description>
</option>
</list>
</parameter>
<parameter name="MAX_MODEL2_C_QUANTILE">
<brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>
<description>
The tweaking constant has different meanings depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recommended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recommended quantile: 0.7
Chen model: Residuals whose absolute value is greater than the tweaking constant are totally ignored. Recommended quantile: > 0.9
</description>
<type>double</type>
<default>
<item>0.5</item>
</default>
<minimum inclusive="no">0</minimum>
<maximum inclusive="no">1</maximum>
</parameter>
<parameter name="MODEL3">
<type>string</type>
<brief>A maximum likelihood estimation model selection</brief>
<description> A maximum likelihood estimation model selection.
</description>
<default><item>NONE</item></default>
<list>
<option value="NONE">
<brief>None: no tier three maximum likelihood estimation</brief>
<description>
None: no tier three maximum likelihood estimation
</description>
<exclusions>
<item>MAX_MODEL3_C_QUANTILE</item>
</exclusions>
</option>
<option value="HUBER">
<brief>Huber: approximates the L2 norm near 0, and the L1 norm thereafter. Has one continuous derivative.</brief>
<description>
A highly recommended model that works well in many situations.
</description>
</option>
<option value="HUBER_MODIFIED">
<brief>Huber Modified: approximates the L2 norm near 0 and the L1 norm thereafter. Has two continuous derivatives.</brief>
<description>
An adaptation of the highly recommended Huber model that has two continuous derivatives.
</description>
</option>
<option value="WELSCH">
<brief>Welsch: approximates the L2 norm near 0, but then decays exponentially to zero.</brief>
<description>
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.
</description>
</option>
<option value="CHEN">
<brief>Chen: a highly aggressive method that intentionally removes the largest few percent of residuals.</brief>
<description>
This method dramatically increases the influence of smaller residuals (beyond the L2 norm) while simultaneously totally ignoring the largest residuals.
</description>
</option>
</list>
</parameter>
<parameter name="MAX_MODEL3_C_QUANTILE">
<brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>
<description>
The tweaking constant has different meanings depending on the model being used:
Huber models: The point at which the transformation motion from L2 to L1 norms takes place. Recommended quantile: 0.5
Welsch model: Residuals whose absolute value is twice the tweaking constant are approaching negligible significance. Recommended quantile: 0.7
Chen model: Residuals whose absolute value is greater than the tweaking constant are totally ignored. Recommended quantile: > 0.9
</description>
<type>double</type>
<default>
<item>0.5</item>
</default>
<minimum inclusive="no">0</minimum>
<maximum inclusive="no">1</maximum>
</parameter>
</group>
<group name="Convergence Criteria">
<parameter name="SIGMA0">
<brief> Standard deviation of unit weight
</brief>
<description>
Converges on stabilization of Sigma0. Convergence occurs when the change
in sigma0 between iterations is less than or equal to Sigma0.
</description>
<type>double</type>
<minimum inclusive="no">0</minimum>
<default>
<item>1.0e-10</item>
</default>
</parameter>
<parameter name="MAXITS">
<brief> Maximum number of iterations
</brief>
<description>
Maximum number of times to iterate. The application stops iterating at
MAXIT, or when convergence is reached.
</description>
<type>integer</type>
<minimum inclusive="yes">1</minimum>
<default>
<item>50</item>
</default>
</parameter>
</group>
<group name="Camera Pointing Options">
<parameter name="CKDEGREE">
<type>integer</type>
<minimum inclusive="yes">0</minimum>
<default>
<item>2</item>
</default>
<brief>
Degree of polynomial fit to original camera angles
</brief>
<description>
The degree of the polynomial fit to the original camera angles
and used to generate <def>a priori</def> camera angles for the first
iteration.
</description>
</parameter>
<parameter name="CKSOLVEDEGREE">
<type>integer</type>
<minimum inclusive="yes">0</minimum>
<default>
<item>2</item>
</default>
<brief>
The degree of the polynomial being fit to in the bundle adjustment
</brief>
<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 <def>a priori</def> 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.
</description>
</parameter>
<parameter name="CAMSOLVE">
<type>string</type>
<brief> Camera pointing parameters to include in the bundle adjustment</brief>
<default>
<item>ANGLES</item>
</default>
<description>
This parameter is used to specify which, if any, camera
pointing parameters to include in the adjustment.
</description>
<list>
<option value="NONE">
<brief> Don't solve for any camera pointing factors</brief>
<description>
If this option is selected, no camera pointing parameters
will be adjusted.
</description>
<exclusions>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
<item>TWIST</item>
<item>OVEREXISTING</item>
</exclusions>
</option>
<option value="ANGLES">
<brief>
Solve for camera angles: right ascension, declination and optionally twist
</brief>
<description>
Camera angles in each <def>cube</def> 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.
</description>
<exclusions>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="VELOCITIES">
<brief>Solve for camera angles AND their angular velocities</brief>
<description>
Camera angles and their angular velocities will be adjusted in the
solution. Solving for angles and velocities is equivalent to using
CKSOLVEDEGREE=1.
</description>
<exclusions>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="ACCELERATIONS">
<brief>Solve for camera angles, their angular velocities and accelerations</brief>
<description>
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.
</description>
<exclusions>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="ALL">
<brief>Solve for all coefficients in the polynomials fit to the camera angles.</brief>
<description>
If this option is selected, all coefficients of the solve
equation will be adjusted in the solution (CKSOLVEDEGREE+1
coefficients)
</description>
</option>
</list>
</parameter>
<parameter name="TWIST">
<brief> Solve for twist</brief>
<description>
If this option is selected, the twist angle will be adjusted in the
bundle adjustment solution.
</description>
<type>boolean</type>
<default>
<item>Yes</item>
</default>
</parameter>
<parameter name="OVEREXISTING">
<brief> Fit polynomial over the existing pointing</brief>
<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.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
</parameter>
</group>
<group name="Spacecraft Options">
<parameter name="SPKDEGREE">
<type>integer</type>
<minimum inclusive="yes">0</minimum>
<default>
<item>2</item>
</default>
<brief>
Degree of polynomial fit to original camera position
</brief>
<description>
The degree of the polynomial fit to the original camera position
and used to generate <def>a priori</def> camera positions for the
first iteration.
</description>
</parameter>
<parameter name="SPKSOLVEDEGREE">
<type>integer</type>
<minimum inclusive="yes">0</minimum>
<default>
<item>2</item>
</default>
<brief>
The degree of the camera position polynomial being fit to in the bundle
adjustment.
</brief>
<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 <def>a priori</def> 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.
</description>
</parameter>
<parameter name="SPSOLVE">
<type>string</type>
<brief> Spacecraft position parameters to include in the adjustment</brief>
<default>
<item>NONE</item>
</default>
<description>
This parameter is used to specify which, if any, spacecraft
position parameters to include in the adjustment.
</description>
<list>
<option value="NONE">
<brief>Don't solve for any spacecraft position parameters</brief>
<description>
No spacecraft position parameters will be adjusted.
</description>
<exclusions>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
<item>OVERHERMITE</item>
</exclusions>
</option>
<option value="POSITIONS">
<brief>Solve for the spacecraft positions</brief>
<description>
Spacecraft positions will be adjusted in the solution, but
not the velocity or the acceleration.
</description>
<exclusions>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="VELOCITIES">
<brief>Solve for the spacecraft positions and velocities</brief>
<description>
Spacecraft positions will be adjusted in the solution, as
well as the velocities of the spacecraft at each instance.
</description>
<exclusions>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="ACCELERATIONS">
<brief>Solve for the spacecraft positions, velocities, and accelerations</brief>
<description>
Spacecraft positions will be adjusted in the solution, as well
as the velocities and accelerations of the spacecraft at each
instance.
</description>
<exclusions>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
</exclusions>
</option>
<option value="ALL">
<brief>Solve for all coefficients in the polynomials fit to the camera position.</brief>
<description>
If this option is selected, all coefficients of the solve
equation will be adjusted in the solution (SPKSOLVEDEGREE+1
coefficients)
</description>
</option>
</list>
</parameter>
<parameter name="OVERHERMITE">
<brief> Fit polynomial over the existing Hermite spline</brief>
<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.
</description>
<type>boolean</type>
<default>
<item>No</item>
</default>
</parameter>
</group>
<group name="Community Sensor Model Options">
<parameter name="CSMSOLVESET">
<internalDefault>none</internalDefault>
<type>string</type>
<brief>Specify a set of a CSM parameters to solve for.</brief>
<description>
Specify one of the parameter sets from the CSM GeometricModel API to solve for.
All parameters belonging to the specified set will be solved for.
</description>
<exclusions>
<item>CSMSOLVETYPE</item>
<item>CSMSOLVELIST</item>
</exclusions>
<list>
<option value="VALID">
<brief> Solves for CSM parameters that are not NONE.</brief>
</option>
<option value="ADJUSTABLE">
<brief>Solves for real or fictitous CSM parameters.</brief>
</option>
<option value="NONADJUSTABLE">
<brief>Solves for fixed CSM parameters.</brief>
<description>
Solve for fixed CSM parameters. These parameters are generally not adjusted
but do have uncertainty which can help constrain the solutions and improve
a posteriori uncertainties for other parameters.
</description>
</option>
</list>
</parameter>
<parameter name="CSMSOLVETYPE">
<type>string</type>
<brief>Specify a type of a CSM parameters to solve for.</brief>
<description>
Specify a parameter type from the CSM GeometricModel API to solve for.
All parameters of the specified type will be solved for.
</description>
<exclusions>
<item>CSMSOLVESET</item>
<item>CSMSOLVELIST</item>
</exclusions>
<list>
<option value="NONE">
<brief>Solve for unitialized CSM parameters</brief>
</option>
<option value="FICTITIOUS">
<brief>Solve for CSM parameters calculted by resection</brief>
</option>
<option value="REAL">
<brief>Solve for measured CSM parameters</brief>
</option>
<option value="FIXED">
<brief>Solve for fixed CSM parameters</brief>
</option>
<description>
Solve for fixed CSM parameters. These parameters are generally not adjusted
but do have uncertainty which can help constrain the solutions and improve
a posteriori uncertainties for other parameters.
</description>
</list>
</parameter>
<parameter name="CSMSOLVELIST">
<type>string</type>
<brief>Specify an explicit list of CSM parameters to solve for.</brief>
<description>
All CSM parameters in this list will be solved for. Trailing and leading whitespace
will be stripped off. Use standard ISIS parameter array notation to specify multiple
parameters.
</description>
<exclusions>
<item>CSMSOLVESET</item>
<item>CSMSOLVETYPE</item>
</exclusions>
</parameter>
</group>
<group name="Target Body">
<parameter name="SOLVETARGETBODY">
<type>boolean</type>
<default><item>false</item></default>
<brief>
Solve for target body parameters. The parameters, their a priori values, and uncertainties are input
using a PVL file specified by TBPARAMETERS below.</brief>
<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
$ISISROOT/appdata/templates/jigsaw/TargetBodyParameters.pvl.
</description>
<inclusions>
<item>TBPARAMETERS</item>
</inclusions>
</parameter>
<parameter name="TBPARAMETERS">
<type>filename</type>
<fileMode>input</fileMode>
<brief>
File containing target body parameters to solve for, their a priori values and uncertainties.
</brief>
<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 $ISISROOT/appdata/templates/jigsaw/TargetBodyParameters.pvl. Instructions for the PVL
structure are given in the template.
</description>
<filter>
*.pvl
</filter>
</parameter>
</group>
<group name="Control Point Parameters">
<parameter name="CONTROL_POINT_COORDINATE_TYPE_BUNDLE">
<type>string</type>
<brief> Coordinate type to use for bundling and outputting control points</brief>
<default>
<item>LATITUDINAL</item>
</default>
<description>
This parameter indicates which coordinate type will be used to present
the control points in the bundle adjustment and bundle output.
</description>
<list>
<option value="LATITUDINAL">
<brief> Coordinates will be planetocentric latitudinal</brief>
<description>
If this option is selected all control points will be adjusted, corrected,
and reported in planetocentric latitudinal coordinates (latitude,
longitude, and radius).
</description>
<exclusions>
<item>POINT_X_SIGMA</item>
<item>POINT_Y_SIGMA</item>
<item>POINT_Z_SIGMA</item>
</exclusions>
</option>
<option value="RECTANGULAR">
<brief> Coordinates will be body-fixed rectangular</brief>
<description>
If this option is selected all control points will be adjusted, corrected,
and reported in body-fixed rectangular coordinates (X, Y, and Z).
</description>
<exclusions>
<item>RADIUS</item>
<item>POINT_LATITUDE_SIGMA</item>
<item>POINT_LONGITUDE_SIGMA</item>
<item>POINT_RADIUS_SIGMA</item>
</exclusions>
</option>
</list>
</parameter>
<parameter name="CONTROL_POINT_COORDINATE_TYPE_REPORTS">
<type>string</type>
<brief> Coordinate type to use for bundling and outputting control points</brief>
<default>
<item>LATITUDINAL</item>
</default>
<description>
This parameter indicates which coordinate type will be used to present
the control points in the bundle adjustment and bundle output.
</description>
<list>
<option value="LATITUDINAL">
<brief> Coordinates will be planetocentric latitudinal</brief>
<description>
If this option is selected all control points will be adjusted, corrected,
and reported in planetocentric latitudinal coordinates (latitude,
longitude, and radius).
</description>
</option>
<option value="RECTANGULAR">
<brief> Coordinates will be body-fixed rectangular</brief>
<description>
If this option is selected all control points will be adjusted, corrected,
and reported in body-fixed rectangular coordinates (X, Y, and Z).
</description>
</option>
</list>
</parameter>
</group>
<group name="Parameter Uncertainties">
<parameter name="POINT_LATITUDE_SIGMA">
<brief> Global latitude uncertainty for all points (meters)
</brief>
<description>
This optional value will be used as the global latitude
uncertainty for all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="POINT_LONGITUDE_SIGMA">
<brief> Global longitude uncertainty for all points (meters)
</brief>
<description>
This optional value will be used as the global longitude
uncertainty for all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="POINT_RADIUS_SIGMA">
<brief> Global radius uncertainty for all points (meters)
</brief>
<description>
This value will be used as the global radius uncertainty for
all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
<inclusions>
<item>
RADIUS
</item>
</inclusions>
</parameter>
<parameter name="POINT_X_SIGMA">
<brief> Global body-fixed X uncertainty for all points (meters)
</brief>
<description>
This optional value will be used as the global
uncertainty for all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="POINT_Y_SIGMA">
<brief> Global body-fixed X uncertainty for all points (meters)
</brief>
<description>
This optional value will be used as the global
uncertainty for all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="POINT_Z_SIGMA">
<brief> Global body-fixed X uncertainty for all points (meters)
</brief>
<description>
This optional value will be used as the global
uncertainty for all points. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="SPACECRAFT_POSITION_SIGMA">
<brief> Global uncertainty for spacecraft coordinates (meters)
</brief>
<description>
This value will be used as the global uncertainty for spacecraft
coordinates. Units are meters.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="SPACECRAFT_VELOCITY_SIGMA">
<brief> Global uncertainty for spacecraft velocity (meters/second)
</brief>
<description>
This value will be used as the global uncertainty for spacecraft
velocity. Units are meters/second.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="SPACECRAFT_ACCELERATION_SIGMA">
<brief> Global uncertainty for spacecraft acceleration
(meters/second/second)</brief>
<description>
This value will be used as the global uncertainty for
spacecraft acceleration. Units are meters/second/second.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="CAMERA_ANGLES_SIGMA">
<brief> global uncertainty for camera angles
(decimal degrees)</brief>
<description>
This value will be used as the global uncertainty for camera
angles. Units are decimal degrees.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="CAMERA_ANGULAR_VELOCITY_SIGMA">
<brief> Global uncertainty for camera angular velocity
(decimal degrees/second)</brief>
<description>
This value will be used as the global uncertainty for camera
angular velocity. Units are decimal degrees/second.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
<parameter name="CAMERA_ANGULAR_ACCELERATION_SIGMA">
<brief> Global uncertainty for camera angular acceleration
(decimal degrees/second/second)</brief>
<description>
This value will be used as the global uncertainty for camera
angular acceleration. Units are decimal degrees/second/second.
</description>
<type>double</type>
<internalDefault>none</internalDefault>
<minimum inclusive="yes">0</minimum>
</parameter>
</group>
<group name="Output Options">
<parameter name="FILE_PREFIX">
<type>string</type>
<internalDefault>none</internalDefault>
<brief>Output file prefix</brief>
<description>
File prefix to prepend for the generated output files. Any prefix that is not a
file path will have an underscore placed between the prefix and file name.
</description>
</parameter>
<parameter name="BUNDLEOUT_TXT">
<brief> Standard bundle output file - bundleout.txt
</brief>
<description>
Selection of this parameter flags generation of the standard
bundle output file
</description>
<type>boolean</type>
<default>
<item>yes</item>
</default>
</parameter>
<parameter name="IMAGESCSV">
<brief> Outputs image data (body-fixed) to csv file - bundleout_images.csv
</brief>
<description>
Selection of this parameter flags output of image data
(in body-fixed coordinates) to a csv file.
</description>
<type>boolean</type>
<default>
<item>yes</item>
</default>
</parameter>
<parameter name="OUTPUT_CSV">
<brief> Outputs point and image data (body-fixed) to csv file - bundleout_points.csv
</brief>
<description>
Selection of this parameter flags output of point and image data
(in body-fixed coordinates) to csv file.
</description>
<type>boolean</type>
<default>
<item>yes</item>
</default>
</parameter>
<parameter name="RESIDUALS_CSV">
<brief> Outputs image coordinate residuals to csv file - residuals.csv</brief>
<description>
Selection of this parameter flags output of image coordinate
residuals to a csv file
</description>
<type>boolean</type>
<default>
<item>yes</item>
</default>
</parameter>
<parameter name="LIDAR_CSV">
<brief> Outputs lidar data to csv file - lidar.csv</brief>
<description>
Selection of this parameter flags output of lidar data
points to a csv file
</description>
<type>boolean</type>
<default>
<item>no</item>
</default>
</parameter>
<parameter name="OUTADJUSTMENTH5">
<brief> Outputs bundle adjustment values to HDF5 file - adjustment_out.h5</brief>
<description>
Selection of this parameter flags output of bundle adjustment
values to an HDF5 file. The HDF5 file may be empty if all the cubes
have CSM states.
</description>
<type>boolean</type>
<default>
<item>no</item>
</default>
</parameter>
<parameter name="ADJUSTMENT_INPUT">
<type>filename</type>
<internalDefault>none</internalDefault>
<fileMode>input</fileMode>
<brief>
Reads in and applies adjustment values
</brief>
<description>
Reads in and applies bundle adjustment values from an HDF5 file,
usually the outputted adjustment_out.h5 file.
</description>
<filter>
*.h5
</filter>
<inclusions>
<item>
UPDATE
</item>
</inclusions>
<exclusions>
<item>ONET</item>
<item>CNET</item>
<item>LIDARDATA</item>
<item>OLIDARDATA</item>
<item>OLIDARFORMAT</item>
<item>SCCONFIG</item>
<item>OBSERVATIONS</item>
<item>RADIUS</item>
<item>OUTLIER_REJECTION</item>
<item>REJECTION_MULTIPLIER</item>
<item>ERRORPROPAGATION</item>
<item>MODEL1</item>
<item>MAX_MODEL1_C_QUANTILE</item>
<item>MODEL2</item>
<item>MAX_MODEL2_C_QUANTILE</item>
<item>MODEL3</item>
<item>MAX_MODEL3_C_QUANTILE</item>
<item>SIGMA0</item>
<item>MAXITS</item>
<item>CKDEGREE</item>
<item>CKSOLVEDEGREE</item>
<item>CAMSOLVE</item>
<!-- <item>TWIST</item> -->
<item>OVEREXISTING</item>
<item>SPKDEGREE</item>
<item>SPKSOLVEDEGREE</item>
<item>SPSOLVE</item>
<item>OVERHERMITE</item>
<item>CSMSOLVESET</item>
<item>CSMSOLVETYPE</item>
<item>CSMSOLVELIST</item>
<item>SOLVETARGETBODY</item>
<item>TBPARAMETERS</item>
<item>CONTROL_POINT_COORDINATE_TYPE_BUNDLE</item>
<item>CONTROL_POINT_COORDINATE_TYPE_REPORTS</item>
<item>POINT_LATITUDE_SIGMA</item>
<item>POINT_LONGITUDE_SIGMA</item>
<item>POINT_RADIUS_SIGMA</item>
<item>POINT_X_SIGMA</item>
<item>POINT_Y_SIGMA</item>
<item>POINT_Z_SIGMA</item>
<item>SPACECRAFT_POSITION_SIGMA</item>
<item>SPACECRAFT_VELOCITY_SIGMA</item>
<item>SPACECRAFT_ACCELERATION_SIGMA</item>
<item>CAMERA_ANGLES_SIGMA</item>
<item>CAMERA_ANGULAR_VELOCITY_SIGMA</item>
<item>CAMERA_ANGULAR_ACCELERATION_SIGMA</item>
<!-- <item>BUNDLEOUT_TXT</item>
<item>IMAGESCSV</item>
<item>OUTPUT_CSV</item>
<item>RESIDUALS_CSV</item>
<item>LIDAR_CSV</item>
<item>OUTADJUSTMENTH5</item> -->
</exclusions>
</parameter>
</group>
</groups>
<liens>
<item>Add items to glossary, example(s) and tips on how to analyze the
results.
</item>
</liens>
<examples>
<example>
<brief>Solve with CSM parameters</brief>
<description>
<p>
This is an example where the cubes in the network have been run through csminit.
When specified in CSMSOLVELIST, parameters described in the CsmInfo group can
be adjusted during the bundle.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b></p>
</description>
<terminalInterface>
<commandLine>fromlis=cubes.lis cnet=input.net onet=output.net radius=yes csmsolvelist="(Omega Bias, Phi Bias, Kappa Bias)" control_point_coordinate_type_bundle=rectangular control_point_coordinate_type_reports=rectangular point_x_sigma=50 point_y_sigma=50 point_z_sigma=50
</commandLine>
<description>
jigsaw CSM example
</description>
</terminalInterface>
</example>
<example>
<brief> Simple run of jigsaw with images from a linescanner </brief>
<description>
<p>
This example runs jigsaw in a very simple way using four MRO CTX images. Only the required parameters are entered, with all other parameters
left at their default settings. This bundle solution only solves for the camera orientation (see the CAMSOLVE and TWIST parameters). This command does not
update the SPICE information attached to the four cubes.
</p>
<p>
A possible use for this simple run would be to test a network to identify control points that are not well placed.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b></p>
</description>
<terminalInterface>
<commandLine>
fromlist=ctx.lis cnet=hand_dense.net onet=hand_dense-jig.net
</commandLine>
<description>
This command line only sets the three required parameters.
</description>
</terminalInterface>
<guiInterfaces>
<guiInterface>
<image src="assets/linescan/example_linescan_gui.png" width="1273" height="958">
<brief>
Example GUI
</brief>
<description>
The top of the GUI shows the parameters filled in for input cube list,
the input control network and the output control network. All other parameters
were left at their default values.
<br></br>
</description>
<thumbnail src="assets/linescan/example_linescan_gui_thumb.png" width="500" height="376" caption="jigsaw Linescan image example" />
</image>
</guiInterface>
</guiInterfaces>
<dataFiles>
<dataFile path="assets/linescan/ctx.lis">
<brief> Cube list file </brief>
<description>
Input file defining the file names of the four cubes used in the control network.
The file names can include a path if needed. Each file name is on a separate line and
the last file name can have new line at the end, but it is not required.
</description>
<parameterName> FROMLIST </parameterName>
</dataFile>
</dataFiles>
</example>
<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>a relative control</b> network covering the Apollo 15 landing site. </brief>
<description>
<p>
A relative network is a network that connects overlapping images with tie points but has no tie points connected to a ground source. Since there is no
connection to ground in the network, this bundle will only solve for camera specific parameters. The bundle could still solve for other parameters and be
correct relative to the camera position, but it would increase the complexity of the bundle. The proceeding two examples will include grounded networks,
so we will wait to increase the complexity of the bundle until ground points are included. Additionally, in this example we are evaluating the solution and
do not want to apply it to the images yet, therefore, update is set to 'no'.
</p>
<p>
This relative bundle turns on and parameterizes the camera twist and camera acceleration solve parameters. Camera twist is a flag that allows the bundle to solve
for the camera's rotation around the bore sight axis and uses the same uncertainty estimation as the other two rotations. Setting the camera solve parameter to acceleration, however,
does require uncertainties to be set for the angles (deg), angular velocity (deg/s), and angular accelerations (deg/s**2). These values were set with increasing
constraint because of the increasing affect alterations of higher order parameters have on the bundle solution.
</p>
<p>
The 'overexisting' flag tells the bundle solution to approximate the camera rotation with a zero polynomial function added to the existing rotation data (adding the
polynomial <b>over</b> the <b>existing</b> data). Without the 'overexisting' flag, the bundle fits a polynomial to the existing rotations, throws out the existing data
points, and uses the polynomial to calculate the approximate ephemerides when needed.
</p>
<p>
This bundle also lowers the max iterations to 10 (from default 50). Lowering the max iterations does not affect the bundle solution. However, setting a lower
iteration limit can serve as a flag if you expect your network to bundle quickly. Finally, the sigma0 convergence criteria was not changed from its default
value, it was only explicitly stated in this call.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b></p>
</description>
<terminalInterface>
<commandLine>
fromlist=cubes.lis cnet=relative_reg_jig4_edit.net onet=relative_reg_jig5.net update=no file_prefix=jig5 sigma0=1.0e-10 maxits=10
twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01
</commandLine>
<description>
</description>
</terminalInterface>
</example>
<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>an intermediate ground control</b> network covering the Apollo 15 landing site. </brief>
<description>
<p>
This example jigsaw bundle is run directly after adding ground control points to the previous relative network. With ground control points inserted into the
bundle solution, we will expand the bundle solve parameters to attempt solving for point radius values and the position of the spacecraft.
</p>
<p>
Ground points are weighted more heavily in the bundle than relative control points and adding parameters adds more complexity to the bundle solution. Therefore, it
is common to create and refine a network with only relative points and add ground point in <b>after</b> the relative network (and its bundle solution) is of sufficient quality.
The purpose of this bundle is to ensure the network bundle converges with the added ground points and solve parameters, before committing to updating the camera
pointing on the images, so update is set to 'no'.
</p>
<p>
In addition to the previous solve parameters, this bundle turns on the point radius and spacecraft position solve parameters. Applying the point radius solve
parameter requires the point_radius_sigma to be set. This value is a representation the uncertainty (in meters) of the cameras apriori pointing corresponding to the
correct elevation on the shape model; this value is not a hard constraint. Often this value can be set, and the appropriateness of the set value can be checked using
the 'POINTS DETAIL' section of the bundleout.txt file output by jigsaw. If more than half of the radius total corrections exceed the provided sigma, the uncertainty
may need to be increased.
</p>
<p>
Applying the space craft position solve parameter requires an uncertainty estimation through spacecraft_position_sigma (again this value is not a hard constraint).
The appropriateness of the provided sigma can be evaluated through the bundleout_images.csv X Correction, Y Correction, and Z Correction columns.
</p>
<p>
The 'overhermite' flag allows an estimation the spacecraft position like the 'overexisting' flag estimates the camera pointing, with a zero-polynomial added over
the existing data (for spacecraft position this is a cubic Hermite spline). These options require more memory but provide a solution more representative of small
variations in the original ephemeris data.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b></p>
</description>
<terminalInterface>
<commandLine>
fromlist=cubes_for_ground_update.lis cnet=grounded_relative_reg.net onet=grounded_rr_jig1.net update=no file_prefix=jig1rr sigma0=1.0e-10 maxits=10
twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01
radius=yes point_radius_sigma=500 spsolve=positions overhermite=yes spacecraft_position_sigma=1000
</commandLine>
<description>
</description>
</terminalInterface>
<dataFiles>
<dataFile path="assets/ap15/jig1rrEP_bundleout.txt">
<brief> jig1rr_bundleout.txt </brief>
<description>
A shorten example of a typical bundleout.txt file produced by a jigsaw run with error propegation.
This file was trimmed to hold 10 images, 50 relative points, and all ground points
along with their associated detail sections. Bundleout files typically contain
all image and point from a network put through jigsaw.
</description>
</dataFile>
</dataFiles>
</example>
<example>
<brief>Solve with lidar data</brief>
<description>
<p>
This is an example of how to use simultaneous lidar measurments to constrain
the instrument position. The constraints on the lidar data are already contained
in the lidardata input file.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b>
</p>
</description>
<terminalInterface>
<commandLine>lidar_csv=yes fromlis=cubes.lis cnet=input.net onet=output.net lidardata=lidar_data.json olidardata=lidar_data_jigged.json radius=yes twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1
</commandLine>
<description>
lidar example. Note the lidar_csv, lidardata, and olidardata arguments.
</description>
</terminalInterface>
</example>
<example>
<brief>Run of jigsaw parameterized for Kaguya Terrain Camera (TC) images and <b>a final ground control</b> network covering Apollo 15 landing site. </brief>
<description>
<p>
This last example is of a final jigsaw run of a grounded network. In this example all network adjustments are done, the bundle is converging, the resulting
residuals are acceptable, and therefore we are ready to update the camera pointing on the cubes. During the final run we turn on the error propagation flag, this
provides the variance-covariance matrix of the parameters, from which uncertainties can be computed. This is valuable if you plan to compute certainties for
your update cubes camera pointing (or any kernels resulting from these updated camera pointings).
</p>
<p>
If you want to double check the update was completed, see cathist or catlab (search for 'Jigged').
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b>
</p>
</description>
<terminalInterface>
<commandLine>
fromlist=cubes_for_ground_update.lis cnet=grounded_relative_reg.net onet=grounded_rr_jig1_ErrProp.net update=yes file_prefix=jig1rrEP sigma0=1.0e-10 maxits=10
twist=yes camsolve=accelerations overexisting=yes camera_angles_sigma=.25 camera_angular_velocity_sigma=.1 camera_angular_acceleration_sigma=.01
radius=yes point_radius_sigma=500 spsolve=positions overhermite=yes spacecraft_position_sigma=1000 errorpropagation=yes
</commandLine>
<description>
</description>
</terminalInterface>
<dataFiles>
<dataFile path="assets/ap15/jig1rrEP_bundleout.txt">
<brief> jig1rrEP_bundleout.txt </brief>
<description>
<p>
A shorten example of a typical bundleout.txt file produced by a jigsaw run with error propegation.
This file was trimmed to hold 10 images, 50 relative points, and all ground points
along with their associated detail sections. Bundleout files typically contain
all image and point from a network put through jigsaw.
</p>
<p><b>
For step-by-step instructions on creating a control network and generating a cube list file, refer to the
<a href="https://astrogeology.usgs.gov/docs/how-to-guides/image-processing/bundle-adjustment-in-isis/">
"Bundle Adjustment in ISIS" documentation
</a>.
</b></p>
</description>
</dataFile>
<dataFile path="assets/ap15/tables.txt">
<brief> Instrument pointing and position tables before jigsaw update </brief>
<description>
Table summaries for the InstrumentPointing and InstrumentPosition tables extracted from
a cube label.
</description>
</dataFile>
<dataFile path="assets/ap15/jigged_tables.txt">
<brief> Instrument point and position tables after jigsaw update </brief>
<description>
Table summaries for the InstrumentPointing and InstrumentPosition tables extracted from
a jigsaw updated cube label. The InstrumentPointing table was updated due to the camera
updates solved for in the bundle (camsolve=accelerations). The InstrumentPosition table
was updated due to the spacecraft updates solved for in the bundle (spsolve=positions).
</description>
</dataFile>
</dataFiles>
</example>
</examples>
</application>