Help for MARSBRT

drift_wt and inertia are always (mult,add).

PURPOSE:
This program computes intensity (or "brightness") corrections for a mosaic.
These corrections are intended to reduce radiometric seams in the image.
It requires as input an XML file of "overlaps", such as generated from MARSMAP
using the OVR_OUT parameter.  This file contains statistics on overlapping
regions in the mosaic.  MARSBRT analyzes these to come up with a globally
best solution to reduce the radiometric seams.

The output is an XML file containing corrections to apply to each image.
This file can be supplied to any of the mosaic programs (e.g. MARSMAP).
Note that the result loses some radiometric accuracy, but typically looks
much better.

Corrections can be made in normal image space or, with color input images,
in hue-saturation-intensity (HSI) space (only intensity is adjusted).

This program was derived from MARSNAV and shares many of the same parameters
with that program.  It accomplishes a similar purpose.  But instead of
converting geometric tiepoints to a geometry solution, it converts overlap
"tiepoints" into a brightness-matching solution.

MARSBRT supports any mission, instrument, and camera model supported by the
Planetary Image Geometry (Pig) software suite.


EXECUTION:

A typical execution sequence would be as follows:

marsmap mosaic.lis mosaic.vic zoom=.25 ovr_out=mosaic.ovr
marsbrt mosaic.lis mosaic.brt in_ovr=mosaic.ovr
marsmap mosaic.lis mosaic.vic brtcorr=mosaic.brt

Note that the mosaic must be run once just to get the overlaps; it is then
run again to make use of the brightness solution.


USAGE:
It is important that all images be connected to each other via overlap
"tiepoints".  If an image or block of images is not connected, the entire
block can "drift" in brightness.  This can be counteracted to some extent
using the INERTIA parameter, which can prevent the solution from drifting
too far.  Note that disconnection can occur when removing outliers (see
below).

It is recommended that a small amount of inertia be used in most cases.
For a typical image (DN's in the 0-4k range) a good value might be
(0.1, 0.0001).  For IFF-style images (floating-point I/F radiances) in
a 0-0.5 range, use (0.1, 0.1).  For IFF's in 0-0.1 range, try (0.1,1.0).
Some experimentation may be required.

The simplex method of finding pointing solutions can often benefit by being
rerun multiple times, starting from where it left off the last time, as
opposed to resetting the solution to the initial conditions.  The program
allows this in both batch and interactive modes.  Experience has shown that
as many as half a dozen reruns can still show improvement in the solution.

Note that the mosaic should ideally be nav'd (pointing corrected) before
doing this brightness correction.  That ensures the overlaps are correct.
Also, when generating the overlaps, you rarely need to generate the mosaic
full-size; a zoom of 0.5 or even 0.25 is usually sufficient to get proper
statistics.

Three of the parameters need to vary based on the DN range of the input.
They need not be precise but should at least be adjusted for order of
magnitude differences.  For example, standard images are in the 0-4k range
while floating-point I/F radiances can be in the 0-0.5 range.  The three
parameters are directly tied to the additive correction, whose scale is
related to the DN range.  The parameters are:  inertia(2), drift_wt(2),
and lambda_add.  In general, inertia(2) and drift_wt(2) should go up as
the DN range decreases, while lambda_add should go down with decreasing
DN range.  An order of magnitude change in DN range should mean approximately
an order of magnitude change in these parameters.  The default for lambda_add
is set for typical 0-4k images; the others default to off.

This program does not currently make use of a surface model or coordinate
systems.  Therefore the parameters related to those are unused.  They are
retained just in case they are needed in the future.

An input brightness correction file can be supplied via BRTCORR.  This
serves as a starting point and can be useful to build up the brt corr file
piecemeal.  It can be helpful to do some of the images, then load the results
via BRTCORR and set all those images as references so they don't change.
This way an image with bad overlaps doesn't pull everything else out of
whack.  Once the rest of the images are set, the offending image can be
added back in, letting it adjust as needed without hurting the rest of the
mosaic.  This technique can be especially useful when combined with setting
the border in marsmap when creating the ovr file (e.g. point='"border_left=100,
border_right=100,border_top=200,border_bottom=10"' on marsmap) to eliminate
the bad overlaps.


METHOD:

In a nutshell, the program works by performing a global function minimization
using the "amoeba" simplex method.  Each image gets one additive and one
multiplicative factor, which are applied to every pixel in that image.
These are adjusted until the error represented by the statistics in the
overlap file is minimized.

Initial Conditions
------------------

The starting point for brightness correction is usually a no-op correction.
It is often useful to refine an existing correction, however.  If a brightness
file is provided via the BRT mosaic, it will be read, and the resulting
corrections will be the initial conditions.

Alternatively, it is possible to analyze "overall" overlaps in order to balance
the entire image.  Overall overlaps provide statistics for the entire image,
rather than overlapping areas.  The average mean and standard deviation of
the overall overlaps are computed and used as a target (alternatively, the
OVERALL_MEAN and OVERALL_STDEV parameters can set that target).  A correction
is computed which causes the image to match (exactly; this is algorithmic not
iterative) the overall statistics, and that is used as a starting point.

This can help even out overall differences such as time-of-day acquisition
differences.

Overall statistics must be gathered by marsmap in order for this mode to work.

Error Metric
------------

The error is defined as follows.  Each overlap entry contains a list of the
images involved in that overlap (it often is more than 2).  For each image,
the entry contains the mean and standard deviation of the pixels in the
overlap.  These statistics are modified based on the putative additive and
multiplicative factors.  Ideally the resulting modified mean and stdev should
equal each other across all images in the overlap.  To the extent they don't,
that is the error.

For each pair, the difference between the modified means and stdevs are
computed.  These are normalized by the average of the means and the average
of the stdevs in order to make the very different mean and stdev statistics
combinable.  They are squared (to make it least squares) and combined,
summed across each pair of images, then normalized by the number of pairs.
Finally, the result is multiplied by the number of pixels in the overlap,
so that large overlaps count more heavily than small overlaps.

This metric is then summed across all overlaps, normalized by the total number
of pixels, and that becomes the error metric.

Note that parameters allow you to use only the mean or only the stdev
statistics, and likewise, to use only additive or only multiplicative
corrections.  Generally, however, all should be used.


Outlier Rejection
-----------------

An important feature of MARSBRT is that of outlier rejection.  Overlaps that
really don't match each other are common.  They occur due to sun glints,
parallax (e.g. rover deck vs. ground) obstructing hardware like the MER
LGA which appears in one image but not the other (really a form of severe
parallax), and even differences in lighting causing shadow differences.

These false matches can "pull" on the solution and create very visible seams.
In order to minimize their effect, the error metric for each overlap (weighted
by the number of pixels) is gathered, and the standard deviation of the error
is computed (technically, we use both +error and -error to keep an
approximately normal distribution).  Then, any overlaps whose metric is
outside the limit is deleted.  The limit is defined by the OUTLIER parameter,
which is multiplied by the standard deviation.  So OUTLIER=3 would reject
3-sigma outliers.

After the overlaps are rejected, the solution is restarted from initial
conditions.  This erases the effect of the rejected overlaps, which could
still cause trouble if we restarted from the solution.  This process is
repeated ITER_OUTLIER times, or until no outliers are rejected.

This process works best with smaller overlap regions.  For this reason, the
RADIUS parameter to marsmap was introduced.  That forces the overlaps to be
no bigger than RADIUS in size, so e.g. a left-right edge would be broken into
several overlap regions.  This limits the effect of troublesome false matches
because such false matches are usually localized; the rest of the seam is
often okay and will still be used with smaller regions.

TBD!!!!  The outlier rejection process does NOT take into account connectivity.
It is quite possible for an image (or block of images) to become disconnected
from the rest of the mosaic during outlier rejection.  This is NOT examined
or otherwise accounted for.  This is the primary reason that some amount of
inertia is recommended.  In the future, outlier rejection should ensure
connectivity via some means.

After the outlier passes are done, the solution will be restarted RECYCLE
number of times.  In each recycle, the previous solution is used for the
initial conditions.  Experience with MARSNAV has shown this to be beneficial.


Normalization and Drift
-----------------------

The overall solution should not "drift".  Ideally the average multiplicative
correction will be 1.0 and the average additive correction will be 0.0.
This helps to preserve some radiometric accuracy.  In addition, something
must be done to counteract the degenerate solution: if all mults are 0 there
will be 0 residual error, even though the result is useless.  Using some
inertia helps to maintain the solution near its ideal state, but supplying
enough inertia to rigorously enforce it does not leave enough room for
adjustment.  Reference images can also help to a limited extent.

Thus there are two other methods available to help preserve this property.

The most important is normalization.  When this is on (the default), the
solution additive and multiplicative factors are modified to force their
averages to be 0.0 and 1.0, respectively.  This is done in a way that
preserves the found solution; it's equivalent to changing the brightness
and contrast of the mosaic as a whole.

The second is called drift adjustment.  When computing the error metric for
the function minimization, drift inserts an extra term.  The add/mult factors
are averaged and differenced from their ideal.  This difference is multipled
by DRIFT_WT (drift weight), squared, and added to the error metric.  The
result is a force that tries to pull the solution into the ideal state by
penalizing the solution when it is not.  Unfortunately, this method did not
work well in testing.  It is believed that the inclusion of this term in the
error does not allow enough flexibility to explore promising directions in the
solution.  Amoeba works by modifying one parameter at a time, and all single-
parameter modifications are "bad" according to drift.  A modification has to
be offset by another parameter in order to keep the drift balanced.  Thus,
disappointing results.  This functionality is retained for experimental use
but should not generally be used.


Reference Images
----------------

As with MARSNAV, one or more images can be designated as "Reference" images.
These images are "fixed" in that they receive no correction (mult=1.0 and
add=0.0).  This "anchor" can also keep the mosaic as a whole from drifting
too far in brightness.

Unlike marsnav, no reference image is automatically assigned. REFIMAGE=-1
will turn off all reference images, but that is also the default state.
REFIMAGE is a list, allowing you to specify a number of reference images
if needed.

In order to accommodate large numbers of reference images, REFIMAGE accepts
negative numbers to represent a range,  For example, the sequence 5,-8 says
that 5,6,7,8 are references.  This shorthand is more convenient than the old
UNTIL parameter.  See the help for REFIMAGE.

See the USAGE section above for suggestions on how reference images can be
used in conjunction with an input BRTCORR file to add images to a mosaic.

Ignored Images
--------------

Sometimes it is desirable to ignore images represented in the overlap file.
This can be accomplished via the IGNORE, IGNORE_INTRA, and IGNORE_PARTIAL
parameters.  Overlaps containing ignored images are removed from consideration.
This is helpful for performance tuning on large runs, but also to eliminate
known bad overlaps (say, where shadows differ or the rover parallax dominates)
without having to edit the overlap file.

A common use case for IGNORE is when refining brightness corrections.  Often
a brightness solution will be obtained, but there are a few frames that don't
quite match the others.  In order to preserve the work already done, set
everything but the bad frames as reference images, and ignore everything but
the bad frames and some of their immediate neighbors.  This prevents spurious
overlaps from dominating the solution.


Overlap File Format
-------------------

The overlap file looks very much like a tiepoint file in structure.  A sample
file:

<?xml version="1.0" encoding="UTF-8"?>
<overlap_file version="1.0">
<overlap_set>
  <images>
    <image unique_id="..." key="0"/>
    ...
  </images>
  <overlaps>
    <overlap type="0" n_images="2" n_pixels="238" radius="250">
      <img key="0" mean="55.321" stdev="1.2335" line="1004.54" samp="53.55"/>
    </overlap>
    ...
  </overlaps>
</overlap_set>
</overlap_file>

As with tiepoint files, the individual <overlap> elements identify images
using a key defined by <image> entries.


Overlap Types
-------------

Currently there are four types of overlap.

0) Mean_Stdev

    <overlap type="0" n_images="3" n_pixels="468" radius="100.000000">
      <img key="29" mean="0.218250" stdev="0.018176" line="282.179460" samp="104
.664452"/>
      <img key="30" mean="0.220311" stdev="0.018180" line="285.170722" samp="102
0.639571"/>
      <img key="31" mean="0.195057" stdev="0.014857" line="2.264217" samp="566.7
62307"/>
    </overlap>

Overlap containing mean and stdev statistics.  Each image participating in
the overlap gets an entry.  "n_pixels" refers to the number of pixels in
the overlap area in the mosaic (thus, it can change based on the zoom factor
when the overlaps are generated).  "radius" simply documents the RADIUS
parameter to marsmap.  The "line" and "samp" entries are optional, and
indicate where in the input image the overlap occurs (in 1-based image
coordinates) and is unaffected by zoom.  The specific point in the overlap
named by these coordinates is not rigorously defined, other than that it
must be part of the overlap.  These fields are really intended for future
use in corrections that vary across the image.

Note, the above example is from an IFF mosaic, so the means are I/F radiance
values rather than typical DN's.

1) Overall

    <overlap type="1" n_images="1" n_pixels="992012" radius="0.000000">
      <img key="893" mean="677.168590" stdev="551.558688" line="0.000000" samp="0.000000"/>
    </overlap>

