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 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
|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"> ... </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 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).
<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>
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
$SCENE_DIR in the XML file to represent that base
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
.scene file itself. Using this default value also means that the
variable automatically changes when the scene (and presumably the
file) are relocated.
Overriding the Scene Directory
Rather than use the default value, the value of
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
<classicscene name="Demo Scene"> <scenebasedirectory>/Users/dirsig/scenes/my_scene/</scenebasedirectory> ... </classicscene>
<classicscene name="Demo Scene"> <scenebasedirectory>../scene_content</scenebasedirectory> ... </classicscene>
are valid base directories.
Overriding the scene base directory with the
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
<classicscene name="Demo Scene"> ... <sceneorigin> <location frame="geodetic"> <latitude>43.3921</latitude> <longitude>-77.0243</longitude> <altitude>13.48</altitude> </location> </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).
|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
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.
It is possible to use the
Inclusion of a geometry database is done by using a
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
<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
<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
<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.
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
<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 Emissivity Directory
- The Extinction Directory
- The Absorption Directory
<absdirectory>element specifies the directory where spectral absorption (ABS) are looked for.
- The Source Directory
<srcdirectory>element specifies the directory where spectral radiant intensity (INT) are looked for.
- The Map directory
<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:
<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> <srcdirectory>$SCENE_DIR/sources</srcdirectory> <mapdirectory>$SCENE_DIR/maps</mapdirectory> ... </classicscene>
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:
<classicscene name="Demo Scene"> ... <odbdirectory>$SCENE_DIR/geometry</odbdirectory> <gdbdirectory>$SCENE_DIR/geometry</gdbdirectory> <emsdirectory>$SCENE_DIR/materials</emsdirectory> <extdirectory>$SCENE_DIR/materials</extdirectory> <absdirectory>$SCENE_DIR/materials</absdirectory> <srcdirectory>$SCENE_DIR/materials</srcdirectory> ... </classicscene>
If you want to isolate emissivity and reflectance files into separate
$SCENE_DIR/materials/reflectance), then use the search directory
convention above and specify respective filenames relative to
$SCENE_DIR/materials directory. For example, an emissivity file
emissivity/rubber.ems and a reflectance file as
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 Map List
<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
element that describes the projection in use and a
associates material IDs assigned to geometry to the map being
|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.|
|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).|
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>
All of these options are set as attributes to the wrapping
element that surrounds the individual projection description (the
options are valid for all projections).
Image Origin and Axis Flip
Setting the attribute
true means that the first column
in an image becomes the last, and vice-versa. Similarly, setting the
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>
There are currently no options to the UV projection in the file, but an
<uvprojector> element must be present to indicate it’s usage:
<projector origin="cartesian" flipx="false" flipy="true" extendx="mirror" extendy="repeat"> <uvprojector/> </projector>
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.
<classicscene name="Demo Scene"> ... <landmarks> <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> ... </landmarks> ... </classicscene>
As with the map list, the scene file provides a top level collection of all plumes in the scene for individual plume descriptions).
<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>
|Plume descriptions using this method are only supported by DIRSIG4.|
The following collections can be browsed for existing 3D geometry:
A nice list of additional sources (with formats) can be found at FreeModels.
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:
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.
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):
The following tools can be used to attribute geometry with material descriptions for use in a DIRSIG simulation:
Bulldozer (provided with DIRSIG)
Blender (with DIRSIG plugins) (open source, free)
The following tools can be used assemble complex scenes from attributed objects:
Bulldozer (provided with DIRSIG)
Blender (with DIRSIG plugins) (open source, free)
The following are considered best practices for creating scenes.
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
This is the primary documentation of the scene. It is usually a text based file (preferably with AsciiDoc markup).
.scenefiles 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_DIRbuilt-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_DIRbuilt-in variable when the scene (and presumably the
.scenefile) 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
.scenefiles, that means not defining the
.scenefiles 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).
$SCENE_DIRvariable 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.
$SCENE_DIRvariable 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 (
The Geometry Lists Folder (
Your ODB and GLIST files should reference geometry object files based on their location relative to the
$SCENE_DIR/geometryfolder. For example, if you created a sub-folder in
carsthat contains the file
bmw_535i_red.obj, then the ODB (or GLIST) file entry should contain the path
Your ODB and GLIST files should reference other geometry list files based on their location relative to the
$SCENE_DIR/geometryfolder. 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
$SCENE_DIRvariable 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)
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 (
The Extinction Folder (
The Absorption Folder (
The Sources Folder (
In the Material Database file, specify the path of your external optical proprieties files relative to the
materialsfolder. 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
shotssimulation files contain absolute paths
.simfile created by the graphical user interface will always contain absolute paths. Changing to relative paths can be performed by hand-editing the
.simfile to modify the file paths.
shots/rgb/rgb.simcan 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.ppdwithin the simulation file.