Pathfinder Technical Reference Manual

1.1. Example Problem IMO Test 10

In the following discussions, it is often useful to have an example with which to illustrate particular points. One frequently referenced example is Test 10 from the International Maritime Organization (IMO) (IMO 2016).

This test problem represents a cabin corridor section as shown in Figure 1, the cabins are populated as indicated. The population consists of males 30-50 years old with a minimum walking speed of 0.97 m/s, a mean speed of 1.30 m/s, and a maximum speed of 1.62 m/s. There is no delay in response and the walking speeds are distributed uniformly between the minimum and maximum to the 23 occupants. The passengers in cabins 5 and 6 are assigned the secondary exit; all the remaining passengers use the main exit. The expected result is that the allocated passengers move to the appropriate exits.

The display of occupant movement, Figure 2, does show that occupants have selected the assigned exits. In this display, the paths of all occupants are displayed, with selected occupants and their paths highlighted. For the steering mode analysis, all occupants exited the corridor in 18.0 seconds.

The results for SFPE mode are illustrated in Figure 3. In SFPE mode, the passengers form a queue at the main exit and the flow through this door controls the exit time. For the SFPE analysis, all occupants exited in 21.2 seconds. In SFPE mode, occupants can overlap in space during movement and when the queue forms.

2.1. Geometry Subdivision

The navigation geometry is organized into rooms of irregular shape. Each room has interior (optional) and exterior _boundaries_ that cannot be crossed by an occupant.

Travel between two adjacent rooms is through connecting doors. A door that does not connect two rooms and is defined on the exterior boundary of a room is an exit door. There can be multiple exit doors in a model. When an occupant enters an exit door in SFPE mode, they are queued at the door and removed at the flow rate defined by SFPE. Occupants that enter an exit door in reactive steering mode are removed from the simulation immediately.

Figure 6 illustrates these concepts for the IMO Test 10 problem. The rooms (and corridors) are shaded different colors. Doors from individual rooms to the corridor (just another room in the model) are indicated by a thick orange line. Exit doors are indicated by a thick light green line. Occupants are shown by the blue dots. Superimposed on the geometry is the navigation mesh.

Any location on the navigation mesh can be categorized as one of four terrain types: open space, stairs, doors and exit. Ramps and rooms are both classified as open space. Each terrain type has an effect on the behavior of occupants on that section of the mesh.

3.1. Idle Goals

When occupants idle, they wait until an event occurs. While the occupant is waiting in SFPE Mode, they stand still until the event occurs. While the occupant is waiting in Steering Mode, they use separation to maintain a distance from other occupants (see Section 6.4.2).

Because the occupant may move in Steering Mode, they are assigned a containment area that depends on the previous seek goal in the occupant’s behavior. If the occupant leaves this area because of separation, they create and use a temporary seek goal to return to the area.

The areas are defined as follows:

3.2. Seek Goals

When an occupant seeks, they are trying to find a destination on the mesh. The occupant uses path planning, path generation, and path following to reach the destination as discussed in Chapter 4.

3.3. Goals

The following are the types of goals in Pathfinder. Some have a corresponding behavior action in the user interface, while others may be created as sub-goals of a particular behavior action.

In the user interface, an occupant may be assigned a Goto Refuge Rooms behavior action. There is no corresponding goal in the simulator, however. For unassisted agents, this merely becomes a Goto Rooms goal.

For assisted clients, however, they are assigned the following sequence of goals:

3.3.2. Door Distance Map

The first step of room-filling is to acquire a door distance map that indicates how far away a door is for any point in the room. This map is generated by sub-dividing the room into smaller triangles as shown in Figure 7. For each vertex of the sub-divided triangle, a distance value is generated that is the minimum distance to a set of doors. A color-mapped version of this distance map is shown in Figure 8.

The set of doors used to generate the distance map varies per-occupant based on whether the occupant can move in the room. For assisted occupants who cannot move on their own and will be left in the room, the set includes all doors attached to the room. For all other occupants, the set only includes doors that are active. An active door is one that has occupants waiting to enter on the other side or that has had an occupant pass through into the current room in the past 15 seconds. The occupant will periodically check to see if the door distance map has changed and update their decisions accordingly.

4.1. Path Planning

Path planning is the process of determining a plan for moving toward a destination.

Given an occupant seeking a destination, there may be multiple paths to reach the destination, each with differing lengths, numbers of occupants along the way, and various hazards. A naïve path planning approach to choosing a route would be to take the shortest route. This may not be the fastest or best route to the destination for a particular occupant, for this they need to find the path out of a room in the least amount of time. In Pathfinder this is solved by the Locally Quickest method.

The occupant uses the following steps to plan a path.

4.2. Path Generation

Once a local target has been chosen through path planning, a path is needed to reach the target. Pathfinder uses the \(A*\) search algorithm (Hart, Nilsson, and Raphael 1968) and the triangulated navigation mesh. The resulting path is represented as a series of points on edges of mesh triangles. These points from \(A*\) create a jagged path to the occupant’s goal.

To smooth out this jagged path, Pathfinder then uses a variation on a technique known as string pulling (Johnson 2006). This re-aligns the points so the resulting path only bends at the corner of obstructions but remains at least the occupant’s radius away from those obstructions.

Examples of these generated points, called waypoints, are shown in Figure 9. This example shows the projected path of an occupant in a simple rectangular room. The occupant is standing in the lower-left corner and plans to exit out the lower-right corner. The navigation mesh is shown by the thin lines that form triangles inside the rectangular area. An obstruction prevents the occupant from walking straight to the exit. The planned path of the occupant is shown as the dark line and the waypoints are shown as circles. A waypoint is generated for each edge that intersects the path.

Once these waypoints are found, Pathfinder removes intermediate points that lie between two others in a straight line. This creates a series of waypoints only where the direction of travel will change.

4.3. Path Following

Once a path is generated, the occupant needs a way to follow the waypoints.

The occupant performs the following:

The following images show the paths and waypoints for the IMO Test 10 problem for both SFPE (Figure 10) and Steering (Figure 11) modes. The green lines indicate the current seek curves for each occupant. The red lines and points indicate future paths and waypoints. Notice the straight seek curve in the SFPE mode as compared to the spline used in steering mode.

5.1. SFPE Mode Parameters

In SFPE Mode, the following parameters are used.

5.2. Velocity

The velocity (\(v\)) at which an occupant moves depends on several factors, including the occupant’s maximum velocity (\(v_{max}\)) specified in the user interface, the type of terrain being travelled on, speed modifiers and constants associated with the terrain, and occupant density in the current room.

5.2.1. Base Speed

The occupant’s base speed (\(v_{b}\)) is defined as a function of density, terrain, and a speed fraction curve based on the SFPE fundamental diagram. It does not take terrain speed modifiers or constants into account.

\(v_{b} = v_{max}*v_{f}\left( D \right)*v_{ft}\)

Where:

\(v_{max}\) is the occupant’s maximum speed as entered in the user interface as Speed.

\(v_{f}(D)\) is a speed fraction as a function of density as follows:

\[v_{f}(D) = \begin{cases} 1, & D < .55\ pers/m^{2} \\ \text{max}\left\lbrack v_{fmin} , \frac{1}{.85}(1 - .266D) \right\rbrack , & D \geq .55\ pers/m^{2} \end{cases}\]

\(v_{fmin}\) is a minimum speed fraction as defined in the user interface (default=.15), and \(D\) is the occupant density in the current room.

\(v_{ft}\) is a speed fraction that depends on the type of terrain being traversed by the occupant.

It is defined as:

\(v_{ft} = \frac{k}{1.4}\)

For level terrain (rooms) and ramps, \(k = 1.40 m/s\).

For stairs, \(k\) depends on the step slope of the stairway. The SFPE handbook defines \(k\) only for a limited set of known step slopes as follows:

Stair Riser (inches)	Stair Tread (inches)	k
7.5	10.0	1.00
7.0	11.0	1.08
6.5	12.0	1.16
6.5	13.0	1.23

Pathfinder uses this information to determine \(k\) values for any stairs by constructing a piece-wise linear function that maps step slope to k values using these known data points.

The step slope of a stair is defined as:

\(\text{step slope} = \frac{\text{stair riser}}{\text{stair tread}}\)