This overlap type is not really an "overlap" but instead it contains
statistics (mean and standard deviation) about the entire image.  There can
be only one <img> element in this type of overlap.  The line, samp, and radius
attributes are meaningless and are ignored.

2) HSI

    <overlap type="2" n_images="3" n_pixels="2699" radius="200.000000">
      <img key="870" mean="1159.198124" stdev="14.568335" line="38.833518" samp="293.526863"/>
      <img key="872" mean="1663.807538" stdev="43.621013" line="441.286011" samp="650.354704"/>
      <img key="873" mean="1316.756407" stdev="30.641209" line="411.041737" samp="15.104069"/>
    </overlap>

Overlap containing mean and stdev statistics.  This is like Type 0 (Mean_Stdev)
except that instead of considering the raw value of each pixel, we look
at it in Hue-Saturation_intensity (HSI) space.  The pixels (which should be
color, 3-band pixels) are converted to HSI space and then statistics are
gathered on the Intensity value.  If the image is not color, this is treated
the same as type 0.

3) Overall HSI

    <overlap type="3" n_images="1" n_pixels="992012" radius="0.000000">
      <img key="893" mean="677.168590" stdev="551.558688" line="0.000000" samp="0.000000"/>
    </overlap>

Exactly like Overall (type 1) except the values are in HSI space.


