This document describes the DIRSIG material database file.

Summary

All materials used within a scene are defined within a single database referenced from the scene file. A material is considered to be a single class of physical substance (such as healthy grass or concrete) and contains the optical and thermal properties relevant to performing radiometry calculations associated with the material. This document describes the general structure of the material database file (usually denoted with a .mat extension) and the types of materials that can be defined.

Related Materials

The following demos, manuals and tutorials can provide additional information related to this plugin:

Format Overview

The material database uses an older ASCII/Text "tag+value" format that was introduced in DIRSIG3 (in contrast to the formal XML or JSON formats used in current versions of DIRSIG). Careful attention should be paid to the formatting of each entry. A GUI editor is distributed with DIRSIG to facilitate creation and modification of materials.

A Variable

A variable in a DIRSIG "tag+value" format file is composed of a variable name and an assigned value. A variable can be assigned a string, a number, etc.

ANIMAL = Dog

A Section

A section in a DIRSIG "tag+value" format file is composed of a section name and an open/close pair of curly brackets. A section can contain any number of variables and additional sections (aka "sub-sections"):

MEAL {
    NAME = Dinner
    TIME = 5:00
    CALORIES = 800
}
Warning The tag section parser expects the opening curly bracket ({) on the same line as the section name. The closing bracket (}) should be on its own line (and preferably at the same indentation as the start of section for readability).

A DIRSIG material database is composed of a series of material sections. A description of the variables and sections that can be used in a material are described in the remainder of this document.

Note The general format of the material database has not changed significantly since DIRSIG3. However, there has been an evolution to more detailed structure to make the management of newer features easier. The older format of the material entry has a different tag format and has limited component options. It is covered at the end of this document.
Note There is no master list of material IDs or conventions for assigning IDs to materials. Two separate scenes might have completely different material databases with overlapping IDs. The material editor contains some tools to facilitate merging material databases and making sure that IDs are unique.

Material Description

Each material entry is contained in a section named MATERIAL_ENTRY. Even though individual materials might describe very different things (surface versus medium properties), all materials use the same MATERIAL_ENTRY tag. Each entry contains a subset of the following:

  • The attributes for the material

    • Name, ID, and editor color associated with the material

    • Double sidedness, back-side medium, thickness, etc…​

  • The optical properties for the material

    • For a "surface" material, these are surface properties (e.g., reflectance, transmittance, etc.).

    • For a "volume" material, these are bulk properties (e.g., absorption, scattering, etc.).

  • The radiometry solver for the material

    • Specific algorithm and inputs used to compute radiometry (only used by DIRSIG4)

  • The temperature solver for the material

    • Method and inputs to the temperature calculation at a surface

Attributes

Material entries have a set of top-level attribute variables that are used for all material types.

NAME (required)

This is the name associated with the material. It will be used when displaying information about the material while the scene is loaded and is usually a short description of what the material represents. It is strongly recommended to make these names as descriptive as possible.

ID (required)

Each material has a unique alpha-numeric ID. This ID is used to associate the materials with other components of the scene (most notably geometry). An alpha-numeric ID can contain any characters except whitespace (space, tabs, etc.).

Tip Although many older DIRSIG scenes used numerical IDs exclusively, it is strongly encouraged that new materials use an alpha-numeric labels. For example, auto_glass is far more useful than 8088 when looking at the material IDs assigned in an object geometry file.
EDITOR_COLOR (optional)

Whenever this material is used in an editor (e.g. bulldozer), this is the RGB color that will be used for the visualization. Usually this is set to something that will be a good reminder of what the material represents (e.g. grass might have a green editor color). The color is represented as an R, G, B (Red, Green, Blue) triplet where the relative weight of each is expressed on a [0,1] scale.

DOUBLE_SIDED (optional)

