This set of mini-tutorials forms a cookbook of "recipes" for how to create different material types in DIRSIG.

Important The specific steps outlined in these tutorials are for someone following along on a Windows computer, specifically the pre-configured training computers furnished by RIT at the DIRSIG Basic Training sessions. If you are using a different operating system (Linux or MacOS), then some of the file, locations, suggested programs, etc. will be different. However, the general steps will be the same.

In all cases, the approach to use both the DIRSIG graphical material database editor (mat_edit) and a simple ASCII/Text editor to directly construct the material database entry is provided.

Introduction

A DIRSIG material description is composed of a set of components that are briefly introduced here and are described in greater detail in the recipes forming the rest of this document.

The DIRSIG material database is an ASCII/Text file that contains one or more material descriptions or entries. The general format of the file follows a simple "tagged" section and variable format that dates back to the earliest versions of DIRSIG in the 1990s. Each material description is described in a section, and each component of the material is described in a subsection.

Name and Label

Each material has a name that can be used to describe the material. It is advised that these names be verbose enough to quickly communicate key features or heritage of the material. For example, "Asphalt, fresh, Cooper Rd, Irondiquoit, NY, 2000" is far superior to simply "asphalt".

Each material also has a label or ID, which is a single, alpha-numeric token (no whitespace) that is used to associate the material with geometry in the scene. Prior to DIRSIG 4.7, these were purely numeric, so many of the existing DIRSIG scenes and demos will feature labels (or IDs) that are simply 10, 3267, etc. Today it is advised that labels take advantage of the alpha-numerical support to be verbose enough to sufficiently convey the material type, but it is not as detailed as the name. For example, simply "asphalt_new".

Most materials will also include an Editor Color (a fractional triplet describing an RGB color that was used in the old DIRSIG Bulldozer scene construction application) and a Double Sided flag (a polygon that is labeled as "double sided" can be viewed from both the front and the back). The Bulldozer program has been largely replaced by other tools, and DIRSIG5 assumes that all polygons are double-sided, so these two material attributes are not as important these days. However their associated variables are still considered part of the material file format and should be provided for backward compatibility with DIRSIG4.

The example material file snippet below shows the start of a material entry with the NAME and ID (label), EDITOR_COLOR (a dark gray) and DOUBLE_SIDED variables populated.

MATERIAL_ENTRY {
    NAME = Asphalt, fresh, Cooper Rd, Irondiquoit, NY, 2000
    ID = asphalt_new
    EDITOR_COLOR = 0.1,0.1,0.1
    DOUBLE_SIDED = TRUE
    ...
    [additional components]
    ...
}

Optical Properties

Each material is configured with a set of optical properties that are used to describe how surfaces or volumes assigned that material will reflect, transmit, absorb, emit and/or scatter light. Each optical property type (reflectance, transmittance, etc.) has multiple options to handle spectral, spatial and/or angular dependencies.

At this time, the cookbook is focused on surface (not volume) materials, which can have the following properties assigned:

Reflectance

Options are available to use spectral hemispherical reflectance, directional hemispherical reflectance (DHR) and bi-directional reflectance distribution functions (BRDFs).

Transmittance

Options are available to use spectral hemispherical transmittance and bi-directional transmittance distribution functions (BTDFs).

Emissivity

Options are available to use a spectral hemispherical emissivity.

The model will attempt to honor conservation of energy and reciprocity whenever possible, and alert the user when not possible. Therefore, a user can provide a surface material a hemispherical reflectance and the model will derive a hemispherical emissivity when needed. Furthermore, the user can provide a BRDF and the model will derive a directional hemispherical emissivity (DHE) by hemispherically integrating the BRDF at a given view geometry to get a directional hemispherical reflectance (DHR) and compute the DHE as 1 - DHR.

The optical properties for a surface (not a volume) are defined in the SURFACE_PROPERTIES section of the material entry. Each optical property type (reflectance, transmittance, etc.) is described by a subsection within this section.

MATERIAL_ENTRY {
    NAME = Asphalt, fresh, Cooper Rd, Irondiquoit, NY, 2000
    ID = asphalt_new
    EDITOR_COLOR = 0.1,0.1,0.1
    DOUBLE_SIDED = TRUE
    SURFACE_PROPERTIES {
        ...
        [one or more properties]
        ...
    }
}

A list of the available optical properties and how to configure them in the material file is available in the Surface Properties Manual.

Thermal Properties

