Pathfinder User Manual

Disclaimer

Thunderhead Engineering makes no warranty, expressed or implied, to users of Pathfinder, and accepts no responsibility for its use. Users of Pathfinder assume sole responsibility under Federal law for determining the appropriateness of its use in any particular application; for any conclusions drawn from the results of its use; and for any actions taken or not taken as a result of analyses performed using these tools.

Users are warned that Pathfinder is intended for use only by those competent in the field of egress modeling. Pathfinder is intended only to supplement the informed judgment of the qualified user.

The software package is a computer model that may or may not have predictive capability when applied to a specific set of factual circumstances. Lack of accurate predictions by the model could lead to erroneous conclusions. All results should be evaluated by an informed user.

All other product or company names that are mentioned in this publication are tradenames, trademarks, or registered trademarks of their respective owners.

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

Acknowledgements

This work was originally made possible by a Small Business Innovative Research (SBIR) grant (2005-2007) by the United States National Science Foundation.

We would like to thank Rolf Jensen and Associates for their assistance with testing and other suggestions that helped guide the development of the simulator.

We would also like to thank the users whose feedback helps us improve the software and incorporate more useful features. The Pathfinder support forum can be found at www.thunderheadeng.com/pathfinder/support/.

1. Getting Started

1.1. Introduction

Pathfinder is an agent-based egress and human movement simulator. It provides a graphical user interface for simulation design and execution as well as 2D and 3D visualization tools for results analysis.

1.2. Download and Install

You can download the current version, sign up for a free trial, and purchase the software from the Pathfinder Support Page. This page also provides instructions for installation and activation. Troubleshooting info can be found on the Pathfinder FAQs page. There is no functional difference between the trial version of Pathfinder and the full version, the only limitation is the trial license duration.

When installing Pathfinder, the installer will either upgrade an existing version or install Pathfinder to a new location, this behavior is based on the version. In the case of minor updates (e.g. upgrading from Pathfinder 2020.1 to Pathfinder 2020.3), the installer will remove the older version and replace it with the new version. When installing a major update (e.g. Pathfinder 2019 to Pathfinder 2020), the older version will not be modified and the newer version will be installed to a different folder.

Administrator privileges are required to install Pathfinder. This is necessary because the installer adds processes to the operating system for license management.

Pathfinder will regularly check for and notify the user of available updates to the software when configured to do so. By default, Pathfinder will check for updates on startup and display the relevant information in the Check For Updates dialog when one is available.

path ui dialog check for updates
Figure 1. The Check For Updates dialog.

Users can also access this dialog by navigating to Help→Check For Updates

The dialog can be disabled on startup by unchecking Check for newer version on startup. Users can also elect to skip the current update by clicking the Skip Update button, which will prevent update notifications until a new version is released beyond the latest version.

1.3. Graphical User Interface

Pathfinder includes a graphical user interface that is used primarily to create and run simulation models. A screenshot of this user interface is shown in Figure 2. This screenshot displays a model of the Theater de Vest in Alkmaar, Netherlands. The model was created by Van Hooft Adviesburo. For clarity, the image shows only one of the DXF files used to create the geometry. The model includes 2177 occupants.

path scrn gui
Figure 2. An example of the graphical user interface. Model of the Theater de Vest created by Van Hooft Adviesburo.

Pathfinder also includes a second program designed specifically for high-performance visualization of 3D time history. The 3D Results program is shown in Figure 3. In this image, occupants are gathering at a refuge area before proceeding to elevators. Transparency has been used to help view occupants on the refuge floor.

results scrn refuge elevators
Figure 3. An example of the 3D Results view, showing occupants gathering at a refuge area before proceeding to elevators.

In addition to 3D visualization, Pathfinder also provides output in the form of 2D time history plots of CSV (comma separated values) out files and a text summary of room clearing times and doorway flow rates. An example time history plot can be seen in Figure 4. This plot shows the number of occupants in the refuge area and the total number of occupants in the building.

path plot time history
Figure 4. An example time history graph

1.4. Model Representation

The movement environment is a 3D triangulated mesh (Figure 5), designed to match the real dimensions of a building model. This movement mesh can be entered manually or automatically based on imported data (e.g. FDS geometry).

Walls and other impassable areas are represented as gaps in the navigation mesh. These objects are not actually passed along to the simulator, but are represented implicitly because occupants cannot move in places where no navigation mesh has been created.

Doors are represented as special navigation mesh edges. In all simulations, doors provide a mechanism for joining rooms and tracking occupant flow. Depending on the specific selection of simulation options, doors may also be used to explicitly control occupant flow.

Stairways are also represented as special navigation mesh edges and triangles. Occupant movement speed is reduced to a factor of their level travel speed based on the incline of the stairway. Each stairway implicitly defines two doors. These doors function just like any other door in the simulator but are controlled via the stairway editor in the user interface to ensure that no geometric errors result from a mismatch between stairways and the connecting doors.

Elevators are called to a floor when occupants arrive at the elevator door. The elevator model includes capacity, pick-up and discharge floors, and the ability to group elevators in banks.

path scrn triangulated mesh
Figure 5. The triangulated navigation mesh used to represent one floor in the model.

Each occupant is defined by position, a profile that specifies size, speed, etc., and a behavior that defines goals for the occupant. The behavior allows scripting so that, for example, an occupant may wait at a location for a specified time and then proceed to an elevator. The occupant is represented as an upright cylinder on the movement mesh and movement uses an agent-based technique called inverse steering. Each occupant calculates movements independently.

1.5. Simulation Modes

Pathfinder supports two movement simulation modes. In "Steering" mode, occupants use a steering system to move and interact with others. This mode tries to emulate human behavior and movement as much as possible. SFPE mode uses a set of assumptions and hand-calculations as defined in the Engineering Guide to Human Behavior in Fire (SFPE 2019). In SFPE mode, occupants make no attempt to avoid one another and can interpenetrate, but doors impose a flow limit and velocity is controlled by density. You can freely switch between the two modes within the Pathfinder user interface and compare answers.

More information about both modes is provided in the Pathfinder Technical Reference (Pathfinder Technical Reference, n.d.).

1.6. System Requirements

System requirements depend on the type of model being analyzed. To illustrate this, two different models (Table 1) were evaluated using a laptop running 64-bit Windows 8 Pro with an Intel Core i7 2.60 GHz processor, 8 GB of RAM, and NVIDIA NVS 5200M graphics card. The first model (Figure 6) had a single room with 50,000 occupants and did not include any imported geometry. The second model (Figure 7) imported a relatively complex Revit model to create the Pathfinder model and had 3,000 people.

The key parameters are the number of people in the model and the model complexity, measured by the number of navigation mesh triangles used in the Pathfinder solution and the number of imported Revit primitives (triangles). The simple model had only 4 triangles, with the consequence that the movement calculation of the path for each person is simple and that display performance is related to the drawing of people. The Revit model had 21,480 triangles for the navigation mesh but over 1,300,000 triangles for the Revit geometry.

The model with 50,000 people (Figure 6) solved in about 18 minutes, while the Revit model with 3,000 people (Figure 7) took about 5 minutes. The graphical display performance for the model with 50,000 people was responsive at 15 frames/sec, while the Revit model with the imported geometry displayed was slow at 5 frames/sec. When only the Pathfinder navigation mesh was displayed, the Revit model was responsive.

path scrn model 50000
Figure 6. Model with 50,000 people
path scrn model 3000
Figure 7. Revit import model with 3,000 people
Table 1. Comparison of performance for the two models
ParameterModel
PeopleRevit Import
Number of occupants50,0003,000
Number navigation triangles421,480
Number Revit face primitives01,300,000
CPU solution time (s)1090297
Navigation mesh display rate (fps)~15~70
Imported geom display rate (fps)n/a~5

The minimum requirements to run Pathfinder include:

  • 32 or 64-bit Windows 7 or higher
  • A processor the performance of an Intel i5
  • 4 GB of RAM
  • Graphics support for OpenGL 1.2

For a balanced performance we recommend:

  • 64-bit Windows 7 or higher
  • Intel i7-3770 (3.4 GHz, 4 Cores) processor
  • 8 GB of RAM
  • Graphics support for OpenGL 3.2 with an installed graphics card for large Revit models.

Revit models place a premium on graphics capability. We have found that mid-cost gaming graphics cards (GeForce GTX 570 / Radeon HD 7870 or equivalent) allow us to display relative large Revit models with good performance. Benchmarking sites that we find useful to compare CPU and graphics card performance can be found at: http://www.cpubenchmark.net/ and http://www.videocardbenchmark.net/.

1.7. Configuration Files

Pathfinder stores data related to user preferences in a file called Pathfinder.props. By default, this file can be found in one of:

%APPDATA%\Pathfinder\Pathfinder.props
%PROGRAMDATA%\Pathfinder\Pathfinder.props

If at least one of these files exists, Pathfinder will load the user preferences. If both files exist, Pathfinder will load user preferences from both files, giving preference to the file located in the APPDATA folder. This way the preference file located in the PROGRAMDATA folder can be shared among multiple machines, and the file located in the APPDATA folder on each machine overrides the shared settings.

The PROPS file is stored in a plaintext format, and can be viewed or edited with any conventional text editor. While it is not recommended to edit the file directly, some troubleshooting techniques may involve deleting the PROPS file so that a new one can be created from scratch by Pathfinder.

1.8. Contact Us

Thunderhead Engineering
403 Poyntz Avenue, Suite B
Manhattan, KS 66502-6081
USA

Sales Information: sales@thunderheadeng.com
Product Support: support@thunderheadeng.com
Phone and Fax: +1.785.770.8511

2. Pathfinder Basics

Pathfinder provides three main views for working on evacuation models: the 2D View, 3D View, and Navigation View. These views represent your current model. If an object is added, removed, or selected in one view, the other views will simultaneously reflect the change. Each view is briefly described below.

Navigation View
This view lists all objects in the model in a hierarchical format. It can be used to quickly locate and modify objects by name.
3D View
This view shows a 3D representation of the current model. The model can be explored and modified using various tools.
2D View
This view is very similar to the 3D View, but it provides an additional snapping grid and an orthographic view of the model.

2.1. Navigation View

The Navigation View helps you quickly find objects and data that are not always easily accessible from the 3D and 2D views.

The Navigation View is arranged in the following groups:

Views
This group contains user-defined camera positions.
Imported Geometry
This group stores items that were imported from an image or an IFC, FDS, PyroSim, or other CAD model. These objects do not affect the simulation but are carried through to help with results analysis. They can also be used to generate model elements as described in Section 4.3.
Profiles
This group contains the occupant profiles that have been created using the Edit Profiles dialog.
Vehicle Shapes
This group contains occupant shapes defined as polygons.
Assisted Evacuation Teams
This group contains user-defined teams of assistants and clients in an assisted evacuation scenario.
Behaviors
This group contains user-defined scripts that tell occupants how to behave.
Occupant Sources
This group stores occupant sources, which are defined either by area, room, or door, and can generate occupants during the simulation.
Occupants
This group contains every occupant in the model. If occupants are added to the model using a tool that adds more than one occupant at a time, they will be collected in a sub-group.
Movement Groups
This group stores occupants grouped into movement groups. Members of a movement group will stay together during the simulation.
Movement Group Templates
This group contains templates that can be used to automatically create large number of movement groups. Templates can also be used for generating movement groups during the simulation.
Elevators
This group contains evacuation elevators in the model.
Measurement Regions
This group contains regions defined by area, within which velocity and density measurements will be taken.
Floors
This group defines the floors in the model, and each floor contains all geometry necessary to create a movement mesh, including room, stairway, ramp, door, and exit definitions (Figure 8).
path ui view nav group floors
Figure 8. Navigation View with the Floors group expanded.

The buttons directly above the Navigation View perform the following actions:

path ui icon auto expand Auto Expand Selection
When an object (or occupant) in the 3D or 2D view is selected, this action will expand the groups of the Navigation View as needed to show the selected object.
path ui icon collapse all Collapse All
Collapses all expanded groups in the Navigation View.
path ui icon expand all Expand All
Expands all groups in the Navigation View (including sub-groups).

The Floor selection box above the Navigation View panel (see the top of Figure 8) can be used to manage floors. Any time a room, stair, ramp, or door is created it is added to a floor group matching the current selection in the Floor box. Changing the selection in the Floor box will cause the newly selected floor to be shown and all other floors to be hidden. Also, the Z property for all drawing tools will automatically default to the height of the floor currently selected in the Floor box. The visibility of any object or group of objects can always be manually set using the right-click context menu. This technique is useful if you want to show two floors at the same time (e.g. when creating a stairway).

2.2. 3D and 2D Views

The 3D and 2D views as shown in Figure 9 are the main views in which drawing is performed in Pathfinder. Both views contain tools to draw egress geometry and navigate in a model. The main difference between the two views is that the 3D view allows the model to be viewed from any direction, whereas the 2D view only allows viewing from one, orthographic direction. In addition, the 3D view contains no snap grid, whereas the 2D view does. The 3D view is entered by selecting the perspective camera, path ui icon view 3d, and the 2D view is entered by selecting one of the orthographic cameras, path ui icon view 2d top, path ui icon view 2d front, or path ui icon view 2d left.

At the top of the view is several buttons that show different camera modes, display options, and navigation modes. The panel under this is known as the Property Panel and is a selection context-sensitive panel. If a drawing tool is selected, it will show properties that can used to help draw. If no drawing tool is selected, and an object or several objects are selected, this panel will show the properties relevant to the selection. The panel of buttons on the left shows move/copy and drawing tools. The small panel at the bottom displays messages relevant to the current tool.

path scrn views 2d 3d
Figure 9. 3D and 2D views

2.2.1. Navigating the 3D View

Several tools are provided for navigating through the model in the 3D view, including orbit, roam, pan, and zoom tools.

The main navigation tool for the 3D view is the Orbit tool, path ui icon orbit.

  • By left-clicking and dragging, the model is rotated about its center point.
  • The scroll-wheel can be used to zoom in and out on a specific point.
  • Holding SHIFT on the keyboard and then clicking and dragging will pan the camera.
  • Holding ALT while dragging will zoom in and out.

Another navigation tool in the 3D view is the Roam tool, path ui icon roam. This tool allows the camera to move in and out of the model at will. It has a higher learning curve but is the most flexible viewing tool because it allows the camera to be placed anywhere in the model. This tool can work in three different modes. In the first two modes, the movement speed of the camera can be changed by holding CTRL and spinning the mouse wheel up or down. Spin it up to increase the speed and down to decrease the speed.

Mouse+Keyboard Mode
Click and drag the left mouse button to look around. The camera will remain stationary. Dragging the mouse up will make the camera look up, dragging it down will look down, and dragging it left and right makes it look left and right. Holding CTRL while dragging will make the camera move forward and backward in the XY plane, and holding ALT while dragging will make the camera move up and down along the Z axis.
WSAD Mode
This mode mimics the controls in video games. Click and drag to look around as in the previous mode. Press the W key to move forward along the viewing direction, S to move backward, A to move to the left, and D to move to the right. SPACE moves the camera up along the Z-axis, and C moves the camera down. Pressing these keys moves the camera at a fixed speed. Holding SHIFT while pressing the keys doubles the speed.
Mouse-only Mode

This mode smoothly animates the camera to any location using only the mouse. To do so, press and release the middle mouse button. The cursor will disappear, and the tool will enter Mouse-only Mode. In this mode, moving the mouse will look around as in the other modes except that the mouse button doesn’t have to be pressed. Pressing and dragging the left mouse button will move the camera in the XY plane. The further the mouse is moved from its button press, the faster the camera will move. This can simulate the effect of accelerating the camera. Doing the same with the middle mouse button will cause the camera to move forward/backward in the XY plane with changes along the Y mouse axis and turn left/right with changes along the X mouse axis. Pressing and dragging the right mouse button will move the camera along the Z axis in the same manner. To exit Roam Mode, press and release the middle mouse button again or press Esc on the keyboard.

The other navigation tools include a Pan/Drag tool, which moves the camera left and right and up and down, a zoom tool, which zooms in and out of the model while click-dragging, and a zoom box tool, which allows a box to be drawn that specifies the zoom extents.

Pathfinder can also be navigated while using the Selection/Manipulation tool, path ui icon select. To Orbit the camera while in perspective view, use a right-click and drag combination. Similarly, use a middle-click and drag to Pan in perspective view.

2.2.2. Navigating the 2D view

Navigation in the 2D view is simpler than in the 3D view. The selection tool not only allows objects to be selected if single-clicked, but it allows the view to be panned by middle or right-clicking and dragging, and the view to be zoomed by using the scroll wheel. The drag and zoom tools are also separated into separate tools for convenience.

2.2.3. Resetting the view

At any time, the camera can be reset by pressing CTRL+R on the keyboard, or selecting Reset All tool, path ui icon view reset. This will cause the entire model to be visible in the current view. For all navigation tools but the Roam tool, reset will make the camera look down the negative Z axis at the model. For the roam tool, however, reset will make the camera look along the positive Y axis at the model.

The camera can also be reset to the current selection at any time by pressing CTRL+E. This will cause the camera to zoom in on the selected objects and the orbit tool to rotate about the center of their bounding sphere.

2.2.4. Filling the view

Very similar to resetting the camera, the view can be fit by pressing F on the keyboard or selecting the Fill View tool, path ui icon view fill. The difference between the Fill View and Reset All tools is that filling the screen does not change the view angle of the camera. Instead the camera will recenter/rezoom to fit the screen.

2.2.5. Drawing in the 3D and 2D views

Drawing can be performed in both the 3D view and the top 2D view. The 3D view allows the user to see the model from any angle, but most tools restrict drawing in the XY plane. The top view completely restricts drawing to the XY plane, but it also displays an optional snap grid. The snap grid size can be set under Edit snap grid spacing in the View menu, and it can be turned off by deselecting Show Snap Grid in the View menu.

Drawing is performed in one of the two following modes:

Normal Mode
Single-click a drawing tool button on the left side of the view. Draw the object using the instructions in the appropriate section of the manual. When the object has been completed, the drawn object(s) will be selected and the view will revert to the previous navigation tool.
Sticky Mode
Double-click a drawing tool’s button on the left panel before beginning to draw. When the object is completed, the same drawing tool will remain selected and more objects can be drawn with the tool. To escape this mode, press ESC on the keyboard, and the previous navigation tool will be selected. A green dot on the tool’s icon indicates that the tool is currently in sticky mode. Single-clicking the tool’s icon again will turn off sticky mode but keep the tool selected.

At any time while drawing, the user can press ESC, which causes the current object to be cancelled and the previous navigation tool to be selected.

For each tool there are often two ways to create its object.

  • Draw the object graphically using the mouse and keyboard.
  • Interactively create the object by typing information such as coordinates, widths, etc., in the tool’s property panel.

The property panel will update the graphical preview immediately to reflect changes in the input. This allows fine-grained control in creating the object. The individual drawing tools are discussed in Chapter 3.

2.3. View Options

Pathfinder provides a variety of view options for displaying both navigation geometry and imported geometry that can also aid with drawing. This includes options for rendering geometry, displaying agents, coloring rooms, and setting the transparency of rooms.

2.3.1. Render Options

In the toolbar above the properties window in the 2D and 3D views, there are a number of buttons as shown in Figure 10 that control how geometry is rendered.

path ui toolbar render options
Figure 10. Render options

From left to right, the buttons are:

Wireframe Rendering
Displays imported 3D geometry as wireframe only. This option is mutually exclusive with the solid rendering option. It is useful for drawing doors in the 2D view when 3D geometry has been imported.
Solid Rendering
Displays imported 3D geometry filled in. This is selected by default.
Show Materials
Shows materials applied to the faces of imported 3D geometry. This is selected by default.
Show Object Outlines
Shows the outlines of 3D imported geometry. This is similar to showing the wireframe and solid versions at the same time.
Smooth Lighting
Uses a more realistic shading model to show all geometry. This may be a little slower to render on older graphics cards.
Show Navigation Geometry
This toggles the visibility of all the navigation geometry. It does not affect anything else (including imported geometry and occupants).
Show Imported Geometry
This toggles the visibility of all imported 3D geometry.
Show Occupants
This toggles the visibility of occupants.
Show Behaviors
This toggles the visibility of behavior objects, such as waypoints.
Show Occupant Sources
This toggles the visibility of occupant sources.
Show Measurement Regions
This toggles the visibility of measurement regions.
Show View Objects
This toggles the visibility of view objects.

2.3.2. Occupant Display

Occupants can be displayed using a number of options. They can be viewed as simple shapes, including disks and cylinders. They can also be displayed as the artist’s mannequin or as their respective human avatars specified in their profiles. These options are available under View menu and Occupant Display submenu.

When occupants are not viewed as people, they can also be colored in several ways, available under View→Occupant Color:

Default
If an occupant has an individually-set color, the occupant is colored with this; otherwise, the occupant’s profile color is used.
By Movement Group
If the occupant is part of a movement group, this colors all the occupants in their group the same color. The group color is set in the properties panel for the selected movement group. If the occupant is not in a movement group, their default color is used.
By Movement Group Template
If the occupant is part of a movement group that was created from a movement group template, this option colors the occupant using the color of the movement group template; otherwise, their default color is used.
By Behavior
Colors the occupant using the color specified in the property panel of the occupant’s behavior.
By Profile
Colors the occupant using the occupant’s profile color, even if the occupant has an individually set color.

2.3.3. Coloring Rooms

Rooms can be colored in a variety of ways. All coloring options are available under the View menu and Color Rooms submenu. Rooms can be colored by the following options:

Default
Displays each room with a unique color.
By Occupant Density
Colors the room with a color scale based on the occupant density of the room, defined as number_of_occupants/room_area. Red indicates high density and blue indicates low density.
Mixed
Rooms are colored by occupant density if they contain agents; otherwise, they are colored with their unique colors.
By Room Type
Rooms are colored according to the type of room.
  • path ui color room normal Indicates a normal room
  • path ui color room refuge Indicates a Refuge Area

2.3.4. Room Opacity

Sometimes it is useful to be able to see through rooms and stairways, such as when drawing on top of an imported background image. To change the opacity of a set of components, select them and in the property panel, change the opacity. Opacity settings will carry through to 3D results visualization.

2.4. Model Organization with Groups

The main method of organization in Pathfinder is to use groups. In every model there are already some implicit groups that cannot be modified, including Views, Imported Geometry, Profiles, Vehicle Shapes, Assisted Evacuation Teams, Behaviors, Occupant Sources, Occupants, Movement Groups, Movement Group Templates, Elevators, Measurement Regions, and Floors as shown in Figure 11. Sub-groups can be created to further organize the model as discussed in the following sections.

path ui view nav predefined groups
Figure 11. Predefined groups

2.4.1. Creating sub-groups

Sub-groups can be created under all groups (floors are discussed in Section 3.1.) Groups can also be created in other sub-groups.

To create a new group:

  1. Right click the desired parent group in the navigation view
  2. Select New Group or select New Group from the Model menu.
  3. A dialog will display allowing the user to select the parent group (which will automatically be selected if performed from the right-click menu) and a name for the new group.
  4. Click "OK" to create the new group.

2.4.2. Changing groups

An object can be moved from one group to another at any time.

To change an object’s group:

  1. Drag the object to the desired group in the Navigation View or right click the object and select Change Group.
  2. This will show a dialog that will allow the user to choose the new group. The options shown for the new group will only be valid groups for which the group can be changed.
  3. Select "OK" to change the group.

2.5. Keyboard Shortcuts

By default, Pathfinder uses a variety of keyboard shortcuts that are standard to Windows and Java applications. To accelerate model creation, shortcuts can be added or changed to in a variety of ways.

Some keyboard shortcuts are used by Java UI components. If a shortcut does not result in the expected behavior, it may be in direct conflict with a preexisting Java shortcut. It is best practice to avoid these conflicts (Default Swing key bindings (IBM n.d.)).

2.5.1. Keyboard Shortcut Editor

The Keyboard Shortcut Editor Window can be found in the File→Preferences dialog and clicking Edit Actions and tools can are bound to a combination of modifier keys (ALT, CTRL, SHIFT, etc.) and other key presses.

path ui dialog keyboard shortcuts
Figure 12. Keyboard Shortcuts Dialog

The dialog is split into sections similar to those used in the Pathfinder toolbar menus. There are additional tabs for shortcuts related to tool activation, object selection, and context sensitive actions.

To change a shortcut, click on cell in the Key Press column and a window launches (Figure 13) with four different options.

Type an input
Input the desired keybinding to map it to the action.
Clear
Remove the current keybinding from the action.
Reset
Assign the default keybinding to the action.
Cancel
Exit the editor window without making any changes.
path ui dialog keyboard shortcut listener
Figure 13. Keyboard Shortcuts Listener

3. Creating Movement Space

Pathfinder is built on the idea of creating floor space on which occupants can walk. Every navigation component drawn in Pathfinder is some piece of flooring that can be travelled on, which can range from floors, to doorways, to stairs. Obstructions exist as holes in the floor.

The main egress components include rooms, which are empty floor spaces bounded by walls, doors, which connect rooms on the same level, stairs/ramps, which connect rooms on different levels, and elevators, which connect multiple levels.

Rooms
Can have any polygonal shape, and can never overlap on the same level.
Doors
Can be either thick if they are occupying a doorway (the area between two rooms) or thin if they are simply connecting two touching rooms.
Stairs/Ramps
Are always rectangular and implicitly contain a thin door on each end to connect the adjacent rooms.
Elevators
Can be any shape and can travel in any direction.

To organize egress components, Pathfinder provides the concept of floors, which group together components at different Z locations.

3.1. Floors

Floors are the primary method of organization in Pathfinder. At their most basic level, they are simply groups in which rooms, doors, stairs, ramps, and exits can be placed, but they also control the drawing plane for most tools and filtering of imported geometry.

In every Pathfinder model, at least one floor must exist, and at any given time, there is one active floor. Whenever any navigation object is drawn, it will either be placed in the active floor or a subgroup of the active floor.

By default when a new model is started, there is one floor at Z=0, and additional floors are either created automatically depending on where the geometry is drawn or manually created. In addition, new navigation components are automatically sorted into the appropriate floor when drawn.

3.1.1. Automatically Creating Floors

When nothing is selected in the model, the Floor Creation panel is shown, as in Figure 14. This panel controls the automatic creation of floors and automatic sorting of new objects into floors.

path ui props floor creation
Figure 14. Floor Creation Panel
Auto sort egress components
If this is checked, navigation components are automatically sorted into the appropriate floor when created or modified; if this is unchecked, new navigation components are placed in the group specified under New Egress Components and remain in this group until manually moved.
Automatically create floors
If this is checked, floors are automatically created as navigation components are created and modified.
Floor height
This specifies the height at which new floors are automatically created. If a navigation component is created or moved to a location that is at least this distance from the previous floor, a new floor will be created at a multiple of this distance from the previous floor.
Group
If Auto sort egress components is unchecked, this drop-down specifies the group/floor for new navigation components.

The following scenario demonstrates how objects are organized when auto-sort and auto-floor-creation are enabled (organization of the model is shown in Figure 15):

  1. A new model is created. The floor height is left at the default of 3 m.
  2. "Room00" is drawn at Z=0 m, and is auto-placed in "Floor 0.0 m".
  3. "Room01" is drawn at Z=1.5 m, and is auto-placed in "Floor 0.0 m".
  4. "Stair01" is drawn connecting "Room00" to "Room01" and is auto-placed in "Floor 0.0 m".
  5. "Room02" is drawn at Z=-1.5 m. A new floor, "Floor -3.0 m" is auto-created, and "Room02" is auto-placed in it.
  6. "Stair02" is drawn connecting "Room02" and "Room00" and is auto-placed in "Floor -3.0 m".
  7. "Room03" is drawn at Z=7.5 m.
  8. A new floor, "Floor 6.0 m" is auto-created, and "Room03" is auto-placed in it.
path ui view nav auto floor creation
Figure 15. Auto floor creation and sorting

In this example, only rooms and stairs were created. The floors were automatically created and the rooms and stairs were automatically sorted into the appropriate ones.

3.1.1.1. Using Auto-sort with an Existing Model

Automatic floors can be created and components sorted into the floors by performing the following:

  1. Open the model.
  2. Clear the selection so that the Floor Creation panel is visible (Figure 14).
  3. Ensure that the desired creation/sorting options are enabled and that the correct floor height for the model is set.
  4. Select all the components that should be auto-sorted (if everything should be sorted, select the Floors top node).
  5. Right-click the selection, and from the shortcut menu, click Sort into Floors.
  6. The appropriate floors will be created and all selected items will be sorted into the appropriate floors.

3.1.2. Manually creating floors

Floors can also be created manually at any time.

  1. Click on the floor drop-down box above the Navigation View, and select <Add New> as shown in Figure 16. A dialog will open asking for the floor location.
  2. Enter the Z plane location (Figure 17) or click on a snap point in the 3D or 2D view and click okay. This Z plane will be used to update the drawing tools' working Z location when this floor is made active.

There are two other options in this dialog:

Set as active floor
The floor is set to be the active floor in the model after being created.
Resort existing egress components into new floor
All existing components that belong in the new floor will be moved to it.

By default, the name of the floor is Floor \(x\) where \(x\) is the working plane of the floor.

Manually Adding a New Floor
path scrn props adding new floor
Figure 16. Adding a new floor
path ui dialog new floor
Figure 17. Floor Location Z plane

3.1.3. Changing the Active Floor

To change the active floor, click the floor drop-down box as shown in Figure 16, and select the desired floor. This will make that floor active and all other floors non-active.

Whenever the active floor is changed, the following additional changes take place in the model:

  • The floor, all objects in the floor group, and all occupants on the floor are set visible.
  • All other floors, sub-objects of other floors, and occupants on those floors are set hidden.
  • The working plane of the room and wall subtraction tools is set to the working plane of the floor.
  • A clipping filter is applied to imported geometry so that only geometry within the Z clipping planes of the active floor is visible.

3.1.4. Showing All Floors

To show all floors click the floor drop-down box as shown in Figure 16, and click <Show All>.

This will additionally show all occupants on the floors and all sub-objects of the floors groups, and it will set the import filter to the union of all the floors' filters.

3.1.5. Floor Properties

To edit a floor’s properties, first select the desired floor. The property panel as shown in Figure 18 will appear, showing the floor’s name, its Working Z location, and the Z clipping planes (Z Min Filter and Z Max Filter) for imported 3D geometry.

It also shows some statistics of the floor including the total area of the floor (Area), number of people on the floor (Pers) and density of people. Refuge Area and Speed Modifier are discussed in Section Room properties.

path ui props floor
Figure 18. Floor property panel
Working Z
Controls the plane on which new rooms and wall obstructions are drawn.
Z Min and Max Filters
Control the clipping planes of imported 3D geometry when the floor is visible. Anything below Z Min and above Z Max is clipped.
Z Min Filter
Can be a Z plane location or can have the special value, CURR_FLOOR. If it is CURR_FLOOR, then the clipping plane is set to the working Z location if there are any floors below this floor or \(-\infty\) if there are no floors below.
Z Max Filter
Can be a Z plane location or can have the special value, NEXT_FLOOR. If it is NEXT_FLOOR, then the Z plane is set to the working Z plane of the next higher floor if one exists, or \(+\infty\) if there are no higher floors.

3.2. Rooms

Rooms are open space on which occupants can freely travel. Each room is bounded on all sides by walls. Rooms can be drawn so that they touch each other, but an occupant can only travel between them if they are connected by a door. Only one room can occupy a given space at any time, so if one room is drawn overlapping another, the overlapping area will be subtracted from the old room and given to the new. Rooms can also be merged into one, separated into constituent parts, and have internal, thin boundaries drawn in them. These features are discussed in the following sections.

3.2.1. Adding New Rooms

Pathfinder provides two tools for adding new room geometry:

Polygonal Room Tool
The Polygonal Room tool path ui icon room polygon allows for the creation of complex shapes with any number of vertices (Figure 19).

Left-click anywhere in the model to set the first point, and continue left clicking to add more points to the polygon. When at least three points are defined, right-clicking will close the polygon and complete the shape.

Alternatively, X,Y coordinates can be entered from the keyboard with the Add Point and Close Polygon buttons from the property panel.

path scrn room polygon
Figure 19. Drawing a room with the polygon tool
Rectangular Room Tool
The Rectangular Room tool path ui icon room rectangular creates simple rectangular geometry by left-clicking two points in the model (Figure 20).

The rectangular area can also be created by entering coordinates for two points in the property panel and clicking Create.

path scrn room rectangle
Figure 20. Drawing a room with the rectangle tool

In addition to creating new areas, both of these tools can be used on existing geometry to create negative areas. Creating new geometry over existing areas removes any interfering portion from those areas. The newly created geometry can then be deleted, leaving the negative space behind. This is discussed further in the section, Arbitrarily-shaped obstructions (desks, tables, etc.).

3.2.2. Drawing Plane

Each room tool draws on a particular Z plane that is specified in the property panel for the tool as shown in Figure 21.

path ui props drawing plane
Figure 21. Drawing plane property

The Z plane can be specified either manually by typing the location into the Z Plane field or by picking the location from the 2D View or 3D View as follows:

  1. Select one of the room drawing tools.
  2. In the tool property panel, click Pick Z from Scene. This will clear the tool property panel while waiting for the user to click a location.
  3. Click a point in either the 3D View or a 2D View. The tool property panel will return for the selected drawing tool, and the Z Plane field will be filled with the Z coordinate of the clicked location.

3.2.3. Splitting Rooms

Rooms can be split into two or more pieces using the Thin Wall tool. To do this, specify the two points such that they are on the outermost boundary of the room to be divided. The original geometry will be divided into two or more new rooms with that line as the boundary between them as shown in Figure 23.

Dividing a Room
path scrn room original
Figure 22. Original room
path scrn room thin wall split
Figure 23. Two new rooms from the original

3.2.4. Separating and Merging Rooms

In addition to dividing rooms, Pathfinder has two additional means to aid in creating more complex room geometry.

Merge
The Merge command is used to join two or more rooms that share boundaries into one room. They can also be merged with stairs and ramps, but the stairs and ramps will be converted into rooms and will lose their stair/ramp properties.

To Merge rooms:

  1. Select the neighboring rooms
  2. Select Merge from either the Model menu or the right-click menu (Figure 24)
Merging rooms
path scrn room separate
Figure 24. Two rooms to Merge
path scrn room merged
Figure 25. New merged room
Separate
The Separate command breaks a room into its constituent parts along any negative space that divides it (Figure 27).

To Separate a room:

  1. Select the room to be separated
  2. Select Separate from either the Model menu or the right-click menu (Figure 26).
Separating a room
path scrn room shared point
Figure 26. Single room shared point
path scrn room separated
Figure 27. Two separated rooms

3.2.5. Room Properties

To view and edit room properties, select a room. Its properties will be displayed in the property panel as shown in Figure 28.

path ui props room
Figure 28. Room properties panel
Name
An identifying name for room.
Visible
Whether the room is currently visible. Uncheck to hide the room.
Color
The color of the room. If unchecked, a default room color is used.
Opacity
The opacity of the room. Making this value less than 100% will cause objects behind the room to become visible.
X, Y, and Z Bounds
The geometric bounds of the room.
Area
The geometric area of the room.
Pers
The number of occupants currently placed in the room.
Density
The number of occupants/area
Refuge Area
Marks the room as a Refuge area, which can then be specified in a list of rooms for the Goto Refuge Rooms action as discussed in Section 5.3.3. When this option is selected, occupants will be tagged as "safe" whenever they are in the room. The "safe" times are reported in the Occupants Summary (Section 12.7) and Occupant History (Section 12.8) output files.
Speed Modifier
A time-variable factor that affects the speed of each occupant who travels in the room. When occupants travel in the room, their maximum speed is multiplied by this factor. This could be used, for instance, to represent the effect of smoke on occupant speeds. By default, the modifier is 1.0 throughout the simulation. To change this, click the link. The Edit Speed Modifier dialog appears as shown in Figure 29. In this figure, for instance, the room initially leaves occupant speeds unmodified, but over the first 40 seconds ramps occupant speeds down to 25% of their maximum values.
Capacity
A maximum capacity of the room, which can be specified using an occupant count or a density. Specifying room capacity is optional. If at any time during the simulation the room capacity reaches the limit, no occupants will enter the room until the room capacity decreases below the limit.
Accepted Profiles
A list of occupant profiles for which the occupants can enter this room. By default, all occupant profiles are accepted.
path ui dialog edit speed modifier
Figure 29. Edit Speed Modifier dialog

3.2.6. Preventing Room-Crossing

In some cases, such as modeling seating rows or shops in a mall, it may be desirable to only allow occupants to exit the room and not cross through it. This can be accomplished by making all the doors connected to the room one-way (see Doors) and ensuring that their directions point out of the room. Pathfinder provides a tool to make this easy. Instead of individually setting the one-way status of all the connecting doors, perform the following:

  1. Select the room(s) that should not be crossable.
  2. Right-click one of the rooms, and from the menu select Make Doors One-way. A dialog will appear as in Figure 30.
  3. From this dialog, choose whether occupants can only Enter or Exit the room. If any of the room’s doors were already marked as one-way, another option will be provided to overwrite the one-way status of those doors.
  4. Click OK in this dialog to make the doors one-way.

Pathfinder will automatically calculate the correct directions for the doors to make the rooms exit-only or enter-only.

path ui dialog door one way
Figure 30. Make Doors One-way dialog

3.2.7. Mesh Optimization

Pathfinder performs automatic mesh optimization. An example of mesh optimization is removing multiple vertices in a straight line, or removing extra vertices left over after merging rooms. In some cases, it might be beneficial to disable mesh optimization.

To disable mesh optimization, select Preferences from the File menu, and uncheck Optimize Navigation Geometry.

3.3. Obstructions/Holes

In Pathfinder, obstructions are modeled as holes in the navigation geometry. Holes can be created with an arbitrary polygonal shape or as thick walls.

3.3.1. Arbitrarily-Shaped Obstructions

To model an obstruction (e.g. an office desk or other standing obstacle) within a room, the subtractive property of rooms is used. This means that the room containing the obstruction must already exist.

To create the obstruction:

  1. Select the Add a Polygonal Room tool or the Add a Rectangular Room tool and draw the shape and location of the obstructed area. This will subtract the area from the old room and create a new room.
  2. Next, delete the new room. A hole is left in the old room in the shape of the obstruction. This process is shown in Creating an obstruction.
Creating an obstruction
path scrn room existing
Figure 31. Start with an existing room
path scrn room obstruction draw
Figure 32. Draw the obstruction shape
path scrn room obstruction delete
Figure 33. Delete the new room
path scrn room obstruction
Figure 34. The cut out area obstructs movement

3.3.2. Thin Walls

Thin, internal walls or boundaries can be added to rooms with the Thin Wall tool path ui icon wall thin.

To use this tool, click two points in the model as shown in Figure 35. Pathfinder will attempt to connect these two points with an internal boundary edge.

path scrn wall thin
Figure 35. Adding a thin wall to a room

3.3.3. Thick Walls

The wall tool path ui icon wall thick is used to make rectangular obstructions in existing geometry (Figure 36).

To make a thick wall:

  1. Click on the wall tool.
  2. Enter the desired wall width in the property panel.
  3. Click or click-drag the two points the wall is to pass through. Holding the shift key will switch between alignment left and right of the defining line.
path scrn wall thick draw
Figure 36. Drawing thick walls

3.4. Doors

In Pathfinder, occupants cannot pass between two rooms unless they are joined by a door. Doors provide useful flow measurements in simulation results. Also, in the SFPE mode doors act as the primary flow control mechanism. You can add doors using the Add a New Door tool.

When adding doors, different parameters provide hints to Pathfinder for finding a valid door as shown in Figure 37.

Min Width
Restricts potential edges to only those that are longer.
Max Width
Used as a target width for the door. If the full width isn’t available, Pathfinder will display a shorter door as you hover with the mouse.
Max Depth
Represents the depth of the door cavity and is used to determine how far apart two rooms can be and still be joined by a door. Doors can be added between rooms that are separated by up to this distance.
path scrn props door create
Figure 37. Door tool property panel

3.4.1. Thin Doors

Thin doors can be used to connect two rooms that touch one another as shown in Figure 38. A door is needed in this example to allow occupants to travel from one room to the other.

To create a door in this manner:

  1. Select the door tool path ui icon door.
  2. Then use one of the following three methods:
    1. Manual Entry: Enter the coordinates of the door in the property panel. If the coordinates specify a valid door location, the Create Door button will enable. Click this button, and a door no larger than Max Width will be created. For thin doors, Max Depth will be ignored.
    2. Single Click: Move the cursor over the desired door location in the 3D or 2D view. A preview door will be displayed if the cursor is on a valid edge. The door displayed will lie either to the left or right of the hover point relative to the boundary edge, depending on whether Max Width is positive or negative. Single click to place the door. The previewed door will then be added to the model.
    3. Click-drag: Move the cursor over the location of one end point of the door, and click drag along the same edge. While dragging, a preview door will be displayed from the first to the second point. When the mouse is released, a door is created along the edge between the two specified points. Creating a door in this manner ignores all the properties in the tool panel.
  3. The created door will appear as a thin, orange line in the 3D and 2D views as shown in Figure 39.
path scrn room shared wall
Figure 38. Two rooms with a shared wall
path scrn room door thin
Figure 39. Adding a thin door to connect the rooms

3.4.2. Thick Doors

Thick doors are often useful in realistic models, especially when CAD geometry has been imported. In real scenarios, rooms will not touch each other by infinitely thin walls as shown in Figure 40.

To create a thick door to connect these rooms:

  1. Select the door tool path ui icon door
  2. Use one of the following three methods:
    1. Manual Entry: Make sure Max Depth is greater than or equal to the distance between the edges the door will lie between. Enter a point on one of the edges in the property panel. If the coordinates specify a valid door location, the Create Door button will enable. Click this button, and a door no larger than Max Width will be created.
    2. Single Click: Make sure Max Depth is greater than or equal to the distance between the edges the door will lie between. Then move the cursor over the desired door location in the 3D or 2D view. A preview door will be displayed extending between the rooms if the cursor is on a valid edge. The door displayed will lie either to the left or right of the hover point relative to the boundary edge, depending on whether Max Width is positive or negative. Single click to place the door.
    3. Click-drag: Move the cursor over the edge of one of the rooms, and click drag along the corresponding edge on the second room. While dragging, a preview door will be displayed connecting the two edges. When the mouse is released, a door is created between the edges of the two rooms, where the diagonal of the rectangular door connects the two specified points. Creating a door in this manner ignores all the properties in the tool panel.
  3. The created door will appear as an orange rectangle in the 3D and 2D views as shown in Figure 41.

When simulating, thick doors have a special representation: the area of the door will be partitioned in two, and each half is attached to its touching room. A thin door is placed in the middle of the area to represent the thick door.

path scrn room wall gap
Figure 40. Two rooms separated by a gap
path scrn room door thick
Figure 41. Thick door connecting the rooms

3.4.3. Door Properties

To edit a door’s properties, select the door. Its properties will appear in the property panel as shown in Figure 42.

path ui props door
Figure 42. Door property panel
Width
The width of the door. Changing this value will change the width of the door, but the value cannot exceed the length of its room edge.
Flow Rate
Checking this box overrides the default door flow rate setting in the Simulation Parameters Dialog (see Section 11.1). Setting this value controls the maximum occupant flow rate for the door in units of pers/s. This could be used, for instance, to specify a gated mechanism, such as a turnstyle. A value of 0.9 pers/s, for instance, would mean that one occupant can go through the door every 1.1 seconds (1/0.9).
State
Indicates the timed opening, closing, and changing the one-way direction of the door, see Section 3.4.3.1. A One-way door is one through which occupants can only travel in one direction.
Wait Time
Amount of time for which each occupant must wait at the door before walking through it. This can be used to simulate turnstyles or doors with access keys. The specific wait time for each occupant will be drawn at random from a predefined continuous or discrete distribution.
Accepted Profiles
A list of occupant profiles for which the occupants can enter this door. By default, all occupant profiles are accepted.
3.4.3.1. Door State

By default, all doors are always open throughout the simulation. To change this, click the link to the right of State.

The Edit Door State dialog will appear as shown in Figure 43. This dialog allows the initial state of the door to be specified as well as additional timed states.

As shown in the figure, for example, the door is initially open, closes at t=10 s, opens in +X direction at t=20 s, and then opens in both directions again at t=30 s.

Even though a door can only be travelled through in two possible directions, the drop-down box allows +X, -X, +Y, and -Y. When one of these directions is chosen, the actual direction Pathfinder chooses is the closest along the door’s normal.

path ui dialog edit door state
Figure 43. Door State dialog

3.5. Stairs

Stairs in Pathfinder are represented by one straight-run of steps. They can be created with two tools. One tool allows creation of stairs between two semi-parallel boundaries of rooms, and the other allows creation of stairs that extend from one room boundary until a criterion is met, such as number of steps, height of stairs, etc., or until another room is reached.

One requirement of all stairs for successful simulation is that each end of the stairs must connect to boundary edges of the rooms, meaning that there must be empty space at the top of the stairway and empty space below the bottom. See Stair geometry requirements for an illustration of this issue. The size of the gap must be greater than or equal to the radius of the largest occupant to travel on the stairs.

Stair geometry requirements
path scrn stair incorrect
Figure 44. Shows a stair that will not simulate correctly
path scrn stair correct
Figure 45. Shows a stair that will simulate correctly

3.5.1. Stairs Between Edges

One way to create stairs is to draw them between two pre-existing rooms. Stairs of this type will match the ends of the stairs exactly to the edges that they were drawn between, which means that the tread rise and run may or may not match the actual slope of the stairs. In Pathfinder, the speed on stairs is determined by the specified tread and run. The geometric slope of stairs is for display only and not used to calculate the speeds.

To create stairs between edges:

  1. Ensure that both the connecting rooms are visible. If the rooms are on different floors, at least one room will have to be manually set visible, which can be done through the right-click menu in the Navigation View.
  2. Select the two-point stair tool, path ui icon stair 2. The property panel will display the stair creation properties as shown in Figure 46.
  3. The stairs can now be created in one of the three following ways:
    1. Manual Entry: Set the desired stair width, and for each edge on which the stairs should be created, enter a point. If the points are valid, a preview stair will be shown in the 2D or 3D view and the Create button will enable. Click Create to add the stairs.
    2. Two-click: Set the desired stair width. Move the cursor over the first edge, and a preview line similar to a thin door will appear previewing the top or bottom of the stairs. Single-click to set the point. (Figure 47) Now move the cursor over the second edge. Now a preview of the stairs will appear connecting the first edge to the second. Single-click on the second edge to create the stairs (Figure 48).
    3. Two-click with drag: Click-drag on the first edge to specify both the starting point and width of the stairs. Release the mouse and then single-click on the second edge to place the stairs.

To change the display, you may:

  1. Measure the total vertical rise of the stair.
  2. Set the tread rise to total rise/desired step count
path ui props stair 2
Figure 46. Property panel for the two-point stair tool
Drawing stairs with the two-point stair tool
path scrn stair 2 edge 1
Figure 47. Click the first edge
path scrn stair 2 edge 2
Figure 48. Click second edge to finish stairs

3.5.2. Stairs Extending from One Edge

Another way to create stairs is to have them extend from an edge and exactly match the specified tread rise and run. They will stop when they meet a specified criterion or reach another room.

The property panel for the one-click stair tool, as shown in Figure 49, provides four ways to terminate the stairs:

Step count
The stair will have this many steps.
Total rise
The stair will be this tall in the Z direction.
Total run
The stair will be this length in the XY plane.
Total length
The hypotenuse of the stair will be this length.
path ui props stair 1
Figure 49. Property panel for the one-point stair tool

To create stairs in this manner:

  1. Select the one-point stair tool, path ui icon stair 1. The property panel will show.
  2. If the tread rise is positive, the stairs will extend up from the starting edge, and if it is negative, the stairs will go down. Similarly, if the tread run is positive, the stairs will extend away from the room, and if it is negative, the stairs will extend in toward the room. Another way to change these values is to hold CTRL on the keyboard to make the tread rise negative and hold SHIFT to make the run negative.
  3. Now the stairs can be created in one of the three following ways:
    1. Manual Entry: Set the desired stair width, tread rise, tread run, and termination criterion. Specify the starting point on the desired edge. If the location is valid, a preview stair will be shown, and the Create button will enable. Click Create to add the stairs.
    2. Single-click: Set the desired stair width, tread rise, tread run, and termination criterion. Move the cursor over the starting point on the room’s boundary. A preview stair will be displayed. Single click to place the stairs.
    3. Click-drag: Set the desired tread rise, tread run, and termination criterion. Now click-drag along the room’s boundary to specify both the location and the width of the stairs.
  4. Release the mouse to create the stairs.
path scrn stair 1 edge 1
Figure 50. Drawing stairs using the one-point stair tool

After creating stairs in this manner, the Z location of the next floor or room will have to match the top of the stairs exactly for the next room to connect properly to the stairs. This can be done by clicking the top of the stairs in the 3D or 2D view when choosing the Z location for either the floor or next room.

After creating a one-click stair, you can only modify the stair by clicking the handles and dragging to existing geometry.

3.5.3. Stair Properties

Stairs have a number of properties that control their geometry and behavior of occupants that travel on them. When a stair is selected, these properties can be seen in the stair’s property panel as shown in Figure 51.

path ui props stair
Figure 51. Stair property panel
Riser and Tread
Together, these parameters control the speed at which occupants can travel on the stairs during simulation. The default speed on stairs uses the SFPE speed modifiers, see (Pathfinder Technical Reference, n.d.). While the one-point stair tool uses the tread rise and run to create the initial shape of the stair, these properties can later be changed without affecting the stair shape.
Length
The total length of the stair from the bottom to top edge. This is the same as the hypotenuse formed by the total stair rise and total stair run.
Width
The width of the stair.
Top Door and Bottom Door
Clicking these links show the dialog in Figure 52. Here, properties of each implicit door can be edited independently of the other door, including Width, Flow Rate, and State. For more information on these properties, see Section 3.4.3.
One-way
Indicates whether the stair should only allow occupants to travel in one direction and if so, which direction.
Speed Modifier
A time-variable factor that affects the speed of occupants who travels on the stair. This acts the same as the Speed Modifier property for rooms (see Section 3.2.5).
Capacity
A maximum capacity of the stair, which can be specified using an occupant count or a density. This acts the same as the Capacity property for rooms (see Section 3.2.5).
Additional Info
Clicking this link shows additional information about the stair, such as its geometric bounding box, area, and number of occupants.
Accepted Profiles
A list of occupant profiles for which the occupants can enter this stair. By default, all occupant profiles are accepted.
path ui dialog props door top
Figure 52. Stair door property dialog

3.6. Ramps

Ramps are nearly identical to stairs in how they are created and represented. Like stairs, they have two implicit doors at either end and always take the shape of a rectangular piece of geometry.

They also have very similar creation tools: the two-point ramp tool path ui icon ramp 2, and the one-point ramp tool path ui icon ramp 1. The key difference between ramps and stairs is that ramps do not affect the speed at which occupants travel by default.

3.7. Escalators

Pathfinder provides some limited support for escalators. They are essentially stairs with slightly modified properties.

To create an escalator, perform the following:

  1. Create a stair as discussed previously.
  2. Select the stair (or several) so its properties are visible in the property panel as shown in Figure 51.
  3. Set a one-way direction for the stair.
  4. Click the Speed Modifier drop-down, and choose Speed Constant as shown in Figure 53.
  5. Edit the speed of the escalator in the speed constant field. As with the Speed Modifier for stairs, the Speed Constant can be time-variable. This would normally be used to turn the escalators on or off throughout the simulation by using the values 1.0 and 0.0 respectively, but any value can be entered.
path ui props stair escalator
Figure 53. Changing a stair into an escalator

In the results view, escalators do not appear differently than stairs.

By default, occupants do not walk on moving walkways or escalators, and they will not stand on any specific side. This can be changed by modifying the occupant’s profile and selecting their Escalator Preference (see Section 5.1). If an occupant is walking, the escalator’s speed constant will be added to the occupant’s current speed on the escalator.

3.8. Moving Walkways

Pathfinder also provides limited support for moving walkways. This is similar to creating escalators, but instead of setting a speed constant on an existing stair, the speed constant is set on a Ramp instead, which can be made flat like a walkway.

3.9. Elevators

Pathfinder supports elevators in egress-mode operation, which is based on current thinking described in Using Elevators In Fires (Bukowski and Li 2010).

The basic operation of elevators in evacuations can be summarized as follows:

  • Each elevator has one discharge floor. This is where the elevator starts at the beginning of the simulation and where it will take occupants it has picked up.
  • Each elevator has at least one pickup floor. These are floors where the elevator will pick up occupants that it will take to the discharge floor.
  • An elevator is called on a pickup floor by an occupant when they come within .5 m of the elevator door.
  • The elevator uses a priority system to serve called floors. By default, floors are served from top to bottom; however, other floors can be given higher priority to simulate fire floors.
  • When travelling to a pickup floor, the elevator can change to another pickup floor mid-flight if a higher-priority floor is called that is above the elevator’s current location.
  • Once an elevator has picked up occupants, it will only travel to the discharge floor before letting the occupants off. It will not travel to any other floor to pick up more occupants.

3.9.1. Creating Elevators

Elevators can be made after creating the rest of the model.

Perform the following steps to create the elevator (refer to Figure 16):

  1. Draw a room that defines the shape of the elevator, preferably on the discharge floor, see Figure 54.
  2. Draw all doors on the boundary of the base room, see Figure 55. Occupants will use these doors on every floor to enter and exit the elevator.
  3. Right-click the base room, and from the right-click menu, select Create Elevator, see Figure 56. This will show the New Elevator dialog as shown in Figure 57.
  4. In the New Elevator dialog, enter all parameters for the elevator:
    Name
    The name of the elevator.
    Nominal Load
    The number of people in a full load (estimated). Please read the Nominal Load section below for details.
    Elevator Geometry
    The base room that defines the elevator shape. This defaults to the room that was originally selected.
    Travel Direction
    A vector defining the direction the elevator can travel. This vector will automatically be normalized. The elevator can travel negatively against this vector.
    Elevator Bounds
    This defines the bottom-most and top-most floors the elevator can connect to.
    Elevator Timing
    This defines a basic timing model used to calculate the travel times for the elevator to travel from the discharge floor to each pickup floor.
    Acceleration (Elevator Timing) [optional]
    The acceleration of the elevator.
    Max Velocity (Elevator Timing)
    The maximum velocity that the elevator can accelerate to.
    Open+Close Time (Elevator Timing)
    The sum of the door opening and closing times. Each value will be taken as half of this.
    Call Distance
    The distance away from the elevator door at which an occupant can call the elevator.
    Double-Deck
    Whether the elevator should use two connected decks to transport occupants. Please see the Double-Deck Elevators Section for details.
  5. Click OK to create the elevator.

If necessary, Pathfinder will automatically subtract holes in existing geometry to make space for the elevator shaft. It will also delete existing rooms, doors, stairs, and ramps in the elevator shaft. Pathfinder will ask before making any of these changes.

In order for occupants to use elevators, they must either be allowed to use elevators in their Profile under Restricted Components (see Section 5.1.2) or be explicitly told to do so through their behaviors, as discussed in Behaviors. Occupants can be encouraged to prefer elevators to stairs using the Elevator Wait Time Profile parameter (see Section 5.1.3).

