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.

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


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
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: