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

Keywords: maps, materials, reflectance

== Summary ==
This demo provides a basic example of a reflectance map, which is a tool
that allows the user to use a spectral reflectance cube (perhaps derived
from a calibrated sensor) to define the hemispherical reflectance of a
material.  This is a useful mechanism to incorporate a measured background
into a scene.

== Details ==
A "reflectance map" is a optical property that pulls the hemispherical
reflectance (HR) from a spectral image file.  Although the image file
can be a single band or an RGB image, the primary purpose is to allow
spectral image cubes (10s or 100s of bands) to be used.  The reflectance
data is expected to be an ENVI binary data and header file pair.  The data
should adhere to the following requirements:

* The band centers _should be_ provided in the ENVI header file
  (for example, `wavelength = { 0.400, 0.410 ...}` tag).
** The option exists to specify the band centers with the setup.
* The band units _must be_ microns (for example,
  `wavelength units = Micrometers`).
* The data type doesn't matter as long as it represents hemispherical
  reflectances, which should range from 0 -> 1.
  ** If the user supplies integer or floating point using a range other
     than [0:1], then a linear scaling can be applied (see the `GAIN` and
     `BIAS` options) to scale the values into the expected reflectance
     range.

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

=== Scene Geometry and Materials ===
This scene consists of an infinite ground plane defined in the
`geometry/demo.odb` file that is assigned material label `1`.

The scene contains a two materials that are defined in the
`materials/demo.mat` file:

. Material ID #1 -> Ground reflectance
. Material ID #2 -> Panel reflectance

The key component is the *Surface Properties*. We see the *ImageMapped*
reflectance property being requested, which is what the "reflectance map"
optical property is called.  Inside the property description, the name of
the spectral reflectance image file is provided as well as some options.

==== Ground Reflectance Material ====
The input reflectance cube image is `maps/neon116.img`.  This image
was captured by the airborne NEON image spectrometer.  The image is
101 x 111 with 386 spectral channels.  The original, calibrated spectral
radiance image was converted to a spectral reflectance cube using
calibration data.  The image data is single-precision floating point
and it already adheres to the [0:1] range requirement.

This material can be setup by either manually editing the material database
or by using the *Custom* reflectance property option:

----
MATERIAL_ENTRY {
    ID           = 1
    NAME         = Terrain (Reflectance Map)
    EDITOR_COLOR = 0, 1, 0
    DOUBLE_SIDED = TRUE

    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }

    SURFACE_PROPERTIES {

        REFLECTANCE_PROP_NAME = ImageMapped
        REFLECTANCE_PROP {
            IMAGE_FILENAME = neon116.img
            DRAPE_PROJECTION {
                INSERT_POINT = -50.5, -55.5, 0.0
                GSD = 1.0
                ORIGIN = IMAGE
                FLIPX = FALSE
                FLIPY = FALSE
                EXTENDX = MIRROR
                EXTENDY = MIRROR
            }
            OPTIONS {
                CLIP_VALUES = TRUE
                ENABLE_CACHE = TRUE
            }
        }
    }
}
----

For this material, we are using the "drape projection" (consult the *Maps*
manual for more details).

==== Panel Reflectane Material ====
The second material in this scene is applied to a polygon hovering just
above the ground. It is also assigned a reflectance map, but it uses the UV
projection method.  To use this projection, the panel OBJ file contains UV
coordinates.  The second difference is that the image driving this material
is small (only 5 x 1), contains only a single band and it is stored as 16-bit
unsigned data.  In this case, we have supplied a `GAIN` of `0.0000038147`,
which scales the largest value in the image (65,535) down to a
hemispherical reflectance value of `0.25`.

----
MATERIAL_ENTRY {
    ID           = 2
    NAME         = Panel (Reflectance Map)
    EDITOR_COLOR = 0, 1, 0
    DOUBLE_SIDED = TRUE

    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }

    SURFACE_PROPERTIES {

        REFLECTANCE_PROP_NAME = ImageMapped
        REFLECTANCE_PROP {
            IMAGE_FILENAME = panel_refl.img
            UV_PROJECTOR {
                ORIGIN = IMAGE
                FLIPX = FALSE
                FLIPY = FALSE
                EXTENDX = MIRROR
                EXTENDY = MIRROR
            }
            OPTIONS {
                GAIN = 0.0000038147
                BIAS = 0.0
                CLIP_VALUES = TRUE
                ENABLE_CACHE = TRUE
            }
        } 
    }
}
----


=== Sensor ===
The sensor for the simulation uses a simple, single channel QVGA (320x240)
format camera.  For this simulation, there is no sub-pixel sampling and
we are using the *Raw* capture method to output the spectral radiance at
0.01 micron (10 nm) spectral samples.


=== Atmosphere ===
This simulation uses the uniform atmosphere model with a 100% diffuse
illumination and a spectrally-constant total hemispherical irradiance
of Pi. With the materials being Lambertian and the illumination being
diffuse and with this magnitude, the output "radiance" image is actually
in reflectance.


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

. Run the `demo.sim` file
. Load and observe the output image (see `demo.img`)


== Results ==
The simulated image below shows the output spectral radiance image
displayed using red, green and blue channels.
One of the pixels in the output radiance image is then plotted to show
how the spectral reflectance (of a location containing vegetation) was
correctly incorporated.

.Band #5 from the output of the simulation.
image::images/demo.png[]

.Spectral plot of output radiance for some vegetation captured in the input reflectance image.
image::images/pixel_radiance.png[]