For step slopes above .75 (the maximum in the table), the values are extrapolated down to a minimum k of .034. This ensures that very steep stairs do not cause occupants to become excessively slow. For step slopes below .5 (the minimum in the table), \(k\) is linearly interpolated to 1.4 at a step slope of 0 (while not realistic, this would correspond to a flat stairway). This produces a \(k\) function as shown in Figure 12.

5.3. Movement through Doors

When using Pathfinder in SFPE Mode, the occupant flow rate through the door is specified by the SFPE guidelines. This is implemented using a delay timer that controls how quickly occupants are allowed to pass through the door. This timer is initially set at zero. When an occupant passes through the door, the simulator calculates a delay time based on the specific flow of the door. That delay time is added to the door and must elapse before another occupant is allowed to pass through.

Each door may have a different specific flow depending on the direction occupants are going through the door and the type of terrain connected to the door. The specific flow for a particular direction through a door is

\(F_{s} = \left( 1 - .266 * D \right)*k*D\)

The evacuation speed constant, \(k\), depends on the terrain of the previous room, and \(D\) is the maximum of the occupant densities in the rooms attached to the door. Because the flow equation is quadratic, the value of \(D\) is clamped to the range [1.9, 3.0] pers/m2. This range ensures that low densities do not slow the flow rate and that high densities do not reduce the flow rate to zero.

In the user interface, if Door Flow Rates at High Density, Use a Calculated Specific Flow is selected, the density is calculated as described above. Otherwise, it is set to 1.88 pers/m2 to maximize the flow rate.

The time it takes \(n\) occupants to pass through a door with effective width \(W_{e}\) is:

\(T = \frac{n - 1}{F_{s}}\)

The \(n\) value is reduced by 1 because the first occupant through a door does not have to wait for a time delay.

In counter-flow situations, an occupant from \(R_{1}\)­ may be waiting at a queue to enter \(R_{2}\) while an occupant from \(R_{2}\) may be waiting to enter \(R_{1}\). In this case, the queues evenly exchange their next occupant and both occupants are allowed through the door. The delay time placed on the door queue becomes the sum of the delay times from each occupant’s passage, which maintains the correct flow rate for the simulation.

5.4. Collision Handling/Response

In SFPE mode, while occupants cannot collide with other occupants, they can still collide with walls. Collision handling is applied in two steps. The first step occurs before movement is attempted for a time step, and the second occurs during movement. For the pre-movement step, the travel velocity is adjusted to force the occupant to slide along any nearby walls. After the travel velocity is adjusted, the occupant attempts to move using this new velocity. During the movement stage, wall collisions are still possible, so the occupant will simply halt at the earliest collision.

6.1. Velocity

As an occupant moves along their path, they calculate a modified maximum velocity, \(\acute{v}_{max}\), that depends on the occupant’s current terrain, specified maximum velocity, \(v_{\max}\), and the spacing of surrounding occupants. The spacing of surrounding occupants is used to estimate an occupant density, \(D\), as described below. These parameters are then used in the equations to calculate v in SFPE mode which becomes \(\acute{v}_{\max}\).

In steering mode, both \(v_{f}(D)\) and \(v_{ft}\), which are used to calculate \(\acute{v}_{max}\), may either be left at the SFPE default or may be user-defined in the occupant profile as piece-wise linear functions. \(v_{f}(D)\) is entered as a function of occupant density and \(v_{ft}\) is entered as a function of either stair step slope or ramp slope, depending on the terrain type. Stair step slope is entered in the user interface by specifying a stair’s riser and tread. Ramp slope is determined by the normal of the triangle that belongs to a ramp node and cannot be entered directly by the user.

A triangle’s slope is calculated as follows:

\(slope = \frac{\sqrt{{n_{x}}^{2} + {n_{y}}^{2}}}{n_{z}}\)

\(n_{x}\), \(n_{y}\), and \(n_{z}\) are the components of the triangle’s normal. In addition, different \(v_{f}(D)\) and \(v_{ft}\) functions may be defined for when the occupant goes up or down stairs or ramps. This is in contrast to SFPE calculations, which use the same functions for both up and down.

