Help for MARSDEBAYER

PURPOSE:

MARSDEBAYER removes the Bayer pattern from a color CCD image, such as
used with the MSL cameras Mastcam, MAHLI, and MARDI.  The result is a
three-band color image.

The Bayer pattern is a method of making a color CCD where each pixel is
supplied with an individual red, green, or blue filter.  These filters are
arranged in a 2x2 pattern that repeats across the image:

   R  G
   G  B

making a larger image look like:

   R  G  R  G  R  G
   G  B  G  B  G  B
   R  G  R  G  R  G
   G  B  G  B  G  B
   R  G  R  G  R  G
   G  B  G  B  G  B

Thus each 2x2 cell has one red, one blue, and two green pixels.

The output can be a single 3-band image, or three individual 1-band images.
What's in the output is determined by the ZOOM_MODE parameter.  The possible
values are:

* NORMAL - No zooming; the output is the same size as the input.  For Red
  and Blue, there is only one-quarter of the data necessary; for Green there
  is only half the data.  The rest is filled in according to the INTERP keyword.
  This is the mode that is used onboard by the MSL MMM cameras.

* HALF_SCALE - The output is half the size of the input.  Each Bayer cell
  this corresponds to a single pixel in the output.  The Green cells are
  oversampled by 2x; they are averaged to produce the output value.

* UPPER - Like HALF_SCALE, but only the "upper" of the two Green pixels is used
  in each Bayer cell, with no averaging.

* LOWER - Like HALF_SCALE, but only the "lower" of the two Green pixels is used
  in each Bayer cell, with no averaging.

* TALL - The result has the same vertical size as the input, but half the
  horizontal size.  This changes the aspect ratio by a factor of 2.  This
  preserves all the Green pixel data without replication.  The Red and Blue
  pixels are doubled per the INTERP parameter.

* AVERAGE - No de-Bayering is done, but the 4 pixels in each Bayer cell are
  averaged together.  The output is thus a single one-band file at half scale
  compared to the input.

* NONE - No de-Bayering is done; the output is a single one-band file looking
  the same as the input.  This mode could be useful to extract a subframe from
  an image (potentially not even a Bayer pattern image) while keeping the
  camera model correct.  It is also useful to process images from filters
  where the Bayer pattern effectively disappears (e.g. the MSL Mastcam infrared
  filters).  In this mode, the new-style labels write "IDENTITY" as the
  Bayer method, indicating the image no longer has the Bayer pattern (even
  though the operation was a no-op).

For 3-band output modes, a single band can be selected for output if desired.

In addition, the SL/SS/NL/NS parameters can be used to subframe the image,
pulling out only the selected section.  Note: the subframe parameters apply
to the coordinates of the original image, before any resizing is done.

In all cases, the camera model in the label is updated to reflect the new
geometry.

EXECUTION:

marsdebayer inp=bayer.vic out=color.vic

where:
bayer.vic is the input 1-band image with the Bayer pattern
color.vic is the output 3-band color image (of the same size, in this example)

METHOD:

The algorithm itself is trivial.  If the geometry changes, either due to a
zoom or subframe, then the PIG library is used to adjust the camera model
in the label and rewrite it.  In addition, the downsample and/or subframe
parameters in the label are updated, so that future reconstructions of the
camera model from kinematics (e.g. for mosaic pointing correction) will still
work properly.

The MALVAR interpolation algorithm demosaics the image based on convolution
matrices developed by Malvar, He, and Cutler at Microsoft.  The advantage
of using the MALVAR bilinear interpolation method is that for every pixel, 
the neighboring known color pixels are used in the interpolation estimate 
instead of being discarded.  The interpolation is corrected by measuring
the gradient for the known color at the pixel location.  A gain factor is 
then used to control how much of the measured gradient correction is applied.
The algorithm and matrices are described in detail in their paper:  

H.S. Malvar, Lei-Wei He, R. Culter, "High-Quality Linear Interpolation for 
Demosaicing of Bayer-Patterned Color Images", IEEE International Conference on
Acoustics, Speech, and Signal Processing Volume 3. (2004)

http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=1326587

Output Labels

Two label modes are supported: old-style and new-style.

If BAYER_MODE is in the input file, old-style is used.  This replaces the
BAYER_MODE value with one of the following:

MIPL_REPLICATED
MIPL_AVERAGED_COLOR
MIPL_UPPER
MIPL_LOWER
MIPL_TALL_REPLICATED
MIPL_AVERAGED_MONO
MIPL_INTERPOLATED
MIPL_MALVAR_INTERPOLATED

BAYER_MODE is used in MSL (MMM cameras) but has been deprecated in newer
missions (InSight, 2020, MSAM).  If BAYER_MODE is not in the input file,
new-style is used.  This sets CFA_VENUE to GROUND, and sets BAYER_METHOD
to one of the following:

MALVAR
BILINEAR
RED_BILINEAR
GREEN_BILINEAR
BLUE_BILINEAR
AVERAGED
RED_AVERAGED
GREEN_AVERAGED
BLUE_AVERAGED
PANCHROMATIC
IDENTITY
OTHER

If one were to replicate what the MSL Mastcam camera does onboard, the
parameters to use depend on the filter:

L0: -malver
L1: -green
L2: -blue
L3: -red
L4: -red
L5: -none
L6: -none
L7: -none
R0: -malvar
R1: -green
R2: -blue
R3: -red
R4: -none
R5: -none
R6 :-none
R7: -blue


HISTORY:
  2011-10-06 rgd - Initial version
  2014-10-02 nar - Added MALVAR demosaicking algorithm
  2015-05-18 nar - Bug fix
  2015-08-11 nar - Added multiplicative factor, rotation, and offset parameters
  2016-03-14 nar - Bug fix
  2018-01-25 rgd - Added BAYER_METHOD support, fix downsample bug, add ONLY_BAND
  2019-10-02 Walt Bunch - IDS-7926 - Initialized some variables.
             Commented unused variables. Added test script and log.

COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: