Updated lronaccal to use time-dependent darkfiles for dark calibration (#4520)

- Added check to determine if poles were a valid projection point in ImagePolygon when generating footprint for a map projected image. [#4390](https://github.com/USGS-Astrogeology/ISIS3/issues/4390)

- Updated the LRO photometry application Lronacpho, to use by default the current 2019 photometric model (LROC_Empirical). The model's coefficients are found in the PVL file that exists in the LRO data/mission/calibration directory. If the old parameter file is provided, the old algorithm(2014) will be used. This functionality is desired for calculation comparisons. Issue: [#4512](https://github.com/USGS-Astrogeology/ISIS3/issues/4512), PR: [#4519](https://github.com/USGS-Astrogeology/ISIS3/pull/4519)

- Added a new application, framestitch, for stitching even and odd push frame images back together prior to processing in other applications. [4924](https://github.com/USGS-Astrogeology/ISIS3/issues/4924)

- Added changes to lronaccal to use time-dependent dark files for dark correction and use of specific dark files for images with exp code of zero. Also added GTests for lronaccal and refactored code to make callable. Added 3 truth cubes to testing directory.  PR[#4520](https://github.com/USGS-Astrogeology/ISIS3/pull/4520)

### Changed

- Updated the LRO calibration application Lrowaccal to add a units label to the RadiometricType keyword of the Radiometry group in the output cube label if the RadiometricType parameter is Radiance. No functionality is changed if the RadiometricType parameter is IOF. Lrowaccal has also been refactored to be callable for testing purposes. Issue: [#4939](https://github.com/USGS-Astrogeology/ISIS3/issues/4939), PR: [#4940](https://github.com/USGS-Astrogeology/ISIS3/pull/4940)

#ifndef lronaccal_h

#define lronaccal_h

#include "Cube.h"

#include "lronaccal.h"

#include "UserInterface.h"

namespace Isis{

  extern void lronaccal(UserInterface &ui);

  extern void lronaccal(Cube *iCube, UserInterface &ui);

}

#endif

 No newline at end of file

      will reduce the number of samples in the output image by a factor of at

      most the SpatialSumming mode value.

    </p>

    <p>

      The LROC NAC camera has the ability to acquire images of differing sizes in

      both line and sample.  The starting hardware detector pixel for the

    <p>

      The calibration equation is:

      <pre>  reportedDN = ObservedDN - MeanBias - DarkCurrent </pre>

      <pre>

        reportedDN = ObservedDN - MeanBias - DarkCurrent 

      </pre>

        Where:

      <pre>

        ObservedDN = TrueDN + E

        E is a randomly sampled value from (mu, sigma^2) and mu=0

   TrueDN is the signal that would be reported in an idealized case of an instrument with zero noise.</pre>

        TrueDN is the signal that would be reported in an idealized case of an instrument with zero noise.

      </pre>

    </p>

    <p>

      The dark average produced is dependant on which options are selected.

      There are three options for dark calibration/correction. If the image has exposure code of zero, 

      the nearest dark files with exposure code of zero will be used.

      Nearest pair of darks (Default):

      This option selects the two closest dark files (before and after the observation) and 

      computes a time-weighted average. In the ideal case, this average product should characterize

      the dynamic dark response the best. Note: Each dark file is an average of a month’s worth of

      dark observations under given settings (i.e., exposure code, summing mode, etc.). The maximum

      time range between pairs of dark files is 45 days. If a suitable pair is not found, the latest

      dark file taken before the image will be used.

      pixel_dark_average =

      avgDarkLine1_pixel * |darkfile1_time - time|   +   avgDarkLine2_pixel * |darkfile2_time - time|

      / (1.0 * ( |darkFile1_time - time| + |darkFile2_time - time| ) )

      Nearest dark file:

      This option selects the nearest dark file (before or after the observations).  

      This option is typically only used when a pair of darks do not surround the observation.  

      For example, during the mission, new NACs may not have a dark file in the dark catalog 

      for times after the observation being calibrated.  In this case, lronaccal will use 

      only the previous NAC dark in the calibration steps. However, suppose the image is calibrated

      again after new darks have been added to the catalog. In that case, the default options for 

      lronaccal will use a pair of dark observations, and the resulting calibrated image may have 

      slightly different intensities than the NAC processed with only a single dark file. 

      Note: While this is not a default option, if only one dark is available, lronaccal will

      automatically apply the nearest dark file.  The user can see which dark(s) were applied in 

      the cube header.

      Custom dark:

      This option uses a single custom dark file that the user must supply with the DarkFile parameter.  

      This option is typically only used in special cases, such as calibrating very long exposure NAC images.

    </p>

    <p>

      Using a spiceinited cube as input has the advantage of not requiring that local 

      mission-specific kernels be available. (See spiceinit web=true.)

    </p>

  </description>

  <history>

    <change name="Adam Licht" date="2013-02-28">

      No longer treat negative DNs differently in the Non-linearity correction.

    </change>

    <change name="Victor Silva" date="2020-01-06">

      Added option for base calibration directory

    </change>

    <change name="Victor Silva" date="2020-06-19">

      Updated dark calibration to use nearest pair of dark images to calibrate

    </change>

    <change name="Victor Silva" date="2020-10-04">

      Updated dark calibration documentation to provide more clarity to dark file options

    </change>

  </history>

  <category>

      </parameter>

    </group>

    <group name="Dark Options">

    <group name="Dark File Options">

      <parameter name="Dark">

        <type>boolean</type>

        <default><item>True</item></default>

        <brief>

        Calibrate using the average dark pixels.

        Calibrate using average dark pixels.

        </brief>

        <description>

          Calibrate using average dark pixels. This is also referred to 

          as dark correction. These dark calibration/correction files

          are included in the data directory (lro/calibration/nac_darks).

        </description>

        <inclusions><item>DarkFileType</item></inclusions>

      </parameter>

      <parameter name="DarkFileType">

        <type>string</type>

        <brief>

          Calibrate using average dark pixels from 

          Nearest Single, Pair, or Custom dark file(s). 

        </brief>

        <description>

          There are three options for dark calibration/correction. If the image has exposure code of zero, 

          the nearest dark files with exposure code of zero will be used.

          PAIR (Nearest pair of darks) [Default]:

          This option selects the two closest dark files (before and after the observation) and 

          computes a time-weighted average. The maximum time range between pairs of dark files 

          is 45 days. If a suitable pair is not found, the latest dark file taken before the image 

          will be used.

          NEAREST (Nearest dark file):

          This option selects the nearest dark file (before or after the observations).  

          Note: While this is not a default option, if only one dark is available, lronaccal will

          automatically apply the nearest dark file. 

          CUSTOM (Custom dark):

          This option uses a single custom dark file that the user must supply with the DarkFile parameter.  

          This option is typically only used in special cases, such as calibrating very long exposure NAC images.

        </description>

        <default><item>Pair</item></default>

        <list>

          <option value="PAIR">

            <brief>Pair</brief>

            <description>

              Pair of dark calibration files that the image time lies between

            </description>

            <exclusions><item>DarkFile</item></exclusions>

          </option>

          <option value="NEAREST">

            <brief>Nearest</brief>

            <description>

              Single dark calibration file that is nearest the image time

            </description>

        <inclusions><item>DarkFile</item></inclusions>

            <exclusions><item>DarkFile</item></exclusions>

          </option>

          <option value="CUSTOM">

            <brief>Custom Dark File</brief>

            <description>

              User provided dark calibration file

            </description>

            <inclusions>

              <item>DarkFile</item>

            </inclusions>

          </option>

        </list>

      </parameter>

      <parameter name="DarkFile">

        <type>filename</type>

        <default><item>Default</item></default>

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

        <brief>

        Calibrate using the average dark pixels.

        </brief>

        <description>

        </description>