path scrn elevator room
Figure 54. Draw elevator room geometry
path scrn elevator door
Figure 55. Draw elevator door
path scrn elevator create
Figure 56. Select Create Elevator in right-click menu
path ui dialog elevator new
Figure 57. New Elevator dialog

3.9.2. Elevator Representation

Once an elevator is created, it will appear in the model as a series of "rooms" and doors connected by a transparent elevator shaft as shown in Figure 58. There is one room and set of doors for each floor to which the elevator can connect. In the 3D and 2D Views, each room is shaped the same as the base room that created the elevator. In the Navigation View, each room is shown under the elevator rather than the Floors top node, see Figure 59. In addition, each set of doors for the room is shown under the room. By default, each of the rooms is named after the floor on which it connects. If the elevator is disconnected completely from a floor as discussed in Connecting/Disconnecting floors, the room is named "<Disconnected Level>".

path ui elevator selected
Figure 58. New elevator shaft highlighted.
path ui view nav elevator selected
Figure 59. Elevator in Navigation panel.

3.9.3. Elevator Properties

Once an elevator is created, the elevator’s properties can be edited by first selecting it from the navigation view or by ALT-clicking one of its rooms from the 2D or 3D view. Its properties can be edited in the property panel as shown in Figure 60.

path ui props elevator
Figure 60. Elevator property panel
Nominal Load
The number of people in a full elevator load (estimated). Please read Section 3.9.4 below for details.
Open Delay
The minimum amount of time an elevator’s doors will stay open on a pickup floor.
Close Delay
The minimum amount of time the elevator’s doors will stay open after an occupant passes through one of the doors. This can also be thought of as the time someone in the elevator will hold the door open waiting for another occupant to enter. This delay time will reset every time an occupant passes through the doors. If the delay time passes without another occupant passing through the doors or without another occupant appearing in range of the doors or the elevator reaches capacity, the doors will close. The total amount of time for elevator doors to stay open, assuming no other occupants are within sight of the elevator who are heading toward it, can be summarized as: \(t_{\text{open}} = \max\left( \text{delay}_{\text{open}},t_{\text{last}} + \text{delay}_{\text{close}} \right)\)
Discharge Floor
The floor at which occupants will discharge during an evacuation.
Floor Priority
The priority of the floors for pickup. By default this is top-down. This can be changed, however by clicking the text, which will show the Floor Priority dialog as shown in Figure 61. This allows the simulation of a fire floor.
Level Data
Click the Level Data: Edit link to edit timing for each floor. This will open the Elevator Levels dialog as shown in Figure 62.
Delay
The time delay from the start of the simulation for when the elevator can start picking up occupants from a floor. This value does not affect the discharge floor.
Open+Close Time
The total amount of time it takes to open and close the doors for this floor. The door is assumed to open and close at the same speed, so after arrival at a floor the door will open after a delay of half the specified Open+Closed Time. Similarly, after the door closes the elevator will leave the floor after a delay of half the specified Open+Closed Time.
Pickup Time

The time for the elevator to travel from the discharge to the pickup floor.

Discharge Time
The time for the elevator to travel from the pickup to the discharge floor.
Reset
By selecting the Reset option at the bottom of the dialog, an Elevator Timing dialog will open, allowing automated recalculation of the Level Data parameters. The timing options shown are the same as those shown when creating the elevator.
Initial Floor
The floor at which the elevator deck will be located at the beginning of the simulation.
Call Distance
The distance away from the elevator door at which an occupant can call the elevator.
Double-Deck
Whether the elevator should use two connected decks to transport occupants. Please see Section 3.9.7 for details.
path ui dialog elevator floor priority
Figure 61. Elevator Priority dialog
path ui dialog elevator levels
Figure 62. Elevator Levels dialog

3.9.4. Nominal Load

The nominal load is an estimate of the number of people that represent a full elevator load. The default value is based on an estimate of how many occupants of default size (diameter = 45.58 cm) would normally fill the elevator in steering mode. Increasing or decreasing the nominal load will cause occupants' sizes to be scaled up or down while they are on the elevator.

The scale factor (default: 1.0) is determined by a correlation to the density produced by the nominal load. This makes it possible to adjust loading while still accounting for differences in individual occupants' size.

In steering mode, the geometry of the elevator can lead to reduced loads (e.g. if the elevator is 2.8 persons wide). Please verify that the resulting (post-simulation) elevator loads match elevator manufacturer recommendations.

3.9.5. Connecting/Disconnecting Floors

When an elevator is created, by default it is connected to every floor its doors touch along the elevator shaft. Individual elevator doors can be disabled, however, to prevent entering/exiting the elevator through those doors on specific floors.

To do so:

  1. Right-click the elevator door on the desired floor from the Navigation View or 3D/2D View.
  2. Select Disable from the right-click menu.

To re-enable it, right-click the door from the Navigation View and select Enable.

Alternatively, right-click an elevator level and select Disable to disconnect all the elevator’s doors on that level, effectively preventing the elevator from picking up occupants on that level.

3.9.6. Call Sets

By default, each elevator is called individually. Elevators can be grouped into call sets, however, so that when one is called, all elevators in the call set respond and travel to the pickup level.

To create a call set:

  1. Create a group in the top Elevators group.
  2. Add the desired elevators to the new group.

All elevators in the group will be in the same call set as shown in Figure 63.

path ui view nav elevator group
Figure 63. Elevator call sets

3.9.7. Double-Deck Elevators

Double-deck elevators use two connected decks to transport occupants, which increases the efficiency of moving occupants between floors. Occupants use a double-deck elevator similarly to a regular elevator.

After calling an elevator, the double-deck elevator arrives at the given floor, and the doors of its two decks open at the two adjacent floors (even and odd). When the decks are loaded, the double-deck elevator moves to the discharge floors.

A double-deck elevator requires two discharge floors, one for each deck. In Pathfinder, the Discharge Floor denotes the lower discharge floor. The upper discharge floor is directly above the lower discharge floor.

After arriving at the discharge floor, the elevator doors of both decks open, allowing occupants to leave both decks of the elevator.

There are several conditions that must be followed when using a double-deck elevator in Pathfinder:

  • The total numbers of elevator levels above and below the pair of discharge levels must be even. However, any non-discharge level can be disabled.
  • The vertical distance between each pair of even and odd level must be equal to the vertical distance between the lower and upper discharge floor, since the distance between the elevator decks is fixed. However, the distances between the different level pairs can be arbitrary.
  • Neither the lower, nor the upper discharge levels can be disabled.

3.10. Exits

In Pathfinder, exits are merely thin doors that exist on the boundary of the model. An exit can only have a room on one of its sides.

Exits are created in almost the same way as thin doors as discussed in the section, Thin doors. The only difference is that the door must lie on an edge of a room, and the edge must not be shared between two rooms.

Exit doors are displayed the same as thin doors except that they are green as shown in Figure 64.

path scrn door exit
Figure 64. An exit door

4. Importing Files

Pathfinder can import a large number of image and CAD formats. Imported files can be used as an aid to more quickly generate the navigation mesh and give more context and visual appeal to a simulation.

4.1. Importing Images

Background images can be imported by clicking Add a Background Image on the Model menu.

  1. When clicked, a dialog will appear prompting for an image file. The following image formats are currently supported: BMP, GIF, JPG, PNG, and TGA. After a file is selected, a new dialog will appear as shown in Figure 65. This dialog allows properties of the image to be specified so that the proper scaling, rotation, and offset can be applied.
  2. An anchor point is specified on the image that indicates where that point is located in 3D space of the model. By default, the point you click will be placed at the origin point (0,0,0) in the model.
  3. To specify the scaling for the image, two points, A and B, and a distance between them can be specified (Figure 66).
  4. To specify the rotation of the image, an angle can be input that specifies the angle of the vector from A to B with the vector (1,0,0). As shown in the figure, the A→B vector should be 90 degrees from the X axis.
  5. Click OK and the image will be placed in the model as specified (Figure 67).
path ui dialog import background anchor
Figure 65. Set the anchor point
path ui dialog import background scale
Figure 66. Set scaling points A and B
path scrn import background
Figure 67. Background image added to the model.

The imported image is added to the Imported Geometry → Background Image group in the Navigation View. The image can be edited and deleted from there.

4.2. Importing CAD Files

Pathfinder can import geometry from several CAD formats, including buildingSMART’s IFC format for building information models (BIM), AutoCAD’s DXF (Drawing Exchange Format), DWG, FBX, DAE, and OBJ files.

Depending on which type of file is imported, Pathfinder also provides various tools to generate the navigation mesh elements such as rooms, doors, and stairs, see Section 4.3.

To import one of these files:

  1. Under the File menu, select Import and select the desired file.
  2. After selecting a file, a step-by-step dialog will open as shown in Figure 68.
path ui dialog import cad units
Figure 68. CAD import dialog (units)
path ui dialog import cad 2d
Figure 69. 2D CAD import options
  1. The first prompt asks whether the CAD data should be imported into the current model or into a new one. Importing into the current model allows many CAD files to import into one Pathfinder model.
    FBX Exporter
    If an FBX file is being imported, the second prompt will ask what software was used to export the file. If a SimLab FBX plugin was used to create the FBX file, choose SimLab from the drop-down box; otherwise; choose Unknown. This selection controls the default settings in the subsequent prompts. In some cases, Pathfinder is able to detect whether the file was exported using a SimLab plugin and will select this option automatically.
  1. Units: Select the base unit in which the CAD file was created. If the drawing was saved in a more recent file format, the prompt will default to the unit type stored in the file. The dialog box shows the model’s width, depth, and height based on the selected unit as a guide for selecting the unit.
  2. Import Settings: The next prompt allows the user to control how some of the data is imported and to correct some data that may have been written incorrectly by the file’s CAD exporter.
    Normal Tolerance (DWG/DXF only)
    Controls the quality of curved objects. Decreasing this value produces higher quality objects at the expense of slower rendering speed. The default value of \(15^{\circ}\) provides a nice balance.
    NURB Gridlines (DWG/DXF only)
    Controls the quality of NURB surfaces. Increasing this value gives higher quality curves at the expense of slower rendering speed. The default value of \(5\) provides a good balance.
    Auto-correct inverted polygons
    Some CAD files contain information about the normal of a polygon that affects how the polygon is lit. In some cases, the normal may not match the orientation of the polygon, which can cause the polygon to appear too dark. Selecting this option will allow Pathfinder to try to detect these cases and correct the orientation of the polygon so it may be lit correctly. This option works well in most models and is generally safe to leave on.
    Crease Angle
    Some CAD files do not provide lighting data for objects to determine whether they should look smooth or faceted. In this case the crease angle is used to determine this information. If the angle between two adjacent faces is greater than this value, the faces will be look like they are two separate, faceted faces. Otherwise, the two faces will look like one smooth curved face. This option may also affect whether the edges of faces are displayed when the Show Object Outlines option is enabled as explained in Section 2.3.1.
    Merge identical materials
    Some CAD exporters (namely SimLab’s Revit FBX plugin) will create a unique material per object in the file, which may lead to hundreds or thousands of materials that have duplicate properties. Selecting this option allows the materials with duplicate properties to be merged into one material, significantly reducing the number of materials in the model with no loss of quality. The only disadvantage to using this option is that some selection granularity is lost when using the Select All by Material action as more objects will be assigned the same material.
    Ignore transparency color (FBX only)
    In FBX files, material transparency is determined from a transparency color and factor. Some CAD exporters (SimLab’s FBX plugins) export the color incorrectly. Selecting this option will allow Pathfinder to ignore the transparency color in the FBX file and only use the transparency factor, which allows transparency in these files to import correctly. This option should only be selected if it is known that the file came from a SimLab plugin or there are transparency problems without it selected (For example, objects that should be transparent are not or vice versa).
    Object Grouping (IFC only)
    Specifies how objects will be grouped once imported into Pathfinder. The value can be one of the following:
    Spatial (default)
    The objects are grouped based on the spatial layout of the model. For instance, the top group is the building site, the next group is the building, the next are the floors, etc.
    By Type
    Objects are grouped by type. For instance, there will be a group for walls, furniture, slabs, etc.
  1. Options: This prompt allows the user to specify more options for import. Before this prompt is shown, Pathfinder will attempt to discern if the CAD file contains a 2D Floorplan or a 3D Model and will select default values for the options based on the detected type.
    Lines
    Check to import lines in the file (default=checked only for floorplans.)
    Faces
    Check to import faces in the file (default=checked only for 3D models.)
    Geometry Offset
    Will offset imported geometry on the X, Y, and Z planes by the specified values.
    Flatten so geometry lies in one plane
    If checked, all geometry will be scaled in the Z dimension by a very small scale (1e-9). This is useful for floorplans that have entities drawn in several planes. This option will flatten them all into one plane (default=checked only for 2D floorplans.)
    Add a blank rectangle to obscure lower floors
    If checked, a solid rectangle of the specified color will be added to the model. This is useful to obscure geometry located on lower floors. The imported rectangle will have its Import Type set to <ignored> by default so it does not contribute to generating the model as described in Section 4.3, (default=checked only for 2D floorplans.)
  1. Choose Finish to import the file.

All imported elements will be added to the "Imported Geometry" node in the Navigation View. If the CAD file was a DWG or DXF, the grouping structure will include the model level, the layer level, and all entities distributed within the layer. For IFC files, the grouping is determined by the Object Grouping setting as specified above. For other CAD files, the grouping structure will match the node structure in the file. If both lines and faces were included in the import and an entity contained both lines and faces in the CAD file, the entity is split into two in Pathfinder - one with the lines, and one with the faces.

While this option is no longer available, both imported line and face data is now sent directly to the 3D results viewer instead, eliminating the need for a background image.

4.2.1. Imported Objects

When a CAD file is imported, there may be many resulting objects. Depending on the type of imported file, there are various levels of information that may be imported for each resulting object. Each object has a name and always includes some geometric information, such as the 2D curves or 3D faces composing the object. For some files, such as IFC files, there may be even higher-level information such as whether the object is a door and the door’s width. Pathfinder uses this information to generate model elements as described in Working with Imported Data.

Common to all import objects is the ability to set some visual properties, such as color and opacity for each component of the geometry. The imported geometry is sent as-is to 3D Results, resulting in a clean and fast graphical representation of the data.

When an imported object is selected, its property panel appears as shown in Figure 70.

path ui props geom ifc
Figure 70. Imported IFC object’s property panel

Imported objects have the following properties:

Visible
Whether the object is currently being shown in the 3D or 2D view.
Material
The material applied to the selected faces when the Show Materials option is turned on. Clicking the material button will open the Material Dialog as shown in Figure 83. In this dialog, the material can either be edited or a new material can be applied to the faces by selecting one from the list on the left and clicking the OK button. To remove the reference to the material, select the <No Material> option from the material list.
Color
The color of the selected objects when they have no material or the Show Materials option is turned off.
Opacity
The opacity of the selected objects when they have no material or the Show Materials option is turned off.
X, Y, Z Bounds
The bounds of the object’s geometry.
Object Type
The object’s originating type as specified in the imported file. For IFC files, this is the object’s IFC Entity type, such as IfcRoof. This value cannot be changed.
Import Type
Specifies how the object is to be treated when automatically generating the model as described in Section 4.3.1. Pathfinder chooses the value for this property during import. For more information on how the Import Type is chosen, see the section for each import file type (see Section 4.2.2).
Generate Model from BIM Selection
This action attempts to generate a Pathfinder model from the selected imported objects. For more information, see Section 4.3.1.

4.2.2. Importing IFC Files

IFC files provide building information model (BIM) data in a fully 3D format. This format contains advanced data about the types of objects in the building, including slabs, stairs, doors, etc., and it provides the smoothest workflow for converting imported objects into Pathfinder elements (see Section 4.3.1). It is also supported as an export format for many architectural CAD packages, including Revit.

When exporting an IFC file from another CAD package, such as Revit, it is preferable to use the IFC 2x3 Coordination View, though other IFC views should work as well.

Each object imported from an IFC file corresponds with an IFC Entity instance. Currently, only instances with 3D geometry are imported. In addition, openings (holes) are pre-subtracted from objects, and the openings are not imported as objects. For example, a wall in the IFC file might be associated with an opening object for a window. When importing, Pathfinder will subtract the opening’s geometry from the wall geometry and only import the resulting wall. The window would additionally be imported as a separate object.

The Object Type for each object is set to the object’s IFC Entity type, such as IfcWall. The Import Type is chosen automatically based on the object’s Object Type and possibly other properties specified in the IFC file. For instance, an IFC object with entity type, IfcCovering has an associated PredefinedType property that specifies what kind of covering it is, such as a wall covering or floor covering. For floor coverings, Pathfinder will automatically set the object’s Import Type to Floor during import. Other types of coverings become Obstruction.

Table 2 specifies how the Import Type is chosen for imported IFC objects:

Table 2. IFC Import Type for IFC Objects
IFC Entity TypeIFC Predefined TypeObject NameImport Type
IfcBuildingElementProxy"Path of Travel" "RPC Male" "RPC Female"<ignored>
IfcCoveringFLOORINGFloor
IfcDoorDoor
IfcElementObstruction
IfcRampFloor
IfcSlabFloor
IfcStairStair
IfcTransportElementESCALATORStair
IfcTransportElementMOVINGWALKWAYFloor
<all others><ignored>

The IFC Entity Type includes derived entities unless specifically listed in the table. For instance, IfcElement includes IfcBeam, IfcColumn, etc., since those entities derive from IfcElement and are not listed in the table. IfcElement does not, however, include IfcDoor since IfcDoor is in the table. In addition, IfcDoor includes both IfcDoor and IfcDoorStandardCase since IfcDoorStandardCase is derived but not listed.

4.2.3. Importing DXF Files

DXF is a basic CAD format provided by Autodesk. This format supports basic geometry types, including 3D faces, lines, and text, but it does not support material information, such as textures, lighting parameters, etc.

Import Type for all DXF objects is Obstruction. In order for the Import Type to be more useful, it must be set manually. Some suggestions for doing so are given in Section 4.3.1.

4.2.4. Importing DWG Files

The DWG format is similar to DXF, but it also has basic support for materials, including textures. It has only basic support for mapping textures onto objects, however, and few CAD applications can export DWG files. Some, such as Revit, exclude material and texture information (see more information in Importing Revit Files below).

Import Type for all DWG objects is Obstruction. In order for the Import Type to be more useful, it must be set manually. Some suggestions for doing so are given in Section 4.3.1.

4.2.5. Importing FBX Files

FBX provides support for 3D faces only, but it has very good support for material information and materials mapping. In addition, many 3D modeling applications have built-in support for exporting FBX files.

Import Type for all FBX objects is Obstruction. In order for the Import Type to be more useful, it must be set manually. Some suggestions for doing so are given in Section 4.3.1.

4.2.6. Importing PyroSim and FDS Files

PyroSim and FDS files provide objects with 3D faces. If the imported file contains holes, the holes will be automatically subtracted from the solid obstructions and discarded. If the file contains grids, the grids will be intersected with each other as FDS would, and the remaining faces of the grids will be imported. If the file contains OPEN vents, the vents will be subtracted from the appropriate grid faces and discarded.

Import Type for all PyroSim and FDS objects is Obstruction. In order for the Import Type to be more useful, it must be set manually. Some suggestions for doing so are given in Section 4.3.1.

4.2.7. Importing Revit Files

While Pathfinder cannot directly import Autodesk Revit files (RVT), there are several ways to export the data from Revit into a file format that Pathfinder can read. Each method has advantages and disadvantages as discussed below.

4.2.7.1. Revit to FBX using third-party plugin

This method requires the use of a third party plugin, but it generally produces good results with materials, textures, and texture coordinates well-supported. In many cases, this is the most reliable method of reproducing the graphical representation of the original Revit file within Pathfinder. SimLab Soft is one company that provides commercial FBX export plugins for several CAD packages, including Revit and Sketchup, among others, and provides robust texture support.

To export using a third-party plugin, perform the following:

  1. Download and install the appropriate plugin.
  2. Follow the plugin’s instructions to export an FBX file from Revit. If the plugin supports embedded media, select this option before exporting. This option allows textures to be embedded into the FBX file, making it much easier to transfer the FBX to another computer, as only file has to be transferred.
  3. If the FBX file is to be imported into Pathfinder on the same computer as the one that exported the file or the embedded media option was selected, continue to the next step; otherwise, some additional steps may be necessary to ensure the textures can be found when importing into Pathfinder:
    1. Determine the directory into which the FBX exporter saved the textures. Some exporters may place the textures in a sub-directory of the FBX file and give it the same name as the FBX file. Others may save the textures to a common program-specific location. The SimLab Revit exporter, for example, saves textures for a particular file to C:\ProgramData\Autodesk\Revit\Addins\SimLab\FBXExporter\data\Imported_Textures\# where # is a number specific to the exported file, such as 40.
    2. If the folder is not already a sub-directory of the FBX file, cut this folder and paste it in the same location as the FBX file. The pasted folder may be left as is or renamed to be the same as the FBX file, without the .fbx extension.
    3. Transfer the FBX file and the texture folder to the computer that will be importing the FBX file into Pathfinder.
  4. Import the FBX file into Pathfinder.
4.2.7.2. Revit to IFC (direct)

The first method exports a building information model (BIM) in the industry foundation classes (IFC) format. For more information on the IFC format, see Section 4.2.2.

To perform the export in Revit 2019, perform the following:

  1. Open the desired RVT file within Revit.
  2. Under the File menu, click Export→IFC.
  3. Choose the desired IFC filename.
  4. Click Modify setup to choose different export settings, if desired.
  5. Click Export to save the file.
  6. Import the IFC file into Pathfinder.
4.2.7.3. Revit to DWG (direct)

This method exports a DWG file directly from Revit, which can then be imported into Pathfinder. While simple to perform and only requires Revit, this method loses all information about materials, including textures, due to Revit’s limited DWG support.

To perform the export in Revit Architecture 2014, perform the following:

  1. Open the desired RVT file within Revit Architecture.
  2. Click the Revit icon at the top left revit ui icon.
  3. Select Export→CAD Formats→DWG.
  4. In the DWG Export dialog, for Export, select <In session view/sheet set>.
  5. For Show in list, select Views in the Model.
  6. Click the Check None button, and then in the view table, select the check box for 3D View (Other views may be chosen, but the DWG will only contain entities visible in the selected views).
  7. Click Next and choose a file name for the DWG file.
  8. Click OK to create the DWG.
  9. Import the DWG into Pathfinder.
4.2.7.4. Revit to FBX (direct)

This method exports an FBX file directly from Revit, which can then be imported into Pathfinder. As with exporting a DWG, this method is simple to perform and only requires Revit. Unfortunately, this method also loses all information about materials and textures because Revit encrypts the material data, making it unreadable by Pathfinder.

To export using Revit Architecture 2014, perform the following:

  1. Open the desired RVT file within Revit Architecture.
  2. Click the Revit icon at the top left revit ui icon.
  3. Select Export→FBX.
  4. Choose a file name for the FBX file.
  5. Click OK to create the FBX.
  6. Import the FBX into Pathfinder.
4.2.7.5. Revit to FBX to AutoCAD to DWG

This method requires both Revit and AutoCAD and does not perform a perfect conversion, but it retains some information about materials and texture coordinates.

The steps described here use Revit Architecture 2014 and AutoCAD 2014:

  1. Open the desired RVT file within Revit Architecture.
  2. Click the Revit icon at the top left revit ui icon.
  3. Select Export→FBX.
  4. Specify the desired filename and click Save.
  5. Open AutoCAD.
  6. On the Insert tab in the ribbon, select Import.
  7. Select the FBX file created by Revit.
  8. The FBX Import Options dialog will appear, see the recommended settings below.
  9. Click OK to finish the import. You may receive a warning about the clip plane of the camera.
  10. Save the file as a DWG.
  11. Import the DWG into Pathfinder.

The following are recommended settings for the FBX import:

Import section
Make sure Objects and Materials are checked. Lights and Cameras are unused in Pathfinder.
Assign Objects to Layers
Any option may be selected, but By Material is a useful option for Pathfinder.
Unit Conversion
This section is somewhat misleading. While the Current Drawing Unit is correct, the FBX file unit tends to be incorrect. No matter what unit is displayed in the greyed-out text for FBX file units, the actual unit in the FBX file is always FOOT. The appropriate values need to be specified to make the proper unit conversion. For instance, if the current drawing unit is Millimeters, you can enter the value, 1 on the left and 304.8 on the right because there is 1 foot per 304.8 millimeters.
Block
Uncheck Insert file as block.

4.3. Working with Imported Data

Each type of file that can be imported provides an aid for creating navigation geometry. The different types can be worked with in various ways to create the desired rooms, stairs, and doors.

4.3.1. Generate Model Automatically

The easiest way to create a complete Pathfinder navigation mesh, including rooms, doors, and stairs, is to use the Generate Model from BIM action. This action works best with imported IFC files, but it can work with other CAD file types as well, as long as those files contain 3D face data, such as from DXF, DWG, and FBX files. These non-IFC file types require some extra steps as outlined below.

To use this action, perform the following steps:

  1. Import all CAD files that contribute to the model into the same Pathfinder model.
  2. If any of the imported files were not IFC, set the Import Type for the objects imported from those files. These files default all objects to the Import Type, Obstruction, so this only needs to be done for non-Obstruction objects.
    Some fast ways to do this include:
    1. If the imported objects are grouped together in the navigation view by type, select the group containing the objects such as the one containing all the doors, and set the Import Type in the property panel to Door.
    2. If the imported objects contain the object type in their name, such as Door43, use the search tool (Edit→Find) to select all with the text Door in the name. Then set the Import Type to Door on the whole selection.
  3. Delete any objects that should not contribute to the Pathfinder model or set their Import Type to <ignored>. This may be necessary, for instance, if the file contained stand-in objects, such as the building envelope.
  4. In the Model menu, click Generate Model from BIM. This will show the Generate Settings dialog as explained in Section 4.3.1.2.
  5. Set the desired properties for generating the model, and click Generate. This will generate rooms, stairs, and doors for the entire imported model.
  6. If any exits still need to be added, do so manually.
  7. There may be extra detached rooms that are not needed in the model. An easy way to remove these is to first right-click a room that should be in the result, and click Select Connected Components from the right-click menu. Select the Entire graph option in the dialog, and click OK. Hide the selected objects. Repeat this until all required components have been hidden. The remaining extra rooms can be selected and deleted.

If only a subset of the imported objects needs to be modeled in Pathfinder, either set the Import Type for unnecessary objects to <ignored> before generating the model with the above steps or perform the following instead:

  1. Select the imported objects that should be turned into navigation elements. The selection does not have to include objects with Import Type set to Obstruction, as obstructions are automatically subtracted during model generation.
  2. Right-click the selected objects, and from the menu, click Generate Model from BIM Selection.
  3. In the Generate Settings dialog, enter the desired settings and click Generate.
4.3.1.1. Generate Process

The following table describes how Pathfinder converts imported objects into Pathfinder navigation elements based on their Import Type and any additional properties that may have been imported along with the object:

Table 3. Import types to Pathfinder Navigation Elements
Import TypePathfinder TypeDetails
<ignored> – These objects are completely ignored when generating the model.
DoorDoorTo generate a Pathfinder door, Pathfinder first obtains the geometry of the imported door that will define the shape of the Pathfinder door. If the imported door has an associated wall opening, the wall opening’s geometry is used. If not, the door’s geometry is used. The minimum bounding rectangle of the geometry is then used to define the Pathfinder door shape. If the door’s geometry was used and the door has an associated opening width property, the resulting door will be no wider than this opening width. The minimum bounding rectangle is then extruded into a box such that the bottom of the box is slightly below the bottom of the source geometry and the top is slightly above the top of the source geometry. This box is then subtracted from the generated rooms, and a Pathfinder door is used to fill the gap.
EscalatorStair and Room

The conversion is performed the same as for Import Type Stair. If the resulting stair must be treated as an actual escalator, its properties must be set after generating the model. See Section 3.7 for more information.

FloorRoom

Pathfinder will identify the potential walking surfaces of the imported objects. It will then identify all potential obstructions and subtract them from the walking surfaces. NOTE: With the exception of objects with Import Type, Door and <ignored>, all imported objects are treated as obstructions to flow, even if they don’t have Import Type, Obstruction.

Moving WalkwayRoom

The conversion is performed the same as for Import Type Floor. If an actual moving walkway is needed instead of a room, delete the generated room and create a moving walkway as described in Section 3.8.

Obstruction – These objects do not directly become Pathfinder objects. Instead they become either holes in the rooms or thin boundary walls.
RampRoom

The conversion is performed the same as for Import Type Floor. If an actual ramp is needed instead of a room, delete the generated room and create a ramp instead as described in Section 3.6.

StairStair and RoomTo generate a Pathfinder stair, the imported object’s steps are first generated as if they were rooms. Like with rooms, overhead obstructions, such as railings, are subtracted from them. After this, the steps of the stair are connected together using Pathfinder stairs. If multiple steps can be strung together in a row and have similar rise and run characteristics, they all become one stair. Otherwise, they are separated into multiple stairs so that each stair has similar rise/run to the underlying imported geometry. This process may leave part of the stair geometry, such as the landings, as rooms.
4.3.1.2. Generate Settings

When using the Generate Model from BIM action, various settings can be specified in the Generate Settings dialog as shown in Figure 71.

path ui dialog bim generate settings
Figure 71. Generate Settings dialog

The following settings are available in the Generate Settings dialog:

Max Slope
Determines the maximum slope of a floor to be considered as a walkable surface. A slope of 0° indicates a flat surface, while a slope of 90° is vertical.
Max head height
The maximum height for objects to be considered overhead obstructions. Overhead obstructions are used to cut out portions of the resulting rooms to prevent occupants from walking in that space. Imported objects higher than this will not be counted as obstructions.
Generate from tops of solids
If checked, walkable surfaces will only be generated from closed, solid objects if the surface is on the top of the solid (i.e. there are no other surfaces in the object above it). This helps reduce the number of surfaces that will be considered for generating rooms, which also reduces the computation time. The result should be the same, however, if this is checked or unchecked. If it seems like any rooms are missing from the result, try unchecking this option.
Exclude rooms in solids
If checked, rooms that were generated inside solid objects such as walls are excluded from the result. This helps reduce the number of resulting rooms. If any rooms appear to be missing from the result, try unchecking this option.
Close gaps smaller than x
If checked, thin boundary edges are inserted into a room anywhere where there are room boundaries close together. This is useful in combination with Exclude rooms with area less than x to reduce the complexity of the model.
Exclude rooms with area less than x
If checked, rooms with small area are excluded from the result. This is useful in combination with Close gaps smaller than x to reduce the complexity of the model and remove portions where an occupant would not walk, such as between a desk and wall.
Use imported names
If checked, the resulting navigation elements (rooms, doors, stairs) will be named after the imported object from which they derived. Otherwise, a generic name will be used.
Generate doors

If checked, adds Pathfinder doors to the navigation mesh from the imported doors.

Generate stairs

If checked, adds Pathfinder stairs to the navigation mesh from the imported stairs.

Max vertical step distance
The maximum allowed distance in the Z direction between steps of a stair. If an imported stair contains any consecutive steps further away than this, they will not be connected.
Max horizontal step distance
The maximum allowed distance in the XY direction between steps of a stair. If an imported stair contains any consecutive steps further away than this, they will not be connected.
Min stair width
The minimum width of resulting stairs. If an area that looks like a stair is narrower than this distance, it will not result in a stair.
4.3.1.3. Limitations

While the Generate Model from BIM action can quickly provide a good starting point for a Pathfinder simulation, it does have some limitations, including:

  • Escalators are only supported as Pathfinder stairs. Their speed and direction are not determined during extraction.
  • Moving walkways are only supported as Pathfinder rooms. Their speed and direction are not determined during extraction.
  • Elevators are not currently supported.
  • Generated doors may be slightly wider than the actual door opening. This is because the shape of the door is determined from either the imported door’s associated wall opening or the door geometry. In the former case, the actual door opening may be slightly smaller than the wall opening due to the door jam. In the latter case, the door geometry often includes door trim, which may be several inches wider than the actual door opening. In addition, some CAD packages may export a curtain wall door with windows on the side as one door object. In this case, the resulting door may be quite a bit wider than the actual door opening because the wall opening/door geometry would include the side windows.
  • Pocket doors might be twice as wide as they should be since their opening may include the space inside the walls.
  • Doors might be thicker/deeper than the surrounding wall if the CAD package that exported the IFC file uses deep wall openings rather than openings that are just deep enough to cut out an opening in the wall. This should not significantly impact the simulation unless the opening is extremely deep.
  • The presence of a door threshold may prevent a door from generating correctly.
  • Pathfinder stairs are only generated from objects marked with the Import Type, Stair. Some objects, such as steps in a stadium might look like stairs but are actually marked as floors. In this case, stairs will not be automatically generated, and will look like small, disconnected rooms instead.
  • Pathfinder may treat some objects as obstructions that should not participate in the extraction process, such as a stand-in object representing the building envelope. This is caused by limitations in the IFC format or the exporting CAD package, where these objects are marked with the entity type, IfcBuildingElementProxy. This type is merely a stand-in data type for objects not inherently supported by the IFC standard. They may or may not be physical objects in the model, and there is currently no way to differentiate, so Pathfinder treats them all as obstructions.
4.3.1.4. Troubleshooting CAD Import

Depending on the imported CAD data, some problems may arise when generating the Pathfinder model. Table 4 below may help determine the source of the problem and resolve it.

Table 4. CAD Import Problem, Cause and Solution
ProblemCauseSolution
There is a wall in the middle of a generated room where there was no obstruction or there is a gap between rooms when they should be connected.The wall/gap might actually be a very thin gap that exists between adjacent imported slabs. Pathfinder does not currently close these small gaps automatically.Either draw a door along the edge that bridges the gap or adjust the geometry of the rooms and merge them together.
A generated door should connect two rooms but is an exit instead.This can happen if the imported door had no associated wall opening, the door’s geometry was thinner than the surrounding wall, and there is no slab or other floor object under the door.Select the door and use the manipulation tool to connect the door to the other side of the door opening.
A generated door appeared where it wasn’t expected.This may happen if a single door was broken into several pieces and/or objects were marked as doors that weren’t actually doors. For instance, this might happen if the door trim is modeled as a separate object than the actual door, and the trim is also marked as a door. In this case, the piece of trim is modeled as a separate door.Delete the door and draw manually instead.
A generated door was too small.This is usually caused by the same problem as above.Select the door and change the Width in the property panel to the desired size or delete and redraw the door if this does not work properly.
A generated door was too wide.This can happen due to limitations in the door extraction algorithm, see Section 4.3.1.3.Select the door and change the Width in the property panel to the desired size.
A door is missingThe imported object’s Import Type was not set to Door, or the door had no walking surface under it, did not have an associated wall opening, and was thinner than the surrounding wall. This might also happen if there is a door threshold.Draw the door manually.
A room is missingThis may either be because the imported object defining the floor did not have its Import Type set to Floor or the Exclude rooms in solids option was turned on and there is a solid object in the model marked as an obstruction that should not be in the model, such as one representing the building envelope.Undo the import, ensure the imported object’s Import Type is set to Floor, and delete any objects that should not be in the model. Then try generating the model again. If this still does not work, draw the room manually.
A stair is missingThe imported stair object was not marked as a Stair or the step distances exceeded the limits set in the generate settings.Undo the import, set the Import Type to Stair, and then perform the Generate Model from BIM action again, or draw the stair manually.
An imported stair was broken into several Pathfinder stairs.This can happen if an imported stair does not conform to a Pathfinder stair, such as with spiral stairs. This might also happen if there are multiple directions from which an occupant could step down off a step of the stair. Another cause could be that the step rise/run changed drastically from one step to another, such as if the top or bottom step does not align exactly with the connecting slabs.If the stair should have been generated as a single Pathfinder stair, delete the generated stairs and draw the stair manually.
The steps of the generated stair do not match the steps of the imported stair exactly.This can happen if the steps of the imported stair do not have a consistent step height or tread depth or the imported stair did not line up exactly with the slabs it was connecting. In this case, Pathfinder averages the rise/run of the resulting steps over the entire rise/run of the stair, which may cause the steps to be slightly out of alignment with the imported stair.If desired, select the Pathfinder stair and change its step rise/run in the property panel.
An elevator is missing.Generating elevators is not currently supported.Create the elevator manually, see Section 3.9.
An escalator has extra steps off of the side.Escalators are generated as stairs. Pathfinder generates stairs using a generic algorithm where any flat surface can be treated as a step. If some of the geometry looks like it might be a step, Pathfinder will create a stair going to it.Delete the extra stairs.

4.3.2. Extract Rooms Individually

While automatic model generation should work for most 3D CAD files, it may not always produce the desired result, the user might want more control over the rooms that are generated, or it might just be too prohibitive to set the Import Type for some non-IFC CAD files.

Pathfinder provides an Extract Room tool path ui icon room extract that can address these issues. This tool allows rooms to be extracted individually using a flood-fill algorithm. While it may take more effort to extract all the necessary rooms, it does not require objects to have an Import Type specified unless an object is to be ignored.

To use the Extract Room tool:

  1. Select the tool from the drawing tool panel on the left of the 3D or 2D view. The tool properties are shown in Figure 72.
    Max Slope
    Refers to the maximum grade that a person can walk on. Only imported polygons that have a slope less than this will be included in the result.
    Max Head Height
    Refers to the maximum height of all the agents that will be included in the simulation. This parameter is used to subtract overhead obstructions from the resulting room.
    Gap Tolerance
    Provides some control in dealing with imperfections in the imported data. If walls are closer than the gap tolerance, Pathfinder will add an extra thin wall in that area, helping to split of rooms so the result does not bleed into undesired areas.
path ui props room extract
Figure 72. Property panel for the Extract Room tool
  1. Once the appropriate parameters have been chosen, either enter a location on the floor of the desired room into the property panel or click this point in the 3D or 2D view.
  2. If this point does not have any overhead obstructions within Max Head Height and the point is on a polygon with a slope less than Max Slope, Pathfinder will march out from this point on the imported geometry’s polygons until it finds the boundaries of the room. It will also subtract overhead obstructions within Max Head Height from the resulting room.

Below is an example of a 3D CAD model Figure 73 and a room extracted from it Figure 74.

path scrn cad 3d
Figure 73. Example CAD model
path scrn room extracted 3d
Figure 74. Room extracted from the CAD model

When using the extract room tool, Pathfinder will include all imported geometry with faces, even if hidden. If an object must be excluded from room extraction, the object’s Import Type must be set to <ignored> before performing extraction. Otherwise, this tool completely ignores the Import Type of the objects.

4.3.3. Working with 2D CAD

2D CAD data can be worked with in two ways:

  • It can be used as a guide for drawing rooms similarly to background images with the added benefit of being snapped to
  • It can have rooms extracted from it similarly to 3D imported geometry as described above.

To sketch the rooms using the built in drawing tools, refer to Section 3.2.

Extracting rooms from 2D CAD data works similarly to extracting rooms from 3D CAD data. As in 3D extraction, the Extract Room tool path ui icon room extract is used. In addition, the user must click a point in the model with the tool, and one room will be extracted.

The main difference from 3D extraction is that the clicked point must not lie on any 3D imported faces marked for room extraction; instead it must be in empty space (or on the background rectangle imported with a 2D floorplan). The clicked point should also be surrounded by imported 2D lines. These lines will form the boundary of the resulting room. For this reason, any lines that do not contribute to the room’s boundary, such as notations, symbols, etc. should be deleted, hidden, or excluded from room extraction prior to clicking the extraction point.

To manually exclude imported geometry from floor extraction, select the geometry and from the property panel, set the Import Type to <ignored>. When determining which imported geometry to extract rooms from, the 2D room extraction tool will automatically exclude hidden objects and those manually ignored.

Once the desired point is clicked, the surrounding 2D lines looking at the model from the Top View will be projected along the Z axis onto the active floor’s working Z plane. These projected lines will then be used to define the room around the clicked point. If the surrounding lines do not form a closed boundary as shown in Figure 75, the resulting room will spill outside of the lines and form a room around the bounding box of all the lines as shown in Figure 76. In this case, this outer portion of the room can be separated from the inner portion using the Thin Wall tool as discussed in Section 3.3.2. Once separated, the outer portion can be deleted.

When the extraction tool is finished finding a room, the room will lie in the working Z plane of the active floor.

path scrn cad 2d
Figure 75. Imported 2D CAD drawing
path scrn room extracted 2d
Figure 76. Floor extracted within bounding box.

4.3.4. Working with Images

Working with background images requires the user to draw all rooms, doors, and stairs over the background image (Figure 77). Because the drawn navigation geometry will cover the background image, it may be preferable to make the navigation geometry transparent. This can be accomplished by selecting the drawn navigation components and lowering the opacity in the property panel. Figure 78 shows a background image with rooms and doors drawn on top, with a lowered opacity for the drawn rooms.

path scrn cad background image
Figure 77. Imported background image
path scrn room traced background image
Figure 78. Rooms drawn over image

To draw rooms on top of a background image, refer to Section 3.2.

4.3.5. Filling in Missing Pieces

Once rooms have been extracted using the Extract Room tool, the model will still be missing doors and stairs (Figure 79). Doors and stairs must be added manually as discussed in Section 3.4 and Section 3.5 of this guide.

One feature that may be of particular interest to help this process, however, is the internal door feature of the door tool. This feature automatically finds areas within a room that look like potential doorways and can be used to create a thick door in this area.

To use this feature:

  1. Select the door tool.
  2. In the property panel for the tool as shown in Figure 42.
    Max Width
    Refers to the maximum width of the doorway to search for.
    Max Depth
    Refers to the maximum thickness of the doorway. These numbers may need to be larger than for the normal creation of a door to find potential doorways.
  3. Once the appropriate parameters have been entered, move the cursor over the desired doorway (Figure 80). A door preview will be displayed. If it doesn’t, adjust the search parameters in the property panel and try again.
  4. If the door appears correctly, left click the mouse button. The doorway area of the room will be subtracted from the room, and the thick door will be created in its place (Figure 81).
path scrn door gap
Figure 79. Doorway wall gap
path scrn door gap click
Figure 80. Click inside the gap
path scrn door gap created
Figure 81. New door in the gap

4.3.6. Flattening and Z Location

Sometimes when importing from 3D CAD models, extracted rooms may not be at the proper height or may have some undesired slope. These issues can be corrected either before or after extracting rooms by using the Set Z dialog (Figure 82).

To do so, follow these steps:

  1. Select the objects that need to be corrected.
  2. Right-click the selection and select Set Z.
  3. This will open the Set Z dialog as shown in Figure 82.
  4. Set the desired options, and select OK to modify the geometry in the selection.
path ui dialog set z
Figure 82. Set Z dialog

The dialog shows the following properties and options:

Selection Bounds
Shows the minimum and maximum Z locations of the selected objects.
Flatten Objects
If selected, each object in the selection will be flattened so that all of its geometry lies in the same plane. The location of the plane is determined by the Move to option.
Move to
This specifies how the geometry should be moved in the Z direction. This can be one of the following values:
Absolute Z
All the selected objects will be moved to the same Z plane. If Flatten Objects is not selected, each object is moved such that its minimum Z touches the specified plane.
Z Offset
Each object in the selection is moved by the specified Z Distance. If Flatten Objects is selected, the object is first flattened to the plane that touches the minimum Z of the object’s original geometry, and then moved by the Z Distance. \(z=z_{\text{offset}}+z_{\text{multiplier}}*n\)

4.3.7. Materials

Materials define advanced display properties that can be applied to faces contained in the imported geometry. They are only shown when the Show Materials path ui icon toggle materials option is selected in the 2D View or the 3D View, see Section 2.3. Materials can be shared among faces; when a material is edited, all faces referencing that material are updated.

Materials are extracted from import files in different ways, depending on the file type:

DWG, FBX, DAE, OBJ
These files have a concept of materials. Each material that is referenced by an object in the file will be imported into Pathfinder. Currently, Pathfinder supports the diffuse color, diffuse texture, opacity color, ambient color, specular color, and emissive color settings of the material. Only the diffuse color and texture can be changed in the material dialog, however.
FDS and PSM
Pathfinder materials are constructed from the color and texture settings of the surfaces in these file types.

To see the materials that have been imported from the DWG or PSM file, on the Model menu, select Manage Material Database. The Material Dialog will appear as shown in Figure 83.

path ui dialog materials
Figure 83. Materials dialog

Pathfinder provides some default database materials. Most of these materials start with the prefix, psm_ as in PyroSim. Other materials were either created manually by the user or were imported with the CAD or PyroSim file.

Materials can be added manually by clicking Import under the material list. Currently, a new material must be created from an image on disk that defines the texture of the material. The image is copied into the database directory. Newly created materials are added to the database, and can be used across instances of Pathfinder.

Materials that were imported are only stored in the current Pathfinder file. They are not available when a new model is created, and there is currently no way to import these into the database.

Materials can be deleted by clicking Remove under the material list. If the material exists in the database, all its associated files in the database directory will also be permanently removed.

The following material properties can be edited:

Color
Selecting this option makes the material a solid color.
Texture Image
Selecting this option makes the material show a texture image.
Width and Height
Define the dimensions of the texture image in the model. For instance, if the image depicts a 4x4 array of bricks with no mortar, and each brick is 8"x3", the Width would be 32" and the height would be 12".
Opacity
Defines the opacity of the material.

4.3.8. Reorganizing and Making Fast Edits

Sometimes the imported data may not be organized in a convenient manner. For instance, it might be desirable to change some feature of all the windows, but the windows in the model may not be in the same group, making it difficult to select all of them at once.

In cases such as these, the similar objects may have the same color. If so, right click one of the objects, and choose Select All by Color. Alternatively, choose Select All by Material. This will find all objects with the same color or material and select them, making it easy to change some shared property or move them into another group for easy selection later.

4.4. Importing FDS Output Data

Pathfinder can use the PLOT3D data output from FDS to create time history data for each occupant as they move throughout the simulation. In cases where FDS PLOT3D output data is available for \(CO\) Volume Fraction, \(CO_{2}\) Volume Fraction, and \(O_{2}\) Volume Fraction; Pathfinder will also output Fractional Effective Dose (FED) for each occupant specified.

FDS data integration is a measurement only and does not alter the movements or decision making within the Pathfinder simulation. However, enabling this feature causes simulations to require additional runtime because of the additional processing load relating to reading the FDS output files and mapping PLOT3D data to occupants.

To enable FDS Integration:

  • On the Simulation menu, click Simulation Parameters.
  • On the FDS Data tab, select Enable FDS Integration.
  • Click Edit and select the SMV file from the FDS simulation of interest.

The dialog (Figure 84) will display information about the attached SMV file and indicate which quantities were found.

path ui dialog sim params fds data 2020 2
Figure 84. The Solution Parameters dialog after enabling FDS Integration.
Slowing Occupants in Response to Smoke
By selecting the Occupants Slow Down in Smoke checkbox, the maximum velocity of occupants in a smoke filled area will be limited. This slowing effect uses FDS PLOT3D output for SOOT Visibility in conjunction with the speed-visibility relationships observed in (Fridolf et al. 2019).

For more information about how Pathfinder computes the maximum walking speed of occupants in smoke, see (Pathfinder Technical Reference, n.d.).

Measuring Occupant FED
The parameter, Hypoxia FED Threshold, defines the oxygen concentration at which hypoxia contributes to the FED calculation. When oxygen concentration is above the threshold, low \(O_{2}\) hypoxia will not contribute to accumulated FED. The default value of 19.5% prevents misleading FED accumulation for occupants that are in safe conditions. (Pathfinder Technical Reference, n.d.)

To enable FED and PLOT3D quantity output for one or more occupants:

  1. Select one or more occupants
  2. In the selection editor, click More
  3. In the Additional Occupant Properties dialog, on the Output tab, enable Print CSV Data
  4. In the Print CSV Data dropdown, select Yes

Once the simulation has completed, CSV data is available for each specified occupant in the output folder. See Section 12.8 for more information on the CSV data.

For information on how FED is calculated or how its use was verified in Pathfinder, see (Pathfinder Technical Reference, n.d.) and (Pathfinder Verification and Validation, n.d.) documents respectively.

4.5. Importing Custom Avatars

When viewing occupants as people in either Pathfinder or Pathfinder Results, occupants and vehicles are represented by a 3D avatar. Avatars are chosen in either the Edit Profiles dialog (see Section 5.1) or the Edit Vehicle Shapes dialog (see Section 5.2). While Pathfinder ships with many avatars, they might not cover all modeling scenarios. Custom avatars can be imported into Pathfinder to meet additional requirements.

4.5.1. Custom Avatar Requirements

The following file formats are supported for importing custom avatars:

Occupant Avatars
FBX, DAE
Vehicle Avatars
FBX, OBJ, DAE

Avatar files should follow these rules:

  • There should be one avatar per file.
  • When using an FBX file, if possible, the textures should be embedded in the file; otherwise, the textures will have to be manually copied to the avatar directory (see Section 4.5.5 below). Other file formats require copying textures.

Occupant avatars have the following additional constraints:

  • There should be at least one "animation" where the avatar is in a T-pose or an A-pose or some variation. There can be other animations in the file, but this will adversely affect loading performance.
  • Occupant avatars must be "rigged", meaning there is a joint hierarchy specified in the FBX or DAE file. The rig must be human-like.
  • Joint names in the FBX or DAE file must follow standard conventions used by industry-wide software.
other scrn blender human rigged pose
Figure 85. Example of a "rigged" human character model in the "A" pose in Blender.

4.5.2. Where to Find Custom Avatars

There are a variety of sources for custom avatars. They can either be purchased or downloaded online from third-party vendors specializing in 3D models or they can be created using third-party tools. Pathfinder has been successfully tested with avatars provided from the following sources:

Adobe Fuse
A tool for creating custom avatars with a library of clothing options and other customizable features. Available at https://www.adobe.com/products/fuse.html.
MakeHuman Community
An open source tool for creating 3D characters. Available at http://www.makehumancommunity.org/.
Adobe Mixamo
A free online source for high quality character models and animations. This service provides mostly fantasy characters, but it has some more realistics options as well. Available at https://www.mixamo.com/.

4.5.3. Importing a Custom Occupant Avatar

To import a custom occupant avatar, perform the following steps:

  1. On the Model menu, click Edit Profiles.
  2. In the Edit Profiles dialog, click the list of avatars next to 3D Model to bring up the 3D Model dialog.
  3. In the 3D Model dialog, click the Import button.
  4. Choose the desired file that contains the occupant avatar to import. This will copy the avatar file along with some other supporting files into %APPDATA%/Pathfinder/models/md5/avatarname , where avatarname is the name of the avatar file.

4.5.4. Importing a Custom Vehicle Avatar

To import a custom vehicle shape avatar, perform the following:

  1. On the Model menu, click Edit Vehicle Shapes.
  2. In the Edit Vehicle Shapes dialog, click the list of avatars next to 3D Model to bring up the 3D Model dialog.
  3. In the 3D Model dialog, click the Import button.
  4. Choose the desired file that contains the vehicle avatar to import. This will copy the avatar file along with some other supporting files into %APPDATA%/Pathfinder/models/props/avatarname , where avatarname is the name of the avatar file.

4.5.5. Fixing Avatar Issues

After importing a custom avatar, it may need further adjustments in order to display correctly. The following is a list of recommendations for fixing avatar issues:

Table 5. Custom Avatar Issues
ProblemCauseFix
Avatar has missing textures.Avatar file was an FBX without embedded textures or an OBJ or DAE file.Copy image files from original avatar location to target avatar location under %APPDATA%/Pathfinder/models.
Some or all of occupant avatar body parts do not move during animations.FBX/DAE file might not be rigged or might not follow common joint naming conventions.No fix currently. Contact support@thunderheadeng.com to report.
Avatar is facing the wrong direction.Avatar in originating file was not facing the front.Apply a rotate transform in the BEA file as described in Section B.1.
Avatar is too big/too small.Avatar was not modeled with realistic units or the units were wrong/unspecified in the avatar file.Adjust the scale factor in the BEA file as described in Section B.1.
Avatar is offset from the actual occupant location.Avatar was not located at the origin in the source avatar file with feet on the ground.Apply a translate transform in the BEA file as described in Section B.1.
Avatar appears to slide/skate when walking.Avatar has different proportions than those assumed by the importer.Adjust the naturalspeed for the walking animations in the BEA file as described in Section B.2.2.
OtherAvatar type is unsupported by Pathfinder.Contact support@thunderheadeng.com to report.

4.5.6. Avatar Performance Considerations

The avatars that ship with Pathfinder have been optimized for use in Pathfinder Results, allowing many thousands of occupants to be displayed onscreen at once with good performance. Custom avatars are not optimized for Pathfinder Results, as they contain no level-of-detail information and often have much more detail than is necessary for displaying thousands of occupants. Using custom avatars will likely result in reduced results display performance compared to using avatars supplied by Pathfinder.

Currently the only ways to mitigate this problem are to either limit the number of occupants using the custom avatars or use custom avatars that are designed with low polygon counts and/or low-resolution textures.

4.5.7. Making Avatars Available to Other Pathfinder Users

When avatars are imported into Pathfinder, they are copied into the %APPDATA%/Pathfinder/models/ location, which limits their use to the current user on the current machine. If the results of a Pathfinder model containing these custom avatars are loaded by another user or on another machine, the occupants using the custom avatars will look like the Mannequin model that ships with Pathfinder. To make these custom avatars available to others users, perform the following from the computer and user account from which the avatars were imported:

  1. In File Explorer, navigate to the following location: %APPDATA%/Pathfinder/models
  2. If copying occupant avatars, navigate to md5. If copying vehicle avatars, navigate to props.
  3. Copy the desired avatar folders.
  4. On the machine on which the avatars are to be made available, in File Explorer, navigate to the following: %PROGRAMDATA%/Pathfinder/models. If this location does not yet exist, create it.
  5. If copying occupant avatars, create/navigate to md5. If copying vehicle avatars, create/navigate to props.
  6. Paste from the clipboard.

5. Creating Occupants

In Pathfinder, occupants are defined in two parts: Profiles and Behaviors.

Profile
Defines fixed characteristics of the occupants, such as maximum speed, radius, avatar, and color.
Behavior
Defines a sequence of actions the occupant will take throughout the simulation, such as moving to a room, waiting, and then exiting.

5.1. Profiles

Pathfinder uses an occupant profile system to manage distributions of parameters across groups of occupants. This system helps you control the occupant speed, size, and visual distributions. To edit occupant profiles, you can use the Edit Profiles dialog (Figure 86).

To open the Edit Profiles dialog: on the Model menu, click Edit Profiles, or double-click the word Profiles in the Navigation View.

path ui dialog profile
Figure 86. The Edit Profiles dialog
Description
Provides a place to enter descriptive text. This value is not used outside the Edit Profiles dialog.
3D Model
Provides a way to use a specific set of 3D human models for an occupant profile. When rendering occupants as 3D human models belonging to the current profile, Pathfinder will choose one of the 3D models selected in the 3D Model dialog.

To select 3D models:

  1. Click Edit on the 3D Model row. This will open the 3D Models dialog (see Figure 87).
  2. To enable or disable a particular model, click the model’s icon. If the <hidden> choice is selected, no 3D Model will be shown for the occupant.

By clicking the Import button in the 3D Models dialog, custom avatars can be imported into Pathfinder. See Section 4.5 for more information.

path ui dialog 3d models 2020 2
Figure 87. An example of the 3D model dialog.

5.1.1. Characteristics Tab

Priority Level
Completely relative and higher values indicate a higher priority. For instance, if three occupants meet with assigned priorities of 4, 6, and 12, they will behave the same as if their priorities were 0, 1, and 2, respectively. This allows occupants of lower priority to move out of the way of those of higher priority. This would be useful when simulating first responders that must be able to move easily through a crowd of occupants.
Shape
The occupant can be either a cylinder or a polygonal shape. In the case of a Cylinder, Diameter, Height, Reduction Factor and Minimum Diameter can be specified.
Diameter
The 'shoulder width' of the cylinder representing the occupant. It is used for collision testing and path planning during the simulation. This value will also affect how many occupants can be added to a room without overlapping. The default value of 45.58 cm is based on the average of measurements of male and female persons from nine countries (Pheasant and Haslegrave 2005). An earlier edition is referenced by G. Keith Still in his Ph.D. thesis (Still 2000). As shown in the Pathfinder Validation and Verification Manual, this size (and Interpersonal Distance) results in movement that matches the SFPE and experimentally measured fundamental diagrams. Caution should be used in changing the default Diameter value.
Height
specifies the height of the cylinder used for inter-occupant collisions. This is useful for limiting collisions that might occur between occupants on different floors when the floors have been modeled close together.
Reduction Factor
[optional] Is enabled by default and is useful in helping occupants to "squeeze" by one another in congested areas. This factor is unitless and should be selected to be between 0 and 1. It can be considered a way to get the benefits of elliptical occupant shape (i.e. it gives the occupants a radius corresponding to turning sideways) despite the simulator’s exclusive use of circular occupant diameters. When occupants cannot otherwise move due to occupant-occupant collisions, this factor is multiplied against the shoulder width to shrink the collision circle and potentially allow occupants to ease through congestion.
Minimum Diameter

[optional] Is designed for models that have narrow seating areas and aisles. In cases where there is some detail of the geometry that makes it difficult for full-width occupants to move, this option can be enabled to alter the occupant-geometry collision test to accommodate the narrower geometry. The occupant-occupant collision test is not affected by this feature. Occupants will reduce their diameter to this value only if the geometry would otherwise prevent them from further following their path. The default value of 33.00 cm is based on the maximum depth of a human body for 95th percentile of measured individuals (Pheasant and Haslegrave 2005).

Polygon
If this option is selected, a dropdown menu is used to select the vehicle shape. Vehicles are used to model an occupant using an alternate mode of transportation, such as a wheelchair or bed as used in assisted evacuation. See Section 5.2 for more information on creating vehicle shapes or Chapter 6 for more information on assisted evacuation. The Edit button can be used to access the Vehicle Shapes dialog. The optional Reduction Factor can be used in the same way as for the cylinder shape, because occupants with vehicle shapes sometimes temporarily use cylinder shapes in their movement calculations to avoid stuck situations.

5.1.2. Movement Tab

The Movement tab provides parameters related to how occupants use their surroundings.

Initial Orientation
Specifies an angle in degrees counter-clockwise from the positive x-axis which the occupants will use as their orientation in the beginning of the simulation. Occupants can also be made to orient on a specific point. This can be done outside of the Edit Profiles dialog by right clicking selected occupants, and selecting Orient Occupants on Point from the context menu.
Requires Assistance to Move
Specifies whether the occupant requires assistance from another occupant in order to move. This is useful when modeling assisted evacuation as described in Chapter 6. This option is recommended for occupants that are unable to move under their own power (e.g. in a bed or other carrying device).
Ignore One-way Door Restrictions
Whether the occupant will ignore the direction specified for one-way doors.
Escalator Preference
Specifies how the occupant will stand or walk on escalators and moving walkways. The following options are available:
Stand anywhere
Occupants will get on the escalator and stand at any position. The occupant will stand still and travel on the stair at the stair’s speed constant.
Stand left
Occupants will get on the escalator and stand at the left side. The occupant will stand still and travel on the stair at the stair’s speed constant.
Stand right
Occupants will get on the escalator and stand at the right side. The occupant will stand still and travel on the stair at the stair’s speed constant.
Walk
The escalator’s speed constant will be added to the occupant’s desired speed on the stair to determine the occupant’s final speed, and they will attempt to walk around standing occupants.
Restricted Components
Specifies which components the occupant can use during path planning. The following options are available:
All
The occupant can use all components of that type.
None
The occupant cannot use any components of that type.
Up Only
[escalators only] The occupant can only use escalators that move occupants up.
Down Only
[escalators only] The occupant can only use escalators that move occupants down.
Based on Behavior
[elevators only] The occupant will only use elevators when their behavior contains a Go To Elevators action. See Section 5.3.3 for more information. Otherwise, the occupant can use all non-restricted elevators at any time.
From List
The occupant can only use certain components. When using this option, the list can be specified in one of the following ways:
Reject
The occupant will not use any of the specified components.
Accept
The occupant can only use one of the specified components of that type.

5.1.3. Door Choice Tab

The Door Choice tab provides parameters related to how occupants choose doors to exit from in each room. For more information about door choice see the (Pathfinder Technical Reference, n.d.).

Current Room Travel Time
The cost factor that affects the cost of travelling to a door in the occupant’s current room, ignoring all other occupants. Higher values increase the door’s cost in this category, making the Current Room Travel Time relatively more important.
Current Room Queue Time
The cost factor that affects the cost of waiting in a queue at a door in the occupant’s current room. Higher values increase the door’s cost in this category, making the Current Room Queue Time relatively more important.
Global Travel Time
The cost factor that affects the cost of travelling from a door to an exit or the occupant’s next goal, ignoring all other occupants. Higher values increase the door’s cost in this category, making the Global Travel Time relatively more important.
Elevator Wait Time
The time during which the occupant will prefer to use an elevator. This is done by pretending that there is no queue in front of the elevator, and that the elevator is ready to pick up the occupant. After the elevator wait time runs out, the occupant will be more likely to choose the stair. The elevator wait time is reset every time the occupant starts a new behavior action.
Current Door Preference
The value used to make occupants stick to their currently chosen doors, preventing excessive door switching. A value of 100% will cause occupants to never switch doors once an initial door is chosen, and a value of 0% will allow occupants to freely change their selected doors.
Current Room Distance Penalty
The value used to exponentially increase the cost associated with travelling based on how far the occupant has travelled in the current room. This causes the occupant to prefer shorter routes over faster routes the further they have travelled in the current room. Every time the occupant travels this distance in the current room, the travel time cost will have doubled. Setting this value to zero will disable this feature.

5.1.4. Output Tab

The Output tab provides the Print CSV Data option. When checked, additional CSV output data is generated for each occupant using this profile. The file contains data for each time step, such as occupant speed, location, etc. For more information, see Section 12.8.

5.1.5. Advanced Tab

The Advanced tab provides the following parameters:

Acceleration Time
Is a Steering Mode parameter that specifies the amount of time it takes for the occupant to reach maximum speed from rest or to reach rest from maximum speed. The resulting forward acceleration of each occupant is \(\text{forward_acceleration}=\text{max_speed}/\text{accel_time}\). The occupant uses a separate reverse acceleration of \(2*\text{forward_acceleration}\) and a separate lateral acceleration of \(1.5*\text{forward_acceleration}\).
Persist Time
The amount of time an occupant will maintain an elevated priority when trying to resolve movement conflicts. See the (Pathfinder Technical Reference, n.d.) for more details.
Collision Response Time
The distance ahead at which an occupant will start recording a cost for colliding with other occupants when steering. It is multiplied by an occupant’s current speed to calculate the recording threshold. As an example, with the default value of 1.5 s and the default maximum speed of 1.19 m/s, the occupant will look ahead 1.785 m from their current position to detect potential collisions and calculate costs.
Slow Factor
Specifies a fraction of the occupant’s speed at which they are considered to be slow. A slow occupant will consider backward directions to separate with others, while a fast moving occupant has a tighter, more focused direction.
Wall Boundary Layer
Specifies the distance that occupants try to maintain with walls and other static obstructions.
Personal Distance
The desired distance one occupant will try to maintain with others in a queue. This may be entered explicitly as a distance, from queue area, or from queue density. When entered as a distance, it is defined as the gap distance between the occupants' shapes rather than their center-to-center distance. If entered as an occupant area, the personal distance is calculated based on sphere packing: \(c = \frac{2}{\sqrt[4]{12}}\sqrt{a}-d\) Where \(c\) is personal distance, \(a\) is the occupant area, and \(d\) is the occupant’s shoulder width. Personal distance is calculated similarly when entered as occupant density, except that \(a=\frac{1}{\rho}\) where \(\rho\) is occupant density.
Social Distancing
Enables or disables Pathfinder’s social distancing model for the occupant profile. When enabled, the desired social distance can be set as a constant value or a distribution of values, enabling occupants to have different desired social distances. Social distance is defined differently than Personal Distance in that it is the center-to-center distance between occupants, whereas the personal distance is the gap distance between their shapes. In addition, social distance is enforced more strictly than personal distance and is more useful for maintaining larger distances between occupants (> 1 m).

Each of these parameters (except on/off parameters) can be set using a constant value, a uniform distribution between two values, or either a normal (Gaussian) or log-normal distribution (see Section 5.1.6).

Each occupant in the Pathfinder model is linked to one profile. Profile parameters can be edited in the profiles dialog at any time and the occupants using that profile will be automatically updated. Occupants' profiles can be set when adding the occupants or by selecting the occupants after being created and editing the Profile box in the property panel.

5.1.5.1. Advanced Speed Properties

In most cases, users only need to enter the maximum speed of an occupant in the Characteristics tab of the Edit Profiles dialog. The actual speed of the occupant throughout a simulation will vary according to this speed and a set of assumptions from the Engineering Guide to Human Behavior in Fire (SFPE 2019), which takes into account the type of terrain being traversed (stairs, ramps, etc.) and the density of surrounding occupants. See the (Pathfinder Technical Reference, n.d.) for more information.

Pathfinder allows for fine-grained control over the speed of the occupant, however, and the SFPE assumptions can be customized or replaced with other assumptions.

To do so, follow these steps:

  1. In the Model menu, click Edit Profiles to open the Edit Profiles dialog.
  2. Click the Characteristics tab.
  3. Next to Speed, click the drop-down box and select Advanced as shown in Figure 88.
path ui dialog profile characteristics speed advanced
Figure 88. Editing advanced speed properties

This will open the Advanced Speed Properties dialog as shown in Figure 89.

path ui dialog advanced speed props
Figure 89. Advanced Speed Properties dialog

As noted in the Advanced Speed Properties dialog, when simulating in SFPE mode, only the maximum speed property is used. All others in the Advanced Speed Properties dialog are ignored.

Clicking Reset to Defaults in the Advanced Speed Properties dialog will reset all advanced speed properties to their default values in Pathfinder.

Each tab in the dialog allows the customization of occupant speed on each terrain type in Pathfinder, including Level Terrain, Stairs, and Ramps.

5.1.5.1.1. Level Terrain Tab

The Speed Density Profile can be used to set the occupant’s speed as a function of the surrounding occupant density, also known as the fundamental diagram. One of three options may be chosen for the profile:

SFPE
The fundamental diagram as specified in the Engineering Guide to Human Behavior in Fire (SFPE, 2003) is used to adjust occupant speed.
Constant
The maximum speed is multiplied by a constant factor to determine the occupant’s speed. In most cases, the occupant will either try to move this speed or stop.
From Table
The speed is entered as a fraction of the occupant’s maximum speed as a function of surrounding occupant density. The values are entered in the Speed-Density Profile dialog as shown in Figure 90. The profile is defined as a piece-wise linear function, where sample points are entered into a table. For densities within the entered range, the speed fraction is interpolated. For densities outside the range, the speed fraction is equal to that entered for the nearest specified density. A preview of the fundamental diagram is shown to the right of the table. The SFPE profile, which is the default profile, may be loaded by clicking Load SFPE profile below the table.
path ui dialog speed density profile
Figure 90. Speed-Density Profile Dialog
5.1.5.1.2. Stairs Tab

The following properties may be entered in the Stairs tab:

Speed Fraction Up
Defines a speed factor when the occupant travels up stairs.
Speed-Density Up
Defines the speed-density profile to use when the occupant travels up stairs.
Speed Fraction Down
This specifies the speed fraction when the occupant travels down stairs.
Speed-Density Down
This specifies the speed-density profile to use when the occupant travels down stairs.

The above parameters define a factor that is multiplied by occupant’s maximum speed to determine their speed up or down stairs.

The factor may be specified in one of three ways:

SFPE
The assumptions from the SFPE Engineering Guide to Human Behavior in Fire are used to determine the speed fraction up stairs. This option uses the rise and run of the stair to determine the speed.
Constant
A constant factor is applied to the maximum speed.
From Table
The speed factor can be entered as a function of stair slope. Stair slope is defined as step rise/step run. The function is entered as a piece-wise linear function.

Additionally, the Speed-Density Up and Speed-Density Down parameters have the From Level Terrain option. This option forces the occupant to use the same speed-density profile as specified on the Level Terrain tab when the occupant travels up or down stairs.

5.1.5.1.3. Ramps Tab

The Ramps tab has nearly identical properties available as on the Stairs tab. The only difference is that Speed Fraction Up and Speed Fraction Down are entered in terms of the ramp’s geometric slope rather than step slope. The geometric slope is determined per triangle in the resulting navigation mesh and depends on the triangle’s normal direction.

5.1.6. Stochastic Parameters

Many parameters, including speed, can be specified by a constant value or in terms of a probability distribution.

Pathfinder supplies inputs for the following distributions:

Table 6. Distribution Options
DistributionDescription
ConstantSpecifies a constant value.
UniformGenerates random values that are uniformly distributed between the specified minimum and maximum parameters.
Normal

Generates random values that are normally distributed from the specified mean and standard deviation, as shown in the following equation: \(f(x) = \mu + \sigma x\)
Where \(\mu\) and \(\sigma\) are the mean and standard deviation, respectively, and x is a random number from a standard normal distribution. Generated values are bounded by the minimum and maximum parameters.

Lognormal

Generates random values that are lognormally distributed from the specified location andscale parameters, as shown in the following equation: \(f(x) = e^{\mu + \sigma x}\)
Where \(\mu\) and \(\sigma\) are the location and scale parameters, respectively, and x is a random number from a standard normal distribution. Generated values are bounded by the minimum and maximum parameters.

5.1.7. Seeds

Each occupant has a unique random seed that determines the specific values generated from a profile distribution. Each of these occupant-specific values can be seen by selecting an individual occupant. These specific values will never change unless the distribution is changed in the profile or a new seed is manually generated for the occupant. This ensures that two simulation runs with the same input model will give the same answer. New seeds can be generated for occupants by right-clicking the occupants and selecting Randomize.

For an example of the effects of the changing the seed or profile, consider the following scenario:

  1. A profile has been created using a uniform distribution of speed on the range 1 m/s to 2 m/s.
  2. An occupant is created using this profile.
  3. Using the occupant’s unique random seed, Pathfinder assigns the occupant a speed of 1.6 m/s based on the occupant’s profile.
  4. The simulation is run several times, and each time the occupant has a maximum speed of 1.6 m/s.
  5. The occupant’s profile is changed so that its speed range is .5 m/s to 1 m/s.
  6. Pathfinder assigns the occupant a new maximum speed of .6 m/s, which is used for all subsequent simulations.
  7. The user randomizes the occupant, and Pathfinder assigns a new maximum speed of .91 m/s to the occupant.

5.1.8. Customizing Occupants

When occupants are selected, their property panel appears as shown in Figure 91. Occupants can be given custom profile data once they are added to the model. This can be done by selecting a set of occupants and checking the box next to the parameter to be customized. Customized properties will be overwritten if an occupant switches their profile during simulation, see Section 5.3.3.12.

When using custom profile data, only constant values can be used for occupant parameters. In addition, once a parameter is customized, any changes to that parameter in the profile will not affect the customized value.

path ui props occupant
Figure 91. Using a custom occupant profile

Occupants with individually customized parameters can easily be found by right-clicking all or a sub-set of occupants and selecting Select Customized Occupants from the right-click menu if any exist in the selection.

5.1.9. Profile Libraries

Profiles can be saved and reused using profile libraries (Figure 92). Profile libraries are managed in the Profile Libraries dialog. To open the Profile Libraries dialog, on the Edit Profiles dialog, click Add From Library Alternatively, the Profile Libraries dialog can also be opened by clicking Edit Profile Libraries on the Model menu.

path ui dialog profile libs
Figure 92. Profile Libraries Dialog

The list on the left side of the dialog shows all profiles contained in the current Pathfinder model. The list on the right side of the dialog shows all profiles stored in the profile library. Profiles can be moved between the lists using the buttons in the middle of the dialog. Create New Library clears the list of library profiles so that a new library can be created. Load Library opens a profile library from file. Pathfinder supports loading profiles from profile library files (PLIB) and from standard Pathfinder model files (PTH).

To create a Pathfinder library file (PLIB) based on profiles in the current model:

  1. Click Create New Library to create a new empty library.
  2. Use the arrow buttons to copy profiles from the current model to the library.
  3. Click Save Current Library

The dropdown menu on the right side of the dialog can be used to load predefined libraries. To fill the predefined libraries box, Pathfinder scans two locations: a folder in the Pathfinder installation shared by all users and a folder in the current user’s APPDATA path, see Table 7.

Table 7. Pathfinder Library Locations
PLIB File LocationSuggested Use
C:\Program Files\PyroSim 20XX\lib\profiles
(or alternate install folder)
Built-in libraries included with Pathfinder. Administrator access is required to modify this location. Changes to PLIB files from this location will affect all users sharing the computer.
%APPDATA%\Pathfinder\profilesRecommended location for storing PLIB files. Non-admin users have write access to this folder. Changes to PLIB files in this location will affect only the current user.

All predefined profile libraries are opened as read-only to prevent accidental modification. To modify a library, you will need to resave to overwrite the existing PLIB file. See Appendix A, for more information on the occupant profiles provided with Pathfinder.

5.2. Vehicle Shapes

An occupant can be assigned a vehicle to use throughout the simulation. When using a vehicle, an occupant uses the shape of the vehicle rather than the default cylinder shape when performing collision detection. Any convex polygon can be used as the vehicle shape.

Vehicle shapes are not intended to be used as shapes of regular occupants. A vehicle movement is fundamentally different from an occupant movement. Unlike regular occupants, vehicles are not allowed to move sideways. Consequently, the vehicles follow a different path, which accounts for this movement restriction. Vehicles also avoid collisions with other occupants and walls differently from regular occupants. Finally, vehicle movement uses more complex calculation, which can increase the run time of the simulation.

The vehicles can be created and customized in the Edit Vehicle Shapes dialog (Figure 93). To open the Edit Vehicle Shapes dialog: on the Model menu, click Edit Vehicle Shapes.

path ui dialog edit vehicle shapes
Figure 93. The Edit Vehicle Shapes Dialog

The Description box provides a place to enter descriptive text. This value is not used outside the Edit Vehicle Shapes dialog.

Height
Specifies the height of the vehicle shape.
3D Model
Specifies the avatar to display for the vehicle when viewing occupants as people. This 3D model is shown in addition to the 3D model specified in the occupant’s profile. If <shape> is chosen as the 3D model, an extruded polygon is used as the 3D model for the vehicle. The color of the extruded polygon will match the color of the occupant. Custom avatars can also be imported as described in Section 4.5.
Occupant Animation
The animation that should be used for the occupant using the vehicle.
Default
Uses the occupant’s normal animation as if they are not using a vehicle.
Wheelchair
Makes the occupant look like they’re using a wheelchair.
Bed
Makes the occupant appear to be lying flat on their back.
Occupant Offset
Specifies how far the occupant’s 3D model should be moved to line up with the vehicle’s 3D model. A value of (0,0,0) will put the occupant’s 3D model at the vehicle’s origin as shown in the vehicle preview.
Points
Specify the shape of the vehicle as projected onto the ground. The shape must be specified as a convex polygon. All changes in this list are displayed in the vehicle preview to the right.
Pivot
Specifies the position of the pivot, which is a point around which the vehicle shape rotates. The pivot can lie inside or outside of the vehicle shape.
Positions of attached occupants
Specify the locations where an assistant can attach in order to move the vehicle. This is only needed for assisted evacuation and is ignored if the occupant using the vehicle never requests assistance (see Chapter 6 for more information). All changes in this list are displayed in the vehicle preview to the right.
Shape Area
Shows the area of the vehicle shape. This area is used for occupant density calculations.
Corresponding Occupant Count
Shows how many regular occupants fit inside the vehicle shape. This amount is used to determine whether occupants will fit in rooms that they are about to enter. For example, if an elevator has a nominal load of 10 people, then a bed, which corresponds to 12 people, will not be able to fit inside. Note that the corresponding occupant count is not used for occupant density calculation in SFPE mode.

The Vehicle Preview shows a graphical preview of the projected shape of the vehicle and provides additional capability to add, remove, and change points of the vehicle shape, the pivot location, and the positions of attached agents.

The dashed lines depict the horizontal and vertical axes. Their intersection (by default point x=0, y=0) is the pivot of the vehicle, around which the vehicle body rotates. The red arrow points in the direction of the movement of the vehicle. The pivot can be moved both inside and outside of the vehicle shape.

A point can be added to the vehicle shape or positions of attached occupants by right clicking inside the graphical editor. When moving the cursor close to a point, the point changes its color to orange indicating that it can be selected. A selected point changes its color to yellow. This selection is also displayed in the point editors on the left side of the dialog.

Any point can be moved by selecting and dragging, and it can be deleted by right clicking and selecting the Delete Point option. Mouse wheel can be used to zoom in and out, and mouse dragging can be used to move around. Reset View button resets the view so that all points are visible. The Undo/Redo buttons can be used to undo/redo any action within the 2D Graphical Editor.

A warning will appear at the bottom of the dialog in case constraints like minimum number of points in the vehicle shape, convexity, distance of assisting occupants from the vehicle shape etc. are violated.

For more information about the navigation of polygonal shapes in Pathfinder see the Pathfinder Technical Reference (Pathfinder Technical Reference, n.d.).

5.3. Behaviors

Behaviors in Pathfinder represent a sequence of actions the occupant will take throughout the simulation. Once they occupant has completed all actions, they are removed from the simulation. Actions may be added that can make the occupant wait or travel to a destination, such as a room, point, or exit.

The last destination for the occupant can be thought of as the occupant’s sink. By default, there is one behavior in the model called "Goto Any Exit". This behavior simply makes the occupant move from their starting position to any exit present in the model by the fastest route.

As with profiles, any number of occupants can refer to a single behavior. Any changes to the behavior will be reflected in referring occupants.

5.3.1. Creating a New Behavior

To create a new behavior:

  1. Right click the Behaviors node from the Navigation View, and from the right-click menu, click Add a Behavior, which will open the New Behavior dialog shown in Figure 94.
  2. In the New Behavior dialog, enter a behavior name, and optionally specify an existing behavior to base the new behavior on. Using this option will copy all the actions from the existing behavior.
path ui dialog new behavior
Figure 94. New Behavior dialog

With the new behavior selected, the behavior property panel will appear as shown in Figure 95.

path ui props behavior
Figure 95. Behavior Property Panel
Initial Delay
Specifies an initial delay that makes the occupant wait at their starting position before moving to the next action. If this link is clicked, it will show a dialog where different distribution curves can be entered for the delay, similar to those discussed in Profiles.

5.3.2. Adding Actions

Additional actions can be added to any behavior, such as going to a room, a waypoint, an elevator, or simply waiting in place. To add an action, select a behavior or existing behavior action. The property panel (Figure 96) will show a drop-down button with the description of an action that can be added. To add the currently shown action, simply click the button. To add a different action, click the down-arrow shown to the right of the button and select the desired action from the behavior actions list.

path ui props behavior add actions
Figure 96. Behavior actions list

Once the desired action is clicked, a creation panel will be shown above the 3D/2D View depending on the action. Enter the desired parameters in the creation panel as discussed in the following sections, and then click Create to create the action and append it to the behavior. If the behavior itself was selected when adding the action, then the new action will be appended to the end of the list. If, instead, an action was selected when the new action was created, then the new action is inserted directly after that selected action.

Actions always occur in the order shown in the Navigation View. For instance, as shown in Figure 97, an occupant using "Behavior1" would first go to any elevator, then go to "Room00", then wait for 20 seconds, then go to "Room09". After reaching "Room09", the occupant will be removed from the simulation. The actions can be reordered at any time by dragging and dropping an action in the list in the Navigation View.

path ui view nav behavior actions
Figure 97. Example of action order for a behavior

5.3.3. Behavior Action Types

Table 8. Behavior Actions Summary
ActionDescription
Goto WaypointSpecifies that an occupant should go toward a specific point on the navigation mesh.
Goto RoomsSpecifies that an occupant must select a room out of a set, and go to it.
Goto ElevatorsTells an occupant to use evacuation elevators.
WaitTells an occupant to wait in their current location for a specified amount of time.
Wait UntilInstructs an occupant to delay their movement until a specified simulation time passes.
Assist OccupantsInstructs the occupant to join an assisted evacuation team and begin assisting occupants who request assistance from that team.
Wait For AssistanceIndicates that the occupant should wait for assistance from other occupants.
Detach from AssistantsDetaches a client from their assistants, allowing the assistants to continue helping other clients.
Goto Refuge RoomsInstructs the occupant to go to one of a set of rooms marked as refuge areas.
Goto ExitsInstructs an occupant to take the fastest route to a set of exits.
Change BehaviorInstructs an occupant to change a behavior to a new behavior picked randomly from a behavior distribution.
Change ProfileInstructs an occupant to change to a different profile picked randomly from a profile distribution.
5.3.3.1. The Goto Waypoint Action

A Goto Waypoint action specifies that an occupant should go toward a specific point on the navigation mesh. Once they arrive within a certain radius of the point, they will move on to the next action in their behavior.

To add one of these actions:

  1. Click the Goto Waypoint button from the behavior actions list
  2. Enter the Location or click a point on the model
  3. Enter the Arrival Radius or drag the mouse after you click the location to specify the radius

These parameters can be entered manually in the creation panel or be filled in by clicking a point on the navigation mesh in the 3D or 2D View or click-dragging to specify the location+arrival radius. When clicking or click-dragging, the action is created when the mouse button is released.

5.3.3.2. The Goto Rooms Action

A Goto Rooms action specifies that an occupant must select a room out of a set, and go to it. Once they cross a door into the room, they are considered to be in the room and can move on to the next action in their behavior. If multiple rooms are specified for the action, the occupant will go to the one that is fastest to reach.

To add a Goto Rooms action:

  1. Click the Goto Rooms button from the behavior actions list.
  2. Click the Rooms link to specify the rooms with a dialog or left-click the desired rooms in the 3D or 2D View.
  3. Right-click in the 3D/2D View to finish selecting the rooms and create the action, or click Create.
5.3.3.3. The Goto Elevators Action

A Goto Elevators action tells an occupant to use evacuation elevators. When using this action, an occupant will go to a specified elevator, call it, wait for it to arrive, enter it, and then wait for it to reach the discharge floor. Once they reach the discharge floor, they can begin their next action. The Goto Elevators action can only be used for occupants who are not on the discharge floor of the desired elevator. If multiple elevators are specified for the action, the occupant will use the one that allows them to reach the discharge floor fastest.

To add a Goto Elevators action:

  1. Click the Goto Elevators button from the behavior actions list.
  2. Either click the Elevators link to specify the desired elevators with a dialog or left-click the desired elevators in the 3D or 2D View.
  3. Right-click in the 3D/2D View to finish selecting the elevators and create the action, or click Create.
5.3.3.4. The Wait Action

A Wait action tells an occupant to wait in their current location for a certain amount of time. Once that time has elapsed they will begin their next action.

