BayerPattern2
=============
:stem: latexmath
:source-highlighter: highlight.js

Keywords: bayer, truesense, color filter array

== Summary ==
This demonstration uses an advanced feature in the DIRSIG5 *BasicPlatform*
plugin to simplify the setup of color filter array (CFA) focal planes.  In
this case, the two currently supported CFA patterns are shown: (1) the
classic, 3-color RGB Bayer pattern and (2) the 4-color, Pan+RGB Truesense
pattern.

NOTE: This feature is not supported by the graphical platform editor. It
      requires hand-editing the platform file and an open/save cycle in
      the graphical platform editor will effectively erase the setup.

== Related Materials ==
The following demos, manuals and tutorials can provide additional
information about the topics at the focus of this demo:

* Related Demos
** The http://www.dirsig.org/demos/index.html#BayerPattern1[BayerPattern1] demo.
* Related Manuals
** The http://www.dirsig.org/docs/new/basicplatform_plugin.html#CfaPatterns[BasicPlatform] plugin manual.
* Related Tutorials
** N/A


== Details ==

=== Platform ===
The `<channelpattern>` element inside the `<spectralresponse>` of each
`<focalplane>`.  The `name` attribute for the `<channelpattern>` element
defines which pattern to use and the elements inside this element define
the mapping from an internally defined set of named filters to a set of
named channels.

==== Bayer Pattern
The `bayer.platform` file contains the classic Bayer filter pattern
that was invented by Bryce E. Bayer at Eastman Kodak in 1976
(https://worldwide.espacenet.com/textdoc?DB=EPODOC&IDX=US3971065[U.S. patent 3971065])
and is commonly used in many consumer electronics.  This pattern utilizes
a 3-color pattern with red, green and blue filters.

.The classic, 3-color Bayer pattern.
image::images/bayer_pattern.png[width=300]

Therefore, it expects the user to tell it the names of the channel
responses that should be mapped to those three filters.  The focal
plane consists of a spectral response that defines 3 channels (`RED`,
`GREEN` and `BLUE`) and the "channel pattern" that defines the
mapping from the internal Bayer pattern filter names to these channel
names.

* Bayer `red` filter -> `RED` channel
* Bayer `green` filter -> `GREEN` channel
* Bayer `blue` filter -> `BLUE` channel

NOTE: This explicit mapping from logical (internal) filter names to the
      user-defined channel names allows the user to name channels something
      more specific or to even utilize different channels than the original
      filter pattern was intended for (for example, use an "orange" channel
      in place of the normal "red" channel).

[source,xml]
----
              <spectralresponse>
                <channellist>
                  <channel name="RED">
                    ...
                  </channel>
                  <channel name="GREEN">
                    ...
                  </channel>
                  <channel name="BLUE">
                    ...
                  </channel>
                </channellist>
                <channelpattern name="bayer">
                  <mapping filtername="red" channelname="RED"/>
                  <mapping filtername="green" channelname="GREEN"/>
                  <mapping filtername="blue" channelname="BLUE"/>
                </channelpattern>
              </spectralresponse>
----

NOTE: The channel names are not important, as long as the names specified
      when the channels are defined are used in the mappings.  For example,
      the "RED" channel could have been named "R", "red", "red4" or even
      "COW", "david", etc.

In the example platform files included here, the channels are simple
rectangular passband shapes, but measured (tabulated) channels could be
used.


==== Truesense Pattern
The `truesense.platform` file contains a Truesense filter setup, which
was invented by Eastman Kodak in 2010.  This pattern utilizes a 4-color
pattern with pan, red, green and blue filters.

.The 4-color Pan+RGB Truesense pattern.
image::images/truesense_pattern.png[width=300]

Similar to the Bayer setup, it expects the user to
tell it the names of the channel responses that should be mapped
to those four filters.  The focal plane consists of a spectral
response that defines 4 channels (`Pan`, `Red`, `Green` and `Blue`)
and the "channel pattern" that defines the mapping from the internal
Truesense pattern filter names to these channel names.

* Truesense `pan` filter -> `Pan` channel
* Truesense `red` filter -> `Red` channel
* Truesense `green` filter -> `Green` channel
* Truesense `blue` filter -> `Blue` channel

NOTE: This explicit mapping from logical (internal) filter names to the
      user-defined channel names allows the user to name channels something
      more specific or to even utilize different channels than the original
      filter pattern was intended for (for example, use an "orange" channel
      in place of the normal "red" channel).

[source,xml]
----
              <spectralresponse>
                <channellist>
                  <channel name="Pan">
                    ...
                  </channel>
                  <channel name="Red">
                    ...
                  </channel>
                  <channel name="Green">
                    ...
                  </channel>
                  <channel name="Blue">
                    ...
                  </channel>
                </channellist>
                <channelpattern name="truesense">
                  <mapping filtername="pan" channelname="Pan"/>
                  <mapping filtername="red" channelname="Red"/>
                  <mapping filtername="green" channelname="Green"/>
                  <mapping filtername="blue" channelname="Blue"/>
                </channelpattern>
              </spectralresponse>
----


=== Scene ===
For the scene, an RGB map defines a white background with some black
text and a set of red, green and blue panels.

.The RGB image used to define the input scene.
image::maps/map.png[width=640]


== Setup ==
Since the CFA setups in the platform file are not supported by the
graphical platform editor, it is suggested you run the simulations
from the command line:

. Run `dirsig5 bayer.sim`, which will produce `bayer.img` image file
  as the primary output.
. Run `dirsig5 truesense.sim`, which will produce `truesense.img` image
  file as the primary output.


== Results ==
The output of the simulation is a raw pixel stream.  The *ENVI*
image header indicates that both files are single band images.
Although the focal plane measured multiple colors, it did so by
using different filters on different pixels.  It does _not_ measure
all 3 (or 4) colors at every pixel.  Hence, the color information
is mosaic'ed within the array and a demosaicing algorithm must be
employed to create a 3-color RGB image.

.The built-in *Image Viewer* with the single-band, mosaiced output images loaded.
image::images/image_viewer_list.png[width=320]

=== Mosaiced Bayer CFA Image
The image below shows the Bayer CFA raw radiance image produced by
DIRSIG in the DIRSIG *Image Viewer* tool (note the *ENVI* image
header was modified as described above in order to display the raw
data in this 320 x 240 format).  Notice that the Bayer pattern is
visible in the zoom of the color panels.

.The output image from the Bayer CFA has the RGB colors mosaic'ed into a single channel.
image::images/bayer_raw.png[width=640]


=== Mosaiced Truesense CFA Image
The image below shows the Truesense CFA raw radiance image produced
by DIRSIG in the DIRSIG *Image Viewer* tool (note the *ENVI* image
header was modified as described above in order to display the raw
data in this 320 x 240 format).  Notice that the Truesense pattern
is visible in the zoom of the color panels.

.The output image from the Truesense CFA has the Pan+RGB colors mosaic'ed into a single channel.
image::images/truesense_raw.png[width=640]


== References ==
* A survey of demosaic algorithms for Bayer Pattern focal planes
  can be found at: http://www.unc.edu/~rjean/demosaicing/demosaicing.pdf

