MixtureMap1
===========

Keywords: mixture map, fraction map

== Summary ==
This demo utilizes a mixture (or fraction) map to describe the materials
on a terrain.  The original map was created in Maya and stored as an RGB
image, where the three 8-bit channels encoded the relative contribution
of three materials at each location.  This 24-bit mixture image was
converted to a 3 band, floating-point image that DIRSIG expects as input.

== Details ==
Mixture maps (sometimes referred to as _fraction maps_) are similar to a
material map because they are used to define the material properties at
a given location. The primary difference is that a material map defines
a single material at each location and a mixture map defines the relative
proportions of several materials at each location. Mixture maps are
created from remote sensing data using a class of algorithms called 
"unmixing algorithms" that work with a constrained set of materials
and attempt to optimize the relative weights of those materials to
reproduce the multi-spectral or hyper-spectral signature of the pixel.

The mixture map utilized in this demo was produced by a 3D content 
creator using tools that synthesize terrain (perhaps using fractal
generation, erosion, etc.  techniques). The relative proportions of the
grass, dirt and rock featured in the map were computed using the terrain
so that steep areas would be rock, lower areas would be grass, eroded
gullies would be dirt, etc.  The original 24-bit, RGB mixture image
supplied by the 3D asset creator is shown below.  The red, green and
blue channels indicate the relative contributions of grass, dirt and
rock at each location:

.Original RGB mixture map
image::geometry/bundles/terrain/Mixture_Map.png[width=512]

Since this demo uses an RGB image, the setup is limited to only 3
materials.  But a traditional mixture map cube produced from remote
sensing image data might define the mixture of much more than 3 materials.

== Important Files ==
This section highlights key files important to the simulation.

=== Converting the mixture image ===
Since DIRSIG expects the image supplied as a mixture map input to be 
a binary, floating-point image cube containing fractions (range 0 - 1),
the original 24-bit RGB image needs to be converted.  This can be
easily performed using the *gdal_translate* utility provided in the
http://www.gdal.org[GDAL] toolbox:
----
$ gdal_translate -scale 0 255 0 1 -ot float64 -of envi -co INTERLEAVE=BIP -co SUFFIX=ADD Mixture_Map.png Mixture_Map.img
----

The `-scale` option says to scale the input [0,255] range down to [0,1].
The `-ot` (or "output type") option says to make the output 64-bit floating
point.  The `-of` (or "output format") option says to make the output file
an ENVI image/header pair. The various `-co` (or "conversion options") say
to make the output binary data to be "band interleaved by pixel" (rather
than "band sequential") and to add the `.hdr` suffix to the binary image
file to create the header filename. The input 24-bit, PNG mixture image is
`Mixture_Map.png` and the output ENVI file is `Mixture_Map.img` (and
`Mixture_Map.img.hdr`).

=== Organizing the geometry bundle ===
This simulation uses the "bundled" object approach for the terrain.  That
means all the geometry, materials, maps, etc. are contained in a single
folder that can be easily migrated to another scene (see the
*BundledObject1* and *BundledObject2* demos for more details).  The various
files for the terrain bundle can be found in `geometry/bundles/terrain`.

The original geometry for the terrain is `Mesh.obj`, but that file has been
scaled and centered to make it more appropriately sized and positioned for
use in the scene using the *object_tool* utility included with DIRSIG:
----
$ object_tool --input_filename=Mesh.obj --autocenter --scale=4 --geometry --materials --output_filename=terrain.obj
Reading input OBJ file ... 
Reading in geometry file: Mesh.obj
    Part count   = 1
    Facet count  = 50562
    Vertex count = 25600

Center object tool:
    Computing object extents ... done.
    Translating object ... done.
Scale object tool:
    Scaling vertexes ... done.
Geometry summary tool:
    Triangle count = 50562
    Vertex count = 25600
    Minimum = -532.090, -532.090, 0.000
    Maximum = 532.090, 532.090, 201.873
    Size = 1064.181 x 1064.181 x 201.873 [m]

Material summary tool:
    lambert3SG (assigned to 50562 facets)

Writing output OBJ file ... done.
----

Note that the terrain is now about 1 km x 1 km in side with 200+ meters of
elevation and the surface was assigned the material label `lambert3SG` by
the original creator. This material label will be used to associate the
mixture map with the terrain later.

The next step is to create the GLIST file for the bundle.  This file can
be found as `terrain.glist` in the bundle folder:
----
<geometrylist>
  <object search_paths="local">
    <localmaterials>terrain.mat</localmaterials>
    <basegeometry>
      <obj swapyz="false">
        <filename>terrain.obj</filename>
      </obj>
    </basegeometry>
    <staticinstance/>
  </object>
