The scene description file collects all of the geometry present in a scene and provides additional contextual information about the entire scene.


The scene file is an XML file and is essentially a limited geometry list definition (the scene definition usually only includes additional GLIST or ODB files rather than defining portions of the geometry itself) plus extended information about the scene. The scene file has a .scene extension and is one of the primary DIRSIG input files. It is responsible for defining the following:

  • The base directory of the scene

  • The scene origin

    • The [0,0,0] point of the local East-North-Up coordinate system

  • The top level geometry list

  • The material list file name

  • Paths of files needed to build the scene

    • geometry files, geometry lists, material, map, source and property files

  • A central list of all maps used in the scene

  • Landmark locations within the scene

  • Any metadata associated with the scene

  • Information about plumes within the scene

Note The DIRSIG graphical user interface has an incorporated scene editor that can be used to create and modify scene files without having to edit the XML directly

The scene file is wrapped by a <classicscene> XML element that takes a single attribute that defines the name associated with the scene, e.g.

<classicscene name="Demo Scene">

The name of the scene is considered to be metadata (though not contained within the metadata section of the XML file) and it is referred to as such in the scene editor.

Meta Data

The scene description allows for attaching arbitrary information to the file that will be maintained through loading and saving, regardless of whether the data is "official" or not. The meta data is provided with name/value pairs. For XML safety it is recommended that the text of the value is wrapped in an XML CDATA element (to avoid misinterpreting special characters in the string).

Example metadata element.
<classicscene name="Demo Scene">
      <value><![CDATA[A demonstration scene]]></value>

The Base Directory

One of the purposes of the scene file is to setup directories in which scene components are stored (geometry, maps, optical properties, etc..). Since these directories are often stored in or relative to a common directory, the scene file provides an optional helper variable $SCENE_DIR in the XML file to represent that base directory.

The primary advantage of using the $SCENE_DIR variable is to simplify changing the path associated with scene content (see below); it allows the parent directory to be changed in a single place, rather than individually for each directory entry. Using a relative path makes it easy to move the entire scene around the file system without having to update the paths at all.

Using the Default Scene Directory

The default value of the $SCENE_DIR variable is the folder that contains the .scene file itself. Using this default value also means that the variable automatically changes when the scene (and presumably the .scene file) are relocated.

Overriding the Scene Directory

Rather than use the default value, the value of $SCENE_DIR can also set via the <scenebasedirectory> element and may be an absolute or relative path (in the case of a relative path, the current directory is the one in which simulation was run). For example,

<classicscene name="Demo Scene">


<classicscene name="Demo Scene">

are valid base directories.

Important Overriding the scene base directory with the <scenebasedirectory> element is only encouraged in rare cases. Using the default value (the folder containing the .scene file) is almost always a better choice.

The Scene Origin

Any scene defined in DIRSIG has to be tied to a single georeferenced position relative the WGS84 ellipsoid. This geo location becomes the origin of the local cartesian coordinate system in DIRSIG which is used for all non-georeferenced positions. The local coordinate system associates [X,Y,Z] with [East,North,Up] (or ENU) at the georeferenced origin and all conversions in and out of the local coordinate space are based on that relationship.

The scene origin is set by a <sceneorigin> element that contains a geodetic position with the latitude, longitude and altitude of the point (relative to the WGS84 ellipsoid). West and South values for longitude and latitude are indicated by a negative value. The angles are given in decimal degrees and the altitude in meters. For example:

Example scene origin element.
<classicscene name="Demo Scene">
    <location frame="geodetic">

The georeferencing in DIRSIG is "earth-centric" and there is no support for using different ellipsoid definitions at this time. However, there is nothing stopping the user from setting up an arbitrary origin and then dispensing with geo-referencing and keeping everything in the local coordinate space (though Sun-Earth based atmospheric models will only be valid if they work in a consistent space).

Note While the DIRSIG coordinate system is tied to the concept of an ellipsoidal earth, there is no physical model of the globe underlying the scene (the Earth is a notional coordinate space, not a piece of geometry). This means that there is no danger of accidentally burying the scene, but it also means that any portion of the scene that does not model the terrain geometry will see nothing beyond the scene (aside from the atmosphere on the other side).

The Geometry List

The primary component of the scene file is a <geometrylist>, which adds one or more geometry databases to the scene, GLIST files, ODB files, or a combination of the two. Aside from limiting clutter in the scene file, this allows for a central location to turn included geometry on or off.

Note It is possible to use the <geometrylist> tag to define a full geometry list, but any definitions other than basic includes are not supported by the GUI editor.

Inclusion of a geometry database is done by using a <geometrylistinclude> element. This element takes two attributes (see the definition in the glist format) for setting an optional name and/or enabling flag. A typical <geometrylist> entry might look like:

Example geometry list element.
<classicscene name="Demo Scene">
  <geometrylist enabled="true">
    <geometrylistinclude name="Terrain" enabled="true">tile_1/terrain.glist</geometrylistinclude>
    <geometrylistinclude name="Belmeade_Rd" enabled="true">tile_1/Belmeade_Rd.odb</geometrylistinclude>
    <geometrylistinclude name="Belmeade_Rd_tree" enabled="true">tile_1/Belmeade_Rd_tree.odb</geometrylistinclude>
    <geometrylistinclude name="Biltmore_Dr" enabled="true">tile_1/Biltmore_Dr.odb</geometrylistinclude>
    <geometrylistinclude name="Biltmore_Dr_tree" enabled="true">tile_1/Biltmore_Dr_tree.odb</geometrylistinclude>
    <geometrylistinclude name="Briarwood_Dr" enabled="true">tile_1/Briarwood_Dr.odb</geometrylistinclude>
    <geometrylistinclude name="Briarwood_Dr_tree" enabled="true">tile_1/Briarwood_Dr_tree.odb</geometrylistinclude>
    <geometrylistinclude name="Bristol-Winona-StPaul" enabled="true">tile_1/Bristol-Winona-StPaul.odb</geometrylistinclude>

Note that GLIST and ODB files may be used interchangeably within the <geometrylistinclude> and the file type will be determined from the extension.

The Material Database

The database (see the material database manual) containing the materials in the scene is provided via the <matfilename> element:

<classicscene name="Demo Scene">

Note that the full path to the material list file does not need to be given, in which case the directory in which the simulation was run will be used.

The Search Directories

DIRSIG needs to know where to search for files requested throughout the scene. This is handled by having the user set specific paths to file type specific directories. The directories that should be set are:

The Object List Directory

The <odbdirectory> element specifies the directory where Object Database (ODB) files and Geometry List (GLIST) files are looked for. This directory is also used to look for in-scene motion files (for example, DeltaMotion MOV files and GenericMotion PPD files).

The Geometry Directory

The <gdbdirectory> element specifies the directory where Geometric Database (GDB) files and Alias/Wavefront (OBJ) files are looked for.

The Emissivity Directory

The <emsdirectory> element specifies the directory where spectral emissivity and reflectance files are looked for.

The Extinction Directory

The <extdirectory> element specifies the directory where spectral extinction and transmittance files are looked for.

The Absorption Directory

The <absdirectory> element specifies the directory where spectral absorption (ABS) are looked for.

The Source Directory

The <srcdirectory> element specifies the directory where spectral radiant intensity (INT) are looked for.

The Map directory

The <mapdirectory> element specifies the directory where material, mixture, texture, bump, etc. map images are looked for.

Below is an example of these search paths being used:

Older search path configuration.
<classicscene name="Demo Scene">

As the DIRSIG model matured and the complexity of geometry and material descriptions expanded, the idea of introducing new search paths for specific geometry or material property types was determined to be not ideal. Therefore, our best practices encourages "flattening" these search directories and prepending sub-directories on the filenames if more organization is desired. For example, we now encourage the following:

Newer (recommended) search path configuration.
<classicscene name="Demo Scene">

If you want to isolate emissivity and reflectance files into separate sub-directories (e.g. $SCENE_DIR/materials/emissivity and $SCENE_DIR/materials/reflectance), then use the search directory convention above and specify respective filenames relative to the $SCENE_DIR/materials directory. For example, an emissivity file as emissivity/rubber.ems and a reflectance file as reflectance/white_paint.txt.

Important The introduction of "bundling" allows the user to create collections of complete material descriptions and fully-attributed objecs that exist outside of scenes and can be shared by scenes without making copies of files. The DIRSIG_BUNDLE_PATH environment variable can be set to indicate an additional search directory for these elements (see the Bundle Inventory Manual for more information).

The Map List

The <maplist> section contains the maps used by the scene. Each map type takes a different element name (see below) with different inputs. However, there are two attributes common to each map definition. The name attribute can be used as a reminder of what the map represents, while the enabled attribute can be used to turn a map off. Each map entry also contains a <projector> element that describes the projection in use and a matidlist that associates material IDs assigned to geometry to the map being defined.

Note Multiple material IDs can be associated with a single map. This allows the same image file to be shared among maps and minimize memory usage.
Note A material ID used to associate with a map must always have a definition in the material list (in the case of a material map, that definition will not be used if the map is enabled).
Tip The enabled attribute allows the user to temporarily disable a map rather than deleting it from the scene file.

The general structure of the map list looks like:

Example list of property maps.
  <materialmap name="Terrain Material Map" enabled="true">
  <texturemap name="Terrain Texture Map" enabled="true">
  <materialmap name="Building Material Map" enabled="false">


All of these options are set as attributes to the wrapping <projector> element that surrounds the individual projection description (the options are valid for all projections).

Image Origin and Axis Flip

Setting the attribute flipx to true means that the first column in an image becomes the last, and vice-versa. Similarly, setting the flipy attribute to true makes the first row the last row.

Drape (Tile) Projection

The description of the drape projection (or "tile projector") in the file looks like:

Example drape projection setup.
<projector origin="cartesian" flipx="false" flipy="true" extendx="mirror" extendy="repeat">

UV Projection

There are currently no options to the UV projection in the file, but an empty <uvprojector> element must be present to indicate it’s usage:

Example UV projection setup.
<projector origin="cartesian" flipx="false" flipy="true" extendx="mirror" extendy="repeat">


Scene landmarks are simply labeled locations within the scene (those labels can be used by other tools to quickly and easily reference a position). The list of landmarks is wrapped by a <landmarks> element and each individual landmark is defined with a <landmark> element and labeled with a "name" attribute. The landmark definition must also include a description and the location point defined in element of the same name.

Example list of landmarks.
<classicscene name="Demo Scene">
    <landmark name="Storage shed">
      <description><![CDATA[Small storage shed]]></description>


As with the map list, the scene file provides a top level collection of all plumes in the scene for individual plume descriptions).

Example Blackadar plume description.
<classicscene name="Demo Scene">
      <steptime>             0.1</steptime>
      <stepcount>            320</stepcount>
      <directinsolation>   600.0</directinsolation>
      <airtemperature>     300.0</airtemperature>
      <windspeed>            4.0</windspeed>
      <winddirection>       90.0</winddirection>
      <surfaceroughness>    0.01</surfaceroughness>
      <mixedaltitude>     1000.0</mixedaltitude>
      <stackheight>         80.0</stackheight>
      <stackdiameter>        2.0</stackdiameter>
      <releasebuoyancy>     10.0</releasebuoyancy>
      <releasetemperature> 350.0</releasetemperature>
      <puffsperstep>           8</puffsperstep>
      <plumematerialid>        5</plumematerialid>
      <releaserate>        100.0</releaserate>
Important Plume descriptions using this method are only supported by DIRSIG4.

Geometry Tools

Geometry Libraries

The following collections can be browsed for existing 3D geometry:

A nice list of additional sources (with formats) can be found at FreeModels.

Geometry Conversion

Often a geometry model cannot be found directly in the Alias/Wavefront OBJ format that DIRSIG imports and it is necessary to convert it from one format to another. The following (free) tools are alternatives to commercial conversion software:

  • object_tool (provided with DIRSIG)

  • lib3ds (open source, legacy Autodesk/Discrete format conversion)

  • MeshLab (open source, import/export many common formats)

  • Blender (open source, import/export many common formats)

  • FBX Converter (free, converts to/from the FBX format)

Geometry Creation

The following tools can be used to create (author) 3D geometry:

An extensive list of authoring tools (and many others) can be found at the Virtual Terrain Project.

Geometry Processing

The following tools can be used to process and manipulate geometric objects for eventual inclusion into a DIRSIG simulation:


The following tools can be used to assign texture coordinates to existing geometries (and to "paint" onto the surfaces of the objects):

Geometry Attribution

The following tools can be used to attribute geometry with material descriptions for use in a DIRSIG simulation:

Scene Assembly

The following tools can be used assemble complex scenes from attributed objects:

Best Practices

The following are considered best practices for creating scenes.

Folder Hierarchy

A scene folder should contain all of the assets for a given scene. At RIT we have established the following standardized layout. For this example, our scene is contained with the folder hierarchy named example:


This is the primary documentation of the scene. It is usually a text based file (preferably with AsciiDoc markup).


All .scene files should be placed at the top of the scene folder hierarchy. This allows DIRSIG to employ several mechanisms to avoid using absolute paths to the large number of individual files used in a scene.


The top-level geometry folder.


The top of the geometric objects folder. This folder may contain other folders that organize the base geometry by type (for example, "cars", "trees", etc.). This folder hierarchy generally contains GDB and OBJ files. However, this folder hierarchy might also contain ODB and/or GLIST files that define a single primitive object (a box, a sphere, etc.) or a compound object (a conceptual object created by combining one or more simpler objects).


The top of the geometric lists folder. This is where files are that assemble the base geometry objects into scene components are located. This folder usually contains the ODB and/or GLIST files used to instance objects within the scene.


This is the folder where any scene motion descriptions are located.


The top-level materials folder.


