Reviewed jigsaw application documentation. References #4226.

  <description>

    <p>

      <b>jigsaw</b> performs a bundle adjustment on a group of overlapping Isis 3, 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 

      The <b>jigsaw</b> application performs a bundle adjustment on a group of overlapping Isis 3, 

      level 1, <def>cube</def>s from framing and/or line-scan cameras.  The adjustment 

      simultaneously defines 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>

    <img src='assets/images/mdis2_Controlled.png' alt='After jigsaw (controlled)' width='306' height='259' />

    <p>

      <b>jigsaw</b> assumes <b>spiceinit</b> has been run on the input <def>cube</def>s so that 

      The <b>jigsaw</b> application assumes <b>spiceinit</b> has been run on the input <def>cube</def>s so that 

      <def>SPICE</def> is included in the Isis 3 <def>cube</def> labels in the Kernels group.  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 net</def>, and the adjustment parameters.  

      <b>jigsaw</b> outputs a new <def>control net</def> that includes the initial state of the

      points in the network and their final state after the adjustment.  The initial state of

      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 net</def>, and their final

      state as <def>adjusted</def>.  The measured <def>sample</def>/<def>line</def> positions

      states are tagged as <def>adjusted</def>.  The measured <def>sample</def>/<def>line</def> positions

      associated with the <def>control point</def>s in the net are not changed.  <def>SPICE</def> 

      in the <def>cube</def> labels is updated at the end of the adjustment only 

      if the bundle converges and the <b>UPDATE</b> parameter is selected.

    <p>

      Optional output files can be selected to provide more information for analyzing the 

    results.  <b>bundleout.txt</b> provides an overall summary of the bundle adjustment.  

      results.  <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 also be written to a separate

    <b>CSV</b> file and likewise for the point statistics with the <b>output_csv</b>

    option selected.  <b>residuals_csv</b> provides a table of the measured image

      <b>CSV</b> file and likewise for the point statistics with the <b>OUTPUT_CSV</b>

      option selected.  <b>RESIDUALS_CSV</b> provides a table of the measured image

      coordinates and the final <def>sample</def>, <def>line</def>, and overall residuals 

      in both millimeters and pixels.

    </p>

      <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 Retection</i> turned on,

      <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

        <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

        <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>

      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.

      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.

      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="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

      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>

  </history>

  <groups>

        <type>filename</type>

        <fileMode>input</fileMode>

        <brief>

          cube list

          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>

        <internalDefault>none</internalDefault>

        <fileMode>input</fileMode>

        <brief>

          Held list

          List of cubes to hold in the adjustment

        </brief>

        <description>

          This file contains a list of all <def>cube</def>s whose orientation and position

          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 keywords/value

          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 is missing, then their defaults will be used. There is

          If any of these keywords are missing, then their defaults will be used. There is

          an example template at $base/templates/jigsaw/SensorParameters.pvl that can be

          used as a guide.

        </description>

          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 

          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.

          option is used; otherwise, each subframe is adjusted independently.

        </description>

        <type>boolean</type>

        <default>

   <group name="Maximum Likelihood Estimation">

      <parameter name="MODEL1">

        <type>string</type>

        <brief>A maximum likelihood estimation model selection.</brief>

        <brief>A maximum likelihood estimation model selection</brief>

        <description> A maximum likelihood estimation model selection.

        </description>

        <default><item>NONE</item></default>

            </exclusions>

          </option>

          <option value="HUBER">

            <brief>Huber: aproximates the L2 norm near 0, and the L1 norm therafter.  Has one continuous derivative.</brief>

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

            <description>

               A highly recommend model, that works well in many situations.

              A highly recommended model that works well in many situations.

            </description>

            <exclusions>

               <item>REJECTION_MULTIPLIER</item>

          <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 hignly recomended Huber model that has two continuous derviatives.

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

            </description>

            <exclusions>

               <item>REJECTION_MULTIPLIER</item>

      </parameter>

      <parameter name="MAX_MODEL1_C_QUANTILE">

        <brief>Quantile of the |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model.</brief>

        <brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>

        <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

          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>

      <parameter name="MODEL2">

        <type>string</type>

        <brief>A maximum likelihood estimation model selection.</brief>

        <brief>A maximum likelihood estimation model selection</brief>

        <description> A maximum likelihood estimation model selection.

        </description>

        <default><item>NONE</item></default>

            </exclusions>

          </option>

          <option value="HUBER">

            <brief>Huber: aproximates the L2 norm near 0, and the L1 norm therafter.  Has one continuous derivative.</brief>

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

            <description>

               A highly recommend model, that works well in many situations.

              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 hignly recomended Huber model that has two continuous derviatives.

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

            </description>

          </option>

          <option value="WELSCH">

            <brief>Welsch: aprroximates the L2 norm near 0, but then decays exponentially to zero.</brief>

            <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 agressively than Huber.  Large residuals will have less influence than small residuals,

              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 aggresive method that intentionally removes the largest few percent of residuals</brief>

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

            <description>

               This mehtod dramatically increases the influence of smaller residuals (beyond the L2 norm), while at the same time totally ignoring the largest few

              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>

      </parameter>

      <parameter name="MAX_MODEL2_C_QUANTILE">

        <brief>Quantile of the |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model.</brief>

        <brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>

        <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

          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>

      <parameter name="MODEL3">

        <type>string</type>

        <brief>A maximum likelihood estimation model selection.</brief>

        <brief>A maximum likelihood estimation model selection</brief>

        <description> A maximum likelihood estimation model selection.

        </description>

        <default><item>NONE</item></default>

            </exclusions>

          </option>

          <option value="HUBER">

            <brief>Huber: aproximates the L2 norm near 0, and the L1 norm therafter.  Has one continuous derivative.</brief>

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

            <description>

               A highly recommend model, that works well in many situations.

              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 hignly recomended Huber model that has two continuous derviatives.

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

            </description>

          </option>

          <option value="WELSCH">

            <brief>Welsch: aprroximates the L2 norm near 0, but then decays exponentially to zero.</brief>

            <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 agressively than Huber.  Large residuals will have less influence than small residuals,

              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 aggresive method that intentionally removes the largest few percent of residuals</brief>

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

            <description>

               This mehtod dramatically increases the influence of smaller residuals (beyond the L2 norm), while at the same time totally ignoring the largest residuals.

              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 |resiudual| distribution used to set the tweaking constant of the maximum likelihood estimation model.</brief>

        <brief>Quantile of the |residual| distribution used to set the tweaking constant of the maximum likelihood estimation model</brief>

        <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

          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>

    <group name="Convergence Criteria">

      <parameter name="SIGMA0">

        <brief> standard deviation of unit weight

        <brief> Standard deviation of unit weight

        </brief>

        <description>

          Converges on stabilization of Sigma0.  Convergence occurs when the change

      </parameter>

      <parameter name="MAXITS">

        <brief> iterations

        <brief> Maximum number of iterations

        </brief>

        <description>

          Maximum number of times to iterate.  The application stops iterating at

          </option>

          <option value="ANGLES">

            <brief>Solve for camera angles: right ascension, declination and optionally 

                   twist

            <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, 

        <brief>Enter target body parameters and a priori values using a PVL file</brief>

        <description>

          This option indicates that target body parameters are to be input via the PVL file specified

        by TB_PARAMETERS. All of the following must be in the PVL file- values for coefficients of:

          by TB_PARAMETERS. All of the following values for coefficients must be in the PVL file:

          body pole RA and DEC; prime meridian; triaxial radii and/or mean radius. An example template

          PVL file is located at $base/templates/jigsaw/TargetBodyParameters.pvl.

        </description>

        <exclusions>

        </exclusions>

        <inclusions>

          <item>TB_PARAMETERS</item>

        </inclusions>

          File must be in PVL format. It should contain an object called TargetParameters.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 keywords/value

          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 is missing, then their defaults will be used. An example template

          If any of these keywords are missing, then their defaults will be used. An example template

          PVL file is located at $base/templates/jigsaw/TargetBodyParameters.pvl.

        </description>

        <filter>

          <description> 

            This value will be used as the global uncertainty for spacecraft 

            velocity.  Units are meters/second.

            (meters)</description> 

          </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 

          <brief> Global uncertainty for camera angular acceleration 

            (decimal degrees/second/second)</brief>

          <description> 

            This value will be used as the global uncertainty for camera 

       <parameter name="FILE_PREFIX">

         <type>string</type>

         <internalDefault>none</internalDefault>

            <brief>output file prefix</brief>

         <brief>Output file prefix</brief>

         <description>

                output file prefix

           File prefix to prepend for the generated output files. 

         </description>

        </parameter>