# 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:

Figure 1. Original RGB mixture map

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 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:

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:

1. Run the DIRSIG `demo.sim` file

2. 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.

Figure 2. Output RGB image using the "Bandwise min/max scaling".