Brightness File Format
----------------------

The output file looks very similar to a nav file.  A sample file:

<?xml version="1.0" encoding="UTF-8"?>
<brightness_correction mission="MER:MER2" version="1.0">
  <origination id="rgd" institution="mipl" program="marsbrt">
    <purpose>Brightness correction file for a mosaic
  </origination>
  <priority>
    <entry solution_id="rgd"/>
  </priority>

  <brt_solution solution_id="rgd">
    <image filter="2" frame_id="LEFT" image_id="1000001" instrument="PANCAM_LEFT
" unique_id="MER2PL_297973167"/>
    <correction type="LINEAR">
      <parameter id="ADD" value="-0.000245"/>
      <parameter id="MULT" value="0.898743"/>
    </correction>
  </brt_solution>

  <brt_solution ...>
    ...
  </brt_solution>
  ...
</brightness_correction>

An HSI-space correction looks the same except for the <correction> element.
For example:

...
  <brt_solution solution_id="rgd">
    <image filter="0" frame_id="RIGHT" image_id="3000285024" instrument="MAST_RIGHT" unique_id="MSLMR_403160011"/>
    <correction type="HSI_LIN">
      <parameter id="ADD" value="56.867680"/>
      <parameter id="MULT" value="0.862299"/>
    </correction>
  </brt_solution>
...



HISTORY:

  2010-01    B. Deen - Initial version (derived from marsnav)
  2012-10-10 rgd - Added input BRTCORR parameter
  2013-04-02 rgd - Added HSI space, Overall overlaps, REFIMAGE ranges, IGNORE
  2019-10-02 wlb - IDS-7926 - Initialized some variables; 
		   Commented some unused variables; Added test script and log.
  2020-02-18 wlb - IDS-7927 - Replaced sprintf() calls with snprintf() calls.

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: