Scene Description Format

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 scene file is wrapped by a <classicscene> XML element that takes a single attribute that defines the name associated with the scene, e.g.

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.

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

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.

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:

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

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.

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:

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

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

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.

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:

Below is an example of these search paths being used:

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:

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.

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.

The general structure of the map list looks like:

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.

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

The following are considered best practices for creating scenes.