The second major component of a material is the temperature solver (the algorithm responsible for computing the temperature of the geometry that material is assigned to) and the parameters for that solver (typically, thermodynamic properties including the thermal conductivity, heat capacity, etc.). For more information on temperature solvers consult the Temperature Solver Manual.

Because a large number of users utilize DIRSIG only in the reflective regions of the EO spectrum, the temperature solver and parameters are not a required part of the material description. This initial version of the material cookbook is focused on materials for the reflective region and does not discuss thermal configuration at this time.

Radiometry Solver

The DIRSIG4 model leveraged a light transport mechanism that could be custom configured on a material by material basis. The material component responsible for how energy was reflected, transmitted and emitted was referred to as the radiometry solver (or rad solver for short). This cookbook is intended for use with DIRSIG5, so an explanation of rad solvers and how to configure them is not included here. However, to maintain backwards compatibility, the rad solver configuration is still a required component of a material description. For all the recipes presented here, the "Simple" rad solver will be used with the "low" quality setting. For more information on advanced configuration of rad solvers consult the DIRSIG4 Radiometry Solver Manual.

MATERIAL_ENTRY {
    NAME = Asphalt, fresh, Cooper Rd, Irondiquoit, NY, 2000
    ID = asphalt_new
    EDITOR_COLOR = 0.1,0.1,0.1
    DOUBLE_SIDED = TRUE
    SURFACE_PROPERTIES {
        ...
    }
    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }
}

Making a Lambertian Reflector

