User’s Guide for Smokeview Version 3.1

– A Tool for Visualizing Fire Dynamics 

Simulation Data

Glenn P. Forney

Kevin B. McGrattan

NISTIR 6980 
NISTIR 6980 

User’s Guide for Smokeview Version 3.1

– A Tool for Visualizing Fire Dynamics 

Simulation Data

Glenn Forney

Kevin McGrattan

Building and Fire Research Laboratory

April 2003

U.S. DEPARTMENT OF COMMERCE

Donald L. Evans, Secretary

TECHNOLOGY ADMINISTRATION

Phillip J. Bond, Under Secretary of Commerce for Technology

NATIONAL INSTITUTE OF STANDARDS AND TECHNOLOGY

Arden L. Bement, Jr., 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 analysis performed using this tools.

Users are warned that Smokeview and the companion program FDS 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. These software packages may or may not have predictive

capability when applied to a specific set of factual circumstances. Lack of accurate predictions 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 Introduction 1

1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3 What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Getting Started 4

3 Using Smokeview 4

3.1 Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.1 Particle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.2 Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.3 Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.1.4 Isosurface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.1.5 Plot3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Visualizing Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2.1 Manipulating the Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2.2 Clipping Smokeview Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.3 Setting Data Bounds in Smokeview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2.4 Plot3D Viewing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.3 Examining Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.3.1 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.3.2 Examining and/or Editing Blockages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.4 Documenting Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.4.1 Making Movies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.4.2 Annotating the Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Summary 23

A Command Line Options 24

B Menu Options 24

B.1 Main Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

B.2 Load/Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

B.3 Show/Hide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

B.3.1 Geometry Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

B.3.2 Animated Surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

B.3.3 Particles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

B.3.4 Boundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

B.3.5 Animated Vector Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

B.3.6 Animated Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

B.3.7 Plot3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

B.3.8 Heat detectors, Sprinklers, Thermocouples . . . . . . . . . . . . . . . . . . . . . . . . . 29

B.3.9 Textures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B.3.10 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B.4 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B.4.1 Shades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B.4.2 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.4.3 Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.4.4 Max Frame Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.4.5 Render . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.4.6 Viewpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

B.4.7 Font Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

B.4.8 Aperture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

v
B.4.9 Stereo 3-D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

B.4.10 Clip Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

B.4.11 Edit Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

B.4.12 Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

B.4.13 Set Bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

C Keyboard Shortcuts 34

D File Formats 35

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

D.1.1 Color parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

D.1.2 Size parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

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

D.1.4 Data loading parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

D.1.5 Viewing parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

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

D.2.1 Geometry Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

D.2.2 File Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

D.2.3 Sensor Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

D.2.4 Miscellaneous Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

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

D.3.1 Isosurface File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

D.3.2 Particle File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

D.3.3 Slice File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

D.3.4 Boundary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

D.3.5 Plot3D Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

E Frequently Asked Questions 50

E.1 How can I keep up with new releases and other information about FDS and Smokeview? . . . . . 50

E.2 Smokeview doesn’t look right on my computer. What’s wrong? . . . . . . . . . . . . . . . . . . . 50

E.3 How do I make a movie of a Smokeview animation? . . . . . . . . . . . . . . . . . . . . . . . . 50

References 51

Acknowledgements 52

vi
List of Figures

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

2 Particle file snapshots of a townhouse kitchen fire. . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Slice file snapshots of shaded temperature contours. . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Vector slice file snapshots of shaded vector plots. . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Boundary file snapshots of shaded wall temperatures contours. . . . . . . . . . . . . . . . . . . . 8

6 Isosurface file snapshots of mixture fraction levels. . . . . . . . . . . . . . . . . . . . . . . . . . 10

7 Plot3D contour and vector plot examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

8 Plot3D isocontour example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

9 Motion Dialogue Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

10 Clipping dialogue box and corresponding clipped scene . . . . . . . . . . . . . . . . . . . . . . . 13

11 Bounds Dialogue Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

12 Ceiling jet visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

13 Blockage Edit Dialogue Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

14 Layout for Roomfire Sample FDS Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

15 Intermediate steps for roomfire construction example. . . . . . . . . . . . . . . . . . . . . . . . 21

16 Annotation example using the TICKS and LABEL keword. . . . . . . . . . . . . . . . . . . . . 23

17 Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

18 Load/Unload Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

19 Geometry Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

20 Label Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

21 Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

22 Shades Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

23 Render Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

List of Tables

1 Output Quantities used by Slice and Plot3D Visualizations . . . . . . . . . . . . . . . . . . . . . 7

2 Output Quantities used by Boundary File Visualizations. . . . . . . . . . . . . . . . . . . . . . . 9

3 Keyboard mappings for “eye centered” scene movement . . . . . . . . . . . . . . . . . . . . . . 13

vii
viii
User’s Guide for Smokeview Version 3.1 - A Tool for Visualizing

Fire Dynamics Simulation Data

Glenn P. Forney

Kevin B. McGrattan

Abstract

Smokeview is a software tool designed to visualize numerical calculations generated by the NIST Fire Dynamics Simulator (FDS), a computational fluid dynamics (CFD) model of fire-driven fluid flow. These two tools

are typically used together to respectively simulate and visualize the flow of smoke induced by a fire. Smokeview

visualizes FDS modelling results by displaying: particle flow, 2D or 3D shaded contours of gas flow data such

as temperature and flow vectors showing flow direction and magnitude. Smokeview also visualizes static data

at particular times again using 2D or 3D contours of data such as temperature and flow vectors showing flow

direction and magnitude. Examples of each visualization type are given.

Windows PC versions of Smokeview and FDS and associated documentation may be downloaded from the

web site http://fire.nist.gov/smokeview at no cost. Versions for Linux and SGI/IRIX may also be downloaded

from the same location.

1 Introduction

1.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[1, 2, 3, 4]. This report

documents version 3.0/3.1 of Smokeview updating material found in Refs. [5, 6]. Most features documented were

present in version 3.0. Version 3.1 contains bug fixes and new features for adding margins around the scene for

use with making movies (see Section 3.4.1) and for annotating the scene (see Section 3.4.2).

FDS and Smokeview are used in concert to respectively model and visualize fire phenomena. FDS and

Smokeview are not limited to fire simulation though. For example, one may use FDS and Smokeview to model

other applications such as contaminant flow in a building. Smokeview performs this visualization by displaying

time dependent tracer particle flow, animated contour slices of computed gas variables and surface data. Smokeview also presents contours and vector plots of static data anywhere within a simulation scene at a fixed time.

Several examples using these techniques to investigate fire incidents are documented in Refs. [7, 8, 9].

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

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 placement etc. In order to set up correct

FDS input files more quickly. One can then use Smokeview to edit or create blockages by specifying the size,

location and/or material properties.

Figure 1 gives an overview of how data files used by both FDS and Smokeview are related. New in Smokeview 3.0 are the direct connections between Smokeview and the input and database files. Smokeview examines

these files for surface materials to be used when editing blockages.

A typical procedure for using FDS and Smokeview is to:

1. Set up an FDS input file, a file with a .data extension (e.g., a file named “casename.data”).

2. Run FDS. (e.g. by typing ‘‘fds < casename.data’’ at a command line). FDS then creates one or

more output files used by Smokeview to visualize the case.

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

3. Run Smokeview to analyze the output files generated by step 2. (e.g. by either double-clicking (on the PC)

on the file named casename.smv or by typing smokeview casename at a command line.) Smokeview may also be used to create new blockages and modify existing ones. The blockage changes are saved

in a new FDS input data file.

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

Menus in Smokeview are activated by clicking the right mouse button anywhere in the Smokeview window. Data files may be visualized with Smokeview by selecting the desired Load/Unload menu option.

Other menu options are discussed in Appendix B. Many menu commands may also be executed using keyboard

shortcuts. These shortcuts are listed in Smokeview’s help menu and are described in Appendix C. Visualization features not controllable through the menus may be customized by using the Smokeview preference file,

smokeview.ini, discussed in Appendix D.1.

Smokeview is written in C and Fortran 90 and consists of about 37,000 lines of code. The C portion of

Smokeview visualizes the data while the Fortran 90 portion reads in the data generated by FDS (also written in

Fortran 90). Smokeview uses the 3D graphics library OpenGL[10, 11] and the Graphics Library Utility Toolkit

(GLUT)[12]. Smokeview uses the GLUT software library so that most of the development work can be spent

implementing the visualizations rather than creating an elaborate user interface. Smokeview uses a number of

auxiliary libraries to implement image capture (GD[13, 14], PNG[15], JPEG[16]), image and general file compression (ZLIB[17]) and dialogue creation (GLUI[18]). Each of these libraries is portable running under UNIX,

LINUX and Windows 9x/2000/XP allowing Smokeview to run on these platforms as well.

1.2 Features

Smokeview is a program designed to visualize numerical calculations generated by the Fire Dynamics Simulator.

Smokeview visualizes both dynamic and static data. Dynamic data is visualized by animating particle flow (showing location and “values” of tracer particles), 2D contour slices (both within the domain and on solid surfaces)

and 3D level surfaces. 2D contour slices can also be drawn with colored vectors that use velocity data to show

flow direction, speed and value. Static data is visualized similarly by drawing 2D contours, vector plots and 3D

level surfaces. Smokeview features in more detail include:

2
Animated Isosurfaces Isosurface or 3D level surface animations may be used to represent flame boundaries,

layer interfaces or various other gas phase variables. Multiple isocontours may be stored in one file, allowing

one to simultaneously view several isosurface levels for the same variable.

Color Contours Animated 2D shaded color contour plots are used to visualize gas phase information, such as

temperature or density. The contour plots are drawn in horizontal or vertical planes along any coordinate

direction.

Animated 2D shaded color contour plots are also used to visualize solid phase quantities such as radiative

flux or heat release rate per unit area.

Animated Flow Vectors Flow vector animations, though similar to color contour animations (the vector colors

are the same as the corresponding contour colors), are better than solid contour animations at highlighting

flow features.

Particle Animations Lagrangian or moving particles can be used to visualize the flow field. Often these particles

represent smoke or water droplets.

Data Mining One can analyze and examine the simulated data by altering its appearance to more easily identify

features and behaviors found in the simulation data. One may flip or reverse the order of colors in the

colorbar. One may also click in the colorbar and slide the mouse to highlight data values in the scene.

These options may be found under Options > Shades .

The user may click in the time bar and slide the mouse to change the simulation time displayed. One use for

the time bar and color bar selection modes might be to determine when smoke of a particular temperature

enters a room.

1.3 What’s New

Multiblock Geometry Smokeview shows the multiple block geometry new in FDS 3, and gives the user control

over viewing certain features in a given mesh or block. Using the LOAD/UNLOAD > MULTI-SLICE

menu item one may now load multiple slices simultaneously. These slices are ones lying in the same plane

(within a grid cell) across multiple blocks.

Texture Mapping Jpeg, PNG or RGB image files may be applied to a blockage, vent or enclosure boundary.

This is called texture mapping. This allows one to view FDS scenes more realistically. These image files

may be obtained from the internet, a digital camera, a scanner or from any other source that generates these

file formats. Image files used for texture mapping should be “seamless.” A seamless texture as the name

suggests is periodic in both horizontal and vertical directions. This is an especially important feature when

textures are tiled or repeated across a blockage surface.

Scene Clipping It is often difficult to visualize slice or boundary data in complicated geometries due to the

number of obstructed surfaces. Interior portions of the scene may now be seen more easily by “clipping”

part of the scene away.

Scene Motion The motion dialogue box has been enhanced to more precisely control the movement and orientation of the scene. Cursor keys have been mapped to scene translation/rotation to allow easy navigation

within the scene.

Blockage Editing The Blockage Editing dialogue box has been enhanced to allow one to assign material properties to selected blockages. Comment labels found in the FDS input file may be viewed or edited. Any text

appearing after the closing “/” in an &OBST line is treated as a comment by Smokeview.

Annotating Cases Added to version 3.1 are two keywords, LABEL and TICKS to help document Smokeview

output. The LABEL keyword allows one to place colored labels at specified locations at specified times.

The TICK keyword places equally spaced tick marks between specified bounds. These marks along with

LABEL text may be used to document length scales in the scene.

3
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 links for requesting 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:\nist\fds.

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 all but the very first release of

Windows 95. Though 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. Windows 98,

2000, NT 4.0 and all later versions of Windows 95 contain the OpenGL libraries.

Most computers purchased today are perfectly adequate for running Smokeview with the caveat that additional memory should be obtained to bring the memory size up to at least 512mb in order to display results without

“swapping” to disk and hence slowing down the visualizations. For Smokeview it is more important to obtain a

fast graphics card than a fast CPU. If the computer will run both FDS and Smokeview then it is important to obtain a fast CPU as well. For example, the townhouse case found at http://fire.nist.gov/fds/samples/thouse3d.data

and consisting of over 180,000 grid cells and used in many of the Figures in this report, required 8.5 hours of CPU

time on a 2GHZ Pentium IV Windows XP system. Cases with more grid cells and longer simulation times (the

townhouse case simulated 300 seconds of smoke flow) would clearly benefit from a faster CPU and more memory

which are now becoming available.

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 menu 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 screen dumps, obtaining help etc. Menu items are described in Appendix

B.

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. Data files

may be loaded and options may be selected by clicking the right mouse button and picking the appropriate menu

item.

Smokeview opens two windows, one displays the scene and the other displays status information. Closing

either window will end the Smokeview session. Multiple copies of Smokeview may be run simultaneously if the

computer has adequate resources.

Normally Smokeview is run during an FDS run, after the run has completed and as an aid in setting up FDS

cases by visualizing geometric components such as blockages, vents, sensors, etc. One can then verify that these

modelling elements have been defined and located as intended. One may select the color of these elements using

color parameters in the smokeview.ini to help distinguish one element from another. Smokeview.ini file

entries are described in section D.1.

We cannot give recommendations for specific brands of video cards except to say that because of the intensive

graphics requirements of Smokeview they should be “high-end”. These requirements will only increase in the

future as more features are added. A video card designed to perform well for “fancy” computer games should do

well for Smokeview. Some apparent bugs in Smokeview have been found to be the result of problems found in

video cards on older computers.

4
5.0 s 10.0 s

30.0 s 60.0 s

Figure 2: Cross section of a townhouse showing first and second floor. Particle file snapshots at various times in

a simulation of a townhouse kitchen fire. These plots were generated by adding PARTICLES=.TRUE. to the

&SURF line where particles are to be emitted.

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. Visualizations produced by these data files are described

below. The format used to store each of the data files is given in Appendix D.3. The FDS input data file used to

generate the following examples may be found at http://fire.nist.gov/fds/svsamples/thouse3d.data.

3.1.1 Particle

Particle files contain the locations of tracer particles used to visualize the flow field. Particles may be colored

with various gas properties. Colors are selected from a user definable color palette defined using the COLORBAR

keyword documented in Appendix D.1. Figure 2 shows several snapshots of a developing kitchen fire visualized

using particles where particles are colored black. Sprinkler water droplets if present would have been colored

blue. Particles are stored in files ending with the extension .part and are displayed by selecting the entry from

the Load/Unload menu.

To specify particles as illustrated in Figure 2 add PARTICLES=.TRUE. to the &SURF line where particles

are to be emitted.

3.1.2 Slice

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

5
5.0 s 10.0 s

30.0 s 60.0 s

Figure 3: Slice file snapshots of shaded temperature contours at various times in a simulation. These contours

were generated by using “&SLCF PBY=1.5,QUANTITY="TEMPERATURE" /”.

part of a plane is selected when setting up the FDS input data file. Figure 3 shows several snapshots of a vertical

animated slice where the slice is colored according to gas temperature. Slice files have file names with extension

.sf and are displayed by selecting the desired entry from the Load/Unload menu.

To specify a vertical slice 1.5 m from the y = 0 boundary colored by temperature, use the line:

&SLCF PBY=1.5 QUANTITY=’TEMPERATURE’ /

Other quantities that can be specified are given in Table 1. A more complete list may be found in Ref. [4].

Animated vectors are displayed using data contained in two or more slice files. The direction and length of

the vectors are determined from the U, V and/or W velocity slice files. The vector colors are determined from the

file (such as temperature) selected from the Load/Unload menu. Figure 4 shows a sequence of vector slices

corresponding to the shaded temperature contours found in Figure 3.

To generate the extra velocity files needed to view vector animations, add VECTOR=.TRUE. to the above

&SLCF line to obtain:

&SLCF PBY=1.50,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

3.1.3 Boundary

Boundary files contain simulation data recorded at blockage or wall surfaces. Continuously shaded contours are

drawn for quantities such as wall surface temperature, radiative flux, etc. Figure 5 shows several snapshots of a

boundary file animation where the surfaces are colored according to their temperature. Boundary files have file

names with extension .bf and are displayed by selecting the desired entry from the Load/Unload menu.

A boundary file containing wall temperature data may be generated by using:

6
Table 1: Output Quantities used by Slice and Plot3D Visualizations

Quantity Description Units

DENSITY density kg/m3

TEMPERATURE gas temperature ◦C

U-VELOCITY velocity component m/s

V-VELOCITY velocity component m/s

W-VELOCITY velocity component m/s

VELOCITY velocity magnitude m/s

5.0 s 10.0 s

30.0 s 60.0 s

Figure 4: Vector slice file snapshots of shaded vector plots. These vector plots were generated by using “&SLCF

PBY=1.5,QUANTITY="TEMPERATURE",VECTOR=.TRUE. /”.

7
5.0 s 10.0 s

30.0 s 60.0 s

Figure 5: Boundary file snapshots of shaded wall temperatures. These snapshots were generated by using “&BNDF

QUANTITY="WALL TEMPERATURE"/”.

8
Table 2: Output Quantities used by Boundary File Visualizations.

Quantity Description Units

RADIATIVE FLUX radiative flux kW/m2

CONVECTIVE FLUX convective flux kW/m2

WALL TEMPERATURE wall temperature ◦C

&BNDF ’WALL_TEMPERATURE’ /

Table 2 gives other quantities that can be specified on a &BNDF line. A more complete list of quantities is given

in Ref. [4].

3.1.4 Isosurface

The surface where a quantity such as temperature attains a given value is called an isosurface. An isosurface is

also called a level surface or 3D contour. Isosurface files contain data specifying isosurface locations for a given

quantity at one or more levels. These surfaces are represented as triangles. Figure 6 shows a snapshot of an

isosurface file animation at several time steps for mixture fraction levels of 0.03 0.001. Isosurface files have file

names with extension .iso and are displayed by selecting the desired entry from the Load/Unload menu.

Isosurfaces are specified in the FDS input file (version 1.01 or higher) with the &ISOF keyword. To specify

isosurfaces for mixture fraction with values 0.03 and 0.001 as illustrated in Figure 6 use the line:

&ISOF QUANTITY=’MIXTURE_FRACTION’,VALUE(1)=0.03,VALUE(2)=0.001 /

Other quantities may be specified using values given in Table 1. A more complete list may be found in Ref. [4]

3.1.5 Plot3D

Data stored in Plot3D files use a format developed by NASA[19] and are used by many CFD programs for

representing simulation results. Plot3D files store five data values at each grid cell. FDS uses Plot3D files to

store temperature, three components of velocity (U, V, W) and heat release rate. Other quantities may be stored if

desired.

An FDS simulation will typically create Plot3D files at several specified times throughout the simulation.

Plot3D data is visualized in three ways: as 2D contours, vector plots and isosurfaces. Figure 7a 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 relative speed of the fluid flow.

The vector colors show a scalar fluid quantity such as temperature. Figure 7b shows vectors in a doorway. Note

the hot flow (red color) leaving the fire room in the upper part of the door and the cool flow (blue color) entering

fire room in the lower part of the door. Figure 8 gives an example of isosurfaces for two different temperature

levels. Plot3D data are stored in files with extension .q .

To specify a 30 second time interval between Plot3D files stored with default gas variables, add the line:

&PL3D DTSAM=30.0 /

to the FDS input file.

3.2 Visualizing Output

3.2.1 Manipulating the Scene

The scene may be rotated or translated either directly with the mouse or by using the scene movement dialogue

box illustrated in Figure 9. This dialogue box is opened from the Options > Movement menu item. Clicking

on the scene and dragging the mouse horizontally, vertically or a combination of both results in scene rotation or

translation depending upon whether Ctrl or Alt is depressed or not during mouse movement.

The modifier keys effect scene movement in the following ways:

9
5.0 s 10.0 s

30.0 s 60.0 s

Figure 6: Isosurface file snapshots of mixture fraction levels. These snapshots were generated by using “&ISOF

QUANTITY=’MIXTURE FRACTION’,VALUE(1)=0.03,VALUE(2)=0.001 /”.

a) shaded 2D temperature contour plots in a vertical plane through the fire and a horizontal

plane below the ceiling

b) shaded temperature vector plot in a vertical

plane through the doorway. The “a” key may

be depressed to alter the vector sizes. The “s”

key may be depressed to alter the number of

vectors displayed.

Figure 7: Plot3D contour and vector plot examples.

10
a) temperature isosurface at 140 ◦C b) temperature isosurface at 320 ◦C

Figure 8: Plot3D isocontour example.

Figure 9: Motion Dialogue Box. Rotate or translate the scene by clicking an “arrow” and dragging the mouse.

The Motion Dialogue Box is invoked by selecting Options > Movement

11
No modifier key depressed Horizontal or vertical mouse movement results in scene rotation parallel to the

XY or YZ plane, respectively. Note that 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 Options > Rotation . Equivalently, horizontal or vertical mouse movement

results in scene rotation about the Z or X axis, respectively.

SHIFT key depressed The shift key in Smokeview 3.0 no longer affects scene movement. It was found that

the rotation mode was not needed and could cause confusion.

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 into 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 while the ALT key is depressed.

The scene motion dialogue box may be used to move the scene in a more controlled manner. For example,

clicking on the Rotate X button in Figure 9 and dragging the mouse results in scene rotation about the X (and

only the X) axis. Similarly, clicking the mouse on the Translate Y button results in scene translation along

the Y axis.

Reset View may be used to reset the scene back to either an external, internal (to the scene), or previously

saved viewpoint.

Several new features have been added to this dialogue box in Smokeview 3.0:

Select Rotation Center A pull down list appears in multi-block cases allowing one to change the rotation

center. Therefore one could rotate the scene about the center of the entire physical domain or about

the center of any one particular mesh or block. This is handy when blocks are defined far apart.

Select how the scene moves Radio buttons have been added to allow one to specify whether the scene is

moving (world center or world center - level rotation) or whether the observer is moving (eye center). These modes may also be changed as before by toggling the “e” key. When in “eye center”

mode, several key mappings have been added, inspired by popular computer games, to allow easier

movement through the scene. For example, the up and down cursor keys allow one to move forward

or backwards in the scene while the left and right cursor keys allow one to rotate left or right in the

scene. Other keyboard mappings are described in Table 3.

Rotation Buttons Rotation buttons are now enabled or disabled as appropriate for the mode of scene motion.

For example, if “about world center - level rotations” has been selected, then the Rotate X and

Rotate eye buttons are disabled. A rotation button labelled 90 deg has been added to allow

one to rotate 90 degrees while in “eye center” mode. This is handy when one wishes to move along

a long corridor precisely parallel to one of the walls. The first click of “90 deg” snaps the view to the

closest forward or side direction while each addtional click rotates the view 90 degrees clockwise.

3.2.2 Clipping Smokeview Scenes

It is difficult to view interior portions of a scene when modelling complicated geometries. Scene clipping allows

one to hide portions of the scene by defining up to six clipping planes. All portions of the scene with “x”

coordinates smaller the “x lower” clipping plane will be hidden. Portions of the scene with “x” coordinates

larger than the “x upper” clipping plane will be hidden. The “y lower”, “y upper”, “z lower” and “z upper”

clipping planes behave similarly. These clipping planes are specified by using the clipping dialogue box which is

opened by selecting the Options > Clipping menu item. Figure 10 shows this dialogue box with the “y

lower” clipping plane activated along with the resulting clipped scene. Note that this clipped scene is the same

townhouse kitchen fire scenario used to generate various plots presented earlier in this report.

Keyboard mappings used in Smokeview 2.0 to manipulate clipping plane locations are no longer implemented.

12
Table 3: Keyboard mappings for “eye centered” scene movement

Key Description

Left/Right cursor rotate left/right

CTRL + Left/Right cursor rotate left/right but slower

ALT + Left/Right cursor slide left/right

SHIFT + Left/Right cursor rotate 90 degrees clockwise

Down/Up cursor+(CTRL slide backward/forward

CTRL + Down/Up cursor slide backward/forward but slower

ALT + Down/Up cursor slide down/up

Insert or Page Down look down

Home look level

Page Up look up

F1 decrease speed

F2 reset speed

F3 increase up

F4 look left

F5 look forward

F6 look right

Figure 10: Clipping dialogue box and corresponding clipped scene

13
Figure 11: Bounds Dialogue Box. Select a variable and a bounds type “check box/radio button”, then enter a

lower and/or upper bound. Finally, press “Reload...” or “Update” for the new bounds to take effect.

3.2.3 Setting Data Bounds in Smokeview

Normally, Smokeview determines data bounds automatically when it loads data. Sometimes, however, it is desirable to override Smokeview’s choice. This allows for consistent color shading when displaying several data files

simultaneously.

The Set Bounds... dialogue box is opened from the Options menu. Each file type in Figure 11

(slice, particle, Plot3D etc) has a set of “radio buttons” for selecting the variable type that data bound are to be

applied too. These variable types are determined from the files generated by FDS and are automatically recorded

in the .smv file. The data bounds are set in a pair of edit boxes. Radio buttons adjacent to the edit boxes determine

what type of bounds should be applied.

The Plot3D portion of the bounds dialogue box has an addtional radio button used to chop or hide data.

This feature is illustrated in Figure 12 where those data vales less than 380◦Care chopped or not drawn.

New Bounds Dialogue Box features in Smokeview 3.0 are an option to show “char” (if activated temperature

boundary files are colored black wherever the temperature exceeds the materials ignition temperature) and options

to select contour data types (shaded, stepped and line contours) for PLOT3D display.

3.2.4 Plot3D Viewing Options

Plot3D files are more complicated to visualize than time dependent files 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 six1

different simulated quantities, view flow vectors and iso or 3D contours. Plot3D file visualization is initiated by

1The 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.

14
Figure 12: Ceiling jet visualization created by “chopping data” below a specified temperature by using the

Bounds Dialogue Box as illustrated in Figure 11.

selecting the desired entry from the Load/Unload Plot3D sub-menu and as with time files one may change

color and transparency characteristics.

2D contours Smokeview displays a 2D contour slice midway 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. To view a contour along

either the X or Z axis, depress the x or z keys respectively. Depressing the x, y or z keys while the contour is

visible will cause it to be hidden. 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.

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.

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 default. If the “s” is depressed then every other vector is skipped.

3.3 Examining Input

The previous section describes how Smokeview is used to visualize FDS output. This section explains how

Smokeview may be used to setup FDS input files.

One of the most difficult tasks in setting up an FDS input file is defining the geometry (blockages, vent

locations etc) properly. Smokeview may be used to debug FDS input files by making short runs and observing

whether blockages, vents and other geometric features of a run are located correctly. Blockages may then be

created or changed. This is done with the “Edit Blockage” dialogue box called from the Option menu . The

next two sections indicate how these tasks may be performed.

3.3.1 Debugging

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

file is named testcase1.data.

15
1. Set the stop time to 0.0 using TWFIN=0.0 on the &TIME line. This causes FDS to read the input file and

create a .smv file without performing lengthy startup calculations.

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

fds3 < 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 Load/Unload > Reload testcase1.smv menu item.

4. Make corrections if necessary. Use the BLOCK COLOR or RGB option2 of the OBST keyword to more easily

identify blockages to be edited. For example, to change a blockage’s color to red use:

&OBST XB=0.0,1.0,0.0,1.0,0.0,1.0 BLOCK_COLOR=’RED’ /

or

&OBST XB=0.0,1.0,0.0,1.0,0.0,1.0 RGB=1.0,0.0,0.0 /

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.

3.3.2 Examining and/or Editing Blockages

Normally Smokeview is run during or after an FDS calculation. Smokeview is also used as an aid in setting up

FDS cases by visualizing geometric components such as blockages, vents, sensors, etc.

Blockages may be examined or changed by selecting Options > Edit Geometry which opens up the

dialogue box illustrated in Figure 13. New in Smokeview 3.0 are text edit boxes allowing one to define comments

(any text to the right of the closing “/” on an &OBST line and pull down menus for linking surfaces (&SURF

lines) to obstructions. The surface choices are obtained from the input file or the database file if one is specified

in the input file.

One may associate one, three or six surfaces with an obstruction. If the “3 wall” radio button is selected

then materials for the ceiling (upper surface), walls (vertical surfaces) and floor (lower surface) may be specified.

The “color” check box allows the inputted or default color (manilla) to be displayed on blockage surfaces.

Associating unique colors with each surface one can quickly determine whether blockages are defined with

the proper surfaces. One can then verify that these modelling elements have been defined and positioned as

intended.

The blockage editor works on one block or mesh at a time. For multi-block cases, use the pull-down menu to

select the desired mesh or simply click on a blockage in the mesh to switch to that mesh. The pull-down menu is

necessary for meshes without blockages.

Position coordinates entered into the text boxes are “snapped” to the nearest grid line. Materials appearing

under “Surface Type” come from those materials defined in either the input data file or the database file.

Either 1, 3 or 6 wall properties can be entered by selecting the appropriate radio button.

The following is a short tutorial on how to create the roomfire.data example case distributed with FDS

and Smokeview using the Blockage edit dialogue box to create the blockages. The wall and door dimensions are

diagrammed in Figure 14. An open vent is located on the front wall (Y = 0) between X = 5.5 and X = 6.5 and

between elevations Z = 1.0 and Z = 2.0.

The results of each step are illustrated in Figure 15.

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

BLACK. The RGB keyword uses three floating point inputs ranging from 0.0 to 1.0 to specify the red, green and blue components of color.

16
Figure 13: Blockage Edit Dialogue Box. Click on ‘New’ to create a new blockage or click on an existing blockage

in the Smokeview scene to change its size or location. Change the size or location by entering blockage bounds

directly or clicking on an ‘arrow’ and/or direction buttons.

Step 1 - Create base case: Start by adding the following lines to a file named case1.data.

&HEAD CHID=’roomfire2b’,TITLE=’Sample fire in multiple room layout’ /

&GRID IBAR=48, JBAR=24, KBAR=12 /

&PDIM XBAR=9.6,YBAR=4.8,ZBAR=2.4 /

&TIME TWFIN=0.0 /

&MISC SURF_DEFAULT=’SHEET METAL’,

DATABASE=’c:\nist\fds\database3\database3.data’

REACTION=’POLYURETHANE’ /

This defines the geometry, database file location and default surface and reaction. Run this file with FDS by

typing:

fds < case1.data

The resulting output is illustrated in Figure 15a.

Step 2 - Adding Blockages: The next step is to add blockages for the fire and the two walls. Assume that the

blockage for the fire has dimension 0.6 m×0.6 m×0.4 m and is located at the front, left, bottom corner. Open

the Blockage Edit Dialogue Box and click on the New button. This creates a new blockage one grid cell in size

located in the lower, left, front part of the simulation domain. Expand the blockage to the desired size by either

1) typing in the proper dimension into the edit boxes or by 2) clicking in the stretch/move arrows to stretch/move

the blockage to the proper location/size.

Repeat this process eight more times. Five times for the first wall and three times for the second wall using

dimensions obtained from Figure 14. Separate blockages are needed for the wall portions to the left, above and to

the right of each door. Unfortunately, the Smokeview 2.0 technique of removing pre-existing blockages has not

been implemented in the re-written multi-block blockage editing code.

Each wall is 0.2 m thick. The first wall is 9.6 m×2.4 m and is located in the middle of the short (‘Y’) side

from 2.4 m to 2.6 m. This wall has two doors.

The second wall is 4.8 m×2.4 m and is located in the middle of the long (‘X’) side from 4.8 to 5.0 m. The

wall dimensions and door locations are illustrated in Figure 14. The dotted lines indicate one way of partitioning

the walls into separate blockages.

Again, these blockages may be entered by either 1) typing in the proper dimension into the edit boxes or 2)

clicking in the stretch/move arrows to stretch/move the blockage to the proper location/size.

17
Figure 14: Layout for Sample FDS Case. All units are in meters.

18
The &OBST lines for the “dotted” regions in Figure 14 are contained in the file generated by clicking the

Update button and are given by:

&OBST XB=0.0, 0.6, 0.0, 0.6, 0.0, 0.4/ burner

&OBST XB=0.0, 3.0, 2.4, 2.6, 0.0, 2.4/ Wall 1

&OBST XB=3.0, 4.0, 2.4, 2.6, 2.0, 2.4/ Wall 1

&OBST XB=4.0, 7.0, 2.4, 2.6, 0.0, 2.4/ Wall 1

&OBST XB=7.0, 8.0, 2.4, 2.6, 2.0, 2.4/ Wall 1

&OBST XB=8.0, 9.6, 2.4, 2.6, 0.0, 2.4/ Wall 1

&OBST XB=4.8, 5.0, 0.0, 3.6, 0.0, 2.4/ Wall 2

&OBST XB=4.8, 5.0, 3.6, 4.6, 2.0, 2.4/ Wall 2

&OBST XB=4.8, 5.0, 4.6, 4.8, 0.0, 2.4/ Wall 2

The resulting FDS run is illustrated in Figure 15b.

Step 3 - Defining Wall Materials Run Smokeview case2.smv and open up the Options > Edit Geometry

dialogue box. Click on the wall going across the long side of the structure. Notice that the dialogue box indicates

that this wall is SHEET METAL (the default for this case). Click on SHEET METAL and notice that a number of

different material choices appear. These choices were obtained from the database file found on the &MISC line.

Select OAK for all five wall segments along the long side of the structure and PINE for all three wall segments

along the short side of the structure. Finally, click on the burner and select FIRE BRICK .

Before closing the Options > Edit Geometry dialogue box it is important to click on the UPDATE

button or your edit changes will not be written out to a file.

Rename the updated file to case3.data (at a command line or command shell) and run FDS3 on it. The &OBST

lines as they were modified in this step should look like:

&OBST XB=0.0,0.6,0.0,0.6,0.0,0.4 SURF_ID=’FIRE BRICK’/ burner

&OBST XB=0.0,3.0,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=3.0,4.0,2.4,2.6,2.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=4.0,7.0,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=7.0,8.0,2.4,2.6,2.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=8.0,9.6,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=4.8,5.0,0.0,3.6,0.0,2.4 SURF_ID=’PINE’/ Wall 2

&OBST XB=4.8,5.0,3.6,4.6,2.0,2.4 SURF_ID=’PINE’/ Wall 2

&OBST XB=4.8,5.0,4.6,4.8,0.0,2.4 SURF_ID=’PINE’/ Wall 2

The results are illustrated in Figure 15c.

Step 4 - Completing the case To complete the case add input lines for vents (&VENT commands) and keywords

for various output files. This file is given by:

&HEAD CHID=’case4’,TITLE=’Sample fire in multiple room layout’ /

&GRID IBAR=48, JBAR=24, KBAR=12 /

&PDIM XBAR=9.6,YBAR=4.8,ZBAR=2.4 /

&TIME TWFIN=20. /

&MISC SURF_DEFAULT=’SHEET METAL’,

DATABASE=’c:\nist\fds\database3\database3.data’

REACTION=’POLYURETHANE’ /

&OBST XB=0.0,0.6,0.0,0.6,0.0,0.4 SURF_ID=’FIRE BRICK’/ burner

&OBST XB=0.0,3.0,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=3.0,4.0,2.4,2.6,2.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=4.0,7.0,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=7.0,8.0,2.4,2.6,2.0,2.4 SURF_ID=’OAK’/ Wall 1

&OBST XB=8.0,9.6,2.4,2.6,0.0,2.4 SURF_ID=’OAK’/ Wall 1

19
&OBST XB=4.8,5.0,0.0,3.6,0.0,2.4 SURF_ID=’PINE’/ Wall 2

&OBST XB=4.8,5.0,3.6,4.6,2.0,2.4 SURF_ID=’PINE’/ Wall 2

&OBST XB=4.8,5.0,4.6,4.8,0.0,2.4 SURF_ID=’PINE’/ Wall 2

&SURF ID=’BURNER’,HRRPUA=1000. /

&VENT XB=0.00,0.60,0.00,0.60,0.40,0.40, SURF_ID=’BURNER’ /

&VENT XB=5.50,6.60,0.00,0.00,1.00,2.00, SURF_ID=’OPEN’ /

&VENT XB=0.00,9.60,0.00,4.80,0.00,0.00, SURF_ID=’CARPET’ /

&PART QUANTITY=’TEMPERATURE’,NPSAM=2/

&ISOF QUANTITY=’MIXTURE_FRACTION’,VALUE(1)=0.03,VALUE(2)=0.001 /

&SLCF PBX=3.60,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&SLCF PBX=7.60,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&SLCF PBY=0.40,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&SLCF PBY=1.40,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&SLCF PBY=4.00,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&SLCF PBZ=2.20,QUANTITY=’TEMPERATURE’,VECTOR=.TRUE. /

&BNDF QUANTITY=’WALL_TEMPERATURE’ /

&PL3D DTSAM=20. /

This file is also located at http://fire.nist.gov/fds/svsamples/case4.data and illustrated in Figure 15c. Figure

15d shows the sample case run to 10 seconds with a mixture fraction isosurface representing a layer of constant

smoke density.

3.4 Documenting Output

3.4.1 Making Movies

A movie can be made of a Smokeview animation by converting the visualized scene into a series of PNG or JPEG

files, one file for each time step and then combining the individual images together into one movie file. More

specifically:

1. Set up Smokeview by orienting the scene and loading the desired data files.

2. Select the Options/Render menu and pick the desired frame skip value. The more frames you include

in the animation, the smoother it will look. Of course more frames results in larger file sizes. Choose fewer

frames if the movie is to appear on a web site.

3. Use a program such as the Antechinus Media Editor available at http://www.c-point.com to assemble the

JPEGS or PNGS rendered in the previous step into a movie file.

The default Smokeview image size is 640×480 . This size is fine if the movie is to appear in a presentation

located on a local hard disk. If the movie is to be placed on a web site then care needs to be taken to insure that the

generated movie file is a reasonable size. Two suggestions are to reduce the image size to 320×240 or smaller

by modifying the WINDOWWIDTH and WINDOWHEIGHT smokeview.ini keywords and to reduce the number of

frames to 300 or less by skipping intermediate frames via the OPTIONS/RENDER menu.

(New in version 3.1) Sometimes when copying or “capturing” a Smokeview scene it is desirable, even necessary, to have a margin around the scene. This is because the capturing system does not include the entire scene

but itself captures an indented portion of the scene. To indent the scene, either 1) press the “h” key or 2) select

the Option > Viewpoint > Offset Window menu item. The default indentation is 45 pixels. This may be

changed by adding/editing the WINDOW OFFSET keyword in the smokeview.ini file.

20
a) defined physical and grid dimensions b) defined wall and burner blockages

c) defined surface materials and added vent d) isosurface at 10 seconds

Figure 15: Intermediate steps for roomfire construction example.

21
3.4.2 Annotating the Scene (New in version 3.1)

Smokeview rendered JPEG or PNG image files may be annotated with any package that edits these types of

files. Tick marks and label annotation has been added to Smokeview version 3.1. These annotations can be

placed within the 3D scene and moved around as the scene is moved. This would be difficult to duplicate

with an external image editor. In addition, axis labels are displayed, if desired, by selecting Show/Hide

> Labels > Axis labels .

The current release of FDS places tick marks and labels documenting the scene dimensions. To replace or

customize these annotations add the TICK keyword to a .smv file using the following format:

TICKS

xb yb zb xe ye ze nticks

ticklength tickdir r g b tickwidth

where xb, yb, and zb are the x, y and z coordinates of the first tick; xe, ye and ze are the x, y and z

coordinates of the last tick and nticks is the number of ticks. The coordinate dimensions are in physical units,

the same units used to set up the FDS geometry. The parameter ticklength specifies the lengh of the tick in

physical units. The parameter tickdir specifies the tick direction. For example 1(-1) places ticks in the positive(negative) x direction. Similarly, 2(-2) and 3(-3) place ticks in the positive(negative) y and positive(negative)

z directions.

The color parameters r, g and b are the red, green and blue components of the tick color each ranging from

0.0 to 1.0. The foreground color (white by default) may be set by setting any or all of the r, g and b components to

a negative number. The tickwidth parameter specifies tick width in pixels. Fractional widths may be specified.

The LABEL keyword allows a text string to be added within a Smokeview scene. The label color and start

and stop appearance time may also be specified. The format is given by

LABELS

x y z r g b tstart tstop

label

where x, y, z is the label location in physical coordinates, r, g, b are the red, green and blue color

components ranging from 0.0 to 1.0. Again, if a negative value is specified then the foreground color will be used

instead (white is the default). The parameters, tstart and tstop when the label is visible. The text string is

specified on the next line (label).

Figure 16 shows how the LABEL and TICKS keywords can be used together to create a “ruler” with major

and minor tick marks. These ticks and labels were created using:

TICKS

0.0 0.0 0.0 8.0 0.0 0.0 5

0.5 -2.0 -1. -1.0 -1.0 4.0

TICKS

1.0 0.0 0.0 9.0 0.0 0.0 5

0.25 -2.0 -1. -1.0 -1.0 4.0

TICKS

0.0 0.0 0.0 0.0 0.0 2.0 3

0.5 -1.0 -1. -1.0 -1.0 4.0

TICKS

0.0 0.0 0.0 0.0 4.0 0.0 5

0.5 -1.0 -1. -1.0 -1.0 4.0

LABEL

0.0 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

0

LABEL

2.0 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

2

LABEL

4.0 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

22
Figure 16: Annotation example using the TICKS and LABEL keword.

4

LABEL

6.0 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

6

LABEL

8.0 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

8

LABEL

9.5 -0.6 0.0 -1.0 0.0 0.0 0.0 20.0

m

4 Summary

This report documented the use of Smokeview version 3.0/3.1 to visualize calculations generated by the NIST Fire

Dynamics Simulator. Various visualization techniques such as animated tracer particle flow, contour plots and

isosurfaces were implemented to enable the user to better understand fire and smoke behavior under investigation.

23
A 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 -help

without any arguments which results in output similar to:

NIST Smokeview 3.1 - Apr 7 2003

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

Usage:

smokeview casename -points m -frames n -ini -part -nopart -stereo

where

casename = project id (file names without the extension)

m = maximum number of particles. Default=50000000

n = maximum number of particle frames. Default=5001

-ini = output default smokeview parameters to smokeview.ini

-part = load particle file if present

-nopart = do not load particle file

-stereo = activate stereo mode (if supported)

The -nopart option is used to prevent a particle file from being loaded at startup. The -points and

-frames options are 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. The -benchmark option causes Smokeview to produce precise timings by outputting frame

rates based upon one cycle through the timing loop rather than using moving averages. The -stereo option

may used to access stereo hardware (often called quad buffering) if it is available.

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. Smokeview’s pop-up

menus are implemented with GLUT[12], the graphics library utility toolkit. The user interacts with Smokeview

via 1) menus, 2) keyboard shortcuts and 3) the preference file (smokeview.ini or casename.ini).

24
Figure 17: Main Menu

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

options as illustrated in Figure 17 are: Load/Unload Show/Hide , Options , Tour , Reset ,

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

sections.

B.1 Main Menu Items

Load/Unload This menu option allows one to load or unload particle, iso-surface, vector slice, slice, Plot3D

or boundary files. These time dependent files may be viewed simultaneously, but not concurrently

with the time independent Plot3D files. However, one boundary or one Plot3D file per block may be

viewed at a time. Multiple slices for the same variable may be viewed simultaneously. 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.

Options This menu allows one to specify various smokeview options such as specifying frame rates, dumping

the screen to a PNG or JPEG file, changing font sizes, selecting dialogue boxes etc.

Tour Causes the scene to rotate about its center.

Reset Resets the simulation scene back to an alternate view. The three choices are 1) exterior view, 2)

interior view and 3) saved view. A viewpoint may be saved using the Viewpoint sub-menu of

the Options menu. If a time file 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.

Help Displays a list and explanation of keyboard equivalent commands.

Quit Quit Smokeview.

B.2 Load/Unload

Six types of files may be visualized with Smokeview. These files are loaded using the LOAD/UNLOAD menus

as illustrated in Figure 18. They are particle, vector slice, slice, boundary, isosurface and Plot3D files. Note that

25
Figure 18: Load/Unload Menu

vector slice animations use two or more slice files to display the animated vector slices. 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. To hide a data file, select the Show/Hide

menu option corresponding to the file type to be hidden.

The Smokeview .smv file contains information about all data files appearing in the Load/Unload menu

item. The FDS field modelling software creates this file. (See Appendix D.2 for documentation on the format of

this file).

The character “*” occurring 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.

Open Smokeview (.smv) This menu item allows one (on the PC) to use a dialogue box to open other FDS

cases (.smv) files.

Isosurface File (.iso) This menu item gives the name of all isosurface files and also the option to unload

the currently loaded isosurface file.

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

currently loaded particle file.

Vector Slice File (.sf) This menu item gives the name of all slice files that have one or more associated U,

V and/or W velocity slice files. These slice files must be defined for the same region (or slice) in the

simulation.

Multi-Vector Slice File (.sf) This menu item allows one to load all vector slices occurring in one plane

(within a grid cell) simultaneously. It also gives the option to unload the currently loaded multislices.

Slice File (.sf) This menu item gives the name and location of all available slice files and also the option to

26
unload the currently loaded slice files.

Multi-Slice File (.sf) This menu item allows one to load all slices occurring in one plane (within a grid

cell) simultaneously. It also gives the option to unload the currently loaded multi-slices.

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.

Preference File (.ini) The INI 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.

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

Show File Names Load and Unload menus are now specified using the location and type of visual to be

displayed. Sometimes, however, it is useful to include the file names which is what this menu item

provides.

Reload This menu item allows one to reload files at intervals of 1, 5 or 10 minutes. This is useful when

using Smokeview to display a case that is currently running in FDS.

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 (thermocouples,

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

The geometry menu is illustrated in Figure 19.

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.

27
Figure 19: Geometry Menu

Floor Show or hide the floor.

Ceiling Show or hide the ceiling.

Vents Show or hide the vents.

Walls Show or hide the walls.

Show All Show all geometric features described above.

Hide All Hide all geometric features described above.

B.3.2 Animated Surface

An isosurface is represented in Smokeview as a collection of triangles. Each triangle consists of three edges and

three vertices.

Solid Display the isosurface by shading the triangles.

Outline Display the isosurface by only showing the triangle edges.

Points Display the isosurface by only showing the triangle vertices.

“quantity” levels Display the desired isosurface level (when more than one isosurface is stored in an isosurface file).

Smooth Display the isosurface using smoothed vertex normals.

B.3.3 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.4 Boundary

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

28
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.5 Animated Vector Slice

Toggle the visibility of the animated vector slice file.

B.3.6 Animated Slice

Toggle the visibility of the animated slice file.

B.3.7 Plot3D

2D Contours

Solution Variables A Plot3D data file contains five solution variables. If one or more of the velocity components denoted u, v and w are present in the Plot3D file then speed, calculated using √

u

2 +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)

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.

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.

Solution Value 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.8 Heat detectors, Sprinklers, Thermocouples

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

29
Figure 20: Label Menu

B.3.9 Textures

Toggle the visibility of each or all textures.

B.3.10 Labels

The label menu is illustrated in Figure 20

Color Bars, Time Bars, Title, Axis, Frame Rate, Time Label, Frame label, Block label, Memory Load, Text Labels

Show or hide the individual scene element.

Show All Show all scene elements.

Hide All Hide all scene elements.

B.4 Options

The option menu is illustrated in Figure 21 and detailed below.

B.4.1 Shades

The shades menu is illustrated in Figure 22.

Flip Background 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.

Flip Colorbar Reverse the order of the colors displayed in the colorbar.

Cycle Colorbar Cycle the colors in the colorbar.

Reset Colorbar Return the colorbar to the original display.

30
Figure 21: Option Menu

Figure 22: Shades Menu

31
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.4.2 Units

Select alternate temperature or velocity units. The UNIT keyword described in Appendix D.1 may be used to

incorporate additional unit changes into Smokeview.

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

World Centered - Level Rotation As expected, same as World Centered but with level rotations.

B.4.4 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 and the graphics card is unable to

draw the scene sufficiently fast. The unlimited menu item allows one to display frames as rapidly as the

graphics hardware permits. The Real Time menu item allows one to draw frames so that the simulation time

matches real time. This option has been modified in Smokeview 3.0 to skip frames if necessary in order to display

the frames that are left in real time. 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.

B.4.5 Render

The render menu, illustrated in Figure 23, allows one to create PNG or JPEG image files of the currently displayed scene. The graphics library, GD 2.0.7, was used to create the rendered versions. GD 1.0 is documented

in reference [13, Appendix 4]. GD 2.0.7 now creates images using “full color” allowing for more realistic scene

representations eliminating the color banding that occurred with the previous version because of the limited number (256) of colors used to represent images. Due to patent disputes, GD 2.0.7 has dropped support for the GIF

file format and uses JPEG or PNG instead.

The Render sub-menus allow one to specify an integer between 1 and 20 indicating the number of frames

between rendered images. This allows one to generate 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. Rendering may be stopped by selecting Cancel .

The keyboard shortcut for the render option is r.

B.4.6 Viewpoint

This option allows one to save the location and orientation relative to the observer of the scene.

(New in version 3.1)The Window Offset menu item allows one to indent the scene for use with window

capturing.

32
Figure 23: Render Menu

B.4.7 Font Size

This option allows one to display text in either a normal or a large font.

B.4.8 Aperture

This option allows one to change the perspective used to display the scene which is equivalent to changing the

focal length of a camera lens.

B.4.9 Stereo 3-D

Provides stereo 3-D output on systems equipped with supported video cards. Stereo 3-D requires a computer

graphics card, monitor, software drivers and shuttered glasses. This option only appears if Smokeview is started

from the command line using the ‘‘-stereo’’ command line option and if a video card supporting quad

buffering is supported.

B.4.10 Clip Geometry

Open the dialogue box for clipping the geometry allowing one to see past exterior portions of the scene.

B.4.11 Edit Geometry

Open the dialogue box for editing FDS blockages.

B.4.12 Movement

Open the dialogue box for controlling scene movement. To use the movement arrows, click and hold the mouse

in one of the arrows then move the mouse to achieve the desired movement.

33
B.4.13 Set Bounds

Open the dialogue box for specifying data bounds.

C Keyboard Shortcuts

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

h (New in version 3.1)Toggle window indentation, for use with window caputring.

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

k Toggle the visibility of the time bar.

m Switch between blocks in a case that has more than one block (or mesh).

o Reset a time dependent animation to the initial time.

p Show the next variable in the Plot3D data set.

q Switch between blockage views. These views are blocks that are aligned on grid lines, blocks as

specified by the user (in the .data file) and blocks as generated by a CAD (computer aided drawing)

package.

r Render the current scene as a JPEG or a PNG 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.

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.

w Toggle window clipping on and off. If window clipping is on then the x/X, y/Y, z/Z keys may be

used to clip the scene along the min/max x, y and z axes respectively. The “<” and “>” keys are

used to control the location of the selected clipping plane by decreasing or increasing the plane

location respectively.

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

Left/Right Cursor When the eyeview mode is eye centered then these keys rotate the scene to the left or

right otherwise they 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.

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

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:\nist\fds\smokeview.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:\autoexec.bat file where dir is the directory where the global preference 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 preference

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 is 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

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

AMBIENTLIGHT Sets the color used for specifying ambient light. (default: 0.6 0.6 0.6)

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 0.8 4.0)

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.

COLORBARFLIP Specifies whether the colorbar is flipped (1) or not flipped (0) (default: 0).

DIFFUSELIGHT Sets the color for specifying diffuse light (default: 0.5 0.5 0.5).

FLIP Specifies whether to flip (1) or not to flip (0) the foreground and background colors. By default the

background color is black and the foreground color is white. Setting FLIP to 1 has the effect of

36
having a white background and black foreground. (default: 0).

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

ISOCOLORS Colors and parameters used to display animated isocontours. Default:

ISOCOLORS

10.000000 0.800000 : shininess, transparency

0.700000 0.700000 0.700000 : specular

3

0.960000 0.280000 0.000000

0.750000 0.800000 0.800000

0.000000 0.960000 0.280000

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)

TIMEBARCOLOR Sets the color used to visualize the timebar. (default: 0.6 0.6 0.6)

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

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 lines3in pixels. (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 distance4animated slices are drawn from adjacent solid surfaces. (default:

0.10)

SMOOTHLINES Specifies whether lines should be drawn (1) or not drawn (0) using anti-aliasing (default:

1).

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)

3Except lines used to draw vents

4distance is relative to the maximum grid cell width

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

WINDOWOFFSET Defines a margin offset around the Smokeview scene for use when capturing images to

video. (default: 45)

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 boundary frames in a visualization. To load boundary data between 20 and 150 seconds use:

T_BOUNDARY

1 20. 1 150.

(default: 0 1.0 0 0.0)

T ISO Defines the minimum and maximum times used to include isosurface frames in a visualization. To

load isosurface data between 20 and 150 seconds use:

T_ISO

1 20. 1 150.

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

load particle data between 20 and 150 seconds use:

T_PARTICLES

1 20. 1 150.

T SLICE Defines the minimum and maximum times used to include slice frames in a visualization. To load

slice data between 20 and 150 seconds use:

T_SLICE

1 20. 1 150.

38
(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)

The V BOUNDARY keyword has an optional parameter allowing one to specify which type of

data the bounds should apply to. For example, to specify boundary file bounds for temperature (30.0

◦C, 600.0 ◦C) use:

V_BOUNDARY

1 30.000000 1 600.000000 TEMP

where TEMP is the Smokeview colorbar labels displayed when showing the boundary file.

These suffixes are added automatically when the Bounds dialogue box is used to set data

bounds.

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.

To cause Smokeview to set the minimum and maximum data values to for the first quantity

(usually temperature) to 20 and 600 use:

V_PLOT3D

5

1 1 20.0 1 600.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 integer “1” occurring before the “20” or “600” causes Smokeview to use the next number as a

minimum or maximum value respectively otherwise if “0” is specified then Smokeview ignores the

subsequent min/max value.

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 contour5

levels smaller than 20 or contours greater than 600. The Plot3D bound line 1 2 360.0

1 420.0 indicates that temperatures below 360 ◦Care not drawn and that temperatures above

5This is true for “stepped” or discrete contours. If “continuous” contours are drawn, then “2” and “1” have the same effect.

39
420 ◦Care drawn with the “highest” color (black in black and white mode, red in color mode).

This bound line could also be implemented with the “Set Bounds” dialogue box as illustrated in

Figure 11 resulting in a contour plot as illustrated in Figure 12.

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)

The V SLICE keyword has an optional parameter allowing one to specify which type of data

the bounds should apply to. For example, to specify separate slice file bounds for temperature (30.0

◦C, 600.0 ◦C) and the U component of velocity (-1.0 m/s and 1.0 m/s) use:

V_SLICE

1 30.000000 1 600.000000 TEMP

V_SLICE

1 -1.0 1 1.0 U-VEL

where TEMP and U-VEL are the Smokeview colorbar labels displayed when showing the slice file.

These suffixes are added automatically when the Bounds dialogue box is used to set data

bounds.

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)

ISOFRAMESTEP Defines the number of intervals or steps between loaded isosurface 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)

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

40
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 per cent 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.

APERTURE Specifies the viewing angle used to display a Smokeview scene. Viewing angles of 30, 45, 60,

75 and 90 degrees are displayed when APERTURE has the value of 0, 1, 2, 3 and 4 respectively.

(default: 2)

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)

BLOCKLOCATION Specifies the location or method used to draw blockages. Blockages are drawn either

snapped to the nearest grid (5), drawn at locations as specified in the FDS input file (6) or drawn as

specified in a compatible CAD package (7). A program used to convert DXF formatted CAD files

to files compatible with FDS and Smokeview is available at http://fire.nist.gov/fds/refs/tools.html

(default: 5)

CLIP Specifies the near and far clipping plane locations. Dimensions are relative to the longest side of an

FDS scene. (default: 0.001 3.000)

CULLFACES Hide (1) or show (0) the back side of various surfaces.

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)

FONTSIZE Specifies whether small (0) or large (1) fonts should be used to display text labels. (default: 0)

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

(essentially unlimited))

MSCALE Specifies how dimensions along the X, Y and/or Z axes should be scaled. (default: 1.0 1.0 1.0)

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)

P3DSURFACETYPE Specifies how Plot3D isosurfaces should be drawn. If P3DSURFACETYPE is set to

1 then Plot3D isosurfaces are drawn using shaded triangles. If P3DSURFACETYPE is set to 2 or 3

then Plot3D isosurfaces are drawn using triangle outlines and points respectively. (default: 1)

P3DSURFACESMOOTH When drawing Plot3D isosurfaces using shaded triangles, this option specifies

whether the vertex normals should be averaged (P3DSURFACESMOOTH set to 1) resulting in

smooth isosurfaces or not averaged resulting in isosurfaces that have sharp edges (P3DSURFACESMOOTH

set to 0). (default: 1)

41
RENDERFILETYPE Specifies whether PNG (RENDERFILETYPE set to 0) or JPEG (RENDERFILETYPE set to 1) should be used to render images. (default: 1)

SHOWAXISLABELS Specifies whether axis labels should be drawn (1) or not drawn (0) drawn. (default:

0)

SHOWBLOCKLABEL Specifies whether a label identifying the active block should be drawn (1) or not

drawn (0). (default: 1)

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

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

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)

SHOWFRAME Specifies whether the frame surrounding the scene should be drawn (1) or not drawn (0).

(default: 1)

SHOWFRAMELABEL Specifies whether the frame number 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:

0)

SHOWMEMLOAD Specifies (when run on a PC) whether a label giving the memory used should be drawn

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

SHOWNORMALWHENSMOOTH Specifies that smooth blocks should be drawn as normal blocks (1) or

drawn as smooth blocks (0). (default: 0)

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)

SHOWTIMELABEL Specifies whether the time label 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)

SHOWVENTS Specifies whether vents 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)

SURFINC Smokeview allows one to display two Plot3D iso-surfaces simultaneously. The SURFINC parameter specifies the interval between displayed Plot3D surface values. (default: 0)

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

colors(1). (default: 1)

UNIT This keyword defines how to calculate colorbar label values for non-default units. Note that in the

following example all text to the right of the ‘//‘ characters is not part of the keyword but is used to

explain the format.

default:

UNIT

temperature // text appearing in smokeview unit menu

1 // number of FDS variables that have temperature units

temp // FDS variable, appears in colorbar heading

3 1 // number of units, default unit number

42
C // first unit

1.0 0.0 // newunitval = 1.0*oldunitval + 0.0

F // second unit

1.8 32.0

K // third unit

1.0 273.15

UNIT

velocity // text appearing in smokeview unit menu

4 // number of FDS variables that have velocity units

U-VEL // first variable

V-VEL // second variable

W-VEL // third variable

Speed // fourth variable

3 1 // number of units, default unit number

m/s

1.0 0.0

mph

2.236932 0.0

f/s

3.280833 0.0

USEVIEWPOINT Specifies whether the stored viewpoint parameters should (1) or should not (0) be used

to restore the viewpoint of a scene. (default: 0)

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)

VIEWPOINT Specifies the internal Smokeview parameters used to record a scene’s viewpoint and orientation. This parameter is set automatically by Smokeview when a .ini file is created. (default: none)

XYZCLIP Specifies clip planes in physical coordinates. There are six clipping planes, a minimum and

maximum X, a minimum and maximum Y, a minimum and maximum Z. Each clipping plane may

be used or not. The first parameter is 1 or 0 and specifies whether clipping is turned on or off. The

next three lines specify clipping parameters for the X, Y and Z axes. Each line has the format

minflag min-clipval maxflag max-clipval

where the two flags, minflag and maxflag are 1 if turned on or 0 if turned off. Clipping is

specified with the clipping dialogue box found under the OPTIONS menu item. (default:

0

0 0.0 0 0.0

0 0.0 0 0.0

0 0.0 0 0.0

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 text file

consisting of a set of KEYWORDs followed by DATA describing the FDS case’s geometry, data file names and

contents, sensor information etc.

43
D.2.1 Geometry Keywords

GRID This keyword specifies the number of grid cells in the X, Y and Z directions. For example,

GRID

10 20 30

specifies that there are 10, 20 and 30 grid cells in the X, Y and Z directions respectively.

PDIM This keywords specifies the physical length of the simulation domain in the X, Y and Z directions.

For example,

PDIM

6.0 12.0 5.0

specifies that the length of the X, Y and Z directions is 6.0, 12.0 and 5.0 m respectively.

HIDE OBST This keyword specifies when a blockage should be opened. For example,

HIDE_VENT 10 120.1

specifies that the tenth blockage should be opened at 120.1 seconds. This keyword is automatically

added to the .smv file by FDS version 2.0 . This (and the OPEN VENT, CLOSE VENT) keyword

may be added by hand to FDS version 1.0 files.

OBST This 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, jb2, 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:

read(5,*)nx

do i = 1, nx

read(5,*)idummy

end do

do i = 1, nx

read(5,*)xplt(i)

end do

44
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, jv2, kv1, kv2 are integer arrays containing vent coordinates.

OPEN VENT(CLOSE VENT) These keywords specify when a vent should be opened(closed). For example,

CLOSE_VENT

3 15.6

specifies that the third vent should be closed at 15.6 seconds.

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.

INPF The INPF keyword specifies a file containing a copy of the FDS input file.

ISOF The ISOF keyword defines the .iso file name along with character labels used to describe the data

contents of the isosurface file.

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

data contents of the particle file.

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

contents for each Plot3D variable.

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

contents of the slice file.

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:

45
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

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 and ztherm are the

x, y and z coordinates of the thermocouples.

46
D.2.4 Miscellaneous Keywords

ENDIAN The ENDIAN keyword defines whether a big or little endian6system 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 parameters 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.

TITLE1/TITLE2 The TITLE1 and TITLE2 keywords allow one to specify extra information documenting

a Smokeview case. These keywords and associated labels are added by hand to the smokeview

(.smv) file using the format:

TITLE1

first line of descriptive text

TITLE2

second line of descriptive text

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

Smokeview visualizes Fire Dynamics Simulator data using isosurface, 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 statements 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 Isosurface File Format

Isosurface files are used to store one or more surfaces where each surface represents a region where the solution

take one a particular value. The FDS software outputs isosurface frames at fixed time intervals. Note that char’s

are one byte, short’s are two bytes and “int’s” and float’s are four bytes. A “pseudo-code” representation of the

isosurface file is given by:

version (int)

len1,len2,len3 (3*int)

label1,label2,label3 ((len1+len2+len3+4)*char)

nlevels (int)

level_1, level_2, ..., level_nlevels (nlevels*float)

for each time:

time (float)

for each level

nvertices (int)

6Big-endian and little-endian are terms that describe the order in which a sequence of bytes are stored in computer memory. Big-endian

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 end or the little end.

47
ntriangles (int)

vertices_1, ..., vertex_nvertices (3*short*nvertices)

triangles_1, ..., triangle_ntriangles (3*(byte/short/float)*ntriangles)

end level

end time

The length of each triangles i node is one byte if the number of triangles, ntriangles, is between

zero and 255 (inclusive), two bytes if ntriangles is between 256 and 65536 (inclusive) and four bytes if

ntriangles is greater than or equal to 65536. Note that the isosurface files are written using the C programming

language. These files should be read the same way unless the programming language of choice supports binary

I/O.

D.3.2 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

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.

48
D.3.3 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 a 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.4 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

D.3.5 Plot3D Data

Field data is dumped periodically by FDS in a format used by the graphics package Plot3D[19]. 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)

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

E Frequently Asked Questions

This appendix contains a list of frequently asked questions concerning Smokeview. An updated list may be found

at http://fire.nist.gov/smokeview .

E.1 How can I keep up with new releases and other information about FDS and Smokeview?

An e-mail list has been set up to alert users to changes, upgrades, etc. To subscribe to the list, send an email to

listproc@nist.gov and put the line

subscribe fdsusers Jane Doe

in the text where Jane Doe is your name. Subject line is unimportant. To get off the list, send an email to the

same address and write

unsubscribe fdsusers

Also, you can check the web page http://fire.nist.gov/download to see the date of the most recent update.

E.2 Smokeview doesn’t look right on my computer. What’s wrong?

Some video cards do not use enough bits to represent the “depth buffer”. The depth buffer is used to determine

when objects are hidden and therefore should not be drawn. A problem then can occur when the video card

reduces the number of depth buffer bits from 32 to 16 in order to speed up its performance (less data to transport).

This results in straight lines or polygonal edges appearing to be scalloped. Often reducing the acceleration setting

for the video card can eliminate this problem. To do this:

• click your mouse on the desktop to bring up the ”Display Properties” dialogue box.

• click on the ”Advanced...” button

• Find the dialogue panel that lets you select the ”Hardware acceleration”. Reduce the acceleration (rebooting if necessary) until the scalloping disappears.

If you have upgraded your PC recently, make sure you have loaded the latest drivers for your video card.

E.3 How do I make a movie of a Smokeview animation?

You make a movie of a Smokeview animation by converting the visualized scene into a series of PNG or JPEG

files, one file for each time. More specifically:

• Set up Smokeview orienting the scene and loading the desired data files.

• Select the Options/Render menu and pick the desired frame rate. The more frames you include in the

animation, the smoother it will look. Of course more frames results in larger file sizes.

• Use a program such as the Antechinus Media Editor or Platypus Animator available at http://www.cpoint.com

50
References

[1] 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.

[2] K.B. McGrattan, H.R. Baum, R.G. Rehm, A. Hamins, J.E. Forney, G.P. Floyd, and S. Hostikka. Fire Dynamics Simulator (Version 2) - Technical Reference Guide. Technical Report NISTIR 6783, National Institute

of Standards and Technology, Gaithersburg, Maryland, November 2001.

[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] K.B. McGrattan, G.P. Forney, J.E. Floyd, and S. Hostikka. Fire Dynamics Simulator (Version 2) - User’s

Guide. Technical Report NISTIR 6784, National Institute of Standards and Technology, Gaithersburg, Maryland, November 2001.

[5] G. P. Forney and K. McGrattan. User’s Guide for Smokeview Version 1.0: A Tool for Visualizing Fire

Dynamics Simulation Data. NISTIR 6513, National Institute of Standards and Technology, 1999.

[6] G. P. Forney and K. McGrattan. User’s Guide for Smokeview Version 2.0: A Tool for Visualizing Fire

Dynamics Simulation Data. NISTIR 6761, National Institute of Standards and Technology, 2001.

[7] D. Madrzykowski and R.L. Vettori. Simulation of the Dynmaics of the Fire at 3146 Cherry Road NE,

Washington, DC May 30, 1999. Technical Report NISTIR 6510, Gaithersburg, Maryland, April 2000.

[8] D. Madrzykowski, G.P. Forney, and W.D. Walton. Simulation of the Dynamics of a Fire in a Two-Story

Duplex, Iowa, December 22, 1999. Technical Report NISTIR 6854, Gaithersburg, Maryland, January 2002.

[9] R.G. Rehm, W.M. Pitts, Baum H.R., Evans D.D., K. Prasad, K.B. McGrattan, and G.P. Forney. Initial Model

for Fires in the World Trade Center Towers. Technical Report NISTIR 6879, Gaithersburg, Maryland, May

2002.

[10] Mason Woo, Jackie Neider, Tom Davis, and Dave Shreiner. OpenGL Programming Guide. Addison-Wesley,

Reading, Massachussets, 3 edition, 1999.

[11] Richard S. Wright Jr. and Michael Sweet. OpenGL Super Bible. Waite Group Press, Indianapolis, Indianna,

2 edition, 2000.

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

Reading, Massachussets, 1996.

[13] Thomas Boutell. CGI Programming in C & Perl. Addison-Wesley Publishing Co., Reading, Massachussets,

1996.

[14] Thomas Boutell. GD version 2.0.7, http://www.boutell.com/gd/, November 2002.

[15] Guy Eric Schalnat, Andreas Dilger, and Glenn Randers-Pehrson. libpng version 1.2.5,

http://www.libpng.org/pub/png/, November 2002.

[16] jpeg version 6b, http://www.ijg.org/.

[17] Jean loup Gailly and Mark Adler. zlib version 1.1.4, http://www.gzip.org/zlib/, November 2002.

[18] Paul Rademacher. GLUI version 2.1, http://www.cs.unc.edu/ rademach/glui/.

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

51
Acknowledgements

The authors are grateful to the many people who have contributed to this work providing comments and suggesting improvements, many of which have been incorporated into this version of Smokeview. Further suggestions

or comments are encouraged and may be sent to glenn.forney@nist.gov or to the web site with URL:

http://fire.nist.gov/smokeview .

52