The scene description file collects all of the geometry present in a scene and provides additional contextual information about the entire scene. It is an XML file and is essentially an 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 Top Level Tag

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

<classicscene name="Demo Scene">
...
</classicscene>

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 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">
  <scenebasedirectory>/Users/dirsig/scenes/my_scene/</scenebasedirectory>
...
</classicscene>

and

<classicscene name="Demo Scene">
  <scenebasedirectory>../scene_content</scenebasedirectory>
...
</classicscene>

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:

<classicscene name="Demo Scene">
...
  <sceneorigin>
    <geodeticlocation>
      <latitude>43.3921</latitude>
      <longitude>-77.0243</longitude>
      <altitude>13.48</altitude>
    </geodeticlocation>
  </sceneorigin>
...
</classicscene>

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:

<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>
    ...
  </geometrylist>

 ...
 </classicscene>

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 List

The material list (see the material list documentation) used for all materials in the scene is defined by the <matfilename> tag:

<classicscene name="Demo Scene">
...
  <matfilename>$SCENE_DIR/materials/scene.mat</matfilename>
 ...
</classicscene>

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.

File 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:

  • ODB directory

    • where to look for object database files (.odb) as well as geometry list files (.glist)

  • GDB directory

    • where to look for the actual geometry files, either Alias/Wavefront OBJ format files (.obj) or DIRSIG’s geometry database files (.gdb)

  • EMS directory

    • where to look for spectral emissivity files (.ems)

  • EXT directory

    • where to look for spectral extinction files (.ext)

  • ABS directory

    • where to look for spectral absorption files (.abs)

  • Map directory

    • where to look for map image files of all types (.jpg/.png/.pgm/etc…​)

  • Source directory

    • where to look for spectral source intensity files (.int)

Example:

<classicscene name="Demo Scene">
...
  <odbdirectory>$SCENE_DIR/glists</odbdirectory>
  <gdbdirectory>$SCENE_DIR/geometry</gdbdirectory>
  <emsdirectory>$SCENE_DIR/materials/emissivity</emsdirectory>
  <extdirectory>$SCENE_DIR/materials/extinction</extdirectory>
  <absdirectory>$SCENE_DIR/materials/absorption</absdirectory>
  <mapdirectory>$SCENE_DIR/maps</mapdirectory>
  <srcdirectory>$SCENE_DIR/sources</srcdirectory>
 ...
</classicscene>

The Map List

The <maplist> section which contains all of the maps used by the scene. Each map type takes a different tag (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:

<maplist>
  <materialmap name="Terrain Material Map" enabled="true">
    <matidlist>
      <matid>100</matid>
    </matidlist>
    <projector>
      ..
    </projector>
    ..
  </materialmap>
  <texturemap name="Terrain Texture Map" enabled="true">
    <matidlist>
      <matid>8048</matid>
      <matid>8000</matid>
      <matid>3008</matid>
      <matid>3039</matid>
      <matid>7130</matid>
    </matidlist>
    <projector>
    </projector>
    ..
  </texturemap>
  <materialmap name="Building Material Map" enabled="false">
    <matidlist>
      <matid>101</matid>
      <matid>107</matid>
    </matidlist>
    <projector>
    </projector>
    ..
  </materialmap>
</maplist>

Projections

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:

<projector origin="cartesian" flipx="false" flipy="true" extendx="mirror" extendy="repeat">
  <tileprojector>
    <insertpoint>
      <point><x>5.544</x><y>1171.36</y><z>0</z></point>
    </insertpoint>
    <gsd>0.15</gsd>
  </tileprojector>
</projector>

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:

<projector origin="cartesian" flipx="false" flipy="true" extendx="mirror" extendy="repeat">
  <uvprojector/>
</projector>

This option is set by using the attribute mixing="true" in the <materialmap> tag.

Landmarks

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> tag and each individual landmark is defined with a <landmark> tag and labeled with a "name" attribute. The landmark definition must also include a description and the location point defined in tags of the same name.

Example:

<classicscene name="Demo Scene">
...
  <landmark name="Storage shed">
    <description><![CDATA[Small storage shed]]></description>
    <location>
      <point><x>22.85</x><y>56.95</y><z>0</z></point>
    </location>
  </landmark>
...
</classicscene>

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

Warning As of DIRSIG 4.5.2 the meta data mechanism was not yet implemented in the GUI and meta data would not be read or written to the .scene file (entries in the GUI and the XML file are lost)

Example:

<classicscene name="Demo Scene">
...
  <metadata>
    <entry>
      <name>Author(s)</name>
      <value><![CDATA[DirsigUser]]></value>
    </entry>
    <entry>
      <name>Description</name>
      <value><![CDATA[A demonstration scene]]></value>
    </entry>
    <entry>
      <name>Organization</name>
      <value><![CDATA[RIT]]></value>
    </entry>
  </metadata>
...
</classicscene>

Plumes

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

Example:

<classicscene name="Demo Scene">
...
  <plumelist>
    <blackadarplume>
      <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>
      <stacklocation><point><x>0.0</x><y>0.0</y><z>0.0</z></point></stacklocation>
      <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>
      <debugfilename>blackadar.txt</debugfilename>
    </blackadarplume>
  </plumelist>
...
</classicscene>

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:

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:

Texturing

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:

example/README.txt

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

example/example.scene

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.

example/geometry

The top-level geometry folder.

example/geometry/objects

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

example/geometry/lists

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.

example/geometry/motion

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

example/materials

The top-level materials folder.

example/materials/example.mat

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

example/maps

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

example/images

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.

example/shots

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/car1.mov.

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