The manner in which they wait will vary depending on their most recent destination. For instance, if their previous destination was a waypoint, they will try to stay close to the center of the waypoint. If the previous destination was a room, they will try to move toward the furthest point in the room away from all active doors. This allows other occupants to enter the room.

If their previous destination is an elevator, they will first move toward the walls as in waiting in a room, and then stand still when the elevator travels. In all cases, a waiting occupant will move out of the way of occupants headed toward a destination unless the destination overlaps with the waiting occupant’s most recent destination.

To add a Wait action:

  1. Click Wait from the behavior actions list
  2. Specify the Wait Time
5.3.3.5. The Wait Until Action

A Wait Until action instructs an occupant to delay their movement until a specified simulation time passes. This action is useful for synchronizing movement of many occupants at a time. Occupants fill space during a Wait Until action per the same rules described for the Wait action. Wait Until actions can be specified using three different approaches: occupants can wait until a specific time, the next in a list of times, or the next time in a periodic function.

To add a Wait Until action:

  1. Click Wait Until from the behavior actions list.
  2. Click the time to edit the value, which will show the Wait Until Time dialog as shown in Figure 98.
  3. Choose a sub-action from the drop-down.
  4. Specify the required parameters.
  5. Click OK on the Wait Until Time dialog.
  6. Click Create.
path ui dialog behavior action wait until
Figure 98. Wait Until Time dialog

Within the Wait Until Time dialog, there are three sub-actions available:

Wait until a specific time
This action tells occupants to wait in their current location until the simulation time passes the specified time. If the time has already passed when the occupant begins this action, they will immediately proceed to their next action.
Wait until next scheduled time
This action allows the user to specify a list of wait times. When an occupant begins the wait action, they compare the simulation time to the list of specified times, and wait until the first time greater than the simulation time. If the simulation time is greater than any specified time, the occupant immediately proceeds to the next action.
Wait until next periodic time
This action sets up a periodic list of times.
Time offset
Specifies the first entry in the time list.
Time interval
Specifies the delay between times in the list.

The list of times is then generated from these parameters. For example, if Time offset is set to 60 s, and the Time interval is set to 10 s, the list of times will be [60, 70, 80, 90, 100, …​]. Similarly to the Wait until next scheduled time action, when the occupant begins this action, they will pick the next time in the list and wait until that time passes.

Both the Time offset and Time interval may be specified as distributions. In this case, each occupant will be given a unique list of times to choose from. For instance, if the Time offset is set to a uniform distribution of [50,60] and the Time interval is set to be constant at 10 s, one occupant may get the list, [52.3, 62.3, 72.3, 82.3, …​], and another occupant may get the list [59.2, 69.2, 79.2, 89.2, …​].

5.3.3.6. The Assist Occupants Action

This action is used in assisted evacuation models as discussed in Chapter 6. This action instructs the occupant to join an assisted evacuation team and begin assisting occupants who request assistance from that team. When an occupant joins a team, they become an assistant. Once all occupants requesting assistance have completed their actions for which they wanted assistance, the assistant will begin their next action.

To add an Assist Occupants action:

  1. Click Assist Occupants from the behavior actions list.
  2. Specify the assisted evacuation Team that the occupant will join.
  3. Click Create.
5.3.3.7. The Wait For Assistance Action

This action indicates that the occupant should wait for assistance from other occupants as discussed in Chapter 6. This action requires that the occupants using it have a vehicle shape with at least one attached occupant location as discussed in Section 5.2. When an occupant begins this action, they are considered to be a client, and assistants will approach the client. The client cannot move once they begin waiting for assistants until enough assistants attach to the client to fill all the attached occupant positions. Once all positions are filled, the client begins their next action. The assistant will stay attached to the client until either the client has completed all subsequent actions or the client begins a Detach from Assistants action as described below.

To add a Wait for Assistance action:

  1. Click Wait for Assistance from the behavior actions list.
  2. Specify the Assisting Teams that will assist the client.
  3. Click Create.
5.3.3.8. The Detach From Assistants Action

This action indicates that the occupant should detach from their assistant as discussed in Chapter 6. When an occupant begins this action, they are considered to be a client, and currently being assisted in their movement. Once detached, the occupant can proceed to their next behavior without assistance, only if they do not require assistance to move. This action also allows the assistant to move on to the next occupant requiring assistance.

To add a Detach From Assistance action:

  1. Click Detach from Assistant from the behavior actions list.
  2. Click Create.
5.3.3.9. The Goto Refuge Rooms Action

This action instructs the occupant to go to one of a set of rooms marked as refuge areas as discussed in Section 3.2.5. Like the Goto Exits action, this action must be the last action in the behavior. When an occupant reaches the refuge area, they will remain in the simulation and wait for the simulation to complete. Their behavior while waiting is described in the Wait action above. Additionally, the occupant will be tagged with "refuge_reached", as reported in the Occupants Summary and Occupant History output files as discussed in Section 12.7 and Section 12.8.

This action is created similarly to the Goto Rooms action, except that only rooms marked as refuge areas may be chosen.

5.3.3.10. The Goto Exits Action

This action causes an agent to take the fastest route to a set of exits. Like the Goto Refuge Rooms action, this action must be last in the behavior. Once an agent goes through an exit, they are removed from the simulation and reported as having exited the model in the Occupants Summary and Occupant History output files as discussed in Section 12.7 and Section 12.8.

To add a Goto Exits action:

  1. Click Goto Exits from the behavior actions list.
  2. Specify the Exits through which the occupant may leave.
  3. Click Create.
5.3.3.11. The Change Behavior Action

This action causes an occupant to switch its behavior. After this action, the occupant will start performing actions from a different behavior. This new behavior is randomly selected from a given behavior distribution. Besides other behaviors, the same behavior and No Change can also be selected. If the occupant changes behavior to its current behavior, the behavior will be restarted. If the occupant selects to make No Change, the Change Behavior action will have no effect. It is possible to create loops in the behavior references. That way the occupant might keep performing the actions forever (until the end of the simulation). Note that depending on the specific setup, it is possible that actions that come after a Change Behavior action will not be performed by the occupant.

5.3.3.12. The Change Profile Action

This action causes an occupant to change their profile, which will override all parameters settable in an occupant profile (Section 5.1). This can be used to change an occupant’s speed, shape, avatar, etc., throughout a simulation. The chosen profile is selected from a list of possible profiles, including a No Change item that will prevent the occupant’s profile from changing.

For profile parameters that are specified as distributions (e.g. max speed), a given occupant will always select a value from the same part of the distribution for that parameter. For instance, if a given occupant starts with a profile whose max speed is a normal distribution, and the occupant’s speed is chosen from the 25th percentile, any subsequent profile changes will also lead to the occupant’s speed being chosen from the 25th percentile of the new speed distribution. This ensures that if an occupant’s profile is changed, that parameter will remain consistent for the occupant. In addition, if the parameter does not change with a profile change, the occupant will maintain the previous value. For value sets, such as occupant avatars, it is guaranteed that the occupant will maintain the same value only if the new profile uses the exact same set of values as the previous.

Profile changes can also be used to change an occupant’s shape. It can change from a normal cylinder shape to a vehicle shape. It can also change from one vehicle shape, such as a bed, to another shape, such as a wheelchair. Because vehicles can be used with assisted evacuation (see Chapter 6), take care when switching between shapes during assistance. If an occupant is to change vehicles during assistance, for correct functionality it is best to detach from assistants before changing shapes using a Detach from Assistants action and then re-attach after changing shapes using a Wait for Assistance action.

5.4. Generating Occupants

Occupants can be added to the simulation in a number of ways. The simulation can either be pre-seeded with any number of occupants or it can have occupants continuously generated by occupant sources. When pre-seeding the model, occupants can be placed individually in the 3D or 2D view, distributed in a rectangular region of a particular room, or distributed throughout the entire area of a room.

5.4.1. Individual Placement

Individual occupants can be added to the model with the Add Occupant tool path ui icon occupant single. Occupants can only be placed in pre-existing rooms, stairs, and ramps and cannot overlap other occupants or room boundaries. Left-click a desired position with the mouse, or enter an x-y-z coordinate and press the Create button from the property panel to place an occupant (Figure 99).

path scrn occupant add individual
Figure 99. Adding occupants individually

5.4.2. Group Placement

Groups of occupants can be added to the model with the Add Occupant Group tool path ui icon occupant group. The occupants are distributed throughout this region using parameters in the property panel as shown in Figure 102.

Once the properties have been specified, click-drag to draw the filling rectangle. Both points of the rectangle must lie in the same room (Figure 100). When you release the mouse button, the occupants will be placed within the designated region (Figure 101).

path scrn occupants group rectangle
Figure 100. Selected area for occupants
path scrn occupants group added
Figure 101. Occupants added to the rectangular area

When an occupant is selected, the property panel allows the occupant’s name, profile, and behavior to be edited. All profile parameters are also displayed, showing exactly what value will be used for that specific occupant. Any of these parameters can be overridden by checking the box next it and entering the desired value. See Section 5.1.8 for more information.

path ui props occupant group
Figure 102. Add Rectangular Group of Occupants Property Panel
5.4.2.1. Random or Uniform Placement

Random placement places occupants randomly within the designated area, such that no overlapping of occupants occurs. If the number of desired occupants is too great to accomplish this, a prompt will ask whether or not to continue with overlapping occupants. Uniform placement places occupants in an orderly hex pattern, allowing greater occupant densities before overlap occurs. Again, a prompt will ask whether to continue with overlap if the density is too great.

5.4.2.2. Count or Density

This option specifies whether to place a set number of occupants or place enough occupants to achieve a certain density. Several template densities are provided, and Custom can be selected from the densities drop-down menu to enter a new value.

5.4.2.3. Profile

This option allows a distribution of profiles to be set for the occupants, such as specifying that 25% of the added occupants should be females < 30 years old, 30% children, etc. The label shows the currently set distribution, and if there is more than one profile defined in the model, the value can be clicked to edit the distribution. This will open a dialog as shown in Figure 103.

path ui dialog profile distribution
Figure 103. Editing the distribution of profiles
5.4.2.4. Behavior

This option allows the distribution of behaviors to be set and is set by specifying percentages of each behavior. The dialog is similar to Figure 103.

5.4.3. Room Placement

In addition to distributing occupants in placement regions, occupants can be distributed throughout entire rooms.

To do this:

  1. Select the desired rooms and choose Add Occupants from the Model menu or the right-click menu as shown in Figure 104. This will bring up the Add Occupants dialog (Figure 105). For an explanation of the dialog’s options, please see Section 5.4.2.
  2. Click the OK button after selecting the desired options to place occupants and exit the dialog.
path scrn menu context add occupants
Figure 104. Add occupants in context menu
path ui dialog add occupants
Figure 105. Add occupants dialog

5.4.4. Occupant Sources

Occupant sources define areas in which occupants are generated dynamically throughout the simulation.

To add an occupant source, use the Add Occupant Source tool path ui icon occupant source or right click on a door or a room in the model, and select Add Occupant Source If an occupant source that is attached to a component is later deleted from the model the user will be notified and the occupant source will either be attached to a different component or deleted.

There are three options for specifying the physical location of the occupant source within the model, as shown in Figure 106.

path ui props occupant source create
Figure 106. New Occupant Source Options

An occupant source can be defined by a rectangular region or attached to a component in the model.

From Rectangle
Use this option to draw a box that defines a placement region. This region is intersected with the navigation mesh, and new occupants are created at random positions in the intersected areas.
From Door
Use this option to attach the new occupant source to an existing door. The door can be selected either from the drop-down menu or by clicking on the component in the model. New occupants will be created at random positions along the door.
  • If the door is one-way, the occupants will be placed slightly off of the door toward the one-way direction.
  • If the door is an exit, the occupants are placed slightly inside the model.
  • If the door is attached to an elevator, occupants are placed slightly outside the elevator.
From Room
Use this option to attach the new occupant source to an existing room. The room can be selected either from the drop-down menu or by clicking on the component in the model. New occupants will be created at random positions inside the room.
5.4.4.1. Parameters of an Occupant Source

Once the location of an occupant sources is defined, additional parameters that relate to the occupants that are generated can be specified. Figure 107 below shows parameters that can be specified for an existing occupant source.

path ui props occupant source
Figure 107. Parameters of an Occupant Source
Flow Rate
Rate in persons per second at which new occupants will be created (Section 5.4.4.1.1).
Enforce Flow Rate
Specifies whether the occupant source should keep generating occupants regardless of how crowded its area is (Section 5.4.4.1.2).
Profile
Specifies a profile distribution.
Behavior
Specifies a behavior distribution.
Component
Shows which door or room the occupant source is attached to, if any.
Movement Group Template
Specifies the distribution of movement groups for occupants that are part of a movement group. An Ungrouped option is available for occupants that will not be part of any movement group. (See Section 7.4)
5.4.4.1.1. Flow Rate

The rate, in persons per second, at which new occupants will be created. The flow rate can be either constant or specified as a function from a table. The flow rate table editor is shown in Figure 109 below. The editor can also be used to automatically construct a periodical step function. To do so, click the Step function button. The Step Function dialog is shown in Figure 108 below. The editor with a generated step function is shown in Figure 109 below.

The following are the parameters of the step function that can be set in the Create Step Function dialog:

Flow Rate
Flow rate value when occupant generation is ON.
Initial Delay
The amount of time at the beginning of the simulation until the step function begins.
On Duration
Amount of time in each period for which occupant generation is turned ON.
Off Duration
Amount of time in each period for which occupant generation is turned OFF.
Number of Cycles
The number of ON/OFF pairs in which occupants are generated. After this, the occupant source will stop generating occupants.
5.4.4.1.2. Enforce Flow Rate

When Yes is selected, the occupant source will keep generating occupants regardless of how crowded its area is, which can result in overlapping occupants. When No is selected, the occupant source will only generate an occupant if the new occupant will not overlap with another occupant. Otherwise, the occupant source will wait until the next time step to try to generate an occupant again.

path ui dialog create step function
Figure 108. Create Step Function Dialog
path ui dialog flow rate
Figure 109. Occupant Source Flow Rate Editor

5.5. Redistributing Profiles and Behaviors

Once occupants have been created, the distribution of profiles and behaviors can be reshuffled among them.

  1. Select one or more groups of occupants from the Navigation View, right-click them, and from the right-click menu, select Properties, or double-click the occupant group. The Edit Group Distributions dialog will appear as shown in Figure 110.
  2. If more than one profile exists in the model, the Profile link can be clicked to edit the distribution as discussed in Group Placement.
  3. If more than one behavior exists in the model, the Behavior link can be clicked to edit its distribution.
path ui dialog edit group distribution
Figure 110. Edit Group Distributions dialog

5.6. Randomizing Occupants' Positions

After occupants have been created, their positions can be changed to new random positions.

To randomize occupants' positions, select one or multiple rooms, and from the right-click menu select Randomize Occupants' Positions The Randomize Occupants' Positions dialog appears (Figure 111), providing the option to change room and position settings.

  • Reposition within Current Room will make each occupant stay in its current room, while Reposition within Any Selected Room will move occupants freely within selected rooms.
  • Random and Uniform options will redistribute occupants randomly or uniformly, respectively.

After clicking OK, all occupants in the selected rooms will be moved to their newly generated positions. Occupants' orientation will change too, unless it is defined locally for specific occupants or set to a constant angle in the occupants' profile.

path ui dialog randomize occupant position
Figure 111. Randomize Occupants' Positions Dialog

5.7. Reducing Population

It is sometimes necessary to reduce the number of occupants in the model. The number of occupants can be decreased in each room, stair, ramp, or occupant group automatically.

To reduce the number of occupants in a component or in an occupant group, right click on the specific object and select Reduce Population A dialog will appear with the option to set the new occupant count. The deletion method can also be set.

Pathfinder can either keep random occupants, first occupants in the selection, or last occupants in the selection.

6. Assisted Evacuation

Pathfinder supports assisted evacuation scenarios, in which some occupants may assist other occupants. This is particularly useful in hospital evacuations and other scenarios where there may be some disabled occupants who need help for at least part of their journey.

The following is some terminology used in Pathfinder:

Assistant
An occupant who helps other occupants Section 6.1.1.
Client
An occupant who is helped by assistants Section 6.1.2.
Team
A group of assistants Section 6.3.

Assisted evacuation is supported through the behavior system of Pathfinder, allowing a wide range of scenarios to be investigated.

Some possibilities include:

  • Assistants help clients through their entire evacuation, allowing the client to visit multiple intermediate waypoints or rooms or wait at a location while being assisted.
  • Assistants help clients for only part of their evacuation, such as an occupant in a wheelchair who only needs assistance to descend stairs.
  • Assistants help in stages. For example, one team of assistants moves clients to one location and then another team moves the occupants to another location.

Assisted evacuation is also supported by the occupant source system (see Section 5.4.4), which allows clients and assistants to be generated by occupant sources.

6.1. Assistance Process Overview

Technical details of the algorithm for assisted evacuation are available in the Pathfinder Technical Reference (Pathfinder Resources), but a summary from both the assistants' and the clients' perspectives are given here.

6.1.1. Assistants

Initially, the occupant becomes an assistant of a team based on their Assist Occupants action (Section 5.3.3.6).

  • The assistant checks whether any current clients or future clients (from an occupant source) will ever need assistance from them, and, if not, continues on with their next behavior action.
  • If the assistant determines clients are available, they will send an offer to assist a client.
  • When the client accepts the request, the assistant attaches to the client and becomes passive until the client detaches.
  • When there are no more clients available, the assistant moves on to the next behavior action.

6.1.2. Clients

When the simulation begins, the occupant becomes a client of a team or set of teams based on the client’s Wait for Assistance action (Section 5.3.3.7) and then the client waits indefinitely for an assistant from one of those teams to offer assistance. When the client receives an offer, they choose the closest assistants to assign to all open positions on their vehicle (any extra offers are rejected).

All subsequent behaviors are processed with assistants attached until one of the following happens (depending on the terminating action):

  • The client encounters a Goto Exits action, in which case they detach from all assistants shortly before going through the exit and then proceed to go through the exit on their own, even if they cannot move without assistance. They are then removed from the simulation.
  • The client encounters a Goto Refuge Rooms action, in which case the client will go to one of the rooms. Upon entering the room, the client will proceed to the back of the room, detach from the assistants, and wait until the simulation completes.
  • The client encounters a Detach from Assistants action, in which case the client detaches from all assistants and continues on to the next action on their own. (Example: The client is in a wheelchair and needed assistance down stairs.)

6.2. Preparing Clients

There are some considerations to take into account when preparing clients. Table 9 outlines some important client-specific parameters that can help achieve a variety of evacuation outcomes.

Table 9. Important parameters to define client behavior
ParameterLocationUsage
Wait for Assistance ActionBehaviors panelTurns occupant into a "client"
Detach from Assistants ActionBehaviors panelAllows client to detach from assistants and make part of their evacuation journey individually
Vehicle ShapeOccupants panel

Wheelchair and hospital bed are available by default

User-defined vehicles are also available

Requires Assistance to MoveEdit Profiles DialogThe client cannot move without assistance

Preparing occupants who can become clients can be done as follows:

  1. Create a new Behavior for the clients.
    • Add a Wait for Assistance action to the behavior and specify the team or teams that should assist the clients.
    • Add actions that the client should perform while being assisted, such as going to a refuge room or going to an exit. If a Goto Exits action is added, the assistant will automatically detach from the client before the client goes through the door, allowing the assistant to continue helping other clients.
    • If the client should perform part of the journey on their own, add a Detach from Assistants action to the behavior and then add the actions that will be performed individually.
  2. Create the occupant.
    • Assign the client behavior.
    • Choose a Vehicle Shape for the client (see Section 5.1.8 and Figure 112) by editing the Shape parameter on the occupant properties panel. All clients must have a vehicle shape (see Section 5.2). Either choose a default shape or define a custom shape with user-defined positions for assistants.
path ui dialog shape
Figure 112. The Shape Dialog where a user may select a vehicle shape for a client

6.3. Preparing Assistants

Preparing occupants who can become assistants can be done as follows:

  1. Create a new Behavior for the assistants.
  2. Add an Assist Occupants action to the behavior and select the Team on which the occupant should assist (if no team is selected the default team will be used).
  3. Create the occupant or occupant source and assign the Behavior.

6.4. Preparing Teams

Any number of assisted evacuation teams may be created. Assistants join teams through their behaviors and clients ask for assistance from teams through their behaviors. By default, assistants join the default team.

Assistants may only be a member of one team at a time, but they may be a member of several teams during the course of the simulation. This is accomplished by using an Assist Occupants action for each team in the assistant’s behavior.

To edit assisted evacuation teams, on the Model menu, click Edit Assisted Evacuation Teams (see Figure 113)

path ui dialog edit assisted evac teams
Figure 113. The Edit Assisted Evacuation Teams dialog

On the Priority tab, Client Priority controls the order in which clients are evacuated by a team.

The priority can be specified as follows:

Distance to assistants
Assistants on the team will choose the closest client to them.
Specified in the list below
Allows the client ordering to be specified directly by adding clients to a list. Clients in the list are given priority over those absent from the list. The clients in the list are assisted according to the list order. Those absent from the list are assisted based on distance. Once an assistant chooses a client, they are locked into the choice.
For example, say there are three clients listed in the order shown in Figure 113 – "00003", "00018", "00007".
The following behavior may occur:
  1. Client "00018" requests help from "Default Team", but no other clients have yet requested assistance.
  2. An assistant helping with "Default Team" chooses to assist client "00018".
  3. As the assistant is heading toward "00018", client "00003" requests assistance from the team.
  4. The assistant continues on toward "00018", ignoring the request from "00003".
  5. Once client "00018" is helped, the assistant heads toward "00003".

The Assistants tab is read-only and shows all assistants who currently have a behavior that joins the team with an Assist Occupants action at some point in the simulation. You must use an Assist Occupants action to add an assistant to this list.

The Clients tab is read-only and shows all clients who currently have a behavior that requests assistance from the team with a Wait for Assistance action at some point in the simulation. You must use a Wait for Assistance action to add a client to this list.

7. Occupant Grouping

Movement groups are used to keep occupants together during the simulation. This feature can be used to explicitly link occupants present at the start of the simulation and can also be used with occupant sources to link occupants inserted during the simulation. The first case might be used in a simulation that begins with families already seated together in a theater and the second might be used to simulate group arrivals via railway car.

Occupants that are part of a group remain grouped during the entire simulation – there is no facility for leaving and joining groups. In addition, to be members of the same group, occupants must use the same behavior.

While occupant movement groups can be used to create simulations that have the appearance of more realistic behavior, specific data about grouping is generally unavailable in validation studies and the relationship between movement times and specific grouping parameters is unknown. Because grouping adds constraints and never increases the individual movement speed of an occupant, it should generally produce more conservative (i.e. slower) simulation times than the ungrouped equivalent. However, if using groups in an evacuation simulation, it is highly recommended to run the simulation both with and without grouped occupants to identify the impact of occupant groupings on evacuation times.

For output associated with grouped movement, see Section 12.9.

7.1. Grouped Movement

Grouped movement is controlled by two concepts: connected state and the group leader. If a group is in a "disconnected" state, occupants will walk toward the leader. If a group is in a "connected" state, occupants move toward the goal dictated by their behavior. This framework allows groups that have become broken up to re-form and avoids imposing to harsh movement restrictions related to divided doors and other minor navigational differences.

The details of these behaviors are controlled by the following four parameters:

Follow Leader
This parameter makes it possible to manually specify the occupant that will be used as the group leader throughout the simulation. If left unset, the simulator automatically selects a leader and the leader may change over time. The group member nearest the current goal, as specified by behavior, will become the leader.
Maximum Distance
This parameter is used to determine if a group is connected or disconnected. If any part of the group is more than Maximum Distance away from any other part, the group is considered disconnected. More specifically, the longest edge in the minimum spanning tree connecting all occupants in the group must be less than or equal to Maximum Distance for the group to be considered connected.
Slowdown Time
This parameter is used by the leader when a group has become disconnected. The leader will gradually reduce speed before coming to a stop. Slowdown Time determines how long the leader will slow down before stopping.
Enforce Social Distancing Between Group Members
This parameter is used to enforce Social Distancing between group members (see Section 5.1.5). By default, social distancing is not enforced within the group, but group members will social distance with occupants not in their group.

Smaller values for Maximum Distance and Slowdown Time give more cohesive groups and larger values give looser groups.

Group members share component restrictions (see Section 5.1.2). If a component is restricted for some group member, other group members will avoid the component as well.

7.2. Movement Groups

Movement groups are listed in the Tree view within the Movement Groups node. These represent groupings of specific occupants that exist at the start of the simulation.

To create a Movement Group:

  1. Select all occupants that will be members of the group. All selected occupants must share the same behavior.
  2. Right click to activate the pop-up menu, click New Movement Group from Selection.

The new Movement Group will appear in the Tree view within the Movement Groups node. The movement group parameters (e.g. Maximum Distance) can be edited by selecting the movement group in the tree.

To quickly assign an occupant as the leader of their Movement Group:

  1. Select one or more occupant(s). Any occupants not belonging to a movement group will be ignored.
  2. Right click to activate the pop-up menu, click Set Group Leader. This will set each occupant as the leader of their respective movement group(s). Selecting multiple occupants that belong to the same movement group will result in the first selected occupant being set as the leader.

Manually creating individual movement groups is likely only necessary for special cases. Movement Group Templates offer a way to automatically create Movement Groups.

7.3. Movement Group Templates

Rather than describing a specific set of occupants that will move together, Movement Group Templates describe a kind of Movement Group. An example might be "Families, with 1-2 adults and 1-3 children". Pathfinder can use these descriptions to automatically create large numbers of Movement Groups from selections of occupants or during the simulation.

In addition to the three movement parameters described earlier, Movement Group Templates require occupant profile-based creation parameters:

Number of Members
This option can be used when control over the specific profiles used to form the group is not required. It specifies constraints on group size.
Numbers of Members per Profile
This parameter can be used to specify group size constraints along with profile requirements.
Leader’s Profile
This option can be used to force the permanent leader to be selected from a specific profile. This option is only available when the Number of Members per Profile option is used and the Follow Leader option is selected.

To create a Movement Group Template:

  1. On the Model menu, click Edit Movement Group Templates
  2. Click New
  3. Type a name for the template and then click OK.

The new template will be added to the Tree view in the Movement Group Templates node. The created template can now be used to automatically create movement groups.

When Pathfinder uses Movement Group Templates to sort occupants into movement groups, the algorithm is controlled by the following parameters:

Movement Group Templates
This is the distribution of templates that should appear in the resulting movement groups. Click the blue text to edit the distribution. For example, a theater seating area might include 60% groups of 1-4 adults, and 40% groups of families.
Restrict Members to the Same Room
This parameter is active by default and enforces a rule that all members of a group must share the same starting room.
Distance Calculation
The group creation algorithm attempts to form groups from clusters of occupants standing near each other. Clusters are identified using either Travel Distance, which takes walls and other obstacles into account, or Geometric Distance. Geometric Distance is fast because it uses a simple distance calculation, but it may have the undesirable consequence of grouping occupants that are nearby, but on different floors. A height multiplier can be used to discourage the algorithm from grouping occupants located up or down a floor. For example, using a multiplier of 10 would make a 3.0 meter difference in Z effectively a 30.0 meter difference for purposes of the distance calculation.

To create Movement Groups using a template:

  1. Select all occupants that should be sorted into groups. All selected occupants must share the same behavior.
  2. Right-click and on the pop up menu, click New Movement Group(s) from Template
  3. The New Movement Group(s) from Template dialog offers various options that provide control over how Pathfinder will sort the selected occupants into groups.
  4. Adjust parameters as required and click OK.

The new movement groups will be added to the Tree view in the Movement Groups node and the parameters of individual groups can be edited if required.

When using the New Movement Group(s) from Template action, it is important to note that occupant profiles will be reset by the operation.

7.4. Adding Grouped Occupants from Occupant Sources

Sources insert occupants into the model while the simulation is running. By default, sources do not use groupings when adding occupants. Movement Group Templates can also be used to create movement groups dynamically as occupants are added to the simulation from sources. Sources can create grouped occupants using the following parameter:

Movement Group Template
The distribution of templates that will be used when creating grouped occupants. The default value is Ungrouped, which means that the generated occupants will not be part of any movement group. Since groups usually consist of more than one occupant, the source will add all members of a new group one at a time at the prescribed flow rate until the group has been completely added. Once complete, the distribution of movement group templates will again be used to determine grouped (or ungrouped) status of the new occupant.

To configure an occupant source to add grouped occupants:

  1. Select the occupant source.
  2. On the property panel, in the Movement Group Template field, click to enter a distribution of templates to be selected when inserting occupants.

The source will now insert grouped occupants based on the template settings.

8. Views

At any time, the state of the perspective camera can be saved, including its position, orientation, and zoom. This information is stored in an object called a View. A view can be recalled later in either Pathfinder or the 3D Results to view the scene from that perspective.

Views appear in Pathfinder as points and can be hidden either individually or as a whole. To show/hide all views, click the Show View Objects button path ui icon toggle views in the 3D/2D view toolbar.

8.1. Creating a View

To create a view, follow these steps:

  1. Position the perspective camera using one of the navigation tools as discussed in Section 2.2.1.
  2. Create a new view using one of these methods:
    • On the Model menu, choose New View.
    • Right-click Views in the Navigation View, and choose New View.

A new view will appear in the Navigation View as shown in Figure 114.

path ui view nav new view
Figure 114. Creating a View

8.2. Recalling a View

To recall a view, perform any of the following:

  • Double-click the desired view from the Navigation View.
  • Right-click a view from either the Navigation View or the 3D/2D View, and choose Show in 3D View.

This will show the 3D View and the perspective camera will be initialized with the state of the saved view.

8.3. Editing a View

If the orientation of a view needs to be changed, perform the following:

  1. Position the perspective camera into the new desired position.
  2. Right-click the view and choose Update View.

Alternatively, the graphical representation of the camera can be manipulated to move the location of the view as discussed in Section 9.2.

8.4. Views in the Results

In order for the views created in Pathfinder to be available in the Results, a special views file is written to the output folder whenever the simulation is run. When the Results application is opened, it then reads the views from this file and makes them available in the Results.

Because this file is only automatically written when the simulation is run, however, a view can be changed in Pathfinder after running the simulation, making it out of sync with the views in the Results. In order to synchronize the views in Pathfinder and the Results without re-running the simulation, the views file must be manually written. To do so, follow these steps:

  1. Make the desired changes to the view in Pathfinder.
  2. On the File menu, choose Save Views File.
  3. Save over the existing views file.
  4. Re-load the results in the 3D Results Viewer.

8.5. Camera Tours

In previous versions of Pathfinder, tours could also be created inside Pathfinder. This functionality was later moved to the 3D Results. Tours made in previous versions of Pathfinder, however, will still appear in the Navigation View of Pathfinder. While they can no longer be edited within Pathfinder, they can still be deleted. Ones that are not deleted will be written to the Results views file so that they are available in the Results.

9. Editing and Copying Objects

Most objects can be edited in two ways in Pathfinder. One way is to transform the object, including rotating, translating (moving), and mirroring it. Another way is to graphically manipulate the objects by dragging handles. Objects can also be copied, but currently the only way to do this is through the transform tools as discussed in the following section.

9.1. Transforming and Copying Objects

All geometric objects can be transformed and/or copied. All transform/copy options are available through tools in the 3D and 2D views. The following transforms are available and are discussed in the following sections: moving, rotating, and mirroring.

9.1.1. Moving

To move one or more objects, select the objects and click the move tool path ui icon translate from the 2D or 3D view. The property panel for the move tool is shown in Figure 115.

path ui props translate 2020 5
Figure 115. Property panel for the translate tool

The object can be moved either manually or graphically:

Manually
Select Normal Mode and enter the distance to offset the object in the Move X, Y, and Z boxes. Then click Move.
Graphically
This is performed most easily in one of the 2D views. To translate graphically click two points on the model. The vector from the first point to the second defines the movement offset. When moving graphically, objects will only be moved parallel to the camera’s view plane.

Objects can also be copied using the move tool. To do so, select the move tool, select Copy Mode from the property panel, and follow the same steps as above for moving an object. Alternatively, hold CTRL on the keyboard while defining the offset. This will create a copy of the object that has been offset by the move distance.

Similarly, an array of objects can be made by specifying a value greater than 1 for the Copies field in the property panel. The array is created by offsetting each previous copy by the move distance. If, when copying rooms, the resulting copies overlap one another the most recent copies take precedence over earlier ones, meaning that earlier ones will have area subtracted from them.

path scrn translate array 1
Figure 116. Select object and click first point
path scrn translate array 2
Figure 117. Second click creates array

9.1.2. Rotating

To rotate one or more objects, select the objects and click the rotate tool path ui icon rotate from the 2D or 3D view. The property panel for the rotate tool is shown in Figure 118.

path ui props rotate
Figure 118. Property panel for the rotate tool

The object can be rotated either manually or graphically:

Manually
Select Normal Mode and enter the base of rotation, the axis about which to rotate using the right-hand rule, and the angle to rotate. Then click Rotate.
Graphically
This is performed most easily in one of the 2D views. The rotate axis is automatically set to a vector normal to the camera. Rotating requires three mouse clicks.
  • The first specifies the base of rotation (Figure 119).
  • The second defines a reference vector extending from the rotation base (Figure 120).
  • The third defines a second vector extending from the rotation base (Figure 121). The rotation angle is the angle between these two vectors.
path scrn rotate base point
Figure 119. Base point of rotation
path scrn rotate base line
Figure 120. Reference line (red) and rotation angle (green)
path scrn rotated
Figure 121. Rotated object

Objects can also be copied using the rotate tool.

  1. Select the rotate tool
  2. Select Copy Mode from the property panel, and follow the same steps as above for rotating an object. Alternatively, hold CTRL on the keyboard while defining the rotate properties.

This will create a copy of the object that has been rotated from the original using the rotate parameters. Similarly, an array of objects can be made by specifying a value greater than 1 for the Copies field in the property panel. The array is created by rotating each previous copy by the rotate angle.

If copying rooms and resulting copies overlap one another the most recent copies take precedence over earlier ones, meaning that earlier ones will have area subtracted from them. An array is shown in Figure 123.

Creating an array of objects using the rotate tool
path scrn rotate angle lines
Figure 122. Select object and click and second line
path scrn rotate array
Figure 123. Create array from rotation

9.1.3. Mirroring

To mirror one or more objects about a plane, select the objects and click the mirror tool path ui icon mirror from the 2D or 3D view. The property panel for the mirror tool is shown in Figure 124.

path ui props mirror
Figure 124. Property panel for the mirror tool

The object can be mirrored either manually or graphically:

Manually
Select Normal Mode and enter the plane about which to mirror. This can be an axis-aligned plane or a custom plane specified by the plane equation, \(ax + by + cy + d = 0\). Next click Mirror.
Graphically
This is performed most easily in one of the 2D views. The mirror plane is always perpendicular to the camera’s view plane. Defining the plane requires two mouse clicks that define two points in the plane. The steps for mirroring graphically are shown in Figure 126.
Mirroring an object
path scrn mirror line
Figure 125. Select object and draw mirror line
path scrn mirrored
Figure 126. Selected objects mirrored over

Objects can also be copied using the mirror tool. To do so, select the mirror tool, select Copy Mode from the property panel, and follow the same steps as above for mirroring an object. Alternatively, hold CTRL on the keyboard while defining the mirror plane. This will create a copy of the object that has been mirrored from the original using the mirror plane.

9.2. Manipulating Objects with Handles

Some objects, including occupants, rooms, stairs, and doors, can be edited through manipulator handles. Handles act as points on an object that can either be dragged with the selection tool or edited by the keyboard to edit the attached object. Handles only appear on selected objects and show as blue dots as shown in Figure 127.

path scrn handles
Figure 127. Manipulator handles

9.2.1. Selecting and Deselecting a Handle

To select an object’s handle, the object itself must first be selected. Once it is selected, the blue handles should appear. Next select the Select/Edit tool path ui icon select. Now an individual handle can be selected by clicking it, which will make the handle property panel appear as shown in Figure 128. To deselect the handle, press ESC on the keyboard, click anywhere else in the model, or select another object.

path ui props handle
Figure 128. Handle property panel

9.2.2. Editing a Handle

A handle can be edited in one of two ways: it can be edited with the keyboard to enter precise values or it can be edited graphically.

Editing with the keyboard
To edit with the keyboard, a handle must first be selected. Next enter the desired location in the X, Y, and Z fields in the property panel and select the Commit button. The handle will attempt to modify the underlying object using the handle’s internal constraints that are described in the appropriate section of this guide for the respective handle’s object.
Editing graphically
A handle does not have to be selected before editing graphically. To edit graphically, make sure the Select/Edit tool path ui icon select is selected, and press the left mouse button over the desired handle and drag the handle to the desired location. Release the left mouse button, and the object will be edited. A real-time preview of the object being edited will be shown as the mouse is dragged.

9.2.3. Room Handles

When rooms are selected, a handle can be found at every vertex on the boundary of the room. The handles move the underlying vertex to reshape the room. The handles can be moved to any location within the plane of the face the vertex is on. If the vertex is shared between two faces in non-parallel planes, the handle can only be moved along the edge to which it is attached.

9.2.4. Thin Door Handles

When a thin door is selected, three handles will be displayed as shown in Figure 129. The handles on the ends of the door allow the door to be moved along the edge to which it is attached. The middle handle allows the door to be made thick by moving the handle to the edge of another room as shown in Figure 130.

path scrn handles door thin
Figure 129. Thin door with three handles
path scrn handles door thick
Figure 130. Thick door with six handles

9.2.5. Thick Door Handles

When a thick door is selected, six handles will be displayed as shown in Figure 130. The four handles on the corners of the door allow the door to be moved along the edge to which each handle is attached. Each middle handle allows the door to be made into a thin door by dragging to the other middle handle. The middle handle can also be useful to reattach the door to a room if the door somehow became detached (such as by a modification to the room).

9.2.6. Stair and Ramp Handles

When a stair or ramp is selected, six handles will be displayed as shown in Figure 131. The four corner handles each allow the stair/ramp to be moved along the edge to which the handle is attached. The middle handles allow the stair/ramp to be reconnected to another room. The middle handles can also be useful if the geometry of one room attached to a stair/ramp has changed in such a way that the stair/ramp is no longer attached to the room. The middle handle can be used in this case to reconnect to the room.

path scrn handles stair
Figure 131. Stair/ramp handles

9.2.7. Occupant handle

When an occupant is selected, there is only one handle as shown in Figure 132. The sole purpose of this handle is to move the agent to another location. Moving an agent in this manner has a benefit over the translation tool in that the location automatically snaps to an existing room or stair as when adding an agent using the agent dropper tool.

path scrn handles occupant
Figure 132. Occupant handle

9.2.8. Waypoint Handles

When a waypoint is selected, two handles are displayed as shown in Figure 133. The center handle allows the waypoint to be moved to another location similarly to the occupant handle. The perimeter of the circle can be used as a handle to change the arrival radius of the waypoint.

path scrn handles waypoint
Figure 133. Waypoint handles

9.3. Enabling and Disabling Objects

Several objects in Pathfinder can be enabled or disabled. Disabling an object removes the object from the model. A disabled object does not appear in the simulation. Following objects can be enabled and disabled in Pathfinder:

  • Occupants
  • Occupant sources
  • Rooms: disabling a room will automatically disable its occupants and occupant sources; all connected doors, stairs and ramps will also be disabled.
  • Doors: disabling a door will automatically disable its occupant sources.
  • Stairs
  • Ramps
  • Measurement regions

To enable or disable an object, right click on the object in the 3D view or in the navigation tree and select Enable or Disable. Disabled objects are invisible in the 3D view. In the navigation tree, disabled objects are greyed out and crossed out.

10. Model Analysis

Pathfinder contains some useful tools to analyze various properties of a model.

10.1. Measurement Regions

Measurement regions cause the simulator to output time history data for velocity and density within a specific region on the navigation mesh. See Section 12.4 for information about Measurment Region results.

Measurement regions can be created using the Add a Measurement Region tool path ui icon measurement region.

path scrn measurement region rectangle
Figure 134. An example of a measurement region placed in front of an exit door.

Adding one or more density regions will cause the simulator to output a CSV file named filename_measurement-regions.csv containing data for each density region. The data in this file can be used to plot fundamental diagrams in the measurement area.

Output frequency for measurement region CSV data is controlled by the CSV Output Freq. parameter on the Output tab of the Simulation Parameters dialog.

To ensure accurate results, measurement regions must:

  • Intersect exactly one room,
  • Not extend beyond the boundary of the room, and
  • Not intersect any interior walls within the room.

Essentially, measurement regions should be placed on open space that will be used by occupants. Ideally, the measurement region should not be larger than the area where the steady flow under study occurs. If the measurement region is too large, results might indicate a lower value than expected because the quantity is integrated over the entire region.

For additional information about measurement regions, please refer to the Pathfinder Technical Reference.

10.2. Measuring Distances

Distances can be measured by using the measuring tool path ui icon measure.

To do so, select the measuring tool from the 3D or 2D view. To measure distance along a sequence of points, left-click each point. After each point in the path has been specified, right-click to display the cumulative point-to-point distance in a dialog box.

When measuring distances in the 3D view, the distance is taken as the actual distance between snapped points. When measuring distances in the 2D view, however, the distance is taken by projecting the points onto a plane parallel to the camera view plane, and then taking the distance.

11. Simulating

11.1. Parameters

The Simulation Parameters dialog provides a way to control certain features of the simulation, as well as provide some default values.

11.1.1. Time Parameters

The Time tab (Figure 135) provides the following options:

Time Limit
Can be used to automatically stop the simulation after a set simulation time.
Time Step Size
Controls the resolution of simulation time steps. Increase the time step size to speed up simulations, reduce the time step size to ensure simulation accuracy.
path ui dialog sim params time
Figure 135. The Time tab of the Simulation Parameters dialog

11.1.2. Output Parameters

The Output tab (Figure 136) provides the following options:

3D Output Freq
controls the time between 3D output file updates. Increasing this value causes data to be written less often, leading to less disk usage and run faster simulations (no file write delay), but can produce a misleading 3D results visualization. In the 3D results visualization, occupants will move in a straight line between two data points - if the two points are far apart in time, an occupant might appear to pass through an obstruction when it actually navigated properly.
CSV Output Freq
controls the time between CSV output file updates. Increasing the value causes fewer rows to appear in the resulting CSV files (i.e. lower data resolution). This option has a negligible effect on simulation performance or disk usage, but can affect performance in the 2D results.
Runtime Output Freq
controls the time between simulation status updates in the Run Simulation dialog. This option has a negligible effect on simulation performance or disk usage.
Jam Velocity
controls the speed threshold at which occupants are recorded as being jammed in the Occupants output file.
Occupant CSV Data
controls how the CSV data is generated for occupants with Print CSV Data enabled. See Section 12.8 for more information.
Merge into one file
All occupants with CSV data enabled are written to the same file. The file is named filename_occupants_detailed.csv, where filename is the name of the saved PTH file without the .pth extension.
Create one file per occupant
Each occupant with CSV data enabled is written to a different file. The file is named, filename_occupant_id_occname.csv, where filename is the name of the saved PTH file without the .pth extension, id is the integer id of the occupant assigned by the simulator, and occname is the name of the occupant specified in the user interface.
Include Seek Speed in Measurement Region Files
controls whether to include an additional column in the measurement region files called "SeekVelocity", which indicates how fast an occupant is moving relative to the direction of their goal. For instance, if an occupant wants to move in the +X direction, and they are moving in the +X direction at 1.2 m/s, this column will show 1.2 m/s; however, if they instead move in the +Y direction, this will become 0 m/s because they are not moving toward their goal. NOTE: This value is always >= 0, even if the occupant is moving backward away from their goal.
Write Occupant Parameter File
Indicates whether to write the Occupant Parameters file. See Section 12.5 for more information.
Enable Interpersonal Distance Reporting
Enabling this feature will cause the simulator to create two output files: filename_sd_transient.csv and filename_sd_accumulated.csv. These files report interpersonal distancing information based how close together occupants are located. The distance calculation is computationally expensive and adds about 10% to simulation runtime. See Section 12.6 for more information.
Reference Distance
When interpersonal distance reporting is enabled, this value is used to calculate exposure data and is reported as SD in filename_sd_accumulated.csv. See Section 12.6 for more information.
path ui dialog sim params output 2020 3
Figure 136. The Output tab of the Simulation Parameters dialog

11.1.3. Paths Parameters

The Paths tab (Figure 137) provides the following options:

Max Agent Radius Trim Error
This parameter affects how accurately occupants can navigate through tight spaces when the occupants in the simulation have varying sizes. The larger this value is the less likely an occupant is to navigate through a space that has a width close to their body diameter. With larger values, however, the simulation will consume less memory and start faster (sometimes much faster if every occupant has a different size). Each occupant is guaranteed to be able to fit through a space with width equal to the occupant’s diameter plus twice this value.
Constrain Edge Length
Controls the triangulation algorithm used to convert the rooms, stairways, etc. into the triangulated mesh used by the simulator. By default, Pathfinder attempts to generate the fewest and largest possible triangles and this approach works well with Pathfinder’s search algorithms. However, in some situations, "well behaved" triangles can be useful (e.g. to prevent extremely long, thin triangles). This value can be used to "fatten" these triangles.
Max Edge Length
Controls the maximum length of any single edge on a room boundary, and the Min Angle criteria prevents the system from using triangles with any very small (i.e. thin) angles.
Min Angle
Values greater than 30 degrees can cause Pathfinder to "freeze" when it attempts to generate a simulation input file.
path ui dialog sim params paths
Figure 137. The Paths tab of the Simulation Parameters dialog

11.1.4. Behavior Parameters

The Behavior tab allows you to set options for Pathfinder’s two primary simulation modes: SFPE and Steering. To select a simulation mode, choose SFPE or Steering from the Behavior Mode drop-down box.

11.1.4.1. SFPE Mode Parameters

The SFPE mode uses the set of assumptions presented in the Engineering Guide to Human Behavior in Fire (SFPE 2019) and can give answers extremely similar to these hand calculations, depending on selected assumptions. In SFPE simulations, the mechanism that controls simulation movement is the door queue. The SFPE mode uses a simple set of assumptions and usually completes much faster than a comparable steering mode simulation in terms of CPU time.

path ui dialog sim params behavior sfpe
Figure 138. SFPE Behavior tab of the Simulation Parameters dialog

The SFPE mode supports the following options:

Max Room Density
Controls the density at which doors will no longer admit occupants into a room. Using an artificially low value for this number will give faster evacuation times. Using a higher number 3.6 - 3.8 can cause extremely slow evacuation times. Using values above 3.8 pers/m2 can cause the simulation to become stuck due to the density dependent velocity calculation.
Door Flow Rate→Boundary Layer
This value is subtracted from both sides of a door to calculate the effective door width, controlling the flow rate equation. For example, with a Boundary Layer setting of 150 mm, a 1.0 m door would be reduced to a 0.7 m opening giving an \(F_\text{s_max}\) of (1.32 pers/s-m * 0.7 m) = 0.924 pers/s.
Door Flow Rate→Flow Rates at High Density
controls how specific flow for doors is calculated. Specific flow is a measure of occupants per unit of time per unit of effective width. For each door, the specific flow is multiplied by the effective door width to calculate the door flow rate in occupants per unit of time.
Use a Calculated Specific Flow
Specific flow is calculated as a function of room density for a room adjacent to the door. In cases of counterflow, the room with the higher density controls the combined specific flow of the door.
Always Use Max Specific Flow
Allows the door to flow at the optimum density. Minimum Speed Fraction* can be used to set a lower limit on occupant speed. Setting this value too low can cause evacuation times to increase significantly in cases of high initial loading of rooms or if the Max Room Density is set very high.
11.1.4.2. Steering Mode Parameters

The Steering mode is more dependent on collision avoidance and occupant interaction for the final answer and often gives answers more similar to experimental data than the SFPE mode (i.e. steering mode often reports faster evacuation times). Door queues are not explicitly used in Steering mode, though they do form naturally.

path ui dialog sim params behavior steering 2020 2
Figure 139. The Steering Behavior tab of the Simulation Parameters dialog

The Steering mode supports the following options:

Steering update interval
Specifies how often (in simulation time) to update the steering calculation. This could also be considered to be the cognitive response time of each occupant. The higher this number, the faster the simulation will run, as long as the simulation time step is less, but the poorer the decision making skills of each occupant will be.
Minimum flowrate factor
This is used when agents are deciding which doors to use when there are queues at the doors. The factor is multiplied by the door’s nominal flowrate to determine a minimum observed flowrate. A non-zero factor will cause a door to always appear to be flowing even if it is not. This helps prevents occupants from excessively switching doors when flowrates are very low; however, it can also cause occupants to stick with the same door even if it cannot flow any more, such as a door into a refuge room that has filled completely near the door. If occupants are refusing to leave a blocked door into a room when other doors are available, try setting this parameter to 0.
Collision Handling
Controls whether occupants avoid one another and can collide with each other.
Enable Forced Separation

When enabled, this will cause occupants to attempt to always strictly maintain their Personal Distance (Section 5.1.5). When disabled, Personal Distance will only apply while queueing.

Limit Door Flow Rate
When checked, this imposes a maximum flow rate on doors unless they have it explicitly turned off (Section 3.4.3). The flow rate for each door is calculated from the Boundary Layer and Specific Flow, similarly to SFPE Mode. The difference between Steering and SFPE Modes is that Steering does not allow flow rates to be based off room density.

11.2. Starting and Managing a Simulation

To run a simulation: on the Model menu, click Run Simulation path ui icon run sim. The simulation will begin and the Run Simulation dialog (shown in Figure 140) will appear.

path ui dialog run sim
Figure 140. The Run Simulation dialog showing a partially complete simulation.

In this dialog, the abbreviation DTG stands for distance to goal. The maximum distance to goal represents distance to goal for the occupant farthest from its goal. The average distance to goal is the average of all occupants' distances to their respective goals.

The Debug button launches a runtime visualization that shows the progress of the simulation as it is taking place. This function is different from the Results button which launches the 3D visualization view for simulation results.

A simulation can also be paused, resumed, and cancelled at any time.

11.2.1. Simulating via Command-line

Simulations can also be run through the command-line without loading the user interface.

  1. Open a command prompt.
  2. Run testsim.bat located in the Pathfinder install folder.

The only argument is the input .txt file generated by Pathfinder. Pathfinder automatically creates this file when performing a simulation through the user interface.

The input file can be manually created in the user interface by selecting File  Save Simulator Input. When running a simulation this way, it may also be desirable to manually create the geometry file for visualization. To do this, select File  Save Imported Geometry File.

11.3. Stopping and Resuming a Simulation

When running a simulation, there is the option to pause and resume, but this requires Pathfinder to be running the entire time. Sometimes the need arises to be able to stop a simulation and resume later between Pathfinder sessions, such as if the computer needs to be restarted after installing a system update.

To stop a simulation:

  1. Press Cancel during a simulation in the simulation dialog.
  2. Pathfinder will ask the user if a snapshot should be made.
  3. After clicking Yes, the current state of the simulation is written to a snapshot file.

To resume the simulation at a later time:

  1. In Pathfinder open the model to resume.
  2. Go to Simulation  Resume Simulation.
  3. Select the time that the simulation was cancelled and click OK.
  4. The simulation will resume from this time.

12. Results

12.1. Summary Report

The summary report file contains information about the simulation geometry, simulation performance, statistics, and usage information for each room, stairway, and door.

Figure 141 shows a portion of an example summary report file.

path scrn summary report
Figure 141. Listing for an example summary report file.

This file is saved in the simulation directory and given the name filename_summary.txt (where filename is the name of your saved PTH file). To view it, under the Results menu choose Show Summary File. The first section shows the mode the simulation was run in, the total number of occupants, and statistics on the evacuation time. It also shows some information about the mesh, including the number of triangles and the doors. This information can be useful when considering the complexity of a simulation from the standpoint of the simulator.

Each statistic is generated by sampling quantities from the occupants as data points. Only occupants for whom the quantity is relevant are included in the statistic.

Statistics on the following quantities may be printed to summary file:

Exit Time
The time at which an occupant went through an exit door, exiting the simulation.
Finish Time
The time at which an occupant left the simulation by any means.
Refuge reached Time
The time at which an occupant who had a Goto Refuge Room behavior action reached their refuge room (see Behavior Action Types for more information).
Travel Distances
The total distance the occupant travelled throughout the simulation.

The table at the end of the summary file gives a listing of each component (doors, rooms, and stairs) in the simulation. For each component, the FIRST IN column shows the simulation time when the first occupant entered that component. LAST OUT shows the simulation time when the last occupant exited that component. The TOTAL USE column shows how many times a component was entered by occupants. For doors that served more than 1 occupant, the FLOW AVG. column shows the result of dividing the total use by the amount of time the room was in use (LAST OUT - FIRST IN). Each component can be annotated with its group names (e.g. floors). This annotation can be set by selecting Include Group Names in Output in the File→Preferences dialog.

12.2. Door History

The door history file (filename_doors.csv, where filename is the name of your saved PTH file) provides results data for doors. Each row represents a different time step, and the columns are as follows:

Time(s)
The output time for this data row. The frequency of output is controlled by the CSV Output Freq. box in the Simulation Parameters dialog.
Remaining (total)
The number of occupants remaining in the simulation.
Exited(total)
The number of occupants that have successfully passed through an exit door (leaving the simulation).
doorname width(m)
The total width of the specified door.
doorname total boundary(m)
The total boundary layer of the specified door.
doorname [{+/-}{X/Y}]
The number of occupants who have passed through door doorname since the previous output in the specified direction. For columns with no direction specification, this is the total number of occupants to pass through the door in both directions since the previous output.
doorname (Q)
The number of occupants who are waiting in the queue to pass through door doorname at the current time. This only includes occupants who have actually reached the door and are waiting to enter. Occupants that are stacked up waiting to reach a door will not be counted. This value is only meaningful in SFPE mode.

This file is used to display door flow rate, specific flow, and usage history in Pathfinder.

12.2.1. Door Flow Rate and Specific Flow

To view door flow rate or specific flow, click View Door Flow Rates on the Results menu. This opens a time history plot for doors as in Figure 142. This plot shows data from the door history file.

In the left portion of the window is a list of the doors, and on the right is a graph of the data. For each door, the list on the left shows three rows: one for each of the two directions and one for total. The directional data can be hidden by unchecking Include Directional Data under the View menu. Each row in the list shows group names for each door (if the Include Group Names in Output option under File→Preferences was enabled in Pathfinder when the simulation was run). The group names can be hidden by unchecking Show Group Names under the View menu of the history plot dialog.

path scrn plot door flow
Figure 142. A time history plot for door flow rates

By default, door flow rates are shown. Alternatively, on the Mode menu, choose Specific Flow to view door specific flow.

There are three filtering modes for presenting the flow rate that are selectable through the View menu:

Raw
this provides raw flow rate, which is simply \(\frac{\text{num\_occs}}{dt}\), where \(num_occs\) is the number of occupants to pass through the door in an output time step, and \(dt\) is the output time step.
Low-pass Filter
the raw flow rate is filtered with a bi-quad low-pass filter with a user-specified cutoff frequency. This is the default filter, and the default cut-off frequency is .05 Hz. Lower cut-off frequencies produce smoother graphs.
Moving-average Filter
the raw flow rate is averaged over a user-specified period.

