In addition to full radiative transfer models for scattering media (which can be computationally intensive), DIRSIG provides a simplified cloud model using voxel (abstract, 3D-grid) based optical properties. Radiative transfer within the cloud uses a direct solution for first order scattered solar radiance and approximates multiple scattering contributions. It is intended primarily for producing the effects of large-scale clouds on a scene (particularly shadowing), but not for accurate, detailed radiometry of the clouds themselves.

General Approach and Format

The cloud model uses DIRSIG’s standard voxel format for defining concentrations in a sparse 3D matrix of cell data from a user-provided file. However, it loads that data in a new way that is quite different than other geometry in DIRSIG. Instead of defining all of the geometric information in a scene/glist, the user just provides placeholder information for the cloud(s) in a special geometric database called "atmospherics" that link to material entries (via material IDs).

The placeholder must be defined as an instance (and can therefore be translated, scaled, and rotated, statically or dynamically). When DIRSIG runs, it saves a spot for the geometry in the atmospherics database and reads in the actual data later on during initialization. At that time, the atmospheric object becomes a "black box" object in the scene — any rays entering the bounds of the clouds are handled by a specialized rad solver that has knowledge of the voxelization and can compute radiometry for the entire object.

This approach is preferable to the traditional use of the voxels as individual computation blocks (i.e. calculating radiometry in each cell independently) both for speed and quality of the simulation.

Atmospherics Placeholder

The cloud placeholder is defined in a special section within a ".scene" or ".glist" file as a piece of base geometry. The atmospherics object is unique (only one is allowed) so multiple cloud voxelizations or other atmospherics objects should all be defined in the single atmospherics section. The object entry looks like:

<object enabled="true">

The entire atmospherics database can be transformed via the instancing information (care must be taken if multiple atmospherics objects are present). Each cloud_matid entry creates a placeholder object in the database and directs DIRSIG to obtain information about the object in the material file, in the entry that defines the given material ID (4321 in this case).

Cloud Material Entry

Since a cloud is primarily changing the medium through which a ray travels within a DIRSIG scene, the cloud is defined as a change in material and a change in the rad solver that is used for propagating the ray. The material entry (corresponding to the ID in the atmospheric database placeholder) looks like:

    NAME = cucc
    ID = 4321

        ABS_FILE = ./cumulus_clouds/cucc00.abs
        SCT_FILE = ./cumulus_clouds/cucc00.sct
        PHA_FILE = ./cumulus_clouds/cucc00.pha
        CNC_FILE = ./cumulus_clouds/cum30percent.grid
        INSERT_POINT = -30000 -25000 1000
        SCALING = 50 50 50

No information other than the radiometry (rad) solver is expected and all the parameters shown are required. The parameters correspond to:


absolute path to the mass-specific spectral absorption coefficient file [m2g-1]


absolute path to the mass-specific spectral scattering coefficient file [m2g-1]


absolute path to the spectral (rotationally symmetric) phase function file


absolute path to the file containing the voxelized grid of concentration information [gm-3]


the minimum point of the bounding box that surrounds the voxel grid [m]


the size of each cell dimension [m]

The optical properties are described below. Note that the user is welcome to use different units for the concentration and optical property coefficients as long as the absorption and scattering coefficients have units of [m-1] after being scaled by the concentration (which, in turn, is based on the cell water content).

Optical Properties

Three files define the optical properties of the clouds and correspond to ABS_FILE, SCT_FILE, PHA_FILE in the material entry. The absorption and scattering properties describe the extinction in the medium (and in-scattering) and are provided in the form of mass-specific coefficients (also call mass-specific cross sections or specific coefficients). This means that rather than provide full spectral coefficients for every cell in the voxel grid, the user only needs to provide the concentration. The concentration values may be obtained from any source (OPAC [Optical Properties of Aerosols and Clouds] is a good source). Finally, the directional distribution of scattering within the cloud is provided by defining a scattering phase function in the PHA_FILE. This scattering phase function is assumed to be rotationally symmetric around the forward axis.


The mass-specific spectral absorption coefficient uses a verbose file format that provides the spectral points at which the coefficient is defined:

<spectraldata spectralunits="microns">

The number of spectral points is arbitrary, as is the spacing between them. Assuming that the concentration is defined in units of [gm-3], the mass-specific absorption has units of [m2g-1].


The mass-specific spectral scattering coefficient uses a verbose file format that provides the spectral points at which the coefficient is defined:

<spectraldata spectralunits="microns">

The number of spectral points is arbitrary, as is the spacing between them. Assuming that the concentration is defined in units of [gm-3], the mass-specific scattering has units of [m2g-1].


The scattering phase function defines the rotationally symmetric scattering distribution of the cloud at multiple wavelengths. The format of the file is as follows:


  <entry wavelength="0.25">






  <entry wavelength="0.3">




Wavelength units are Microns and the angular units are degrees, measured from the forward direction. The spacing between both angles and wavelengths can be arbitrary (it is usually beneficial to use a finer sampling near the forward direction where the phase function is at its peak).


The concentration file follows the standard voxel file format used elsewhere in DIRSIG, although the material ID entry is ignored (all cells have the same ID, defined in the atmospherics section entry). Additionally, the units of concentration are [m2g-1] (assuming mass-specific coefficient units of [gm-3]). The voxel file has the form of:

142     142     64
        43      57      0       206     795.444 1000.2030
        44      57      0       206     795.228 1000.2030
        41      58      0       206     795.228 1000.2030
        ...     ...     ...     ...     ...     ...

The first line has three integers, denoting the dimensions of the grid [x,y,z] in the scene local coordinate system. In the example above, the grid is 142 x 142 x 64 cells.

The remainder of the file consists of lines with six columns of data. The first three columns indicate the voxel index (counting from 0). The fourth column indicates a DIRSIG material id (ignored for the cloud model). The fifth column indicates temperature in Kelvin. The final column indicates concentration in.

Specifying voxel data for each grid voxel is not required. Unspecified voxels are treated as being empty. Furthermore, empty voxels do not take up memory.