All materials used within a scene are defined within a single list referenced from the scene file (see the scene documentation). 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 list (files ending in ".mat") and the types of materials that can be defined. Property specific documentation is provided elsewhere.

In general, each material entry defines a subset of the following:

  • The material entry information

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

  • The surface properties of the material

    • reflectance, transmittance, etc…​

  • The bulk properties of the material

    • absorption, scattering, etc…​

  • The radiometry solver associated with the surface

    • specific algorithm and inputs used to compute radiometry

  • The temperature solver associated with the surface

    • method and inputs to the temperature calculation at a surface

  • Overridden characteristics of the surface

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

In contrast to many of the modern DIRSIG file formats, the material list uses a tag based format rather than XML and 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 (as well as managing the materal list itself).

Note While the general structure of the material list has not changed much over the last few versions of DIRSIG, there has been an evolution to more detailed entries to cover additional choices that are available. The older, "classic" format of the material entry has a different tag format and has limited component options. It is covered at the end of this document.

The Material Entry

The material list is just a set of material entries (there is no wrapping tag section for the list). Every material in the list has the same structure:

MATERIAL_ENTRY {
    NAME = Tree, Maple, Bark
    ID = 8031
    EDITOR_COLOR = 0.6941, 0.6471, 0.3765

    ...
}
Warning The tag section parser is limited to only reading sections that have the opening curly bracket ("{") on the same line as the tag section name! The closing bracket ("}") should be on its own line (and preferrably at the same indentation as the start of section for readability, though this is not enforced).

Even though individual materials might describe very different things (surface versus medium properties), all materials use the same MATERIAL_ENTRY tag. The entries are as follows:

  • 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

  • ID (required)

    • Each material used in a DIRSIG run has a single, unique numeric ID. This ID is used to associate the materials with other components of the scene (such as geometry)

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

Note There is no master list of material IDs or conventions for assigning IDs to materials. Two separate scenes might have completely different material lists with overlapping IDs. The material editor contains some tools to facilitate merging material lists and making sure that IDs are unique.

Empty 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 list, 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.

Example:

MATERIAL_ENTRY {
    ID           = 201
    NAME         = Empty (re-mapped road)
}

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,

...

MATERIAL_ENTRY {
    ID           = 107
    NAME         = Sandy beach (in air)
    ...
}

MATERIAL_ENTRY {
    ID           = 107, 500
    NAME         = Sandy beach (under water)
    ...
}

...
Note Material variants are only available in DIRSIG versions 4.6.0 and greater.

Surface Properties

Any material that describes a surface (as opposed to a medium) needs to define surface properties such as the reflectance or emissivity of the material. Surface properties are defined in a tag section containing the relevant property models:

MATERIAL_ENTRY {
    ...

    SURFACE_PROPERTIES {

        EMISSIVITY_PROP_NAME = ...
        EMISSIVITY_PROP {
            ...
        }

        REFLECTANCE_PROP_NAME = ...
        REFLECTANCE_PROP {
            ...
        }

        TRANSMITTANCE_PROP_NAME = ...
        TRANSMITTANCE_PROP {
            ...
        }
    }

    ...
}

Each property model definition consists of its name and a (required) property section that is used to set model parameters (even if there are none). The property models that can be set are:

  • EMISSIVITY_PROP

    • This is the model used to find the spectral 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.

  • REFLECTANCE_PROP

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

  • TRANSMITTANCE_PROP

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

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

Derivation of missing properties

Materials are assumed to be in thermodynamic equilibrium which allows DIRSIG to apply Kirchoff’s rule to derive optical properties that may be missing from the definition (e.g. the spectral reflectance can be obtained from the spectral emissivity by assuming an R = 1 - E relationship). This conservation of energy based derivation can only be applied to the "total" property (e.g. the directional hemispherical reflectance), but nothing can be directly derived about the distribution (e.g. the bi-directional reflectance distribution function).

For historical reasons, Kirchoff’s rule is only applied to reflectance and emissivity by default in DIRSIG (transmittance, if present, is not incorporated). To enable conservation of energy for transmissive surfaces (leaves, for instance) with an appropriate emissivity/reflectance, the following can be added to the options dictionary (in the ".options" file):

<dictionary>
  <entry>
    <name>simulation.conservetransmittance</name>
    <type>boolean</type>
    <value>true</value>
  </entry>
</dictionary>

Note that any property that is provided is used directly so it is possible to define surfaces that do not conserve energy — no check is in place to verify that the provided properties do so.

Individual property models are not covered here and the surface properties can be found in the optical property documentation.

Bulk Properties

Any material that describes a 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 containing the relevant property models:

MATERIAL_ENTRY {

    ...

    BULK_PROPERTIES {

        IOP_MODEL {
            ...
        }

    }

    ...
}

or

MATERIAL_ENTRY {
    ...

    BULK_PROPERTIES {

        ABSORPTION_PROP_NAME = ...
        ABSORPTION_PROP {
            ...
        }

        SCATTERING_PROP_NAME = ...
        SCATTERING_PROP {
            ...
        }

        PHASE_FUNCTION_PROP_NAME = ...
        PHASE_FUNCTION_PROP {
            ...
        }
    }

    ...
}

With the exception of the special IOP_MODEL tag which excludes all other entries (see below), each property model definition consists of its name and a (required) property section that is used to set model parameters (even if there are none). The property models that can be set are:

  • ABSORPTION_PROP

    • This is the model used to find the spectral absorption coefficient ([1/m]) of the medium at any point

  • SCATTERING_PROP

    • This is the model used to find the spectral scattering coefficient ([1/m]) of the medium at any point

  • PHASE_FUNCTION_PROP

    • The scattering property only defines the total scattering at a point, but nothing about the directional distribution of the scattering. This is the model that describes that distribution.

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 builk 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 Model

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 water manual.

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. Radiometry solvers are documented elsewhere (see the radiometry solver documentation). Solvers are assigned and setup on a per-material basis in recognition of the fact that different types of material require different strategies and amounts of work. The structure of the radiometry solver section looks like:

MATERIAL_ENTRY {
    ...

    RAD_SOLVER_NAME = ...
    RAD_SOLVER {
        ...
    }

    ...
}

The RAD_SOLVER section is used for providing parameters to the radiometry solver given by the name entry and is required (even if no parameters are necessary). Only one user-supplied radiometry may be provided, though internal solvers may be attached (for example, a LiDAR solver might be added to a surface). These additions are done automatically and independent of the material entry.

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. Temperature solvers and their inputs are defined elsewhere (see the temperature solver documentation) This defines the model that will be used to predict or assign a temperature and its definition will look like:

MATERIAL_ENTRY {
    ...

    TEMP_SOLVER_NAME = ...
    TEMP_SOLVER {
        ...
    }

    ...
}

Overrides

There are a number of material characteristics that can be overriden in the material file via a tag:

MATERIAL_ENTRY {
    ...

    <override> = ...

    ...
}

where possible values of <override> are given below.

DOUBLE_SIDED

By default, materials 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 bechaviour 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 done by setting "DOUBLE_SIDED = TRUE".

Note Turning double sided intersections on is 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).

BACK_MAT_ID

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 list). 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).

Warning Interface materials (those with a "BACK_MAT_ID" can be assigned to any surface material so care must be taken to ensure that the geometry it is assigned to is (effectively) an enclosing surface (to ensure that we exit the medium as necessary). In practice its usually possible to only partially enclose a medium to create the correct transition (e.g. it is useful to define a water body by its surface interface mostly enclosed by the bottom surface).

THICKNESS

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.

Classic Material Format

The classic material format (which is still in use) does not contain and sub sections within the material entry and makes assumptions about the properties and models above. Specifically, it assumes that you are always giving it a spectral emissivity file as input (the "ClassicEmissivity" emissivity property model from which reflectance will be derived using a specularity weight), using the "classic" radiometry solver, and the "therm" temperature solver. The full set of inputs to the classic format is given below, with the majority of entries being related to the temperature solver (see the therm documentation for more details). The table lists the tag name, whether it is required or not, its units, and what it represents:

MATERIAL_ID

Required

Material label/ID

MATERIAL_NAME

Required

Name of material

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

OPTICAL_DESCRIPTION

Optional

Controls surface opacity

EMISSIVITY_FILE

Required

Name of spectral emissivity file

SPECULARITY

Required

(fraction)

Surface specularity

EXTINCTION_FILE

Required

Name of spectral extinction file

DOUBLE_SIDED

Optional

(boolean)

Control double-sided attribute