Once \(\acute{v}_{max}\) is calculated, it is then used by the steering system to calculate a desired velocity vector as described in Section 6.4.

6.2. Acceleration

An occupant’s acceleration is split into multiple components depending on the desired velocity vector calculated by the steering system.

A tangential forward component of acceleration is calculated as:

\(a_{fmax} = \frac{v_{max}}{t_{accel}}\)

Where \(t_{accel}\) is the occupant profile parameter, Acceleration Time.

The tangential reverse component of acceleration is:

\(a_{bmax} = 2*a_{fmax}\)

The radial component of acceleration is:

\(a_{rmax} = 1.5*a_{fmax}\)

These components are combined to determine the final acceleration vector.

6.3. Estimation of Occupant Density

To calculate \(\acute{v}_{max}\) for an occupant, the occupant density \(D\) at that occupant’s location must be known.

Pathfinder estimates the density by using the spacing of the near occupants and the average longitudinal and lateral spacing density relationship demonstrated in Chapter 3 of (Fruin and Strakosch 1987) as shown in Figure 13.

In Pathfinder, the density lines in the figure are treated as contours, each being estimated as an ellipse. The contours are mirrored about Y=0.

To calculate the density for an occupant, the X axis in the figure is aligned with the occupant’s current velocity and the origin is set to the occupant’s location, forming a local coordinate system. Then for each other near occupant, their location is transformed to this local coordinate system. If the local coordinate for the other occupant has an x value less than 0, the occupant is ignored. This prevents an occupant’s speed from being affected by occupants behind them. For occupants with local \(x >= 0\), the density is interpolated or extrapolated from the density contours. The maximum of these densities is then used as the density for the occupant.

6.4. Steering

The steering system in Pathfinder moves occupants so they roughly follow their current seek curve and can respond to a changing environment. Inverse steering, used in Pathfinder, is the process of evaluating a set of discrete movement directions for an occupant and choosing the direction that minimizes a cost function. See Figure 14 for an example of sample directions. The cost function is evaluated by combining several types of steering behaviors to produce a cost. The types of steering behaviors used are determined by the occupant’s current state, and the number of sample directions is controlled by the occupant’s state and current velocity. For more information on states, see Section 6.6.

Pathfinder defines several steering behaviors: seek, idle separate, seek separate, seek wall separate, avoid walls, avoid occupants, pass, lanes, and cornering. Most behaviors award a cost between 0 and 1 for each sample direction. The net cost for a direction is a weighted sum of these values.

6.5. Evaluating Movement

Once the lowest cost direction has been determined, the steering velocity and acceleration are calculated that will move the occupant in the steering direction.

Along with a cost, each steering behavior calculates a maximum distance that should be traveled along the sample direction. This maximum distance is then used to determine the magnitude of the desired velocity, \(\overline{v}_{\text{des}}\), as follows:

\(D_{stop}=\frac{{\acute{v}_{curr}}\,^{2}}{2a_{max}}\)

