User’s Guide for Smokeview Version 

1.0 - A Tool For Visualizing Fire 

Dynamics Simulation Data

Glenn P. Forney

Kevin B. McGrattan

NISTIR 6513
NISTIR 6513

User’s Guide for Smokeview Version 

1.0 - A Tool For Visualizing Fire 

Dynamics Simulation Data

Glenn P. Forney

Kevin B. McGrattan

Building and Fire Research Laboratory

May 2000

U.S. Department of Commerce

William M. Daley, Secretary

Technology Administration

Dr. Cheryl L. Shavers, Under Secretary of Commerce for Technology

National Institute of Standards and Technology

Raymond G. Kammer, Director
Disclaimer

The US Department of Commerce makes no warranty, expressed or implied, to users of Smokeview, and

accepts no responsibility for its use. Users of Smokeview assume sole responsibility under Federal law for

determining the appropriateness of its use in any particular application; for any conclusions drawn from the

results of its use; and for any actions taken or not taken as a result of analyses performed using these tools.

Users are warned that Smokeview is intended for use only by those competent in the fields of fluid

dynamics, thermodynamics, combustion, and heat transfer, and is intended only to supplement the informed

judgment of the qualified user. The software package is a computer model that may or may not have predictive

capability when applied to a specific set of factual circumstances. Lack of accurate predictions by the model

could lead to erroneous conclusions with regard to fire safety. All results should be evaluated by an informed

user.

Throughout this document, the mention of computer hardware or commercial software does not constitute endorsement by NIST, nor does it indicate that the products are necessarily those best suited for the

intended purpose.

iii
iv
Contents

1 Overview 1

2 Getting Started 2

3 Using Smokeview 3

3.1 Data Files ............................................ 3

3.2 Visualizing FDS Output ..................................... 7

3.2.1 Mouse movement . . . ................................. 7

3.2.2 Particle, slice, boundary file visualization . ...................... 8

3.2.3 Visualizing PLOT3D data files ............................. 9

3.3 Checking FDS Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

A Smokeview Command Line Options 14

B Menu Options 15

B.1 Main Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

B.2 Load/Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

B.3 Show/Hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

B.3.1 Geometry Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B.3.2 Particles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B.3.3 Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B.3.4 Animated Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B.3.5 PLOT3D 2D Contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B.3.6 PLOT3D 3D Contours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

B.3.7 Heat detectors, Sprinklers, Thermocouples . . . . . . . . . . . . . . . . . . . . . . 18

B.3.8 Shades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

B.3.9 Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

B.3.10 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

C Keyboard Commands 19

D File Formats 20

D.1 Smokeview Preference File Format (.ini files) . . . . . . . . . . . . . . . . . . . . . . . . 20

D.1.1 Color parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

D.1.2 Size parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

D.1.3 Time and value bound parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

D.1.4 Data loading parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

D.1.5 Viewing parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

D.2 Smokeview Parameter Input File (.smv file) . . . . . . . . . . . . . . . . . . . . . . . . . 25

D.2.1 Geometry Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

D.2.2 File Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

D.2.3 Sensor Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

D.2.4 System Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

D.3 Data File Formats (.part, .sf, .bf and .q files) . . . . . . . . . . . . . . . . . . . . . . 29

D.3.1 Particle File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

D.3.2 Slice File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

D.3.3 Boundary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

D.3.4 PLOT3D Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

References 32

v
List of Figures

1 Diagram illustrating data files and programs used in the NIST Fire Dynamics System (FDS) 2

2 Particle File Example. . ..................................... 4

3 Slice File Example . . ..................................... 4

4 Boundary File Example ..................................... 5

5 PLOT3D Contour Example . . ................................. 6

6 PLOT3D Vector Plot through a door . ............................. 6

7 PLOT3D Iso-contour Example ................................. 7

8 Smokeview coordinate system. ................................. 8

9 Contour plot illustrating a ceiling jet by using a V PLOT3D keyword entry of: “1 2 300.0

1 350.0” for the first (temperature) PLOT3D variable. . . . . . . . . . . . . . . . . . . . 11

10 Using Smokeview to verify model input. This example has a gap in the door soffit and a

burner vent boundary that is too small. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

11 Corrected case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

vi
User’s Guide for Smokeview Version 1.0 - A Tool for

Visualizing Fire Dynamics Simulation Data

Glenn Forney

Kevin B. McGrattan

Abstract

Smokeview is a software tool designed to visualize numerical predictions generated by the NIST Fire

Dynamics Simulator (FDS). FDSis a computational fluid dynamics (CFD) model of fire-driven fluid flow.

These two tools are used in concert to respectively model and analyze scenarios involving features such as

fire, wind, sprinklers, complex geometry etc. Smokeview visualizes FDS modeling results in many ways,

some of which are 1) animating flow of smoke or tracer particles, 2) animating 2D contours of data slices,

3) plotting 2D and 3D static contours or 4) plotting flow vectors .

Smokeview requires a fast CPU, fast video card, a substantial amount of random-access memory (RAM)

and a large hard disk. Smokeview is portable and can be run on a variety of computing platforms. For a

Windows-based PC, the processor should be at least a 450 MHz Pentium II, with at least 256 Mbytes of

memory. Of course, more is better, but this configuration should allow one to do fairly large calculations in

a reasonable time period. For UNIX-based workstations, the processor and memory should be at least as

fast and as large as the PC specs.

Smokeview and FDS may be obtained at the web site http://fire.nist.gov/smokeview or by contacting

the authors at glenn.forney@nist.gov or kevin.mcgrattan@nist.gov.

1 Overview

Smokeview is a software tool designed to visualize numerical predictions generated by the NIST Fire Dynamics Simulator (FDS), a computational fluid dynamics (CFD) model of fire-driven fluid flow. FDS[1, 2, 3]

and Smokeview are used in concert to respectively model and visualize fire scenarios of interest. Smokeview

performs this visualization by presenting: smoke or tracer particle flow (particle files); animated (in time)

contour slices of computed gas quantities (slice files) and surface data (boundary files); and static contour

and vector plots (PLOT3D files) anywhere within a simulation scene at a single fixed time.

Normally Smokeview is used in a post-processing step to visualize FDS data after a calculation has

completed. Smokeview may also be used during a calculation to monitor a simulation’s progress and before a

calculation to visualize blockage, vent, sprinkler and/or heat detector locations etc. in order to set up correct

FDS input files more quickly.

Figure1 illustrates how the data files used by the NIST Fire Dynamics Simulator and Smokeview are

related. A typical procedure for using FDS and Smokeview is to:

1. Set up an FDS input file, a file with a .data extension. Reference [2] gives documentation on FDS input

data files.

2. Run FDS. The fire model FDS then creates one or more output files with extensions .smv, .part,

.sf, .q, .bf .

3. Run Smokeview to analyze the output files generated by step 2.

This report documents step 3. Steps 1 and 2 are documented in reference [2].

1
Smokeview

Particle

(.part)

Boundary

(.bf)

PLOT3D

(.q)

CONFIG

(.ini)

FDS

Input

(.data)

Graphics

Slice

(.sf)

Figure 1: Diagram illustrating data files and programs used in the NIST Fire Dynamics System (FDS)

Particle, slice, boundary and PLOT3D files may be loaded into Smokeview by clicking the right-mouse

button and selecting the appropriate Load/Unload menu option. Other menu options are discussed in Appendix A. Many menu commands may also be executed using keyboard shortcuts. These shortcuts are listed

and explained in Smokeview’s help menu item and Appendix C. Visualization attributes not controllable

through the menus (for example, data minimums and maximums) may be changed by using the Smokeview

customization file named smokeview.ini which is discussed in Appendix D.1.

Smokeview is written using the 3D graphics library OpenGL[4] and the Graphics Library Utility Toolkit

(GLUT)[5]. Implementing a full fledged graphical user interface (GUI) is a daunting task. Using GLUT

allows one to create simple GUI applications with minimal effort so that most of the development can be

spent on implementing the visualizations rather than the creating an elaborate user interface. In addition,

GLUT applications are portable. Currently, Smokeview runs on the PC under Windows 95/98/NT/2000 and

on several UNIX workstations including SGI/IRIX, IBM/AIX, SUN/Solaris, HP/UX and Redhat LINUX.

2 Getting Started

Smokeview may be obtained at the web site http://fire.nist.gov/smokeview . This site gives links to a Setup

program for PC installation. It also contains documentation for Smokeview and FDS, sample FDS calculations, software updates and mechanisms for providing feedback about the software.

After obtaining the setup program, install Smokeview on the PC by either entering the setup program

name from the Windows Start/Run... menu or by double-clicking on the downloaded Smokeview setup

program. The setup program then steps through the program installation. It copies the Smokeview executable,

the GLUT graphics libraries and the Smokeview preference file smokeview.ini to the default directory

c:nnistnfds . The setup program also defines PATH variables and associates the .smv file extension to

the Smokeview program so that one may either type smokeview at any command line prompt or double

click on any .smv file. The installation program assumes that OpenGL has been installed which is true for

2
all but the very first release of Windows 95.1 Windows 98, 2000, NT 4.0 and all later versions of Windows

95 contain the OpenGL libraries.

3 Using Smokeview

Smokeview may be started on the PC by double-clicking the file named casename.smv where casename

is the name specified by the CHID keyword defined in the FDS input data file. The Load/Unload may

be used to read in the data files to be visualized. The Show/Hide menu may be used to change how the

visualizations are presented. For the most part, the menu choices are self explanatory. Menu items exist for

showing and hiding various simulation elements, creating GIF screen dumps, obtaining help etc. Menu items

are described in Appendix A.

To use Smokeview from a “command line”, open a DOS (if running on a PC) or UNIX shell, change to

the directory containing the FDS case to be viewed and type:

smokeview casename

where again casename is the name specified by the CHID keyword defined in the FDS input data file.

Normally Smokeview is run after an FDS case has completed. Smokeview may also be used as an aid

in setting up FDS cases by visualizing geometric components such as blockages, vents, sensors, etc. One can

then verify that these modeling elements have been defined and located as intended. One may select the color

of these elements using color parameters in the smokeview.ini file to help distinguish one element from

another.

3.1 Data Files

FDS generates several data files visualized by Smokeview. Each file type may be loaded or unloaded using

the Load/Unload menu described in Appendix B.2. These data files are:

Particle files Particle files contain the locations of the thermal elements (or particles) used to introduce

heat from the fire or to visualize the flow field. Particles are colored using criteria such as:

1) temperature, 2) burning state: burning, burned out, or 3) whether they are water (sprinkler

droplets). Temperature colors are selected from a user definable color palette defined with the

COLOR keyword documented in Appendix D.1. Figure 2 shows a snapshot of particle flow

where particles are colored according to their temperature. Default colors for other quantities

are yellow for burning, white for non-burning, and blue for water droplets. Particles are stored

in files ending with the extension .part . Particle files are displayed by selecting the desired

particle file from the Load/Unload menu.

Slice files Slice files contain data recorded within a rectangular array of grid points at each recorded time

step. Continuously shaded contours are drawn for simulation quantities such as temperature,

gas velocity and heat release rate. All or part of a plane is selected when setting up the FDS

input data file. Figure 3 shows a snapshot of a slice file where the slice is colored according to

gas temperature. Slice files have file names with extension .sf . Slice files are displayed by

selecting the desired slice file from the Load/Unload menu.

Boundary Files Boundary files contain simulation data recorded at interior or exterior boundary surfaces. Continuously shaded contours are drawn for quantities such as wall surface temperature,

radiative flux etc. Figure 4 shows a snapshot of a boundary file animation where the surfaces

are colored according to their temperature. Boundary files have file names with extension .bf.

1Though the OpenGL libraries could be found on the Internet and installed on a PC running the first release of Windows 95, it is

recommended that Windows be upgraded to a more current release.

3
Figure 2: Particle File Example.

Figure 3: Slice File Example

4
Figure 4: Boundary File Example

Boundary files are displayed by selecting the desired boundary file from the Load/Unload

menu.

PLOT3D files PLOT3D files store five data values at each grid cell. FDS stores temperature, three components of velocity (U, V, W) and heat release rate by default. Other quantities may be stored

if desired. In addition the PLOT3D format allows one to specify internal blockages so that

contour data need not be displayed where the physical domain is blocked off. PLOT3D[6] files

store data in a standard format developed by NASA and used by many CFD programs for representing simulation results. An FDS simulation will typically create PLOT3D files at several

times. PLOT3D data is visualized in three ways: as 2D contours, vector plots and iso-surfaces.

2D contours2 along either of the XZ, XY or YZ planes. In the default Smokeview view, the X

and Z coordinate axes are parallel to the horizontal and vertical screen edges respectively while

the Y coordinate axis occurs front to back “within” the screen. Figure 5 shows an example of

a 2D PLOT3D contour. Vector plots may be viewed if one or more of the U,V and W velocity

components are stored in the PLOT3D file. The vector length and direction show the direction

and speed of fluid flow travel while the vector colors show the solution value. Figure 6 show

vectors which indicate flow direction. 3D contours or iso-surfaces show where the solution attains one particular value. Figure 7 gives an example of an iso-surface. PLOT3D data are stored

in files with extension .q .

The format used to store each of the above data files are given in Appendix D.3 so that Smokeview may be

used to visualize data generated by other fire models.

22D contours may be shaded continuously as are slice and boundary file data or shaded in discrete shades of uniform color.

5
Figure 5: PLOT3D Contour Example

Figure 6: PLOT3D Vector Plot through a door

6
Figure 7: PLOT3D Iso-contour Example

3.2 Visualizing FDS Output

3.2.1 Mouse movement

The left mouse button is used to either rotate or translate the scene depending upon whether the SHIFT, CTRL

or ALT keys are depressed or not during mouse movement. Figure 8 shows an outline view of a Smokeview

scene with X, Y and Z axes labeled. Again note that in the default Smokeview view, the X and Z coordinate

axes are parallel to the horizontal and vertical screen edges respectively while the Y coordinate axis occurs

front to back “within” the screen. Left and right scene motion occurs along the X axis, up and down scene

motion occurs along the Y axis while in and out scene motion occurs along th Z axis. These labels are used

to describe how the mouse effects scene movement in the following way:

No modifier key depressed Horizontal(vertical) mouse movement results in scene rotation parallel to

the XY (YZ) plane. Rotation parallel to the YZ plane is disabled while eye view is in effect. The

view is switched between eye view and world view by either depressing the e key or by selecting

the Show/Hide view menu item. Equivalently, horizontal(vertical) mouse movement results

in scene rotation about the Z(X) axis.

SHIFT key depressed Horizontal(vertical) mouse movement results in scene rotation parallel to the

XZ(YZ) plane. Equivalently, horizontal(vertical) mouse movement results in scene rotation

about the Y(X) axes respectively.

CTRL key depressed Horizontal mouse movement results in scene translation from side to side along

the X axis. Vertical mouse movement results in scene translation “in and out” of the computer

screen along the Y axis.

ALT key depressed Vertical mouse movements results in scene translation along the Z axis. Horizontal

mouse movement has no effect on the scene.

7
x

y

z

Figure 8: Smokeview coordinate system.

Note that the Reset View menu item resets the scene back to the original view.

3.2.2 Particle, slice, boundary file visualization

Particle, slice and boundary files are straightforward to visualize. Once Smokeview has started up, simply

select the desired file from the Load/Unload menu and view the scene.

Particle files are typically much larger than other output files. Several strategies exist for reducing the

memory required to display particle files. All of these strategies involve modifying various keywords found

in the Smokeview preference files. The Smokeview preference file smokeview.ini may be created by

typing “smokeview -ini” at a command line or by selecting the Init File sub-menu of the the

Load/Unload menu. These preference file keywords with default values are given below and are documented in Appendix D.1.

MAXFRAMES

501

MAXPOINTS

5000000

PARTPOINTSTEP

1

PARTPOINTCOMPRESS

2

PARTFRAMESTEP

1

The MAXFRAMES and MAXPOINTS keywords determine the maximum number of data frames and data

points used to read in particles. These two parameters may also be set from the command line when starting

up Smokeview. The PARTPOINTSTEP and PARTFRAMESTEP parameters allow one to skip particles or

particle frames. Finally, the PARTPOINTCOMPRESS allows one to store particle data in a compressed

format. Setting PARTPOINTSTEP and PARTFRAMESTEP to

8
PARTPOINTSTEP

3

PARTFRAMESTEP

3

reduces the memory needed by a factor of nine since every third point and every third particle frame instead

of all points and frames are loaded.

Sometimes it is of interest to change the minimum and maximum axis labels, for example to use the same

min and max for each loaded data file. Data value bounds may be set with the V PARTICLES, V SLICE

and V BOUNDARY keywords. The default values are given by

V_PARTICLES

0 1.000000 0 0.000000

V_SLICE

0 1.000000 0 0.000000

V_BOUNDARY

0 1.000000 0 0.000000

To cause Smokeview to set the min and max labels to 30 and 600 respectively use

V_PARTICLES

1 30.000000 1 600.000000

V_SLICE

1 30.000000 1 600.000000

V_BOUNDARY

1 30.000000 1 600.000000

The integer “1” occuring before the “30” or “600” causes Smokeview to use the next number as a minimum

