Clipper (#3656)

<application name="jitterfit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Application/application.xsd">

  <brief>

    Registers lines from a normal image with lines from the check image.

    Characterize jitter for rolling shutter images.

  </brief>

  <description>

    <p>

      This program co-regsisters lines in the main cube (FROM) with the corrisponding line in

      the checkline cube (FROM2).

      The sensor line used to collect the checkline is used to center the registration around

      the same area in the main cube.

      This program calculates two sets of polynomial coefficients that characterize the jitter in an

      image acquired by a rolling shutter instrument. One polynomial for the line direction and one

      for the sample direction. The ISIS camera model for the instrument can

      then use the coefficients to adjust for the time dependent jitter.

    </p>

    <p>

      The main input cube (FROM) is expected to be a cube from a rolling shutter instrument.

      The checkline cube (FROM2) is expected to contain lines of data read from the same rolling shutter

      instrument, but read at different times than the coorsponding line in the main cube. The check 

      cube must also have an associated table containing the sensor line number and time the line was read. 

      The algorithum co-registers these individual checklines to the main cube and calculates an offset

      in the line and sample directions. It then fits an Nth order polynomial through the offsets and time to

      characterize the jitter. The coefficients are then written to the cube labels so the rolling shutter

      camera model can adjust the look direction of each pixel in the model's detector map.

      The coefficients are

      calculated by coregistering lines in the main cube with each line in the check line cube, where each

      check line was acquired durring the readout of the main cube using the

      same detector, but at a different time. The registration produces sample and line offsets

      which are fed into a least squares solution to determin the coeficients of an Nth degree

      polynomial in time. The coefficients are written to the cube label for use by the ISIS camera model.

    </p>

    <p>

      The main cube (FROM) is expected to be a full frame image collected by a rolling shutter sensor.

      The cube must have two attached tables: 1) A table with a record for each line in the cube where

      the first column contains the sensor line number used to collect the corresponding image line,

      and the second column contains the associated exposure time (normalized -1 to 1). 2) A table

      with one record for each check line where the first column is the sensor line number used to

      collect the corresponding check line and the second column contains the time the line was

      exposed normalized using the same minimum and maximum as the main image times were. Tables that

      meet these requirements are currently attacted to the cube during ingestion to ISIS (i.e., eis2isis).

    </p>

    <p>

      The checkline cube is expected to have individual lines (possibly repeated) from the same sensor as the

      main cube. The checklines must be read during the readout of the main image sequence. 

    </p>

      An example line readout order for a 100 line sensor with 3 check lines read 3 times each

      could be (readout time for a line = line exposure number * exposure duration):

    <pre>

      Type   Line    Exp# 

             Number       

      --------------------

      Main   1-10    1-10 

      Check  75      11   

      Main   11-20   12-21

      Check  50      22   

      Main   21-30   23-32

      Check  25      33   

      Main   31-40   34-43

      Check  75      44   

      Main   41-50   45-54

      Check  50      55   

      Main   51-60   56-65

      Check  25      66   

      Main   61-70   67-76

      Check  75      77   

      Main   71-80   78-87

      Check  50      88   

      Main   81-90   89-98

      Check  25      99   

      Main   91-100  100-109

    </pre>

    <p>

      In this example the 9 check lines cause the last line of the array to be readout

      (9 * exposure duration) later than it would have without the check line readouts.

    </p>

    <p>

      This program was designed around work for the Europa Clipper Europa Imaging System Narrow

      Angel Camera by Randy Kirk. Since the program relies on the check lines and their 

      spatial and temporal relationship to the main lines, the program will not work with

      other instruments unless they provide similar data.

    </p>

  </description>

  <category>

    <missionItem>Europa Clipper</missionItem>

  </category>

  <history>

    <change name="Stuart Sides" date="2020-01-20">

      Original version

    </change>

  </history>

  <groups>

    <group name="Registration">

      <parameter name="FROM">

        <type>cube</type>

        <fileMode>input</fileMode>

        <brief>

          Input cube containing an image that need jitter correction.

          Input cube to be jitter corrected.

        </brief>

        <description>

          This input cube is the cube that needs to be de-jittered. The algorithms jitterfit uses

          This input cube is the cube that needs to be de-jittered. The algorithms used

          are designed for a rolling shutter instrument with an accompanying check line cube

          file (see main description). This cube file must be writable. Coefficients to adjust

          the jitter will be written to the cube labels for use by the rolling shutter cammera model.

          the jitter will be written to the cube labels for use by the rolling shutter camera model.

        </description>

        <filter>

          *.cub

        </brief>

        <description>

          This input cube is the check line cube. It contains a set of lines that were 

          repetedly read from the sensor array intersperesed with the readout of the main

          repeatedly read from the sensor array interspersed with the readout of the main

          image data.

          EXPAND

          ...EXPAND...

        </description>

        <filter>

          *.cub

          The Auto Registration template

        </brief>

        <description>

          The parameter template to use for the Autoregistration process. The default template

          The parameter template to use for the auto registration process. The default template

          calls the Maximum Correlation pattern matching algorithm with predefined parameter values.

          There are other templates available in the system autoreg/template directory.  Also, the user

          can use the 'autoregtemplate' application to create a new template file.

          This will allow the program to access the correct normal cube line number based on the 

          un-enlarged check table values.

          Example: For a 4x enlargement set this value to 4.0.

          ADD WHY

          ...ADD - WHY we would do this...

        </description>

      </parameter>

          Output file where the registration statistics will be written.

        </brief>

        <description>

          SOMETHING 

          This file will contain the statistics gathered during the registration process. The

          format is PVL and is identical to the statistics for all auto registration applications.

        </description>

        <filter>

          *.csv

          Output file that holds the coefficients.

        </brief>

        <description>

          SOMETHING

          FORMAT 

          A comma separated value file of the line and sample coefficients. One line of line, sample for each 

          degree.

        </description>

        <filter>

          *.csv

        <fileMode>output</fileMode>

        <internalDefault>None</internalDefault>

        <brief>

          Output file that holds the residuals.

          Output file that holds the solution residuals.

        </brief>

        <description>

          SOMETHING

          A comma separated value file of the residual information from the least squares solution. The columns are:

          Registered Line, Solved Line, Registered Line Residual, Registered Sample, Solved Sample, Sample Residual, Time Taken

        </description>

        <filter>

          *.csv

                  "delta sample, goodness of fit, registration success " << endl;

  }

  // ???? Question: Why use a file name here? Can't Table read from an open Cube?

  // ???? Question: Why use a file name here? Can't Table/blob read from an open Cube?

  Table mainReadouts(QString("Normalized Main Readout Line Times"), jitterCube.fileName());

  Table checklineReadouts(QString("Normalized Checkline Readout Line Times"), checkCube.fileName());

  <xs:annotation>

    <xs:documentation>2018-03-27 Tyler Wilson - Added  missionItem_type enummeration for Clipper.</xs:documentation>

  </xs:annotation>

  <xs:annotation>

    <xs:documentation>2020-01-20 Stuart Sides - Changed missionItem_type enummeration for Clipper to Europa Clipper.</xs:documentation>

  </xs:annotation>

  <xs:element name="application">

    <xs:annotation>

      <xs:enumeration value="Cassini"/>

      <xs:enumeration value="Chandrayaan 1"/>

      <xs:enumeration value="Clementine"/>

      <xs:enumeration value="Clipper"/>

      <xs:enumeration value="Dawn"/>

      <xs:enumeration value="Europa Clipper"/>

      <xs:enumeration value="ExoMars Trace Gas Orbiter"/>

      <xs:enumeration value="Galileo"/>

      <xs:enumeration value="Hayabusa"/>