\(\left|\overline{v}_{des}\right| = \left\{\begin{matrix} 0, & D_{max} \leq D_{stop} \\ v_{max}, & D_{max} > D_{stop} \end{matrix}\right.\)

\(\overline{v}_{des} = \left|\overline{v}_{des}\right| \overline{d}_{des}\)

Where:

\(D_{\max}\) is the maximum distance for the lowest cost sample direction, \(\overline{d}_{\text{des}}\) is the lowest cost sample direction, and \(\overline{v}_{\text{curr}}\) is the occupant’s current velocity.

The acceleration is calculated as follows (Reinolds 1999):

\(\overline{a} = \frac{\overline{v}_{des}-\overline{v}_{curr}}{\left|\overline{v}_{des}-\overline{v}_{curr}\right|} a_{max}\)

Explicit Euler integration is then used to calculate the velocity and position of each occupant for the next time step from their steering acceleration. The velocity and position are calculated as follows:

\(\overline{v}_{\text{next}} = \overline{v}_{\text{curr}} + \overline{a}\delta t\)

\(\overline{p}_{\text{next}} = \overline{p}_{\text{curr}} + \overline{v}_{\text{next}}\delta t\)

Where:

\(\delta t\) is the time step size, \(\overline{p}_{\text{curr}}\) is the current position, and \(\overline{p}_{\text{next}}\) is the position after the time step.

6.6. Occupant States

Depending on an occupant’s current scripted behavior, they will be in one of two states:

6.7. Priority

Pathfinder provides a priority system that operates on discrete priority levels assigned to each occupant. When occupants encounter other occupants at the same priority level as their own, they behave as indicated above (the common case). If, however, they detect another occupant with a different priority nearby and in front of them, they will slightly alter the above behaviors.

If the other occupant is of lower priority, the occupant will not separate and will use a comfort distance of zero, effectively allowing them to push against the other occupant if necessary. Because there is no notion of occupants exerting force on one-another, the other occupant must respond accordingly.

So in the inverse case of an occupant detecting another of higher priority within their comfort distance, they will ignore their seek behavior and instead use their separation behavior, even if their goal puts them in a seek state. This allows them to back away from the occupant of higher priority, giving the higher priority occupant a chance to move through.

Priority levels are completely relative. For example, if three occupants meet having priorities of 5, 7, and 12, their behavior toward one another would be exactly the same as if their priorities were 0, 1, and 2, respectively. Occupants with higher priority values have higher priority over other occupants.

6.8. Resolving Movement Conflicts

There are some scenarios where an occupant’s movement conflicts with another occupant’s movement due to limitations of the geometry. In these situations occupants must negotiate how to resolve these conflicts such that they can continue moving.

The following examples illustrate how these situations can arise:

Figure 15 - Multiple occupants are simultaneously headed in a common direction and are approaching a physically tight area that will not allow all of them to pass at once (such as a narrow door or narrow hallway).

Figure 16 - Occupants are headed in opposite directions in a crowded hallway (counterflow).

Figure 17 - Occupants have squeezed into a tight area and cannot back up, due to a wall or one-way door.

Figure 18 - Occupants are headed in opposite directions in a hallway that will not physically allow them to pass.

Pathfinder employs special handling to resolve these movement conflicts and prevent occupants from becoming stuck. This is handled as part of each occupant’s steering behavior as follows:

6.9. Collision Avoidance/Response

While the wall and occupant avoidance behaviors will attempt to steer around obstacles, they might not always succeed. This often occurs in crowded situations when occupants cannot avoid being pressed tightly against walls and other occupants. In these situations, additional collision handling is necessary to prevent the simulation from entering an invalid state. There are two collision handling scenarios: one in which two or more occupants collide and another where an occupant collides with the boundary of the navigation mesh (i.e. a wall).

If collision handling is turned on, the occupant will halt at the earliest collision with either a wall or another occupant for a given time step. If collision handling is off, the occupant will only halt at the earliest collision with a wall.

6.10. Movement through Doors

By default, Steering Mode simulations provide no additional constraints on occupants when they move through doors. Flow limiting can be turned on, however, either through the simulation parameter, Limit Door Flow Rate, or the Flow rate parameter on individual doors.

In Steering mode, flow limiting works similarly to that in SFPE mode. For more details, see Section 5.3. The main differences between flow limits in the two modes are as follows:

8.1. Assist Occupants Goal

This goal is specified as the Assist Occupants behavior action in the user interface. This goal allows an assistant to help all clients who are requesting or will request assistance from a particular team until all those clients have either exhausted their goals or detached from their assistants.

The following is a broad step-by-step procedure of how the assist occupants goal progresses:

For each assistant, the Assist Occupants Goal is further decomposed into three other sub-goals:

The process of assigning these goals in a multithreaded application can lead to problems such as the loss of determinism, concurrency exceptions or increased running time due to the necessary synchronization. All these issues are addressed by the coalition formation algorithm described in Section 8.3.

8.2. Wait for Assistance Goal

This goal is specified as the Wait for Assistance behavior action in the user interface. The procedure for this goal is as follows:

At this point, the client has attached assistants. The client then continues with their next goals as they normally would. They detach from their assistants once one of the following occurs:

Instead, a client is assigned the following sequence of goals:

8.3. Coalition Formation Algorithm

Pathfinder is a multithreaded application, in which the agents decide about their movement in a pre-move step and update their state in an update step. Each one of these steps can be performed by the agents in parallel. Assisted evacuation requires the agents to coordinate and cooperate. This behavior brings multiple implementation challenges, because it requires deterministic interactions between agents.

The following fundamental steps are performed by the simulator engine in every step of the simulation:

Notice that the goals are updated in a similar way to the agents. These three steps must be separated in order to preserve determinism.

The following are the procedures added to Pathfinder to support assisted evacuation:

9.1. Idling

At the start of a simulation, each elevator is idle. All doors connecting all levels to the elevator are closed, the elevator is at the discharge floor, and the elevator is waiting to be called from one of the pickup levels. Once called, it proceeds to the pickup stage.

9.2. Pickup

When a pickup level calls an elevator, the elevator moves toward that level. If multiple pickup levels call the elevator at once, the elevator travels to the one with the highest priority as specified in the user interface. As the elevator travels toward the pickup level, it continues monitoring calls. If a call is received from a level with higher priority before the elevator reaches the current pickup level, the elevator switches pickup levels. The time to reach the pickup level is specified in the user interface.

When the elevator reaches a pickup level, it opens its doors and waits for a countdown timer to elapse. The elevator then closes its doors and proceeds to the discharge stage.

9.3. Discharge

After the elevator is loaded at the pickup level, it moves toward the discharge level. The amount of time it takes to reach the discharge level is the same as travelling from the discharge to pickup level as specified in the user interface. Once the elevator reaches the discharge level, it opens its doors. When the elevator is empty, it closes its doors and enters the idle state again.

11.1. NODES

Rooms, doors, and stairways are represented by nodes. At any given time during the simulation each occupant is either inside one of the following nodes or has exited the simulation.

[nodes]
name <node display index>, <animation id>,
[optional: "count" <max occupant count in pers> or "dens" <max occupant density in pers/m^2>]

11.2. VERTS

This section contains all of the vertices that will be used by the geometry (triangles and edges) in the input file.

[verts]
x y z
...

11.3. NAVMESH << NODES, VERTS

This section defines the walkable space within a simulation.

[navmesh]
ixnode ttype ixverta ixvertb ixvertc
...

11.4. DOORS (optional) << NODES

This section defines the doors that will be used if the use_door_queues option is enabled. Associating a door entry with a node causes that node to be recognized by the simulator as a door node and prevents the density calculation from being used to control the speeds of occupants within triangles associated with that node. This section does not define the geometric edges that the door represents.

Exit doors should define only one adjoining room and internal doors should define two such rooms. These entries are used to prevent overcrowding as occupants transition between rooms and to provide for more elaborate merge calculations.

[doors]
ixnode eff_width ixnodeA ixnodeB flowrate doorDir
...

11.5. EDGES (optional)

The entries in this section represent the geometric portion of entities that are defined as edges in the NAVMESH.

[edges]
etype <depends on etype>
...

boundary ixverta ixvertb

This edge type represents a boundary that occupants will not walk across.

door ixnode ixverta ixvertb

This edge type represents an internal door. Doors of this type will not be included in the search for the nearest exit and should have two adjoining nodes defined in the corresponding door record.

exit_door ixnode ixverta ixvertb

This edge type represents an exit door. Doors of this type will be included in the search for the nearest exit and should have one adjoining node defined in the corresponding door record.

11.6. PARAM (optional)

This section allows you to customize global simulation parameters. The format is a list of key value pairs.

[param]
key value
...

11.7. EVENTS

Event entries describe events that will happen during the simulation.

[events]
time event
...

11.8. BEHAVIORS

These entries are descriptions of artificial intelligence for simulation agents.

[behaviors]
key value
...

Behaviors are stored in a JSON key-value format. The supported keys are name and script. Script contains a list of actions separated by a semicolon. Following is a table of available actions for occupant behavior in Pathfinder.

Example of a behavior line:

2: {"name":"Behavior01","script":"goto point (-7.0, 3.0, 0.0) 1.5; tag (last_goal_started); goto exit any"}

11.9. PROFILES

[profiles]
key value
...

This section lists all the properties defined for an occupant profile. Profiles are stored in a JSON key-value format. Following table shows available keys and values for a profile. Note that only properties with values that are not default are written in the file. Furthermore, only profiles that are used by any occupant or occupant source are written in the file.

{"x":[0.55,3.23],
"y":[0.93,0.15],
"type":"pw",
"extrapolate":
false}

{"x":[0.55,3.23],
"y":[0.93,0.15],
"type":"pw",
"extrapolate":
false}

{"val":
{"min":"0.08 m",
"max":"0.1 m",
"type":"unif"},
"type":
"COMFORT_DIST"}

{"x":[0.55,3.23],
"y":[0.93,0.15],
"type":"pw",
"extrapolate":
false}

{"x":[0.55,3.23],
"y":[0.93,0.15],
"type":"pw",
"extrapolate":
false}

Example of a profile line:

0: {"OccProfile.NAME":"Profile00","OccProfile.SHAPE":1, "OccProfile.COLOR":[0.2,0.4,0.8,1.0]}

11.10. ATTRACTORS

[attractors]
key value
...

Attractors define objects that can change an occupant’s behavior based on their location. Attractors are stored in a JSON key-value format. The following table shows available keys and values for attractors.

Examples of attractor lines:

0: {"awareness":"LINE_OF_SIGHT","name":"Attractor00","location":[-11.5,3.0,0.0],"id":0,"behavior":0,"radius":2.0,"influence":1.0}
1: {"awareness":"ROOM_ONLY","name":"Attractor01","location":[-6.499999999999999,3.5000000000000004,0.0],"id":1,"behavior":1,"influence":0.5}
2: {"awareness":"ROOMS","name":"Attractor02","rooms":[0,1],"id":2,"behavior":1,"influence":1.0}
3: {"awareness":"GLOBAL","name":"Attractor03","id":3,"behavior":2,"influence":1.0}

11.11. FUNCTIONS

[functions]
key value
...

Functions are used to map an independent variable x to a dependent variable y. Pathfinder supports two types of functions: piecewise linear and constant. Functions are stored in a JSON key-value format. Following table shows available keys and values for the piecewise linear function.

Constant function stores a single value. Following table shows available keys and values for the constant function.

Example of a function line:

0: {"x":[0.55,3.2779887218045123],"y":[1.0,0.15],"type":"pw","extrapolate":false}

11.12. DISTRIBUTIONS

[distributions]
key value
...

Distributions in Pathfinder are either curves or urns. Curves represent continuous distributions, while urns represent discrete distributions.

Following four curve types are currently supported: constant curve, uniform curve, standard normal curve, and log normal curve. Curves are stored in a JSON key-value format. Following table shows available keys and values for the constant curve.

Following table shows available keys and values for the uniform curve.

Following table shows available keys and values for the standard normal and log normal curves.

Example of a curve line:

2: {"min":"45.58 cm","max":"50.58 cm","type":"unif"}

Urns are also stored in a JSON key-value format. An urn line contains two keys: "urn" and "type". The "urn" key maps to an array of pairs, each pair contains a value mapped to its probability. The sum of all probabilities in an urn must be equal to 1.0. The "type" key maps to the type of variables in the urn. The following types are supported: "int" for integer values, "bool" for true/false values, "string" for string values, and "ud" for double values with units.

Example of an urn line:

3: {"urn":[{"2.0 s":0.33},{"8.0 s":0.33},{"15.0 s":0.33999999999999997}],"type":"ud"}

11.13. COMPONENT RESTRICTIONS

[component-restrictions]
key value
...

This section defines component restrictions for occupants and occupant profiles. Component restrictions are stored in a JSON key-value format. Following table shows available keys and values for the component restrictions.

11.14. ATTRACTOR SUSCEPTIBILITY

[attractor-susceptibility]
key value
...

This section defines attractor susceptibilities for occupants and occupant profiles. attractor susceptibilities are stored in a JSON key-value format. The following table shows available keys and values for the attractor susceptibilities.

Examples of attractor susceptibility:

0: {"values":[{"item":0,"value":.25},{"item":2,"curve":0}]}
1: {"value":.2}
2: {"curve":0}

11.15. OCCUPANT SHAPES

This section defines shapes of occupants, both for polygonal and cylindrical occupants.

[occshapes]
type height attachedAgentsPositions anim model
...

Example of a polygonal occupant shape:

0: type=poly 4 -0.66 -0.38 0.0 0.66 -0.38 0.0 0.66 0.38 0.0 -0.66 0.38 0.0, height=1, attachedAgentsPositions=1 -0.71 0.0 0.0, anim=wheelchair, model=props/Wheelchair/Wheelchair.bea

Example of a cylindrical occupant shapes:

1: type=cylinder, diameterdist=10, height=1.8288, geomradius=0.33
2: type=cylinder, diameter=.42, heightdist=3

11.16. ASSISTED EVACUATION TEAMS

This section defines assisted evacuation teams.

[assisted-evac-teams]
goals name
...

Example of an assisted evacuation team line:

1: goals=3|1,name=AETeam00

11.17. OCCUPANT SOURCES

[occupant-sources]
key value
...

This section defines occupant sources. Occupant sources are stored in a JSON key-value format. Following table shows available keys and values for the occupant sources.

Example of an occupant source line:

1: {"component":13,"behaviors":{"urn":[{"2":0.4},{"0":0.6}]},"enforceFlowrate":false,"name":"OccSource01","profiles":{"urn":[{"0":0.25},{"1":0.25},{"2":0.25},{"3":0.25}]},"bounds":{"min":"(-3.0686769149632847, 5.422381629126958, 0.0)","max":"(-2.2558769149632854, 5.422381629126958, 0.0)"},"flowrate":4}

11.18. TAGS

[tags]
key value
...

Tags sources are stored in a JSON key-value format. Following table shows available keys and values for the tags.

Example of a tag line:

0: {"name":"last_goal_started","predefined":false,"desc":"Last goal started"}

11.19. OCCUPANTS

[occupants]
key value
...

This section describes the occupants present at the beginning of the simulation. The starting node for each occupant is inferred based on the location of the occupant. Occupants' properties are stored in a JSON key-value format. Only properties that differ from the properties of an occupant’s profile are stored in the occupants section. The following table shows only properties that must be always present, since there are no matching profile properties (or for implementation reasons). All Profile properties can also be defined for individual occupants. However, curves are replaced with specific values, and units are omitted. It is assumed that these values are entered in SI units.

If overriding one of "OccProfile.ATTRACTOR_SUSCEPTIBILITY_IDLE" or "OccProfile.ATTRACTOR_SUSCEPTIBILITY_SEEK", the susceptibility is defined the same as in Section 11.14 except that the "curve" keyword is not allowed.

In addition to the previous properties, the following may optionally be specified per-occupant to override the occupant shape as a cylinder:

Example of an occupant line:

0: {"OccProfile.DIAMETER":".5","loc":"-2.017382141545266 -0.32021938754686585 0.0","OccProfile.CURR_DOOR_PREF":"0.55","profile":0,"name":"00001","OccProfile.PRIORITY_LEVEL":"0.34669095427694063","OccProfile.DIST_TRAVELLED_DOUBLE_DIST":"0.002272613706753919","id":0,"behavior":0,"OccProfile.REAC_TIME":"0.1","rseed":7327679609280221184,"OccProfile.MAXVEL":"1.51234"}

11.20. ELEVATORS

Elevators are defined in following sections.

The following section (optional) contains elevator information.

[elevators]
key value
...

Elevators are stored in a JSON key-value format. Following table shows available keys and values for the elevators.

The following section contains further elevator information.

[elevator-discharge]
discharge open-time close-delay size-factor max-density
...

The following section contains information specific to elevator levels.

[elevator-level-data]
elevator-id pickup level-id open-time close-time pickup-time discharge-time delay
...

The following optional section defines linked elevators.

[elevator-links]
<comma separated list of elevator indices>
...

The following optional section defines level priorities of an elevator.

[elevator-priority]
elevator-id, <comma separated list of elevator level indices>
...

11.21. OTHER NOTES

Lines beginning with the comment character ("#") will be ignored.

Lines are considered to be delimited by spaces and commas. Strings containing spaces and commas should be enclosed in double-quotes. The following three VERT definitions are identical to inferno.

1, 1, 0
1.0 1. 0.
1, 1 0