One of the most common material configurations is a material described by a single, spectral, hemispherical reflectance curve. This mini-tutorial will walk through the steps to download spectral reflectance data from a specific source, but the general approach can be adapted to use data from any source. The process for configuring this type of material is:

  1. Acquire the spectral reflectance as an ASCII/Text, two column file of wavelength (column #1, in microns) and reflectance (column #2, as a fraction) pairs, and

  2. Configure a material with the "Simple Reflectance" property that will read this ASCII/Text reflectance file.

For this mini-tutorial, we will use a spectral reflectance curve from a database created by the USGS Spectroscopy Lab. Specifically, the USGS Spectral Library Version 7 includes spectral characterizations of materials compiled over 20 years of operating laboratory, field, and airborne spectrometers. The database contains nearly 2,500 measurements including high spectral resolution reflectance data and data weighted and resampled to match popular multi-spectral sensors (including ASTER, Landsat-8 OLI, Sentinel-2 MSI, and WorldView-3) and hyper-spectral sensors (include AVIRIS, HyMap and Hyperion). The material we are going to use is a light green, painted aluminum. This material can be found by searching for "painted_aluminum" or the sample identifier "GDS333" (the following search URL will go directly to this material in the database: https://crustal.usgs.gov/speclab/QueryAll07a.php?quick_filter=GDS333)

Tip If you do not have internet access to the USGS database, or do not have acces to an appropriate program to merge downloaded data into a single, two-column file, a copy of the final usgs_painted_aluminum_GDS333.txt file can be downloaded here.

The search results will include a description of the material, which will include where the sample came from, how the data was collected, and (in most cases) an image of the sample. The results will also include links to plots of the spectral data. The plot below shows the full spectral coverage of the measurement for this painted aluminum sample:

splib07a Painted Aluminum GDS333 LgGr ASDFRa AREF
Figure 1. Plot of the spectral reflectance from the USGS Spectral Library website.

Importing the Measurement

Downloading the Measurement ZIP File

Clicking on the ZIP file link will download the spectral measurement and some meta-data (README, image of the sample, data plots as images, etc.). If you are asked where to save the ZIP file, choose an appropriate temporary location. On Windows, this typically defaults to your Downloads folder.

Unpacking the Measurement ZIP File

We are going to unpack (unzip) the measurement into a folder using the standard features of Windows File Explorer.

  • ❏ On your Desktop, create a new folder named USGS Painted Aluminum.

  • ❏ Double-click the splib07a_Painted_Aluminum_GDS333_LgGr_ASDFRa_AREF.zip file that was (most likely) saved into your Downloads folder. This should open the ZIP file like any other folder on the computer.

  • ❏ Select all the files in the ZIP folder (Ctrl+A or using the mouse) and drag this file selection to your Desktop/USGS Painted Aluminum folder.

measurement folder
Figure 2. The measurement folder extracted from the ZIP file.

Merging the Wavelengths and Reflectance

The extracted measurement folder contains several files, but the two we are primarily interested in are:

splib07a_Painted_Aluminum_GDS333_LgGr_ASDFRa_AREF.txt

This is a single-column, ASCII/Text file containing the reflectance data for the sample.

splib07a_Wavelengths_ASD_0.35-2.5_microns_2151_ch.txt

This is a single-column, ASCII/Text file containing the wavelengths corresponding to the reflectance measurements.

The optical property we are going to use in DIRSIG expects to be provided a two-column, ASCII/Text file representing wavelength and reflectance data pairs. Hence, we need to merge these two single-column files into a single, two-column file. There are a variety of ways to perform this task, but for this tutorial we will use a spreadsheet application to read each file and then merge the two columns into a single file. Most users will have access to an office suite application such as Microsoft Office, Google Docs, etc. On the RIT training computers, we have LibreOffice installed, which is a quality free and open-source office suite.

Tip On UNIX/LINUX and MacOS, the paste tool can perform this line-by-line merge directly from the command-line.

To merge the two ASCII/Text files and save it as a single, two-column text file using LibreOffice, perform the following steps:

  • ❏ Start the main LibreOffice application using the icon on the Desktop.

  • ❏ Click the Calc Spreadsheet icon in the Create panel on the left side of the main application window.

  • ❏ To open the wavelength data file, select the File → Open menu option, navigate to your Desktop/USGS Painted Aluminum folder, select the splib07a_Wavelengths_ASD_0.35-2.5_microns_2151_ch.txt file and click the Open button.

  • ❏ The Text Import dialog window will appear to help parse this text file. The only change on this dialog is to set the From row: value to 2 so that we skip over the comment line at the top of the file. Click the OK button to complete the import.

text import dialog
Figure 3. The LibreOffice Text Import dialog.

  • ❏ To open the reflectance data file, select the File → Open menu option, navigate to your Desktop/USGS Painted Aluminum folder, select the splib07a_Painted_Aluminum_GDS333_LgGr_ASDFRa_AREF.txt file

  • ❏ Once again, the Text Import dialog window will appear to help parse this text file. The only change on this dialog is to set the From row: value to 2 so that we skip over the comment line at the top of the file. Click the OK button to complete the import. This will open a second spreadsheet window containing the reflectance data.

two sheets
Figure 4. The two, single-column data files open in the LibreOffice spreadsheet program.

We now have two spreadsheets containing the single-column data. To merge them into one, two-column sheet copy and paste the reflectance data from the second sheet into the second column of the wavelength data sheet:

  • ❏ Right-click on the A column header in the splib07a_Painted_Aluminum_GDS333_LgGr_ASDFRa_AREF.txt window and select the Copy item from the popup menu.

  • ❏ Right-click on the B column header in the splib07a_Wavelengths_ASD_0.35-2.5_microns_2151_ch.txt window and select the Paste item from the popup menu.

single sheet
Figure 5. The wavelength and reflectance data merged into a single, two-column sheet.

We now want to save that file as an ASCII/Text file that DIRSIG can read. DIRSIG expects the data to be in a whitespace (space, tab, etc.) delimited ASCII/Text file. To achieve this, we will use the Text CSV save option in LibreOffice and modify the standard CSV formatting parameters to use a tab as a delimiter and to skip wrapping each data value with quotes:

  • ❏ Select the File → Save As menu item.

  • ❏ Make sure the destination folder is your Desktop/USGS Painted Aluminum folder.

  • ❏ Change the File name: to usgs_painted_aluminum_GDS333.txt

  • ❏ Change the Save as type: to Text CSV (*.csv)

  • ❏ Click the Edit filter settings option

save as dialog
Figure 6. The lower portion of the LibreOffice Save File dialog.

  • ❏ Click the Save button

  • ❏ A Confirm File Format dialog will appear asking you to confirm you want to save to the Text CSV format. Click the Use Text CSV Format button.

  • ❏ The Export Text File will then appear. Set the Field delimiter to {Tab} from the dropdown menu. Set the String delimiter to blank. Click the OK button to complete the export.

text export dialog
Figure 7. The LibreOffice Export Text File dialog.
Important If the Export Text File dialog does not appear, you forgot to select the Edit filter settings option on the Save dialog window.

At this point you have a two-column file that can be used to drive a basic spectral reflectance optical property in DIRSIG.

Tip If you do not have internet access to the USGS database, or do not have acces to an appropriate program to merge the two single-column files into a single, two-column file, a copy of the final usgs_painted_aluminum_GDS333.txt file can be downloaded here.

Creating the Material

To create the material that will be driven by the spectral reflectance data we just downloaded and formatted, we will use the DIRSIG graphical material database editor.

Starting the Material Editor

To get started, launch the mat_edit program using one of the following methods:

  • On Windows, using the Material Editor item in the DIRSIG Start sub-menu,

  • From the Tools menu in the DIRSIG Simulation Editor, or

  • From the command-line as mat_edit

mat edit
Figure 8. The material editor interface without any materials loaded.

The left side of the application is the Material List. When a database is loaded, the ID and Name of materials will appear there. The right side of the application is the editor interface for the currently selected material. The myriad of material components are accessed through a set of tabs.

Loading an Existing Database (optional)

If you are adding a new material to an existing database, then use the File → Open menu item to navigate to and open the existing database.

Creating a New Material

To create a new material in the database:

  • ❏ Click the Add Material button below the material list panel on the left side of the window.

  • ❏ The Add Material dialog will appear asking you what type of material to create. Select the Surface material type and click the OK button to create a new, surface material.

mat edit new mat
Figure 9. The Add Material type dialog.
mat edit summary0
Figure 10. The material editor with a new material added.

The right panel will populate with the default parameters for a new material. We will begin by giving this material a useful ID (label) and Name. As we explained in the overview of this cookbook, we will also make sure the Double Sided flag is enabled.

  • ❏ Set the ID to painted_aluminum

  • ❏ Set the Name to USGS Painted aluminum, GDS333, Light green

  • ❏ Click the Double Sided checkbox

mat edit summary1
Figure 11. The new material summary after initial setup.

Setting up the Reflectance Property

The next step is to setup the reflectance property for this material.

  • ❏ Select the Surface Props tab

  • ❏ Select the Reflectance sub-tab

  • ❏ Choose the Simple Reflectance model from the Reflectance Property dropdown menu

  • ❏ Click the Browse icon next to the Text Filename, navigate to the usgs_painted_aluminum_GDS333.txt file you created earlier, and click the Open button to select it

mat edit simple refl
Figure 12. The simple reflectance property configuration.

You might be asking "What about the Emissivity and Transmittance properties?" For this simple material, we are only configuring the reflectance property. The transmittance is assumed to be zero (t = 0) and the emissivity (when needed) will be computed as e = 1 - t - r or e = 1 - r (since t = 0), where r is the reflectance.

Setting up the Radiometry Solver

As we mentioned earlier, DIRSIG5 no longer uses the radiometry solver light transport architecture that DIRSIG4 was built upon. However, for compatibility purposes a radiometry solver is still a required component by the material database reader. The Simple radiometry solver using the LOW was the recommended radiometry solver configuration for general materials in DIRSIG4.

  • ❏ Select the Rad Solver tab

  • ❏ Select the Simple solver from the Radiometry Solver dropdown menu

  • ❏ Select the Low setting from the Quality dropdown menu

mat edit rad solver
Figure 13. The simple radiometry solver configuration.

The Material Summary

The configuration of the material is now complete. Return back to the Summary tab and the text summary in the lower panel of the right-side editor should indicate that the Simple radiometry solver and the Simple reflectance property are configured for this material.

mat edit summary2
Figure 14. The summary tab of the completed material.

Saving the Material

At this point you have successfully created a new material in the database. To save the database with the new material:

  • ❏ Select the File → Save menu item, or

  • ❏ Click the Save icon in the toolbar.

  • ❏ Save your material database as Desktop/B737_300/B737_300.mat.

The Final Material Entry

Although the graphical tool is helpful for navigating the process to create a new material, experienced users might opt to directly edit the material database file, or might construct scripts to automatically generate material database entries.

The material file entry below reflects the configuration that was created in the graphical material editor.

MATERIAL_ENTRY {
    NAME = USGS Painted aluminum, GDS333, Light green
    ID = painted_aluminum
    EDITOR_COLOR = 0.4,0.5,0.5
    DOUBLE_SIDED = TRUE
    SURFACE_PROPERTIES {
        REFLECTANCE_PROP_NAME = SimpleReflectance
        REFLECTANCE_PROP {
            TXT_FILENAME = usgs_painted_aluminum_GDS333.txt
        }
    }
    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }
}

Your material database is now ready to be used.