Getting started

Getting started#

Welcome to the getting started guide of PedPy, we want to guide you through the first steps to set up an analysis of a pedestrian experiment. In this guide, you will learn how to load the movement data, set up measurement areas, and finally compute the flow and the densities.

First things first, to use PedPy install it via:

pip install pedpy

Now, you are ready to set up your first analysis with PedPy.

If you want to follow this Jupyter Notebook on your own machine, you can download it here.

If you use PedPy in your work, please cite it using the following information from zenodo: DOI

Let’s analyze an experiment#

This is a bottleneck experiment conducted at the University of Wuppertal in 2018. You can see the basic setup of the experiment in the picture below:

_images/040_c_56_h-.png

The data for this experiment is available here, which belongs to this experimental series and is part of the publication “Crowds in front of bottlenecks at entrances from the perspective of physics and social psychology”. For our analysis, we are interested in the flow at the bottleneck and density a short distance in front of the bottleneck.

Importing pedestrian movement data#

The pedestrian movement data in PedPy is called trajectory data.

PedPy works with trajectory data which can be created from an import function for specific data files alternatively from a DataFrame with the following columns:

  • “id”: a unique numeric identifier for each person

  • “frame”: index of video frame where the positions were extracted

  • “x”, “y”: position of the person (in m)

PedPy provides an import function to load trajectory data provided here. Since the data we want to analyze is from there, we can directly load the trajectory data with PedPy:

import pathlib

from pedpy import load_trajectory

traj = load_trajectory(trajectory_file=pathlib.Path("demo-data/bottleneck/040_c_56_h-.txt"))
traj

TrajectoryData:
        frame rate: 25.0
        frames: [(np.int64(0), np.int64(1656))]
        number pedestrians: 75
        bounding box: (-2.6042, -1.8723, 2.2641, 5.98)
        data:
           id  frame       x       y                  point
0   1      0  2.1569  2.6590   POINT (2.1569 2.659)
1   1      1  2.1498  2.6653  POINT (2.1498 2.6653)
2   1      2  2.1532  2.6705  POINT (2.1532 2.6705)
3   1      3  2.1557  2.6496  POINT (2.1557 2.6496)
4   1      4  2.1583  2.6551  POINT (2.1583 2.6551)
5   1      5  2.1643  2.6508  POINT (2.1643 2.6508)
6   1      6  2.1723  2.6477  POINT (2.1723 2.6477)
7   1      7  2.1845  2.6485  POINT (2.1845 2.6485)
8   1      8  2.1988  2.6491  POINT (2.1988 2.6491)
9   1      9  2.2138  2.6540   POINT (2.2138 2.654)

The loaded trajectories look like:

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_trajectories

plot_trajectories(
    traj=traj,
    traj_alpha=0.5,
    traj_width=1,
).set_aspect("equal")
plt.show()
_images/81aedfba9c13db050ccba0c613dbe775f6da3ad720e2ed0062710a957b6c3803.png

Let’s analyze the flow at the bottleneck#

For this analysis, we need to define a line where we want to measure the flow (see MeasurementLine). We place the line at the bottleneck as below:

from pedpy import MeasurementLine

measurement_line = MeasurementLine([(0.25, 0), (-0.25, 0)])

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_measurement_setup

ax = plot_measurement_setup(
    traj=traj,
    traj_alpha=0.5,
    traj_width=1,
    measurement_lines=[measurement_line],
    ml_width=2,
).set_aspect("equal")
plt.show()
_images/cf671e8e4ac1f57d3f93455ff6eafa2ea74138a620b4b23adf191bf10a13d112.png

The flow calculation is done with compute_n_t(), with our trajectory data, the measurement line ,and the frame rate the data was recorded.

from pedpy import compute_n_t

nt, _ = compute_n_t(
    traj_data=traj,
    measurement_line=measurement_line,
)

Hide code cell source

 
from pedpy import plot_nt

plot_nt(nt=nt)
plt.show()
_images/135b6b4f1b0b528d9328d4d78e72e69c3bfdf90830576d5452d50189e03df812.png

Let’s compute the density in front of the bottleneck#

Now we are computing the density in an area in front of the bottleneck. The density is usually not measured directly at the bottleneck, but a short distance in front as here the highest densities occur.

For this we need to define a measurement area, which has to be a convex polygon. Such a measurement area can be created with:

