This specification of the geometry is used in all JuPedSim modules. A geometry in JuPedSim is structured in rooms and subrooms. Rooms are connected by transitions and subrooms are connected by crossings.

Structure of the geometry

The main structure of the geometry file is as follows

The main components defining a geometry

                <!-- walls of the subroom -->
                    <!-- obstecals inside the subroom -->
                <!-- doors between two subrooms -->
        <!-- doors between two rooms or a room and the outside -->

Geometry example

Geometry example

Geometry example 2

There are two ways to structure geometries for JuPedSim:

  • Rooms
  • Subrooms

Following picture shows a sample geometry with one room, two subrooms and one obstacle.

A corner defined by one room and two subrooms

subrooms and rooms are two different concepts to organize a geometry. Basically, it is up to the user to organize its geometry “roomwise” or “subroomwise”.

For instance the above mentioned geometry could also be organized using two rooms as follows:

A corner defined by two different rooms

A geometry can be produces manually (for small scenarios) or with jpseditor. In both cases it is recommended to visualize the geometry once finished with jpsvis.

The main components of a geometry are:


The geometry contains at least one room and one transition. Each room has a unique id, an optional caption and at least one subroom. Two rooms are separated by either walls or transitions.

     <room id="0" caption="hall" >


Subrooms define the navigation mesh, i.e the walkable areas in the geometry. Each subroom is bounded by at least one crossing. Here a sample:

 <subroom id="1" class="escalator" speed="0.7" A_x="−1.2" B_y="0" C="0">
     <polygon caption="wall">
         <vertex px="0.0" py="1.0"/>
         <vertex px="−5.0" py="1.0"/>
     <polygon caption="wall">
         <vertex px="0.0" py="3.0"/>
         <vertex px="−5.0" py="3.0"/>
     <up px="−5.0" py="2"/>
     <down px="0.0" py="2"/>
  • id mandatory parameter, also referred by crossings and transitions.
  • class optional parameter defining the type of the subroom. At the moment three classes are defined:
    • floor
    • stair take additionally <up px="-5.0" py="2" /> and <down px="0.0" py="2"/>, which are used for visualisation purposes.
    • escalator_up and escalator_down require <up px="-5.0" py="2" /> and <down px="0.0" py="2"/> to initialise their directions. Used by the router. Additionally, escalators have a speed.
    • platform needs additionally walls of type track-n, see also here.
  • \(A\_x,\; B\_y,\text{and}\; C\) are optional parameter for the explicit plane equation of the subroom, for the construction of a 3D environment and should be used to describe stairs. The plane equation is given by: \(Z = Ax +By + C\). For instance, if the stair goes through the following points: \(P_1(1,0,0),\; P_2 (0,1,0)\; \text{and}\; P_3(0,0,1)\) then the equation is given by: \(Z= -x -y +1\).

  • polygon describes the walls as a sequence of two vertexes.

To ease navigation, it is recommended to always use convex subrooms. In the case the subroom is not convex, additional navigation lines might be required or the floor field router should be used.


One or more obstacles can also be defined within a subroom.

Sample obstacle in a subroom

 <obstacle id="0" caption="table" height="1.0" >
        <vertex px="12" py="10"/>
        <vertex px="11" py="10"/>
        <vertex px="11" py="10"/>
        <vertex px="11" py="9"/>
        <vertex px="11" py="9"/>
        <vertex px="12" py="9"/>
        <vertex px="12" py="9"/>
        <vertex px="12" py="10"/>
  • id, mandatory unique identifier for this obstacle.
  • caption, used in the visualisation.
  • height, optional parameter, not used at the moment
  • polygon, describing the obstacle as a sequence of vertex.


A crossing defines the connection between two subrooms inside the same room. Unlike transition, they are always open.

A sample crossing between two subrooms

 <!-- virtual exits between subrooms -->
 <crossing id="0" subroom1_id="0" subroom2_id="1">
    <vertex px="10.0" py="6.0"/>
    <vertex px="10.0" py="4.0"/>
  • id, mandatory unique identifier for this crossing.
  • subroom1_id, the first subroom
  • subroom2_id, the second subroom sharing this transition. The order is not important.
  • vertex: define two ending points of the crossing.


A transition defines the connection between two rooms and is basically a door. It can be close or open (see “traffic constraints”).

An example transition between two rooms

 <!-- exits between rooms or to outside (room with index = -1) -->
 <transition id="1" caption="main exit" type="emergency"
 room1_id="0" subroom1_id="1" room2_id="-1" subroom2_id="-1">
     <vertex px="15.0" py="-5.0"/>
     <vertex px="17.0" py="-5.0"/>
  • id, mandatory unique identifier. The id is also used to close or open the door in the “traffic constraints” section of the inifile.
  • caption, optional, used in the visualisation.
  • type, optional.
  • room1_id, the first room sharing this transition. The order is not important.
  • subroom1_id, the first subroom sharing this transition located in room_1.
  • room2_id, the second room sharing this transition. The order is not important. If there is no second room (meaning this transition is connected to the outside), then use -1.
  • subroom2_id, the second subroom sharing this transition located in room_2. The order is not important. If there is no second subroom (meaning this transition is connected to the outside), then use -1.
  • vertex: define two ending points of the transition.
  • file: file containing further transitions. See transitions.xml
Tags: jpscore file