or maximum value respectively. If this integer is 0 then Smokeview ignores the subsequent min/max value.

3.2.3 Visualizing PLOT3D data files

PLOT3D files are more complicated to visualize than files containing time dependent data such as particle,

slice or boundary files. For example, only the transparency and color characteristics of a time file may be

changed. With PLOT3D files however, many attributes may be changed. One may view 2D contours along

the X, Y and/or Z axis of up to six3 different simulated quantities, view flow vectors and iso or 3D contours.

PLOT3D file visualization is initiated by selecting the desired file from the Load/Unload PLOT3D submenu and as with time files one may change color and transparency characteristics.

2D contours Smokeview displays the “middle” 2D contour along the Y axis by default when a PLOT3D

file is first loaded. To step the contour slice up by one grid cell along the Y axis, depress

the “space bar”. Similarly to step the contour slice down by one grid cell along the Y axis,

depress the “-” key. The “x”, “y” or “z” keys toggle contour visibility along the X, Y and Z axes

respectively. The PLOT3D variable viewed may be changed by either depressing the “p” key

or by selecting the Solution Variable sub-menu of the Show/Hide menu. Minimum

and maximum PLOT3D values may be set using the V PLOT3D smokeview.ini keyword.

The default V PLOT3D keyword value is given by

V_PLOT3D

3The FDS software stores temperature, three components of velocity (denoted U, V and W) and heat release per unit volume. If at

least one velocity component is stored in a PLOT3D file then Smokeview adds speed to the PLOT3D variable list.

9
5

1 0 1.0 0 0.0

2 0 1.0 0 0.0

3 0 1.0 0 0.0

4 0 1.0 0 0.0

5 0 1.0 0 0.0

where the initial 5 indicates the number of subsequent bound lines. Each bound line begins with

an integer (indicating the PLOT3D variable number) followed by 4 numbers defined the same

as with the V PARTICLE, V SLICE and V BOUNDARY keywords. To set the minimum and

maximum bound for the first PLOT3D variable to 20 and 620 use

V_PLOT3D

5

1 1 20.0 1 620.0

2 0 1.0 0 0.0

3 0 1.0 0 0.0

4 0 1.0 0 0.0

5 0 1.0 0 0.0

Smokeview then uses these bounds to label the PLOT3D color bar from 20 to 620. It draws contours smaller than 20 with the “smallest” color and contours bigger than 620 with the “biggest”

color. In addition to 0 and 1, the V PLOT3D keyword may use 2 as a bound indicator . In the

above example, if 2 rather than 1 is used to define PLOT3D bounds, then Smokeview does not

draw contour levels smaller than 20 or contours greater than 620. This is true for “stepped” or

discrete contours. If “continuous” contours are drawn then “2” and “1” have the same effect.

Figure 9 shows a ceiling jet contour plot drawn using the following V PLOT3D values

V_PLOT3D

5

1 2 300.0 1 350.0

2 0 1.0 0 0.0

3 0 1.0 0 0.0

4 0 1.0 0 0.0

5 0 1.0 0 0.0

The bound line 1 2 300.0 1 350.0 indicates that temperatures below 300 

C are not

drawn and that temperatures above 350 C are drawn with the “highest” color (black in black

and white mode, red in color mode).

Flow vectors If at least one velocity component is present in the PLOT3D file then the “v” key may be

depressed in order to view flow vectors. The length and direction of the vector indicates the flow

direction and speed. The vector color indicates the value of the currently displayed quantity. A

small dot is drawn at the end of the line to indicate flow direction. The vector lengths as drawn

may be changed by depressing the “a” key. Vector plots may be very dense when the grid is

finely meshed. The “s” key may be depressed in order to skip vectors. For example, all vectors

are displayed by result. If the “s” key is depressed, then every other vector is skipped.

10
Figure 9: Contour plot illustrating a ceiling jet by using a V PLOT3D keyword entry of: “1 2 300.0 1

350.0” for the first (temperature) PLOT3D variable.

Iso-Contours Iso-contours also called 3D contours or level surfaces may be viewed by depressing the

“i key or by selecting the PLOT3D 3D Contours sub-menu of the Show/Hide menu.

3.3 Checking FDS Input

Consider the following FDS input file. It describes a small space with a burner adjacent to the near wall, a

small vent on the opposite wall and an interior wall containing a door. Figure 10 is a Smokeview visualization

of this input file. Using Smokeview one may conclude that a blockage and vent are not in their intended

locations.

&HEAD CHID=’testcase1’,TITLE=’Single Fire Plume’ /

&GRID IBAR=32,JBAR=32,KBAR=32 /

&PDIM XBAR=1.0,YBAR=1.0,ZBAR=1.0 /

&TIME DT=0.05,TWFIN=0.05 /

&SURF ID=’burner’,VEL=-.2,PARTICLES=.TRUE.,PARTICLE_COLOR=’RED’ /

&SURF ID=’inlet’,VEL=-.2,PARTICLES=.TRUE.,PARTICLE_COLOR=’GREEN’ /

&OBST XB=0.65,0.85,0.00,0.2,0.1,0.2,BLOCK_COLOR=’GREEN’ /

&OBST XB=0.00,0.30,0.45,0.5,0.0,1.0 /

&OBST XB=0.70,1.00,0.45,0.5,0.0,1.0 /

&OBST XB=0.30,0.60,0.45,0.5,0.7,1.0,BLOCK_COLOR=’BLUE’ /

&VENT XB=0.70,0.8,0.05,0.15,0.2,0.2,SURF_ID=’burner’ /

&VENT XB=0.65,0.85,1.00,1.0,0.2,0.4,SURF_ID=’inlet’ /

This input file contains two errors as can be noted by examining Figure 10. First, the door soffit (the blue

blockage) contains an unintended gap, second the burner vent does not completely cover the underlying

(GREEN) blockage. Note that it is certainly permissible to define a vent this way but for the purposes of

this example it was intended that the vent cover the entire blockage. Blockages may be individually colored

11
Figure 10: Using Smokeview to verify model input. This example has a gap in the door soffit and a burner

vent boundary that is too small.

in order to associate &OBST lines in an FDS data file with blockages in the Smokeview scene. The blue

blockage may be corrected replacing the above blue OBST line with

&OBST XB=0.30,0.70,0.45,0.5,0.7,1.0,BLOCK_COLOR=’BLUE’ /

The burner vent may be corrected by matching the horizontal vent coordinates with the horizontal “GREEN”

blockage coordinates and replacing the ‘burner’ vent line in the above case with

&VENT XB=0.65,0.85,0.00,0.20,0.2,0.2,SURF_ID=’burner’,VENT_COLOR=’GREEN’ /

Figure 11 shows a view of the corrected test case.

The following is a general procedure for identifying problems in FDS input files. Assume that the FDS

input data file is named testcase1.data.

1. Set SET UP=.TRUE. on the &MISC line. This causes FDS to read the input file and create a .smv

file without running the case.

2. After the input file has been modified, run the FDS model by typing:

fds < testcase1.data

FDS creates a file named testcase1.smv containing information that Smokeview uses to visualize

data.

3. To visualize the input file, open testcase1.smv with Smokeview by either typing smokeview

testcase1 at a command shell prompt or if on the PC by double-clicking the file testcase1.smv.

If Smokeview was already running (i.e. from an earlier iteration in this debugging cycle) re-read

testcase1.smv into Smokeview with the Reload testcase1.smv menu item.

12
Figure 11: Corrected case

4. Make corrections if necessary. Use the BLOCK COLOR option4 of the FDS keyword OBST to more

easily identify blockages to be edited. Save testcase1.data file and go back to step 2.

5. If corrections were not necessary, then change the TWFIN keyword back to the desired final simulation

time, remove any unnecessary FDS BLOCK COLOR, VENT COLOR and SET UP keywords and run the

case.

4The FDS BLOCK COLOR and VENT COLOR keywords may have values: RED, BLUE, GREEN, MAGENTA, CYAN, YELLOW, WHITE

or BLACK.

13
A Smokeview Command Line Options

Smokeview may be run from a command shell. Further, command line options may be invoked in order to

alter Smokeview’s startup behavior. Normally these options are not necessary. However, they may be used

for cases with very large particle files or to generate a preference or customization file. To obtain a list of

command line options, type:

smokeview

without any arguments which results in output similar to:

Smokeview 1.0.0 - Release Jan 1 2000 - NIST/BFRL

Visualize fire/smoke flow simulations. All parameters are optional.

Usage:

smokeview casename -points m -frames n -ini -nopart -benchmark

where

casename = project id (file names without the extension)

m = maximum number of particles. Default=5000000

n = maximum number of particle frames. Default=501

-ini = output default smokeview parameters to smokeview.ini

-nopart = do not load particle file

-benchmark = display graphics performance indicators

The -nopart option is used to prevent a particle file from being loaded at startup as in:

smokeview casename -nopart

The -points or -frames options may be used to load more than the default 5,000,000 points or 500

frames where a frame is data for one time step. To load up to 6,000,000 points and 1000 frames then type:

smokeview casename -points 6000000 -frames 1000

where in both cases casename is the basename of the FDS output files. The same effect may be achieved

by using

MAXPOINTS

6000000

MAXFRAMES

1000

in the smokeview.ini or casename.ini file. This file may be created with the -ini option and

contains many other customizable Smokeview parameters. The -benchmark option is used to measure

the performance of Smokeview. When particle files are displayed Smokeview outputs the rate that points

(particles) are displayed per second. Similarly, when iso-surfaces (3D PLOT3D contours) are displayed the

-benchmark option causes Smokeview to output the rate that triangles are displayed per second.

14
B Menu Options

The design philosophy used to develop Smokeview has been to avoid complicated, non-portable user interfaces that are costly to implement. As a result, most of the development effort has gone into the visualization

(display of particle flow, contour plots etc) rather than user interface design and implementation. The graphics library utility toolkit GLUT[5] based on OpenGL[4] is used to implement the “pop up” menus used by

Smokeview to manipulate various features of the graphical scenes. The user interacts with Smokeview via 1)

menus, 2) keyboard shortcuts and 3) the .ini file.

A “pop up” menu is displayed when the right mouse is clicked anywhere within the scene. The main

menu options are: Load/Unload , Show/Hide, Max Frame Rate, Render, Tour, Reset View,

Help and Quit. Several of these menu options have sub-menus. These options are explained in the following sections.

B.1 Main Menu Items

Load/Unload This option allows one to load or unload particle, slice, PLOT3D or boundary files. The

three time dependent files (particle, slice and boundary) may be viewed simultaneously, but not

concurrently with the time independent PLOT3D files. However, only one particle, one slice,

one boundary and one PLOT3D file may be viewed at a time. This menu may also be used to

load and create preference files .ini files and to re-read the .smv file. For more details

see Appendix B.2.

Show/Hide This menu item allows one to show or hide the loaded data files and various scene attributes

such as time/color bars, internal blockages etc. As a file type is shown or hidden (or loaded and

unloaded), the color and time bars are changed to reflect the currently visible data files. More

details are given in Appendix B.3.

Max Frame Rate This option controls the rate at which image frames are displayed. The sub-menus

allow one to specify a maximum frame rate. The actual frame rate may be slower if the scene is

complex. The unlimited menu item allows one to display frames as rapidly as the graphics

hardware permits or to step through the frames manually. The step menu item allows one to

step through the simulation one time step at a time. This menu item may be used in concert

with the Render menu item described below to create images at the desired time and view

orientation for inclusion into reports. This is how figures were generated in this report.

Render This option allows one to create GIF files of the currently displayed scene. The Render submenus allow one to specify an integer between 1 and 20 indicating the number of frames between rendered GIF images. This allows one to generate GIF images encompassing the entire time duration of the simulation which in turn can be converted into movie files (mpeg,

mov, avi etc) using software available on the Internet. This is how movies were displayed

http://fire.nist.gov/smokeviewwere generated. Rendering may be stopped by selecting Cancel.

(Keyboard shortcut for the render option: r)

Tour Causes the scene to rotate about its center.

Reset Resets the simulation scene back to the original view. If a time file (particle, slice and/or boundary) is visible then two sub-menus occur allowing one to reset the view back to the original

position or the time bar back to the initial time.

15
Help Displays a list and explanation of keyboard equivalent commands

Quit Exit or quit Smokeview.

B.2 Load/Unload

Four types of files may be visualized with Smokeview. They are particle, slice, boundary and PLOT3D files.

The format of the data contained in these files is described in Appendix D.3. A sub-menu is present under

Load/Unload for each file type generated for the simulation. Selecting one of the files appearing in the

sub-menu causes it to be loaded and then displayed. The data may be unloaded or freed by selecting an

Unload menu item appearing under the file list. Selecting Unload All, as expected, will unload all files.

If the wish is to temporarily hide a data file, then the appropriate Show/Hide menu option (depending on

the file type to be hidden) should be selected.

The Smokeview input data file contains information about all data files appearing in the Load/Unload

menu item. The FDS field modeling software creates this file. (See Appendix D.2 for documentation on the

format of this file).

The character “*” occuring before a file name in one of the sub-menus indicates that the file has already

been loaded. If the file below is loaded but not visible then use the appropriate Show/Hide option to make it

visible.

Particle File (.part) This menu item gives the name of the particle file and also the option to unload

the currently loaded particle file.

Slice File (.sf) This menu item gives the name of all slice files and also the option to unload the currently loaded slice file.

PLOT3D File (.q) This menu item gives the name of all PLOT3D files and also the option to unload

the currently loaded PLOT3D file.

Boundary File (.bf) This menu item gives the name of all boundary files and also the option to unload

the currently loaded boundary file.

Init File (.ini) The init or preference file contains configuration parameters that may be used to customize Smokeview’s appearance and behavior. This menu item lets one create (or overwrite)

a preference file named either smokeview.ini or casename.ini. A preference file contains parameter settings for defining how Smokeview visualizes data. This file may be edited

and re-read while Smokeview is running.

Smokeview input file (.smv) This menu item is used when debugging FDS input files. It allows one to

reload a Smokeview case (.smv file). A debugging cycle can then be performed consisting of

1) editing FDS input file, 2) running FDS and 3) reloading an updated Smokeview input file.

Unload All This option causes all data files to be unloaded.

B.3 Show/Hide

The Show/Hide menu item allows one to show or hide various parts of the simulation. This menu item

contains sub-menus for Particles, Boundary, Animated Slice, PLOT3D 2D and 3D contours, sensors (ther16
mocouples, heat detectors and sprinklers), Color and time Bars and Geometry. These menu items only appear

if they pertain to the simulation. For example the Particles sub-menu only appears if a particle file has

been loaded. Similarly, the PLOT3D contouring sub-menus only appear if a PLOT3D file has been

loaded. The “*” character is used to indicate whether the visualization feature corresponding to the menu

item is set or active.

B.3.1 Geometry Options

Blockages The three blockage viewing options are Show All, Show Frame and Hide. The first and

last option are self explanatory. The Show Frame option allows one to view only a frame or

outline of each blockage. This makes it easier to see other simulation features when the scenario

has many blockages. Blockages may be displayed in different colors. This allows one to more

easily set up FDS input files by identifying blockages and verifying that they have been defined

as intended.

Grid This option allows one to visualize the grid used to perform the numerical calculations. One selects xy plane, xz plane or yz plane to visualize a single plane or Show All, Hide

All to show or hide all grids. (Keyboard shortcut: g)

Outline Show or hide the outline that frames the simulation scene.

Floor Show or hide the floor.

Vents Show or hide the vents.

Walls Show or hide the walls.

B.3.2 Particles

Smoke (tracer) Toggle the visibility of the particles. If water/sprinkler droplets are present in the particle

file then sub-menus exist for both smoke and water to allow one to show or hide smoke and

water droplets independently.

Sprinkler Toggle the visibility of sprinkler (water droplets).

B.3.3 Boundary

Exterior Show or hide all data contained in a boundary (.bf) file pertaining to the exterior walls.

Interior Show or hide all data contained in a boundary (.bf) file pertaining to interior blockages.

Front, Back, Left, Right, Up, Down Toggle the visibility of whatever exterior boundary surface is selected. Note an exterior boundary menu option only appears if its data is present in the boundary

file.

B.3.4 Animated Slice

Toggle the visibility of the animated slice or slice file.

B.3.5 PLOT3D 2D Contours

Solution Variables A PLOT3D data file contains five solution variables. If one or more of the velocity

components denoted

p

u, v and w are present in the PLOT3D file then speed, calculated using

u2 + v2 + w2, appears in the menu. Any velocity components missing from the PLOT3D file

are set to 0.0 when calculating speed. This menu item allows one to select the PLOT3D solution

variable to be visualized. (Keyboard shortcut: p)

17
xy, xz, yz planes These three menu items, appearing beneath the Solution Variables menu item,

allow one to select which plane (xy, xz or yz) is displayed. (Applicable keyboard shortcuts:

space bar, -, left/right cursor, up/down cursor, page up/down, 1...9)

Flow vectors Toggle visibility of flow vectors. The magnitude and direction of the vectors are determined by the U, V and W components of velocity. The vector color is determined by the

solution variable selected. (Applicable keyboard shortcuts: a, s, v)

Continuous Display contours as smooth continuous shades or as stepped constant shades. (Keyboard

shortcut: c)

Show All Show all three (xy, xz and yz) PLOT3D planes at once.

Hide All Hide all three PLOT3D planes.

B.3.6 PLOT3D 3D Contours

Solution Variables Same as for 2D contours. This menu item allows one to select the solution variable

used to generate the 3D or iso-contour to be displayed.

Level Select the 3D contour level to display. The axis label shown in red corresponds to the 3D

contour level displayed.

Block Size To increase the drawing speed, adjacent grid cells may be combined when viewing 3D contours. Selecting 1 will result in highly resolved contours but may take longer to draw. Selecting

5 will have the opposite effect.

Hide Hide the 3D contour.

B.3.7 Heat detectors, Sprinklers, Thermocouples

Toggle the sensor visibility. The currently implemented sensors are heat detectors, sprinklers and thermocouples.

B.3.8 Shades

Flip Flip the background color between a dark and light shade. A dark background shade looks

better on a computer monitor while a light shade looks better on the printed page.

Color Toggle scene colors between color and shades of gray. This option currently does not convert all

scene colors to shades of gray. It was felt that contours and blockages were the most important

to convert.

Transparent Toggle contours between opaque and transparent. Transparent colors allow one to view the

scene behind the contours giving the one a better sense of scale. Transparent colors however

may make the scene look too confusing when the geometry is complex.

B.3.9 Rotation

Eye Centered Rotate and move the scene relative to the observer’s “eye”. Eye centered views make it

easier to move around within the scene itself as in modern computer games. (Keyboard shortcut:

e. The “e” keyboard shortcut toggles the view between an eye centered and a world centered

perspective.)

World Centered Rotate and move the scene relative to the scene’s center. (Keyboard shortcut: e. The

“e” keyboard shortcut toggles the view between an eye centered and a world centered perspective.)

18
B.3.10 Labels

Color Bars, Time Bars, Title, Frame Rate Show or hide the individual scene element.

Show All Show all scene elements.

Hide All Hide all scene elements.

C Keyboard Commands

Many menu commands have equivalent keyboard shortcuts. These shortcuts are described here and are also

briefly described under the Help menu item from within Smokeview itself.

a Alter the arrow size used to display velocity vectors.

b To increase the drawing speed, adjacent grid cells may be combined into coarser pseudo-grid

cells when generating and viewing 3D contours. The “b” key is used to increment the number

of grid cells that are combined (between one and five grid cells) when generating 3D contours.

Using one grid will result in highly resolved contours but may take longer to draw. Using five

grid cells will have the opposite effect, i.e. will result in coarse contours that can be drawn

quickly.

c Toggle the PLOT3D 2D contour display between solid banded contours and continuously shaded

contours.

e Toggle how the scene is manipulated between an “eye view” where scene motion is relative to

the observer and a “world view” where the scene motion is relative to the scene center.

g Toggle the grid visiblity. When the grid display option is active, the x, y and z keys may be used

to show or hide the grid perpendicular to the x, y and z axes respectively.

i Toggle the visiblity of iso-contours (3D surface contours).

o Reset a time dependent animation to the initial time.

p Show the next variable in the PLOT3D data set.

r Render the current scene as a GIF file which can be viewed in a web browser or inserted into a

word processing document.

s Increment the number of vectors skipped. Useful for making vector displays more readable

when grids are finely meshed.

t Toggle the time stepping mode. Time stepping mode allows one to step through the simulation

one time step at a time.

x, y, z Toggle the visibility of the PLOT3D data planes perpendicular to the x, y and z axes respectively

(parallel to the yz, xz and xy planes).

v Toggle vector visibility. This option is only active when there are U, V and/or W velocity

components present in the PLOT3D data set.

Left/Right Cursor Increment/decrement the PLOT3D plane location displayed in the xz plane.

Page Up, Page Down Increment/decrement the PLOT3D plane location displayed in the xy plane.

Up/Down Cursor Increment/decrement the PLOT3D plane location displayed in the yz plane.

- Decrement PLOT3D data planes, PLOT3D iso-contour levels or time step displayed.

space bar Increment PLOT3D data planes, PLOT3D iso-contour levels or time step displayed.

19
D File Formats

D.1 Smokeview Preference File Format (.ini files)

Smokeview uses preference files to set input parameters not settable using menus or the keyboard and to save

the “state” of a visualization. Smokeview looks for preference files in three locations in the following order:

1. a file named smokeview.ini in a global directory defined by the SMOKEVIEWINI environment

variable. On the PC, the directory C:nnistnfdsnsmokeview.ini is the default location for this

preference file. The SMOKEVIEWINI environment variable may be defined on the PC by adding the

line

set SMOKEVIEWINI=dir

to the c:nautoexec.bat file where dir is the directory where the global customization file is

stored. This step is performed automatically by the Smokeview installation program. This environment variable may be defined on a UNIX workstation by adding the line

setenv SMOKEVIEWINI dir

to a .login or .cshrc start up file again where dir is the directory containing the global customization file. Changes to this smokeview.ini file apply to all cases visualized on the computer

unless overridden by preference files named or located in directories named in steps 2. and 3.

2. a file named smokeview.ini in the directory containing the case being visualized. Changes to this

smokeview.ini file apply to all cases in the current directory unless overridden by the casename.ini

file contained in this directory.

3. a file named casename.ini in the directory containing the case being visualized where casename if

the name of the case.

The smokeview.ini file may be created by typing

smokeview -ini

from the command line or by selecting the Write smokeview.ini menu item. The casename.ini

preference file can be created via the menus or by copying a previously created smokeview.ini file.

Smokeview reads the global smokeview.ini file first (step 1. above), followed by the local smokeview.ini

file (step 2. above), followed by the casename.ini file. The global smokeview.ini file is used to customize parameters for all Smokeview runs. The local smokeview.ini file is used to customize parameters

for just those Smokeview runs contained in the local directory. The casename.ini file is used to customize

parameters for only those Smokeview runs with the prefix casename.

All preference file parameters unless otherwise noted consist of a KEYWORD followed by a value, as in

KEYWORD

value

D.1.1 Color parameters

All colors are specified using a 3-tuple: r g b where r, g and b are the red, green and blue components of the

color respectively. Each color component is a floating point number ranging from 0.0 to 1.0 where 0.0 is the

darkest shade and 1.0 is the lightest shade. For example the 3-tuple 1.0 0.0 0.0 is bright red, 0.0 0.0 0.0 is

black and 1.0 1.0 1.0 is white.

BACKGROUNDCOLOR Sets the color used to visualize the scene background. (default: 0.0 0.0

0.0)

BLOCKCOLOR Sets the color used to visualize internal blockages. (default: 1.0 .8 4.0)

20
BOUNDCOLOR Sets the color used to visualize floors, walls and ceilings. (default: 0.5 0.5 0.2)

COLORBAR Entries for the color palette in rgb (red, green, blue) format where each color component

ranges from 0.0 to 1.0 . The default values (rounded to 2 digits) are specified with

COLORBAR

12

0.00 0.00 1.00

0.00 0.28 0.96

0.00 0.54 0.84

0.00 0.76 0.65

0.00 0.91 0.41

0.00 0.99 0.14

0.14 0.99 0.00

0.41 0.91 0.00

0.65 0.76 0.00

0.84 0.54 0.00

0.96 0.28 0.00

1.00 0.00 0.00

COLOR2BAR Miscellaneous colors used by Smokeview. The default values are specified using

COLOR2BAR

8

1.0 1.0 1.0 :white

1.0 1.0 0.0 :yellow

0.0 0.0 1.0 :blue

1.0 0.0 0.0 :red

0.0 1.0 0.0 :green

1.0 0.0 1.0 :magenta

0.0 1.0 1.0 :cyan

0.0 0.0 0.0 :black

where the 8 indicates the number of colors defined and the character string after the ‘‘:’’ are

ignored.

FOREGROUNDCOLOR Sets the color used to visualize the scene foreground (such as text labels).

(default: 1.0 1.0 1.0)

SENSORCOLOR Sets the color used to visualize sensors. (default: 1.0 1.0 0.0)

SETBW The parameter used to set whether color shades (0) or shades of grey (1) are to used for coloring

contours and blockages. (default: 0)

SPRINKOFFCOLOR Sets the color used to visualize sprinklers before they activate. (default: 1.0

0.0 0.0)

SPRINKONCOLOR Sets the color used to visualize sprinklers after they activate. (default: 0.0 1.0

0.0)

VENTCOLOR Sets the color used to visualize vents. (default: 1.0 0.0 1.0)

21
D.1.2 Size parameters

The parameters described in this section allow one to customize the size of various Smokeview scene elements.

LINEWIDTH Defines the width of lines in pixels except lines used to draw vents. (default: 2:0)

PARTPOINTSIZE Defines the size in pixels of smoke or tracer particles. (default: 1:0)

SENSORABSSIZE Defines the sensor size drawn by smokeview using the same units as used to specify

the grid coordinates. (default: 0:038)

SLICEOFFSET Defines an offset distance between animated slices and adjacent solid surfaces. The

offset distance is relative to the maximum grid cell width. (default: 0:10)

SPRINKLERABSSIZE Defines the sprinkler size drawn by smokeview using the same units as used to

specify the grid coordinates. (default: 0:076)

VECTORLENGTH Defines the length of PLOT3D vectors. A vector length of 1:0 fills one grid cell.

Vector lengths may also be changed from within Smokeview by depressing the “a” key. (default: 4:0)

VECTORPOINTSIZE Defines the size in pixels of the point that is drawn at the end of a PLOT3D

vector. (default: 3:0)

VENTLINEWIDTH Defines the width of lines used to draw vents in pixels. (default: 2:0)

VENTOFFSET Defines a distance used to offset vents drawn from adjacent surfaces. (default: 0:10

(units of fraction of a grid cell width))

WINDOWHEIGHT Defines the initial window height in pixels. (default: 480)

WINDOWWIDTH Defines the initial window width in pixels. (default: 640)

D.1.3 Time and value bound parameters

This section describes parameters used by Smokeview to 1) modify the time intervals used to load data

(keywords beginning with T ) and 2) over-ride the minimum and maximum data values (keywords beginning

with V ) used to convert data to color values. By default, Smokeview reads in data for all time values and

does not over-ride minimum and maximum data values. Each time and data bound keyword (except for

V PLOT3D) has the format

KEYWORD

minflag minvalue maxflag maxvalue

where minflag can be either 0 or 1. If it is 1 then, the subsequent number, minvalue is used by Smokeview to scale the data otherwise if minflag is 0 then minvalue is ignored. The next two parameters

maxflag and maxvalue are defined similarly. The V PLOT3D keyword contains data bound entries for

each variable in the PLOT3D data file. If a PLOT3D “speed” variable was constructed by Smokeview then

the V PLOT3D keyword will contain six entries instead of five.

T BOUNDARY Defines the minimum and maximum times used to include particles in a visualization.

The default values are specified with

T_BOUNDARY

0 1.0 0 0.0

22
To load boundary data between 20 and 150 seconds use

T_BOUNDARY

1 20. 1 150.

T PARTICLES Defines the minimum and maximum times used to include particles in a visualization.

(default: 0 1.0 0 0.0)

T SLICE Defines the minimum and maximum times used to include particles in a visualization. (default: 0 1.0 0 0.0)

V BOUNDARY Defines the minimum and maximum data bounds used to convert boundary data values

to color indices. (default: 0 1.0 0 0.0)

V PARTICLES Defines the minimum and maximum data bounds used to convert particle data values

to color indices. (default: 0 1.0 0 0.0)

V PLOT3D Defines the minimum and maximum data bounds used to convert PLOT3D data values to

color indices. The default values are given by

V_PLOT3D

5

1 0 1.0 0 0.0

2 0 1.0 0 0.0

3 0 1.0 0 0.0

4 0 1.0 0 0.0

5 0 1.0 0 0.0

where the initial 5 indicates the number of subsequent entries, the first integer on each line

indicates the PLOT3D data variable being specified and all other parameters on each line are

defined as above.

V SLICE Defines the minimum and maximum data bounds used to convert slice data values to color

indices. (default: 0 1.0 0 0.0)

D.1.4 Data loading parameters

The keywords in this section may be used to reduce the memory required to visualize FDS data. Keywords

exist for limiting particles and frames. Other keywords exist for compressing particle data and skipping

particles and frames.

BOUNDFRAMESTEP Defines the number of intervals or steps between loaded boundary file frames.

(default: 1)

MAXFRAMES Specifies the maximum number of particle frames that can be read in. (default: 501)

MAXPOINTS Specifies the maximum number of particle points that can be read in from a particle file.

(default: 5000000)

NOPART Indicates that a particle file should not (1) or should (0) be loaded when Smokeview starts up.

This option is used when one wants to look at other files besides the particle file. (default: 0)

23
PARTFRAMESTEP Specifies the interval or steps between loaded particle frames. A particle frame

is all the particles loaded at one particular time step. For example, if PARTFRAMESTEP is set

to 3 then every 3rd particle frame is read in. This and the PARTPOINTSTEP options may be

used together to dramatically reduce the memory required to view particle files. These options

should be used when displaying Smokeview files on computers with limited memory. (default:

1)

PARTPOINTCOMPRESS Specifies how Smokeview stores particle data. Each particle is represented

using three position coordinates and one data value. Using full precision (PARTPOINTCOMPRESS

value of 0), Smokeview uses four bytes per position coordinate and one byte for the data value

or 13 bytes to represent each particle point. If this keyword is set to 1 then Smokeview uses

one byte per position coordinate and one byte for the data value or 4 bytes per particle point.

Finally if this keyword has value 2 then 2 bytes are used to store each position coordinate and

one byte for the data value or 7 bytes per particle point. (default: 2) The recommended value is

2. Using 0 results in almost twice the memory usage without any extra precision in positioning

particles. Using 1, though using less memory than the “2” option, results in granularity effects

when displaying particles which one may find annoying. (default: 2)

PARTPOINTSTEP Specifies the interval or steps between loaded particle points. For example, if

PARTPOINTSTEP is set to 5 then every 5th particle or only 20 % of the particle file is read in.

(default: 1)

SLICEFRAMESTEP Specifies the number of interval or steps between loaded slice file frames. (default: 1)

D.1.5 Viewing parameters

The keywords in this section define how a scene is viewed. Keywords exist for showing or hiding various

scene elements and for modifying how various scene elements appear.

AXISNUM Specifies whether Smokeview should (AXISNUM set to 1) or should not (AXISNUM set to

0) calculate data minimums and maximums based upon statistical limits. For example, if this

parameter is set to 1 then Smokeview will set the minimum and maximum data bound to be the

1st and 99th percentile of the data respectively. (default: 1)

AXISSMOOTH Specifies whether axis numerical labels should be smoothed (AXISSMOOTH set to

1) or not smoothed (AXISSMOOTH set to 0). (default: 1)

EYEVIEW Specifies whether the scene should be rotated relative to the observer (EYEVIEW set to 1)

or the scene center (EYEVIEW=0). (default: 0)

EYEX, EYEY, EYEZ The parameters EYEX, EYEY, EYEZ specify the x, y and z location respectively of the viewing origin (where your eyes are). (default: 0.5 -0.9 1.5)

FRAMERATEVALUE Specifies the maximum rate (frames per second) that Smokeview should display

frames. This value is an upper bound. Smokeview will not display frames faster than this rate

but may display frames at a slower rate if the scene to be visualized is complex. (default:

1000000)

P3CONT2D The parameter P3CONT2D may be set to 0, 1 or 2. If P3CONT2D is set to 0 then PLOT3D

color contours are drawn by coloring each node and letting OpenGL interpolate colors between nodes. If P3CONT2D is set to 1 then discrete or stepped shaded contours are drawn. If

P3CONT2D is set to 2 then contour lines are drawn. (default: 1)

SHOWBLOCKS Specifies how a blockage should be drawn. A value of 0, 1 or 2 indicates that the

blockages are invisible, drawn normaly or drawn as outlines respectively. (default: 1)

24
SHOWCEILING Specifies whether the ceiling (upper bounding surface) should be drawn (1) or not

drawn (0). (default: 0)

SHOWCOLORBARS Specifies whether the color bars should be drawn (1) or not drawn (0) (default:

1)

SHOWFLOOR Specifies whether the floor (lower bounding surface) should be drawn (1) or not drawn

(0) (default: 1)

SHOWFRAMERATE Specifies whether the frame rate label should be drawn (1) or not drawn (0).

(default: 1)

SHOWSMOKEPART Specifies whether smoke or trace particles should be drawn (1) or not drawn (0)

(default: 1)

SHOWSPRINKPART Specifies whether sprinkler droplet particles (if present in the particle file) should

be drawn (1) or not drawn (0). (default: 1)

SHOWTIMEBAR Specifies whether the timebar should be drawn (1) or not drawn (0). (default: 1)

SHOWTITLE Specifies whether the title should be drawn (1) or not drawn (0). (default: 1)

SHOWWALLS Specifies whether the four walls (four vertical bounding surfaces) should be drawn (1)

or not drawn (0). (default: 1)

TRANSPARENT Specifies whether 2D and 3D contours should be drawn with solid colors (0) or transparent colors(1). (default: 1)

VECTORSKIP Specifies what vectors to draw. For example, if this parameter is set to 2 then every 2nd

vector is drawn when displaying vectors. (default: 1)

D.2 Smokeview Parameter Input File (.smv file)

The FDS software outputs simulation results into the Smokeview input file with extension .smv and various

output data files whose format is documented in the next section. A .smv file is a formatted ascii file (ie. a

regular text file) consisting of a set of KEYWORD followed by DATA describing an FDS case’s geometry,

file name and contents, sensor information etc.

D.2.1 Geometry Keywords

OBST The keyword specifies internal blockages. A FORTRAN 90 code segment describing the format

of OBST data is given by

read(5,*)nb

do i = 1, nb

read(5,*)dummy

end do

do i = 1, nb

read(5,*)ib1(i), ib2(i), jb1(i), jb2(i), kb1(i), kb2(i)

end do

where ib1, ib2, jb1, kb1, kb2 are integer arrays containing boundary nodes.

TRNX,TRNY,TRNZ The TRNX, TRNY, TRNZ keywords specify grid nodes in the X, Y, Z coordinate directions. A FORTRAN 90 code segment describing the format of TRNX data is given

by

25
read(5,*)nx

do i = 1, nx

read(5,x)idummy

end do

do i = 1, nx

read(5,*)xplt(i)

end do

TRNY and TRNZ data entries are defined similarly. The first nx data items are not required by

Smokeview.

VENT The keyword specifies vent coordinates. A FORTRAN 90 code segment describing the format

of VENT data is given by

read(5,*)nv

do i = 1, nv

read(5,*)dummy

end do

do i = 1, nv

read(5,*)iv1(i), iv2(i), jv1(i), jv2(i), kv1(i), kv2(i)

end do

where iv1, iv2, jv1, kv1, kv2 are integer arrays containing vent coordinates.

XYZ The XYZ keyword defines the .xyz or PLOT3D grid file name. A FORTRAN 90 code segment

describing the format of XYZ data is given by

read(5,"(a)")xyzfilename

where xyzfilename is a character variable containing the name of the .xyz file.

D.2.2 File Keywords

BNDF The BNDF keyword defines the .bf file name along with character labels used to describe the

data contents of the boundary file. A FORTRAN 90 code segment describing the format of

BNDF data is given by

read(5,"(a)")longlabel

read(5,"(a)")shortlabel

read(5,"(a)")unit

where longlabel, shortlabel, unit are character variables of length 30.

PART The PART keyword defines the .part file name along with character labels used to describe

the data contents of the particle file. A FORTRAN 90 code segment describing the format of

PART data is given by

26
read(5,"(a)")longlabel

read(5,"(a)")shortlabel

read(5,"(a)")unit

where longlabel, shortlabel, unit are character variables of length 30.

PL3D The PL3D keyword defines the .q file name along with character labels used to describe the

data contents for each PLOT3D variable. A FORTRAN 90 code segment describing the format

of PL3D data is given by

do i = 1, 5

read(5,"(a)")longlabel(i)

read(5,"(a)")shortlabel(i)

read(5,"(a)")unit(i)

end do

where the character arrays longlabel, shortlabel, unit each have length 30.

SLCF The SLCF keyword defines the .sf file name along with character labels used to describe the

data contents of the slice file. A FORTRAN 90 code segment describing the format of SLCF

data is given by

read(5,"(a)")longlabel

read(5,"(a)")shortlabel

read(5,"(a)")unit

where longlabel, shortlabel, unit are character variables of length 30.

D.2.3 Sensor Keywords

HEAT The HEAT keyword defines heat detector location data. A FORTRAN 90 code segment describing the format of HEAT data is given by

read(5,*)nheat

do i = 1, nheat

read(5,*)xheat(i),yheat(i),zheat(i)

end do

where nheat is the number of heat detectors and xheat, yheat, zheat are the x, y,

z coordinates of the heat detectors.

HEAT ACT The HEAT ACT keyword defines heat detector activation data. A FORTRAN 90 code segment describing the format of HEAT ACT data is given by

read(5,*)iheat, heat_time

27
where heat time is the activation time of the iheat’th heat detector.

SPRK The SPRK keyword defines sprinkler location data. A FORTRAN 90 code segment describing

the format of SPRK data is given by

read(5,*)nsprink

do i = 1, nsprink

read(5,*)xsprink(i),ysprink(i),zsprink(i)

end do

where nsprink is the number of sprinklers and xsprink, ysprink, zsprink are the

x, y, z coordinates of the sprinklers.

SPRK ACT The SPRK ACT keyword defines sprinkler activation data. A FORTRAN 90 code segment

describing the format of SPRK ACT data is given by

read(5,*)isprink, sprink_time

where sprink time is the activation time of the isprink’th sprinkler.

THCP The THCP keyword defines thermocouple location data. A FORTRAN 90 code segment describing the format of THCP data is given by

read(5,*)ntherm

do i = 1, ntherm

read(5,*)xtherm(i),ytherm(i),ztherm(i)

end do

where ntherm is the number of thermocouples and xtherm, ytherm, ztherm are the

x, y, z coordinates of the thermocouples.

D.2.4 System Keywords

ENDIAN The ENDIAN keyword defines whether a big or little endian5 system is used to represent the

data. The PC (both Windows and LINUX) uses the little endian system for representing numbers while most UNIX workstations use the big endian system. The PC version of Smokeview

uses this keyword to determine whether data should be converted between these two systems

before it is visualized. The valid ENDIAN paramters are BIG or LITTLE.

SYST The SYST keyword defines which system the FDS case was run on. The PC version of Smokeview uses this information (if the ENDIAN keyword is absent) to swap data bytes if the FDS

case was run on a computer with a different “endian” format than the PC.

5Big-endian and little-endian are terms that describe the order in which a sequence of bytes are stored in computer memory. Bigendian is an order in which the big end (most significant value in the sequence) is stored first (at the lowest storage address). Little-endian

is an order in which the little end (least significant value in the sequence) is stored first. The terms big-endian and little-endian are derived

from the Lilliputians of Gulliver’s Travels, whose major political issue was whether soft-boiled eggs should be opened on the big side or

the little side.

28
D.3 Data File Formats (.part, .sf, .bf and .q files)

Smokeview visualizes fire dynamics data using particle, boundary, slice and PLOT3D data files described

in this section along with a Smokeview parameter input file described in the previous section. This section

documents the data format of each data file by showing FORTRAN program code segments used to write the

data out. All files are unformatted and are opened using OPEN statments of the form

OPEN(UNIT=IUNIT,FILE=FILENAME,FORM="UNFORMATTED")

where IUNIT is the FORTRAN unit number used for output and FILENAME is a character variable containing the file name. In the following code segments the standard FORTRAN naming convention of associating

variables beginning with I through N to integer variables and all other alphabetic characters to REAL variables is used. It is assumed that all variables take up four bytes. Variables having DUMMY in the name

indicates that they are not used by Smokeview.

D.3.1 Particle File Format

Particle files are used to store smoke/tracer particles and/or sprinkler droplet information. The particle file

consists of a header and a series of particle frames. Each frame contains particle/droplet positions and data

values for each particle in that frame. The FDS software outputs particle frames at fixed time intervals but

there is no requirement by Smokeview for this to happen. Smokeview reads in the data one frame at a time

noting the time read in for each frame. The header can be described using the code segment

WRITE(IUNIT) DUMMY,DUMMY,DUMMY,IPART,NPPS

WRITE(IUNIT) IBAR,JBAR,KBAR

WRITE(IUNIT) (DUMMY,I=0,IBAR),(DUMMY,J=0,JBAR),(DUMMY,K=0,KBAR)

WRITE(IUNIT) NB

DO N=1,NB

WRITE(IUNIT) IB1(N),IB2(N),JB1(N),JB2(N),KB1(N),KB2(N),1

END DO

WRITE(IUNIT) NV

DO N=1,NV

WRITE(IUNIT) IV1(N),IV2(N),JV1(N),JV2(N),KV1(N),KV2(N),2

END DO

WRITE(IUNIT) NSPR

DO N=1,NSPR

WRITE(IUNIT) XSP0(N),YSP0(N),ZSP0(N)

END DO

where DUMMY is written by FDS but not needed by Smokeview, IPART is the index of the scalar quantity

associated with the particles, NPPS is the maximum number of particles per frame, IB1, IB2, etc are the

indices of blocked grid cells, IV1, IV2, etc indicate vent cell nodes, and XSP0, YSP0, ZSP0 are the

coordinates of the sprinklers. Grid coordinates are obtained by Smokeview from the Smokeview parameter

input file. A particle frame is written using

WRITE(IUNIT) TIME,NP,IDUMMY,(ISPR(N),N=1,NSPR)

WRITE(IUNIT) (XP(I),I=1,NP),

. (YP(I),I=1,NP),

. (ZP(I),I=1,NP),

. (BP(I),I=1,NP)

IF (NASPR.GT.0) THEN

WRITE(IUNIT) NSP

WRITE(IUNIT) (XSP(I),I=1,NSP),(YSP(I),I=1,NSP),(ZSP(I),I=1,NSP)

ENDIF

29
where NP is the number of particles in this frame, ISPR denotes whether the sprinkler has activated, NSPR is

the number of sprinklers, XP, YP, ZP are the particle coordinates, BP is the particle value, NASPR is the

number of active sprinklers, NSP is the number of sprinkler droplets, and XSP, YSP, ZSP are the droplet

coordinates.

D.3.2 Slice File Format

Slice files are unformatted. The slice file header is written out using

WRITE(IUNIT) CDUMMY

WRITE(IUNIT) CDUMMY

WRITE(IUNIT) CDUMMY

WRITE(IUNIT) I1,I2,J1,J2,K1,K2

where CDUMMY is character strings of length 30. Smokeview obtains this information from the Smokeview

parameter input file and not from the slice file. The sextuple (I1,I2,J1,J2,K1,K2) denotes the bounding

grid cell nodes of the slice to be displayed. The sextuple indices correspond to grid cell nodes, or corners, thus

the entire grid would be represented by the sextuple (0,IBAR,0,JBAR,0,KBAR). The grid node positions

are obtained from the Smokeview parameter input file.

The FDS software outputs slice frames at fixed time intervals but there is no requirement by Smokeview

for this to happen. Each slice frame is written using

WRITE(IUNIT) TIME

WRITE(IUNIT) (((QQ(I,J,K),I=11,I2),J=J1,J2),K=K1,K2)

where TIME is the time in seconds when the data is ouput and QQ are the data values.

D.3.3 Boundary Files

The boundary files are unformatted. The header is written out using

WRITE(IUNIT) QUANTITY

WRITE(IUNIT) SHORT_NAME

WRITE(IUNIT) UNITS

WRITE(IUNIT) NPATCH

DO 10 I=1,NPATCH

WRITE(IUNIT) IP1(I),IP2(I),JP1(I),JP2(I),KP1(I),KP2(I)

10 CONTINUE

where QUANTITY, SHORT NAME and UNITS are character strings of length 30, NPATCH is the number

of planes (or “patches”) that make up the solid boundaries plus the external walls. The sextuple arrays

(IP1,IP2,JP1,JP2,KP1,KP2) defines the cell nodes of each patch. The user does not prescribe these.

The FDS software outputs boundary frames at fixed time intervals but there is no requirement by Smokeview for this to happen. The boundary file frame is written using

WRITE(IUNIT) TIME

DO 10 I=1,NPATCH

WRITE(IUNIT) (((QQ(I,J,K),I=IP1(I),IP2(I)),J=JP1(I),JP2(I)),K=KP1(I),KP2(I))

10 CONTINUE

30
D.3.4 PLOT3D Data

Field data is dumped periodically by FDS in a format used by the graphics package PLOT3D[6]. The

PLOT3D data sets are single precision (32 bit reals), whole and unformatted. Note that there is blanking,

that is, blocked out data points are not plotted. The grid data is written out to a file called casename.xyz

using

WRITE(IUNIT) IBAR+1,JBAR+1,KBAR+1

WRITE(IUNIT) (((X(I),I=0,IBAR),J=0,JBAR),K=0,KBAR),

. (((Y(J),I=0,IBAR),J=0,JBAR),K=0,KBAR),

. (((Z(K),I=0,IBAR),J=0,JBAR),K=0,KBAR),

. (((IBLK(I,J,K),I=0,IBAR),J=0,JBAR),K=0,KBAR)

where IBAR+1, JBAR+1, KBAR+1 are the number of grid cells along the I, J, K coordinate directions, X, Y and Z are the physical coordinates of the cell corners, and IBLK is an indicator of whether or

not the cell is blocked. If the point (X,Y,Z) is completely embedded within a solid region, then IBLK is 0.

Otherwise, IBLK is 1. The flow variables are written to a file using

WRITE(IUNIT) IBAR+1,JBAR+1,KBAR+1

WRITE(IUNIT) ZERO,ZERO,ZERO,ZERO

WRITE(IUNIT) ((((QQ(I,J,K,N),I=0,IBAR),J=0,JBAR),K=0,KBAR),N=1,5)

The five channels N=1,5 are by default the temperature (C), the u, v and w components of the velocity (m/s),

and the heat release rate per unit volume (kW/m3).

31
References

[1] K.B. McGrattan, H.R. Baum, R.G. Rehm, A. Hamins, and G.P. Forney. Fire Dynamics Simulator - Technical Reference Manual. Technical Report NISTIR 6467, National Institute of Standards and Technology,

Gaithersburg, Maryland, January 2000.

[2] K.B. McGrattan and G.P. Forney. Fire Dynamics Simulator - User’s Guide. Technical Report NISTIR

6469, National Institute of Standards and Technology, Gaithersburg, Maryland, January 2000.

[3] K.B. McGrattan, H.R. Baum, and R.G. Rehm. Large Eddy Simulations of Smoke Movement. Fire Safety

Journal, 30:161–178, 1998.

[4] Mason Woo, Jackie Neider, and Tom Davis. OpenGL Programming Guide. Addison-Wesley Developers

Press, Reading, Massachussets, 1996.

[5] Mark J. Kilgard. OpenGL Programming for the X Window System. Addison-Wesley Developers Press,

Reading, Massachussets, 1996.

[6] Pamela P. Walatka and Pieter G. Buning. PLOT3D User’s Manual, version 3.5. NASA Technical Memorandum 101067, NASA, 1989.

32
Editorial Review Intranet - Application.cfm Page 1 of 1

http://sqlts01.nist.gov/cfdocs/ERI/eri-manurev.cfm?BIBID=5986 5/12/2000

Signature Page of MRA-OPS Form

U.S. Department of Commerce

National Institute of Standards and Technology

Manuscript Review and Approval

Attach Original of this Form to One Copy of Manuscript and Send to: 

WERB Secretariat, Mail Stop 2500 (Admin. 101/E212)

(ERB Use Only - Version 2.10) 

ERB Control Number Division

Publications Report Number Category Code

Publication Date No. Printed Pages

HOLDREC# Changes Required

Title and Subtitle (Cite in full)

User's Guide for Smokeview Version 1.0 - A Tool for Visualizing Fire Dynamics Simulation Data

Author(s) (Last Name, First Initial, Second Initial)

Forney, G P (Primary) ; McGrattan, K B

Performing Organization:

NIST/GAITHERSBURG

Laboratory and Division

864 - Fire Safety Engineering Division

Sponsoring Organization Name and Complete Address (Street, City, State, Zip)

NIST

Type of Publication Proposed

NISTIR

Proposed for Non-NIST Publication (Cite fully)

Publishing Medium:

Paper

Abstract (A 2000-character or less factual summary of most significant information. If document includes a significant bibliography or literature survey, cite it 

here. Spell out acronyms on first reference.)

Smokeview is a software tool designed to visualize numerical predictions generated by the NIST Fire Dynamics Simulator (FDS), a computational 

fluid dynamics (CFD) model of fire-driven fluid flow. These two tools are used in concert to respectively model and analyze scenarios involving 

features such as fire, wind, sprinklers, complex geometry et. cetera. Smokeview visualizes NIST FDS modeling results in many ways, some of which 

are 1) animating flow of smoke or tracer particles, 2) animating 2D contours of data slices, 3) plotting 2D and 3D static contours or 4) plotting flow 

vectors . Smokeview requires a fast CPU, fast video card, a substantial amount of random-access memory (RAM) and a large hard disk. Smokeview 

is portable and can be run on a variety of computing platforms. For a Windows-based PC, the processor should be at least as fast as a 450 Mhz 

Pentium II, with at least 256 Mbytes of memory. Of course, more is better, but this configuration should allow one to do fairly large calculations in 

a reasonable time period. For UNIX-based workstations, the processor and memory should be at least as fast and as large as the PC specs. 

Smokeview and NIST FDS may be obtained at the website http://fire.nist.gov/smokeview or by contacting the authors at glenn.forney@nist.gov or 

kevin.mcgrattan@nist.gov.

Supplementary Notes

Key Words (Maximum of 9; 28 characters and spaces each; Alphabetic order; Capitalize only proper names)

1. cfd models 2. field models

3. fire simulation 4. fluid flow

5. scientific visualization 6. simulation

7. visualization 8. 

9. 

Availability:

Unlimited

Manuscript Announcement:

Announce Only After Publication.