</geometrylist>
----

=== Setting up the mixture map ===
The bundle GLIST indicates the name of the material database file will be
`terrain.mat`, which is where we will associate the mixture map with the
terrain and define the 3 materials utilized by the mixture map.
The key material label (or ID) to define is `lambert3SG` because that
is what is assigned to the terrain geometry (as noted in the output of
the *object_tool* earlier).  This material description will need to be
hand-crafted (because the graphical material editor cannot perform these
tasks):

----
MATERIAL_ENTRY {
    ID           = lambert3SG
    NAME         = Terrain (mixture map)
    EDITOR_COLOR = 0.000000, 0.000000, 0.500000
    DOUBLE_SIDED = TRUE

    MIXTURE_MAP {
        NAME = Terrain Map
        ENABLED = TRUE
        IMAGE_FILENAME = Mixture_Map.img
        UV_PROJECTOR {
            ORIGIN = CARTESIAN
            FLIPX = FALSE
            FLIPY = FALSE
            EXTENDX = MIRROR
            EXTENDY = MIRROR
        }
        BAND_MATERIAL_LABELS = grass,dirt,rock
    }
}
----

The map uses the UV projector because the terrain OBJ file contains texture
coordinates. The Cartesian origin option is used because that was the
system used by the original asset creator to link the UV texture
coordinates to the mixture map image. This might vary based on the source 
of the asset.

The `BAND_MATERIAL_LABELS` variable indicates that the fractions in the
3-band image indicate the relative fractions of materials with the labels
`grass`, `dirt` and `rock`.

NOTE: Material labels (or IDs) were historically numerical only, but
      the DIRSIG 4.7 release cycle introduced alpha-numeric labels. We
      use those here for clarity, but you can use numbers for labels as
      well.

The asset creator also produced RGB texture images for the three
materials mixed by the map. These input RGB textures are shown below:

image:geometry/bundles/terrain/grass.png[width=256]
image:geometry/bundles/terrain/dirt.png[width=256]
image:geometry/bundles/terrain/rock.png[width=256]

Recall that DIRSIG is inherently a spectral model and that these
RGB textures are great for RGB visualization, but they don't define
the spectral reflectance like we would want in an ideal world. That
being said, DIRSIG does have a way to take an RGB image and use it to
coarsely define the spectral reflectance of a material. The *RgbImage*
reflectance property converts the RGB values in a given pixel into
Lambertian reflectances at 0.650 microns (red channel), 0.55 microns
(green channel) and 0.450 microns (blue channel). The spectral reflectance
is linearly interpolated between those 3 defined wavelengths and flat
extrapolate outside of that wavelength window.  The configuration for
the *RgbImage* property for the "rock" material is shown below:

----
MATERIAL_ENTRY {
    ID           = rock
    NAME         = Rock (RGB mapped)
    EDITOR_COLOR = 0.000000, 0.000000, 0.500000
    DOUBLE_SIDED = TRUE

    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }

    SURFACE_PROPERTIES {
        REFLECTANCE_PROP_NAME = RgbImage
        REFLECTANCE_PROP {
            IMAGE_FILENAME = Rock.png
            SCALE = 0.00392157
            UV_PROJECTOR {
                ORIGIN = IMAGE
                FLIPX = FALSE
                FLIPY = FALSE
                EXTENDX = MIRROR
                EXTENDY = MIRROR
            }
        }
    }
}
----

Note that the label (see the `ID` variable) is set to `rock` because that
was one the labels defined in the mixture map.

The `SCALE` variable is used to define how the RGB values are converted
into hemispherical reflectances.  The supplied value of `0.00392157`
would mean a value of `255` would get converted to a total hemispherical
reflectance of `1.0`. Since a really bright (highly reflective) material
in the real world is usually closer to a total reflectance `0.3` of, this
`SCALE` is not necessarily realistic.

The configuration of the remaining two materials (`grass` and `dirt`)
are similarly defined in `terrain.mat`.


== Setup ==
This section includes any step-by-step instructions for running and
visualizing the simulation.

To run the simulation, perform the following steps:

. Run the DIRSIG `demo.sim` file
. Load the resulting `demo.img` radiance file in the image viewer.


== Results ==
The output of the simulation is a 320x240 image from a nadir viewing
perspective.

.Output RGB image using the "Bandwise min/max scaling".
image::images/demo.png[]