This is where the scene material database files are located. Sometimes there are multiple material database files because there are polarized and unpolarized versions of the scene, or a material database with SAR material descriptions.

example/materials/emissivity, example/materials/extinction, etc.

The material folder usually contains a set of sub-folders to organize the various optical property files are located (for example, EMS, EXT, INT, BRDF, etc. files).


This is where the scene map image files are located. This folder might contain a mixture of PNM, PNG, JPEG, etc. files.


This is where example images of the scene are located. These image assets might be referred to in the README.txt file and/or include the thumbnail images.


This folder might contain one or more example simulations using the scene. These simulations should depend on files only contained within the scene folder (not external file references).

Scene and Material Database Conventions

The following practices will help create scene and material database files that ensure the scene folder can be relocated with ease.

  • Prefer the default value for the $SCENE_DIR built-in variable (see here for more discussion).

    • In the graphical Scene Editor prefer the Use the folder containing the scene file option, which will automatically change the $SCENE_DIR built-in variable when the scene (and presumably the .scene file) is relocated or given to another user. Otherwise, the folder name will need to be updated each time the scene is relocated.

    • If you are hand-crafting .scene files, that means not defining the <scenebasedirectory> element.

  • Place all .scene files in the Scene Base Folder (the top of the scene folder hierarchy).

    • When following the other practices outlined here, it will make the scene more portable (easily relocated or given to another user).

  • Use the $SCENE_DIR variable to specify the locations of sub-folders and files used in the scene.

    • This is a built-in variable that corresponds to the Scene Base Folder. When used properly, it will allow you to specify most files in the scene relative to the top of the scene folder.

    • Using the $SCENE_DIR variable rather than absolute or relative paths to sub-folders and files will make your scenes more portable.

    • This means manually editing the various paths in the Scene Editor rather than using the Browse button. This includes:

      • The Geometry Objects Folder path

      • The Geometry Lists Folder path

      • The Material Database filename

      • The Emissivity Folder filename

      • The Extinction Folder filename

      • The Absorption Folder filename

      • The Sources Folder filename

  • Avoid creating top-level scene geometry list files

    • The scene file contains a geometry list, so rather than create a "whole_scene.glist" (or "whole_scene.odb") file that is included in the scene file, combine your logical scene lists in the scene file itself.

  • Specify a single folder in the geometry paths to simplify file locations

    • Assuming you used the folder hierarchy suggested in the last section, you should set the geometry paths as follows:

      • The Geometry Objects Folder (<gdbdirectory>) to $SCENE_DIR/geometry

      • The Geometry Lists Folder (<odbdirectory>) to $SCENE_DIR/geometry

    • Your ODB and GLIST files should reference geometry object files based on their location relative to the $SCENE_DIR/geometry folder. For example, if you created a sub-folder in $SCENE_DIR/geometry/objects named cars that contains the file bmw_535i_red.obj, then the ODB (or GLIST) file entry should contain the path objects/cars/bmw_535i_red.obj.

    • Your ODB and GLIST files should reference other geometry list files based on their location relative to the $SCENE_DIR/geometry folder. For example, to reference an ODB file stored as $SCENE_DIR/geometry/lists/parking_lot.odb, then your ODB (or GLIST) file should contain the path lists/parking_lot.odb.

  • Use the $SCENE_DIR variable in the path to instance motion files

    • If you follow the suggested hierarchy, then your ODB and GLIST files can specify the paths to Delta, Generic and Flexible motion descriptions as (for example) $SCENE_DIR/geometry/motion/

  • Specify a single folder in the materials paths to simplify file locations

    • Assuming you used the folder hierarchy suggested in the last section, you should set the optical property paths as follows:

      • The Emissivity Folder (<emsdirectory>) to $SCENE_DIR/materials

      • The Extinction Folder (<extdirectory>) to $SCENE_DIR/materials

      • The Absorption Folder (<absdirectory>) to $SCENE_DIR/materials

      • The Sources Folder (<srcdirectory>) to $SCENE_DIR/materials

    • In the Material Database file, specify the path of your external optical proprieties files relative to the materials folder. For example, to reference an EMS file stored as $SCENE_DIR/materials/emissivity/gravel.ems, then your Material Database file should use FILENAME = emissivity/gravel.ems.

  • Avoid making the example shots simulation files contain absolute paths

    • A .sim file created by the graphical user interface will always contain absolute paths. Changing to relative paths can be performed by hand-editing the .sim file to modify the file paths.

    • For example, shots/rgb/rgb.sim can have the Scene file specified as ../../example.scene, since the scene file is assumed to be at the top of the hierarchy, which is two folders up in this example.

    • The path to files contained in the simulation folder can be rewritten as either ./rgb.ppd or simply rgb.ppd within the simulation file.