12.2.2. Door Usage

To view door usage, open the Door Flow Rate Rates dialog, and on the Mode menu, select Occupant Counts. This shows the number of occupants that use a particular door in each output time step.

Alternatively, cumulative totals can be viewed by selecting Cumulative Occupant Counts. This shows the total number of occupants to use the door up until that time.

12.3. Room History

The room history file (filename_rooms.csv, where filename is the name of your saved PTH file) provides the following information columns in each row:

Time(s)
The output time for this data row. The frequency of output is controlled by the CSV Output Freq. box in the Simulation Parameters dialog.
Remaining (Total)
The number of occupants still in the simulation.
Exited (Total)
The number of occupants that have successfully passed through an exit door (leaving the simulation).
roomname
The number of occupants present in room (or stairway) roomname at the current time.

To display this data as a time history plot, click View Room Usage on the results menu. Similarly to door history, the list on the left shows group names for each room (if the Include Group Names in Output option under File→Preferences was enabled in Pathfinder when the simulation was run). The group names can be hidden by unchecking Show Group Names under the View menu of the history plot dialog.

12.4. Measurement Regions Graph

The measurement region file (filename_measurement-regions.csv, where filename is the name of your saved PTH file) provides the following information columns in each row:

Time(s)
The output time for this data row. The frequency of output is controlled by the CSV Output Freq. box in the Simulation Parameters dialog.
Density(pers/m^2)
The density in the observation region at a specified output time.
Velocity(m/s)
The speed in the observation region at a specific output time.
SeekVelocity(m/s)
The velocity in the direction of pedestrians’ desired path.
Count(pers)
The counting heads passing within a time interval.

To display this data as a time history and a speed vs density plot, click View Measurement Regions on the Results menu.

12.4.1. Velocity Mode

To view a speed vs time history graph, click View Measurement Regions on the Results menu, this is the default mode. To view this mode from other alternative modes, on the Mode menu, select Velocity. This shows the speed in the observation region(s) in each output time step.

12.4.2. Density Mode

To view a density vs time history graph, click View Measurement Regions on the Results menu, and on the Mode menu, select Density. This shows the density in the observation region(s) in each output time step.

12.4.3. Speed vs Density Mode

To view a speed vs density graph, click View Measurement Regions on the Results menu, and on the Mode menu, select Speed vs Density. This shows how a change of density in the observation region(s) affects the speed of movement.

The three filtering modes explained earlier could also be applied to measurement region graphs.

12.5. Occupant Parameters

The occupant parameters file (filename_occupant_params.csv, where filename is the name of your saved PTH file) provides a summary of the initial states of almost all parameters assigned to each occupant, such as maximum velocity, occupant radius, etc.

This is useful for verifying the parameter distributions as specified in the occupant profiles (see Section 5.1 and Section 5.1.6 for more information). This file is written by default but can be turned off in the Simulation Properties dialog (see Section 11.1.2).

In addition, any occupants that have customized parameters (Section 5.1.8) will invalidate the distributions. These customized occupants must be manually excluded from the analysis to determine resulting distributions.

12.6. Interpersonal Distance

The interpersonal distance output files (filename_sd_transient.csv and filename_sd_accumulated.csv) provide information related to how closly occupants are located throughout the simulation. Distances are reported as as measured center-to-center.

filename_sd_transient.csv
CSV-format output file containing transient data about occupant separation. For every CSV output time and occupant in the simulation, the closest other occupant is listed along with distance. Additionally, the number and ID of occupants within 1m, 2m, and 3m are listed.
Table 10. Transient Interpersonal Distance CSV File Structure
Column NameTypeOptionalDescription
Time (s)floatSimulation time
IDintUnique ID for occupant
NametextxOccupant name from nav view in UI
Group IDintxUnique ID for occupant group, if present
Closest Occupant IDintxID of closest occupant, if present within 3m
Closest Occupant NametextxOccupant name from nav view in UI, if present within 3m
Closest Occupant Distance (m)floatxDistance to closes occupant, if present within 3m
Occupants Within 1m (count)intNumber of occupants within 1 meter
Occupants Within 1m IDstextxSpace-separated list of occupant IDs within 1m
Occupants Within 2m (count)intNumber of occupants within 2 meter
Occupants Within 2m IDstextxSpace-separated list of occupant IDs within 2m
Occupants Within 3m (count)intNumber of occupants within 3 meter
Occupants Within 3m IDstextxSpace-separated list of occupant IDs within 3m
filename_sd_accumulated.csv
CSV-format output file containing accumulated exposure data for each occupant. For every occupant in the simulation, the occupant who has spent the longest time within reference distance is listed, including the occupant ID and the total amount of time. Additionally a count is made of all occupants who have remained within reference distance of the occupant for more than 1 minute and 5 minutes, including the occupant IDs.
Table 11. Accumulated Interpersonal Distance CSV File Structure
Column NameTypeOptionalDescription
IDintUnique ID for occupant
NametextxOccupant name from nav view in UI
Group IDintxUnique ID for occupant group, if present
SD (m)floatDistance used to calculate reference distance exposure.
Longest Occupant IDintxID of occupant of greatest exposure (longest within distance SD)
Longest Occupant NametextxID of occupant of greatest exposure (longest within distance SD)
Longest Occupant Time (s)floatxTime within distance SD of occupant of greatest exposure
Occupants > 60s (count)intNumber of occupants within distance SD for >60 seconds
Occupants > 60s IDstextxSpace-separated list of occupant IDs within distance SD for >60 seconds
Occupants > 300s (count)intNumber of occupants within distance SD for >300 seconds
Occupants > 300s IDstextxSpace-separated list of occupant IDs within distance SD for >300 seconds

12.7. Occupants Summary

The occupants' summary file (filename_occupants.csv, where filename is the name of your saved PTH file) provides statistics about each occupant in the simulation. Each row of the CSV represents one occupant and provides the following:

id
A unique integer identifier for the occupant assigned by the simulator.
name
The name given to the occupant in the user interface.
exit time
The time at which the occupant went through an exit door.
active time
The amount of time the occupant was actively seeking a location in the model, such as a waypoint or exit.
jam time total
Total time the occupant spent moving at less than the Jam Velocity as specified in the simulation parameters (see Section 11.1.2).
jam time max continuous
The maximum continuous amount of time the occupant spent at less than the Jam Velocity.
level jam time
Time spent by the occupant moving at less than Jam Velocity on level surfaces.
stair jam time
Time spent by the occupant moving at less than Jam Velocity on stairs.
ramp jam time
Time spent by the occupant moving at less than Jam Velocity on ramps.
start time
The time at which the occupant was generated. For occupants pre-seeded in the model, this is always 0. For occupants generated by an occupant source, this could be any time.
finish time
The time at which the occupant left the simulation for any reason.
distance
The total distance the occupant travelled during the simulation.
last_goal_started time
The time at which the occupant started their last behavior action.
refuge_reached time
The time at which an occupant with a Goto Refuge Rooms action reached their refuge room. See Behavior Action Types for more information.
safe time total
The total amount of time the occupant spent in a refuge room.
tag:safe time last
The last time the occupant entered a refuge room.
untag:safe time last
The last time the occupant exited a refuge room.

12.8. Occupant History

For each occupant whose profile has CSV data output enabled (Section 5.1), additional time history data for the occupant is written to a CSV file.

Each row of the file contains the following data for time the occupant:

t(s)
The output time for this data row. The frequency of output is controlled by the CSV Output Freq. box in the Simulation Parameters dialog.
id
The integer identifier of the occupant assigned by the simulator.
name
The name assigned to the occupant in the user interface.
active
Whether the occupant is actively seeking an exit (1 if they are seeking an exit and 0 if not).
x(m), y(m), z(m)
The 3D location of the occupant.
v(m/s)
The velocity of the occupant.
distance(m)
The total distance the occupant has travelled.
location
The occupant’s current room.
terrain type
The terrain type of the occupant’s current room.
safe
Whether the occupant is in a refuge room.
last_goal_started
Whether the occupant has started their last behavior action.
refuge_reached
Whether an occupant with a Goto Refuge Room action has reached their refuge room, see Section 5.3.3 for more information.

For occupants with CSV output enabled, this data may optionally be written to one CSV output file or one file per occupant. This preference is controlled by the Occupant CSV Data option as described in Section 11.1.2.

12.9. Groups Output

The groups output file (filename_groups.csv, where filename is the name of your saved PTH file) provides information about groups that were created before and during the simulation.

Table 12. Groups Output CSV File Structure
Column NameTypeOptionalDescription
Group IDintUnique ID for group
Member IDstextSpace separated list of numeric group member IDs
Group NametextxFor groups created prior to running the simulation, this column lists the group name from the tree view
TemplatetextxFor groups created at simulation runtime, this column lists the name of the template (group type) used to create the group

12.10. 3D Results

Included with Pathfinder is the Pathfinder Results Viewer for visualizing 3D results. This software can be used to visualize results from both Pathfinder and the Fire Dynamics Simulator (FDS) from the National Institute of Science and Technology (NIST).

By default, the Pathfinder Results Viewer starts automatically when a Pathfinder simulation has finished. To start the results viewer manually either click View 3D Results path ui icon results in main toolbar or in the Results menu click View 3D Results.

For more information on using the Pathfinder Results Viewer, refer to the (Pathfinder Results User Manual, n.d.).

13. Troubleshooting

Errors, warnings, mesh connectivity, and other issues can prevent the simulation from running or cause occupants to get stuck. Errors and warnings often provide a tip on fixing the issue. The following sections offer solutions to common problems you might face while using Pathfinder.

13.1. Occupants cannot reach their goals, or they are getting stuck

Check the connectivity of the mesh. Check how various components are connected in the model to debug simulation errors or to ensure model validity.

To determine why a specific occupant cannot reach its next goal:

  1. Right-click the room containing the occupant, and click Select Connected Components from the right-click menu.
  2. From the drop-down box in the Select Connected Components dialog, we choose Entire graph and click OK. (This traces model connectivity to help determine where a door or other connection is missing.)

Pathfinder will highlight the entire graph of components touching the initial selection. We can then inspect the selected components to find out where they are disconnected from the occupant’s goal.

For finer inspection in a highly connected model, select only immediately adjacent components in the Select Connected Components dialog.

Sometimes occupants become "stuck" even on a properly connected mesh, preventing a proper simulation run. There can be many causes of this problem and we do everything we can to prevent it, but it does happen. If occupants are becoming stuck in tight spaces, consider the following steps to resolve the problem:

  1. Alter the navigation mesh in the area where occupants are becoming stuck. This can be especially useful if the area was originally extracted from imported geometry. Sometimes simply re-drawing the area using the drawing tools can fix the issue.
  2. Slightly increase the occupants' Interpersonal Distance in their profile.
  3. Slightly reduce the occupants' Reduction Factor in their profile.
  4. Switch to the SFPE simulation mode. This mode uses the simplest set of assumptions and is not as susceptible to the geometric and movement irregularities that can cause occupants to become stuck.

13.2. Warnings and errors in the navigation tree

Pathfinder shows warnings and errors in the Navigation Tree to help debug potential errors in the simulation. These warnings appear as a small exclamation mark imposed over an occupant or record, path ui icon warning. By hovering the mouse over the warning, a more detailed description of the problem can be determined. For convenience, if an object has problems, the warning marker is propagated up through the navigation tree to its ancestor groups in order to quickly identify problems in the model.

Some common warnings include:

  • Warning if stairs are not connected to rooms at both ends.
  • Warning if stairs or doors overlap along an edge.
  • Warning if stairs or doors create a non-manifold topology (e.g. a stair connects to the inside of a room rather than an outer wall or connects to two rooms on one of its ends).

Problematic objects can be quickly selected by right clicking a group in the tree that has a warning or error icon, and selecting either Select Errors or Select Warnings from the right-click menu. In addition, if the warning on a component indicates that it interferes or overlaps with other components, the objects with which it interferes can be quickly selecting by right-clicking the object with the warning and selecting Select conflicting components from the right-click menu.

As a general note, if the warning "Edge is adjacent to more than 2 triangles" appears when simulating, an option to click Cancel appears to highlight the navigation components causing the warning.

In Pathfinder, there are several objects that can refer to other objects in the model. For instance, an occupant can refer to both a profile and a behavior, a behavior can refer to exits, the goto elevators action can refer to elevators, etc. There are times when it is useful to know what objects are referring to another. For instance, it may be important to know which occupants are using a particular behavior. To do this, right click the behavior (or other in-use object), and from the right-click menu, click Select Referencing Objects. This will highlight all objects currently using that behavior.

13.4. System memory issues

Some models may require significant system memory to run, either because the navigational model is complex with many doors/connections, etc, or simply because there are tens of thousands of occupants. By default, Pathfinder will use up to half of system memory to run the user interface and the simulation. In some cases, this is not enough, which may result in Pathfinder crashing or the operating system becoming unresponsive while the simulation is running. In this case, it may be possible to allow Pathfinder to use more system memory. There are two ways to do this.

The first way is to run Pathfinder from the command line and specify an additional flag that indicates more memory should be allowed for Pathfinder. To do so:

  1. In Windows, click the Start Menu, and then type cmd into the search bar. Enter on the keyboard to start the command prompt.
  2. In the command prompt, type cd "C:\Program Files\Pathfinder 2020" and press Enter. If you installed Pathfinder to a different location, enter that path instead.
  3. In the command prompt, type pathfinder -J-DXmx16000m, where 16000 is the amount of system memory to allow in megabytes. In most cases this amount should not exceed 95% of actual system memory.

For a more permanent way to specify a higher memory limit you can perform the following:

  1. If Pathfinder is not already pinned to the taskbar, in Windows click the Start Menu and type Pathfinder into the search bar. Then right-click the correct Pathfinder executable and select Pin to taskbar.
  2. In the Windows task bar, find the pinned Pathfinder application and right-click it.
  3. In the sub-menu that appears, right-click the Pathfinder executable and select Properties.
  4. At the end of the Target field, type a space on the keyboard and then -J-DXmx16000m. The shortcut dialog will look similar to Figure 143.
  5. Press OK and then start Pathfinder using the pinned shortcut.
windows ui dialog shortcut props
Figure 143. Example Shortcut Dialog

13.5. Issues with custom avatars

If you experience issues displaying a custom occupant or vehicle avatar, see Section 4.5.5 for help troubleshooting.

13.6. Video display problems and crashes on startup

Pathfinder utilizes many advanced graphics card features in order to provide accelerated and enhanced display of models.

Sometimes these graphics features combined with certain display drivers can cause display issues or crashes on startup. The first step in these cases is to ensure you have the latest operating system updates and graphics drivers installed. If you do and you still have display problems or crashing on startup, you can start Pathfinder in Safe Mode, which disables several graphics features. To start in Safe Mode:

  1. Open a command-prompt by opening the start menu and typing cmd. Then press Enter.
  2. In the command-prompt, navigate to the Pathfinder install folder by typing cd "C:\Program Files\Pathfinder 2021".
  3. Start Pathfinder in Safe Mode by typing pathfinder -DSafeMode.
  4. If Pathfinder starts up successfully, you can see which display properties were changed. Under the File menu, click Preferences, and then click on the Rendering tab.
  5. You can enable each item one at a time to see which ones caused the issue.

If you encounter display problems or crashes, please let us know the make/model of your video card and what video driver you are using, even if Safe Mode fixes your issues. That will help us improve the software in future updates.

13.7. Additional support resources

Pathfinder has a support forum located at https://thunderheadeng.freshdesk.com/support/discussions.

If you are unable to resolve your issues from the suggestions in the table, please contact Thunderhead Engineering Email Support.

The Pathfinder software is available for download from the release notes: https://support.thunderheadeng.com/release-notes/pathfinder/

Mail should be sent to:

Thunderhead Engineering
403 Poyntz Ave. Suite B
Manhattan, KS 66502-6081
USA

Appendix A: Pre-defined Speed Profiles

Pre-defined speed profiles are included in Pathfinder as a convenient starting point Table 13. All Pathfinder models are initialized with a "Default" profile. Additional bundles of profiles are included in the lib/profiles subdirectory of the Pathfinder install location.

Table 13. Summary of the profiles included with Pathfinder.
Profile SourceSpeedSpeed-Density RelationSpeed Factor Stairs
DefaultConstant (1.19 m/s)SFPE (built-in)SFPE (built-in)
imo_speed_profiles.plibUniform DistributionFrom TableConstant
fruin_speed_profiles.plibNormal DistributionSFPE (built-in)From Table

The "Default" profile present in new Pathfinder models is based on data in the SFPE’s Engineering Guide to Human Behavior in Fire (SFPE 2019). This profile uses a constant speed of 1.19 m/s and relies on Pathfinder’s defaults for speed-density relation and slope-based speed factor on stairs.

A.1. Profiles from the IMO’s Revised Guidelines for Passenger Ships

The profile bundle imo_speed_profiles.plib is based on data from the IMO’s guidelines (IMO 2007).

This source gives ranges of walking speeds on flat terrain for each of 12 different population groups. This is implemented directly in the Pathfinder profiles as per-profile uniform distributions. The bundle of profiles in Pathfinder includes only the ten population groups that do not correspond to crew members.

A table is given for speed-density relation on flat terrain in terms of "initial specific flow" and a reference "initial speed". These two values were used to create a speed-density factor table shared by all profiles in this set.

plot walking speeds function density
Figure 144. Graph of Walking Speeds as a Function of Density

The revised guidelines also define ranges of walking speeds up and down stairs for all population groups. Since Pathfinder requires a speed factor for stairs rather than a range, these values were approximated by calculating a constant scaling factor based on the average of the flat terrain range and the average of the range of speed on stairs.

A.2. Profiles from Fruin’s Pedestrian Planning and Design

The profile bundle fruin_speed_profiles.plib is based on data from John Fruin’s Pedestrian Planning and Design (Fruin and Strakosch 1987).

This source describes six population groups based on age and gender, and only gives a single normal distribution of walking speeds that is used for all population groups. This is implemented in Pathfinder by re-using the same normal distribution for the six population groups and an "Average All" aggregate profile.

The built-in SFPE-based speed-density relation is used for all profiles in this set. The built-in SFPE-based speed-density relation differs from the original data primarily in the locations where the min and max walking speeds are clamped. The original data was in terms of an absolute measurement of walking speed across multiple people rather than a value that could be normalized to a specific speed (1.2 m/s) and it went to zero at high densities which is undesirable for simulation because it could cause issues with occupants becoming permanently stuck. The following chart compares the original data to the relation used for this profile in Pathfinder.

plot walking speeds function density fruin
Figure 145. Graph of Walking Speeds as a Function of Density from Fruin

Pedestrian Planning and Design (Fruin and Strakosch 1987) gives stairway speeds for two slopes, identified as an "indoor" 32 degree stair (7" / 11.25") and an "outdoor" 27 degree stair (6" / 12"). Speeds are given for the up direction and the down direction and they are individualized for the six population groups and the aggregate group. These speeds were converted to tables of speed modifier fractions. For each slope and direction, the speed on stairs was converted to a fraction of max speed by dividing by the average of the flat walking speed (1.2 m/s) used by all population groups. This made it possible to create tables of speed modifiers unique to each population group and travel direction that contained two data points. For stairs with slopes more or less than the given 32 and 27 degree stairs, the factor is constant (i.e. not extrapolated).

Appendix B: BEA File Format

When Pathfinder imports a custom avatar, a BEA file is also created, located in the import directory of the avatar file. The BEA file tells Pathfinder which animations to use for the avatar and gives additional information about the avatar, such as scaling, rotation, and offset information, and natural speeds for the movement animations.

B.1. MESH Section

The MESH section of the BEA file links to the avatar file and describes any scaling and other transformation properties as follows:

MESH { "avatarfile" scale additional_transforms }

avatarfile
the filename of the avatar relative to this BEA file.
scale
A scaling factor to apply to the avatar if the avatar is the incorrect size. For instance, if the avatar appears to be about 50% of its real size when using a scaling factor of 1.0, try a scaling factor of 2.0 to make it twice as big.
additional_transforms
[optional] May be any number of the following transforms:
rotate rx ry rz rangle
Rotates the avatar about the axis, (rx, ry, rz), an angle of rangle degrees, using the right-hand rule.
translate tx ty tz
Moves the avatar a distance of (tx, ty, tz) units.

The scale factor is always the first transform applied to the avatar. All other transforms are applied in reverse order, meaning that the last listed transform is the first non-scale transform applied to the avatar.

Example:

MESH {"avatar.fbx" 2.0 translate 0 0 .1 rotate 0 0 1 90 rotate 1 0 0 180}

will first scale the avatar by 200%, then rotate it about the X axis by 180°, then rotate about the Z axis by 90°, and finally move it up along the Z axis by .1 m.

B.2. ANIMATIONS Section

The ANIMATIONS section is only used for occupant avatars. There are two categories of animations: IDLE and MOVE. Each category can have several animations types. Each animation type can list any number of animation files. Each animation file is listed with several parameters, depending on the category of the animation.

The animation types are as follows:

Table 14. Animation Types
Animation TypeCATEGORYDescription
IDLESTANDIDLEUsed when an occupant is standing and waiting.
IDLEWHEELCHAIRIDLEUsed when an occupant is in a wheelchair and is waiting or being assisted.
IDLEINJUREDIDLEUnused.
IDLEBEDFLATIDLEUsed when an occupant in on a bed.
IDLESEVERLYINJUREDIDLEUnused.
MOVEFORWARDMOVEUsed when an occupant is walking forward.
MOVEBACKWARDMOVEUsed when an occupant is walking backward. If this animation type isn’t included in the BEA file, the MOVEFORWARD animations are used and played backward.
MOVEFORWARDDOWNSTAIRSMOVEUsed when an occupant is walking forward down stairs.
MOVEBACKWARDDOWNSTAIRSMOVEUsed when an occupant is walking backward down stairs. If this animation type isn’t included in the BEA file, the MOVEFORWARDUPSTAIRS animations are used and played backward.
MOVEFORWARDUPSTAIRSMOVEUsed when an occupant is walking forward up stairs.
MOVEBACKWARDUPSTAIRSMOVEUsed when an occupant is walking backward up stairs. If this animation type isn’t included in the BEA file, the MOVEFORWARDDOWNSTAIRS animations are used and played backward.
MOVEFORWARDWHEELCHAIRMOVEUsed when an occupant is moving forward in a wheelchair without assistance.
MOVEBACKWARDWHEELCHAIRMOVEUsed when an occupant is moving backward in a wheelchair without assistance. If this animation type isn’t included in the BEA file, the MOVEFORWARDWHEELCHAIR animations are used and played backward.

B.2.1. IDLE Animations

IDLE animations are used when an occupant is in an idle state. When several IDLE animations are listed for an animation type, one is chosen at random each time the occupant enters an idle state. IDLE animations are listed with the following format:

animationtype { listofidleanims }

where listofidleanims is a list of animations in this format:

"animfile" transforms

animfile
the name of the animation file, relative to the current BEA file.
transforms
a list of transforms to be applied to the listed animation in reverse order. It includes additional_transforms as specified in Section B.1 with one additional transform:
scale s
Scales the animation by a factor of s. Unlike the scale parameter in the Section B.1, this scale transform is applied in order with the other listed transforms.

B.2.2. MOVE Animations

MOVE animations are listed with the following format:

animationtype { listofmoveanims }

where listofmoveanims is a list of animations in this format:

"animfile" frameoffset naturalspeed maxspeed retargettype transforms

animfile
the name of the animation file, relative to the current BEA file.
frameoffset
the frame offset that defines the start of the animation clip. This should specify a time in the animation when the character is closest to standing up straight. For walking/running animations, the same foot must be stepping forward after each frameoffset for ALL moving animations.
naturalspeed
the natural movement speed in m/s of the animation. When the occupant is moving this at this speed, the animation will be played back at 1x speed. If the occupant is moving at twice this speed, the animation will be played back at 2x speed, etc.
maxspeed
The maximum occupant speed in m/s at which this animation should be used. If the occupant is moving faster than this speed, the next animation of this type is used unless this is the last of its type.
retargettype
[optional] If specified, specifies that this animation was created using a different avatar than the one listed in the MESH section. This can take on the following values:
retarget
Indicates that the animation was created using a different avatar that has the same joint/skeletal structure as the MESH avatar.
retarget_to_self
Indicates that the animation was created using a different avatar with a different joint/skeletal structure than the MESH avatar. The animation file itself contains the avatar for which the animation was made - this only works if the anim file is an FBX file and contains the avatar as well as the animation.
retarget_to "retargetavatarfile"
Indicates that the animation was created using a different avatar with a different joint/skeletal structure than the MESH avatar. retargetavatarfile specifies the file relative to the BEA file that contains the avatar for which the animation was made.
transforms
Same as for the IDLE animations.

Example:

 MOVEFORWARD {
    "anims/walk1.md5anim" 13 .725 1.1 retarget_to "anims/base_mesh.md5mesh"
    "anims/walk3.md5anim" 5 1.800 1.7 retarget_to "anims/base_mesh.md5mesh"
    "anims/maleRun.md5anim"   4 3.170 1000 retarget_to "anims/base_mesh.md5mesh"
}

This exampe indicates that there are three animations for moving forward. The first specifies that the 13th frame of walk1.md5anim is when the occupant is about to step forward. The animation will playback at 1x speed when the occupant is moving .725 m/s. walk1.md5anim should only be used if the occupant is walking less than 1.1 m/s. In addition, walk1.md5anim was created for the avatar specified in base_mesh.md5mesh rather than the avatar specified in the MESH section. walk3.md5anim should be used when the occupant is walking between 1.1 m/s and 1.7 m/s. maleRun.md5anim is used if the occupant is walking faster than 1.7 m/s.

Bibliography

Pathfinder Technical Reference. n.d. 403 Poyntz Avenue, Suite B, Manhattan, KS 66502, USA: Thunderhead Engineering. https://support.thunderheadeng.com/docs/pathfinder/latest/technical-reference-manual/.

Pathfinder Verification and Validation. n.d. 403 Poyntz Avenue, Suite B, Manhattan, KS 66502, USA: Thunderhead Engineering. https://support.thunderheadeng.com/docs/pathfinder/latest/verification-validation/.

Pathfinder Results User Manual. n.d. 403 Poyntz Avenue, Suite B, Manhattan, KS 66502, USA: Thunderhead Engineering. https://support.thunderheadeng.com/docs/pathfinder/latest/results-user-manual/.

Bukowski, Richard W., and Fang Li. 2010. “Using Elevator In Fires.” Consulting – Specifying Engineer, July.

Fridolf, Karl, Enrico Ronchi, Daniel Nilsson, and Håkan Frantzich. 2019. “The Representation of Evacuation Movement in Smoke- Filled Underground Transportation Systems.” Tunnelling and Underground Space Technology 90 (April): 28–41. https://doi.org/10.1016/j.tust.2019.04.016.

Fruin, J.J., and G.R. Strakosch. 1987. Pedestrian Planning and Design. Elevator World. https://books.google.com/books?id=vrckAQAAMAAJ.

IBM. n.d. “Default Swing Key Bindings.” Accessed November 18, 2019. https://ibm.co/2O58h5A.

IMO. 2007. “IMO Guidelines for Evacuation Analysis for New and Existing Passenger Ships.” 4 Albert Embankment, London, Great Britain: International Maritime Organization.

Pheasant, Stephen, and Christine M. Haslegrave. 2005. Bodyspace: Anthropometry, Ergonomics and the Design of Work. 3rd ed. CRC Press. https://books.google.com/books?id=vrckAQAAMAAJ.

SFPE. 2019. SFPE Guide to Human Behavior in Fire. 2nd ed. Springer International Publishing. https://www.springer.com/gp/book/9783319946962.

Still, G. Keith. 2000. “Crowd Dynamics.” PhD thesis, University of Warwick. http://gkstill.com/Support/Links/Documents/2000_still.pdf.