By default, surfaces in DIRSIG4 are only visible from the "front" of the surface (the direction in which the surface normal is facing). This means that we do not need to check for intersections from the backside, saving quite a bit of computation time. This behavior can (and should) be turned off for certain types of materials such as leaves and medium interfaces where we need to see both sides of the surface. This can be achieved by setting DOUBLE_SIDED = TRUE (the default value is FALSE).

Note Turning on double-sided intersections in DIRSIG4 was also a way of dealing with poorly defined geometry models that might have normals that flip back and forth across the surface of the object (this is a problem that can occur when converting one file format to another and can be difficult to fix in the geometry itself).
Important In DIRSIG5, all surfaces are automatically double-sided.
BACK_MAT_ID (optional)

In order to define an interface between two materials, a BACK_MAT_ID needs to be assigned to the material definition. Normally when passing through a transmissive surface we assume that we are in the same medium as we were were on the other side. The presence of BACK_MAT_ID means that the given material ID defines the new medium on the other side (it should refer to a material with bulk properties defined later on in the material databases). The medium material mechanism can be thought of as a state "stack" in which new mediums are pushed onto the stack when passing through an interface from front to back and popped off of the stack when passing in the opposite direction. Since no assumptions are made about the current medium it is possible to embed mediums inside other ones if desired (e.g. an air bubble inside of water).

Important In DIRSIG5, backside materials do not exist and are handled by specific plugins rather than via material configurations.
THICKNESS (optional)

The thickness override can be used to set the virtual thickness of the facet, overriding any value that might have been set as part of a thermal property description. This is useful for objects such as leaves which might be modeled as perfectly flat and purely attenuating surfaces (based on the virtual thickness) with no thickness set otherwise.

A partial material entry featuring the minimal attribute variables.
MATERIAL_ENTRY {
    NAME = Tree, Bark, Maple
    ID = 8031
    ...
}

Surface Properties

Any material that describes a surface (as opposed to a volume) needs to define surface properties such as the reflectance or emissivity of the material. Surface properties are defined in a tag section named SURFACE_PROPERTIES containing the relevant property configurations. A DIRSIG surface material is assigned properties by providing the name of the property to an associated name variable and then supplying the parameters for that property in an associated section. In the example below, the Ward BRDF reflectance property is requested via the REFLECTANCE_PROP_NAME variable and the inputs for that property are supplied in the REFLECTANCE_PROP section:

A partial material entry featuring a reflectance surface property.
MATERIAL_ENTRY {
    ...
    SURFACE_PROPERTIES {
        REFLECTANCE_PROP_NAME = WardBRDF
        REFLECTANCE_PROP {
            DS_WEIGHTS = 0.00 0.37
            XY_SIGMAS = 0.13 0.13
        }
    }
}

DIRSIG supports three difference classes of surface properties. The DIRSIG `Surface Properties Manual describes all of the properties available.

  1. Emissivity (provided via the EMISSIVITY_PROP)

    • This is the property used to define the emissivity (related to the absorption of the material) which describes how well the material emits energy relative the a blackbody at the same temperature. Note that the emissivity is often assumed to be directionally uniform, though the model may change that.

    • A list of available emissivity properties is available here.

  2. Reflectance (provided via the REFLECTANCE_PROP)

    • This is the property used to define the spectral reflectance of the surface, both the total reflectance off of the surface, as well as the bi-directional distribution of that reflectance.

    • A list of available reflectance properties is available here.

  3. Transmittance (provided via the TRANSMITTANCE_PROP)

    • This is the property used to define the spectral transmittance of the surface, both the total transmittance through the surface, as well as the bi-directional distribution of that transmittance.

    • A list of available transmittance properties is available here.

It is not necessary to provide all three properties for a surface. For non-transmissive surfaces it is usually sufficient to provide either a emissivity properties or a reflectance properties (the other will be derived, see below). For transmissive surfaces, at least two of the three properties should be present.

Bulk (Volume) Properties

Any material that describes a volume or medium (as opposed to a surface) needs to define bulk properties such as the absorption or scattering of the material. Bulk properties are defined in a tag section named BULK_PROPERTIES containing the relevant property configurations. A DIRSIG volume material is assigned properties by providing the name of the property to an associated name variable and then supplying the parameters for that property in an associated section.

In the example below, the ClassicAbsorption property is requested via the ABSORPTION_PROP_NAME variable and the inputs for that property are supplied in the ABSORPTION_PROP section:

A partial material entry featuring an absorption bulk property.
MATERIAL_ENTRY {
    ...
    BULK_PROPERTIES {
        ABSORPTION_PROP_NAME = ClassicAbsorption
        ABSORPTION_PROP {
            FILENAME = example.abs
        }
    }
}

DIRSIG supports three difference classes of bulk properties. The DIRSIG Bulk Properties Manual describes all of the properties available.

  1. Absorption Coefficient (provided via the ABSORPTION_PROP)

    • This is the property used to define the spectral absorption coefficient of the medium at any point.

    • A list of available absorption properties is available here.

  2. Scattering Coefficient (provided via the SCATTERING_PROP)

    • This is the property used to define the spectral scattering coefficient of the medium at any point.

    • The scattering coefficient property only defines the total scattering at a point, but nothing about the directional distribution of the scattering (it must be combined with the PHASE_FUNCTION_PROP).

    • A list of available scattering coefficient properties is available here.

  3. Phase Function (provided via the PHASE_FUNCTION_PROP)

    • This is the property that defines the directional distribution of the scattering. (must be combined with the SCATTERING_PROP).

    • A list of available scattering phase function properties is available here.

Each of the individual bulk properties are optional and DIRSIG will only use properties that are given, assuming zero for absorption and scattering otherwise and uniform scattering for the phase function. This method of defining the bulk properties is mostly intended for use with the gas/cloud models that produce a concentration based on ray traversal through primitives (such as voxels or plume "puffs").

The IOP (Inherent Optical Property) model is a special type of bulk property definition that facilitates setting up a large number of interdependent optical properties in a medium. This is often the case in water modeling and it is based on the interface to Hydrolight (a separate radiative transfer code from Sequoia Scientific). As such is can support multiple absorption, scattering and phase function models varying dependently and independently within the medium (usually associated with different constituent particles, such as chlorophyll or suspended solids). All of the individual models are collected at a point to compute the sum of the local properties. For more details on setting up the IOP model, see the IOP manual.

MATERIAL_ENTRY {
    ...
    BULK_PROPERTIES {
        IOP_MODEL {
            ...
        }
    }
    ...
}

Radiometry Solvers

Radiometry solvers do not describe properties of the materials, but rather how the properties are used to do radiometric calculations at the materials surface or within their volume. These solvers are assigned and setup on a per-material basis in recognition of the fact that different types of materials require different strategies and amounts of work.

Important Radiometry solvers were a key component of DIRSIG4 and its Whitted-style ray tracing approach. A material that will be run with DIRSIG4 must contain a radiometry solver configuration. However, DIRSIG5 uses the unified path tracing approach and the radiometry solver configuration is ignored.

The structure of the radiometry solver configuration looks like:

A partial material entry showing the basic radiometry solver setup.
MATERIAL_ENTRY {
    ...
    RAD_SOLVER_NAME = ...
    RAD_SOLVER {
        ...
    }
    ...
}

The RAD_SOLVER section is used for providing parameters to the temperature solver given by the RAD_SOLVER_NAME variable and is required even if no parameters are necessary. Only one radiometry solver can be assigned to a given material. The list of available temperature solvers and their respective inputs is provided in the Radiometry Solvers Manual.

Note Internal radiometry solvers will be automatically added to materials to support additional calculations (e.g., contributions from user-defined sources, LIDAR returns, etc.).

Temperature Solvers

In order to know the temperature of a material in a scene (for thermal emission), a temperature solver should be assigned to the material. This defines the model that will be used to predict or assign a temperature and its configuration will look like:

A partial material entry showing the basic temperature solver setup.
MATERIAL_ENTRY {
    ...
    TEMP_SOLVER_NAME = ...
    TEMP_SOLVER {
        ...
    }
    ...
}

The TEMP_SOLVER section is used for providing parameters to the temperature solver given by the TEMP_SOLVER_NAME variable and is required even if no parameters are necessary. Only one temperature solver can be assigned to a given material. The list of available temperature solvers and their respective inputs is provided in the Temperature Solvers Manual.

Example Standard Materials

A Surface Material

A surface material is used to describe a surface. Surfaces can be either opaque (e.g., a painted metal) or transmissive (e.g., a leaf). These materials always contain a surface specific RAD_SOLVER and a SURFACE_PROPERTIES section containing one or more surface properties.

A basic surface material described with an emissivity.
MATERIAL_ENTRY {
    ID           = steel_1
    NAME         = Steel, painted
    EDITOR_COLOR = 1,1,1
    DOUBLE_SIDED = TRUE
    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }
    SURFACE_PROPERTIES {
        EMISSIVITY_PROP_NAME = ClassicEmissivity
        EMISSIVITY_PROP {
            FILENAME = painted_steel.ems
            SPECULAR_FRACTION = 0
        }
    }
}
A surface material described with a reflectance and transmittance.
MATERIAL_ENTRY {
    ID           = leaf
    NAME         = Oak tree, leaf
    EDITOR_COLOR = 1,1,1
    DOUBLE_SIDED = TRUE
    RAD_SOLVER_NAME = Simple
    RAD_SOLVER {
        QUALITY = LOW
    }
    SURFACE_PROPERTIES {
        REFLECTANCE_PROP_NAME = SimpleReflectance
        REFLECTANCE_PROP {
            TXT_FILENAME = oak_lead_ref.txt
        }
        TRANSMITTANCE_PROP_NAME = SimpleTransmittance
        TRANSMITTANCE_PROP {
            TXT_FILENAME = oak_lead_tau.txt
        }
    }

A Volume Material

A volume material is used to describe a material such as a cloud. These materials always contain a volume specific RAD_SOLVER and a BULK_PROPERTIES section containing one or more bulk/volume properties.

A volume material defined with scattering properties.
MATERIAL_ENTRY {
    ID           = 2
    NAME         = Cloud
    EDITOR_COLOR = 1,1,1
    DOUBLE_SIDED = TRUE
    RAD_SOLVER_NAME = Null
    RAD_SOLVER {
    }
    BULK_PROPERTIES {
        SCATTERING_PROP_NAME = SimpleScattering
        SCATTERING_PROP {
            TXT_FILENAME = cloud_scat.txt
        }
        PHASE_FUNCTION_PROP_NAME = HenyeyGreenstein
        PHASE_FUNCTION_PROP {
            TXT_FILENAME = cloud_asym.txt
        }
    }
}

Example Special Materials

Source Materials

A user-defined source has a special material configuration that will not contain SURFACE_PROPERTIES, BULK_PROPERTIES, RAD_SOLVER or TEMPERATURE_SOLVER sections.

An example source material.
MATERIAL_ENTRY {
    ID           = 50w_hps
    NAME         = 50w High-Pressure Sodium (HPS) Source
    OPTICAL_DESCRIPTION = SOURCE
    INTENSITY_FILENAME  = 50w_High_Pressure_Sodium.int
    SOURCE_SHAPE        = 2
    NORMALIZE_SHAPE     = TRUE
}

Empty (Proxy) Materials

Certain re-mapping mechanisms in DIRSIG require a material ID that may never get used directly (such as when a material ID is used to associate with a material map). In order for these mechanisms to work they need to be originally assigned a material that is in the database, even though it won’t be used and don’t need optical/thermal property definitions. To help clarify this process, it is possible to define an empty material as a placeholder. The empty material still needs the NAME and ID, but can be left blank otherwise.

Note Empty materials are only valid in DIRSIG version 4.6.0 and greater.
An example of an "empty" placeholder material required for a scene level material or mixture map.
MATERIAL_ENTRY {
    NAME         = Terrain (re-mapped)
    ID           = 201
}

Material or Mixture Mapped Materials

Similar to the empty/proxy material described above, a material entry that includes a material map or mixture map will not contain SURFACE_PROPERTIES, BULK_PROPERTIES, RAD_SOLVER or TEMPERATURE_SOLVER sections since the material only defines a remapping to one (or more) other materials.

An example material entry featuring a material map.
MATERIAL_ENTRY {
    NAME = Terrain (re-mapped)
    ID = terrain
    MATERIAL_MAP {
        NAME = Terrain Map
        ENABLED = TRUE
        IMAGE_FILENAME = materials.png
        UV_PROJECTOR {
            ORIGIN = IMAGE
            FLIPX = FALSE
            FLIPY = FALSE
            EXTENDX = MIRROR
            EXTENDY = MIRROR
        }
        LUT {
            6:grass
            28:asphalt
            255:soil
        }
        OPTIONS {
            ENABLE_MIXING = FALSE
        }
    }
}

Material Variants

Material variants address differences in properties and solvers based on the medium that the material is in. This is useful in cases where a single surface might cross a medium transition (e.g. a sandy slope partially under water). In air (the scene atmosphere) the normal material entry will be used. A material variant is provided by using the same ID, but following it with a comma and the medium material ID it should be used in. For example,

Example material variants for a sand material in air and under water.
...
MATERIAL_ENTRY {
    ID           = 107
    NAME         = Sandy beach (in air)
    ...
}
...
MATERIAL_ENTRY {
    ID           = 107, 500
    NAME         = Sandy beach (under water)
    ...
}
...
Important Material variants are only available in DIRSIG4 versions 4.6.0 and greater. They are not supported in earlier versions of DIRSIG4 or in DIRSIG5.

DIRSIG3-Era Materials

A DIRSIG3-era material format (which can still be found in some older scenes) does not contain and sub sections within the material entry and makes assumptions about the properties and models above. Specifically, it assumes the following:

The table below lists the variable’s tag name, if it is required, the units for the variable and a description:

Table 1. Table of variables for a DIRSIG3-era material entry.
Tag Required Units Description

MATERIAL_ID

Required

Material label/ID

MATERIAL_NAME

Required

Name of material

DOUBLE_SIDED

Optional

(boolean)

Control double-sided attribute (default FALSE)

SPECIFIC_HEAT

Required

[cal/g/oC]

Specific heat

MASS_DENSITY

Required

[gm/cm3]

Mass density

THERMAL_CONDUCTIVITY

Required

[(cm Langley)/hour/oC)]

The thermal conductivity

THICKNESS

Optional

[cm]

Characteristic thickness

SOLAR_ABSORPTION

Optional

(fraction)

Mean, broad-band solar absorptivity

THERMAL_EMISSIVITY

Optional

(fraction)

Mean, broad-band thermal emissivity

EXPOSED_AREA

Required

(fraction)

Surface exposed area

SELF_GENERTAED_POWER

Optional

[L/hr]

Internal (self-generated) power source term (default 0)

OPTICAL_DESCRIPTION

Optional

Controls surface opacity

EMISSIVITY_FILE

Required

Name of spectral emissivity file

SPECULARITY

Required

(fraction)

Surface specularity

EXTINCTION_FILE

Optional

Name of spectral extinction file
An example of a DIRSIG3-era material entry.
MATERIAL_ENTRY {
    NAME = Arrow
    ID = 1
    SPECIFIC_HEAT = 0.1000
    THERMAL_CONDUCTIVITY = 20.0000
    MASS_DENSITY = 1.0000
    SPECULARITY = 0.10
    SOLAR_ABSORPTION = 0.2500
    THERMAL_EMISSIVITY = 0.9000
    EXPOSED_AREA = 0.4500
    EMISSIVITY_FILE = 50.ems
    THICKNESS = 4.0
}