from pedpy import MeasurementArea

measurement_area = MeasurementArea([(-0.4, 0.5), (0.4, 0.5), (0.4, 1.3), (-0.4, 1.3)])

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_measurement_setup

plot_measurement_setup(
    traj=traj,
    traj_alpha=0.5,
    traj_width=1,
    measurement_areas=[measurement_area],
    ma_line_width=2,
).set_aspect("equal")
plt.show()
_images/a71916d0cb525cf1006d5e81c1b0b37642b4b8745514c70fa2227209376fef27.png

The density over time is now computed by compute_classic_density(), which takes the trajectory data and measurement area as inputs:

from pedpy import compute_classic_density

classic_density = compute_classic_density(traj_data=traj, measurement_area=measurement_area)

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_density

plot_density(density=classic_density, title="Classic density over time")
plt.show()
_images/47a1604fe87770f3e4e21e596db87209283342508e29e90d99e52b86f11b40cb.png

Now use the Voronoi method for computing the density#

For this we now need information about the area where pedestrians can move, this is called a walkable area in PedPy and is essentially a 2D polygon. We extract the walkable area from this diagram:

_images/experimental_setup.png

The resulting polygon is described in the code below:

from pedpy import WalkableArea

walkable_area = WalkableArea(
    # complete area
    [
        (3.5, -2),
        (3.5, 8),
        (-3.5, 8),
        (-3.5, -2),
    ],
    obstacles=[
        # left barrier
        [
            (-0.7, -1.1),
            (-0.25, -1.1),
            (-0.25, -0.15),
            (-0.4, 0.0),
            (-2.8, 0.0),
            (-2.8, 6.7),
            (-3.05, 6.7),
            (-3.05, -0.3),
            (-0.7, -0.3),
            (-0.7, -1.0),
        ],
        # right barrier
        [
            (0.25, -1.1),
            (0.7, -1.1),
            (0.7, -0.3),
            (3.05, -0.3),
            (3.05, 6.7),
            (2.8, 6.7),
            (2.8, 0.0),
            (0.4, 0.0),
            (0.25, -0.15),
            (0.25, -1.1),
        ],
    ],
)

The resulting walkable area will look like this, together with the trajectories and the measurement area:

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_measurement_setup

plot_measurement_setup(
    walkable_area=walkable_area,
    traj=traj,
    traj_alpha=0.5,
    traj_width=1,
    measurement_areas=[measurement_area],
    ma_line_width=2,
    ma_alpha=0.5,
).set_aspect("equal")
plt.show()
_images/c00aff25c2b6653d1ebcc6c9d8c496a77319cf6ed09c572b31136c1c5445dfd4.png

This time we compute the individual density with compute_individual_voronoi_polygons() using the trajectory data and walkable area as inputs.

from pedpy import compute_individual_voronoi_polygons

individual = compute_individual_voronoi_polygons(traj_data=traj, walkable_area=walkable_area)

The computed Voronoi polygons at one frame look like:

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import DENSITY_COL, plot_voronoi_cells

plot_voronoi_cells(
    voronoi_data=individual,
    traj_data=traj,
    frame=500,
    walkable_area=walkable_area,
    color_by_column=DENSITY_COL,
    vmin=0,
    vmax=10,
).set_aspect("equal")
plt.show()
_images/d2ce6b5b5b892fdc74c944c7e764654dab371279cdb8490807f35926a0abf4c1.png

Using this we can then can compute the mean Voronoi density in the previously defined measurement area with compute_voronoi_density() which takes the individual Voronoi data and the measurement area as inputs:

from pedpy import compute_voronoi_density

density_voronoi, intersecting = compute_voronoi_density(
    individual_voronoi_data=individual, measurement_area=measurement_area
)

Hide code cell source

 
import matplotlib.pyplot as plt

from pedpy import plot_density

plot_density(density=density_voronoi, title="Voronoi density over time")
plt.show()
_images/766b56992d656bf37900d04f79501076e7140b6b00e044645d8f9d45633a934f.png

Now you have set up a first analysis that computed the flow, classic density and, Voronoi density in a bottleneck experiment. With this knowledge, you can now start your own analysis. If you need further information take a look at our User Guide, where you can get more insight into what PedPy can do for you.

We would love to hear some feedback from you!