# ReflectanceMap1

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:

1. Material ID #1 → Ground reflectance

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

1. Run the `demo.sim` file

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

Figure 1. Band #5 from the output of the simulation.
Figure 2. Spectral plot of output radiance for some vegetation captured in the input reflectance image.