README

PedPy

PedPy is a Python library for quantitative analysis of pedestrian dynamics from trajectory data.

It provides a high-level interface for extracting fundamental measures (density, velocity, flow) and advanced analyses such as Voronoi-based methods, profiles, and pair-distribution functions, which can be combined to derive fundamental diagrams.

Features

• Compute core pedestrian measures: density, velocity, flow
• Advanced analyses: Voronoi-based density, profiles, pair-distribution functions
• Directly load trajectory data from multiple tools: Crowdit, Viswalk, JuPedSim, Vadere, Pathfinder
• Easy-to-use API for loading, processing, and visualizing data
• Built-in plotting for quick inspection and comparison of results
• Open-source, tested, and aligned with FAIR and OpenSSF best practices

Getting Started

Installation

PedPy requires Python >= 3.11. It is recommended to use a virtual environment.

Install the latest stable release from PyPI:

python3 -m pip install pedpy

To install the latest development version from the repository:

python3 -m pip install --force-reinstall git+https://github.com/PedestrianDynamics/PedPy.git

[!IMPORTANT] The latest repository version may be unstable. Use with caution.

Quickstart

from pedpy import *

# Load trajectory data from file
traj = load_trajectory(trajectory_file=pathlib.Path("some_trajectory_data.txt"))

# Create measurement area
measurement_area = MeasurementArea([(-0.4, 0.5), (0.4, 0.5), (0.4, 1.3), (-0.4, 1.3)])

# Compute classic density in the measurement area
classic_density = compute_classic_density(traj_data=traj, measurement_area=measurement_area)

plot_density(density=classic_density, title="Classic density")

See the Getting Started Guide for a step-by-step introduction. A more extensive documentation and demonstration of PedPy's capabilities can be found in the User Guide.

Usage

PedPy is designed to be used in scripts or interactive Jupyter notebooks.

• Explore getting started, user guide, and fundamental diagram notebooks.

• For local usage, clone the repository and install the extra requirements for notebooks and plotting:

  bashCopy

  git clone https://github.com/PedestrianDynamics/pedpy.git
  python3 -m pip install jupyter matplotlib

  Then start a Jupyter server:

  bashCopy

  jupyter notebook

Example Visualizations

Documentation

• Full Documentation
• Getting Started Guide
• Extensive User Guide
• API Reference

Citation

If you use PedPy in your work, please cite:

For the latest release (v.1.3.2) the BibTeX entry is:

@software{schrodter_2025_15337052,
  author       = {Schrödter, Tobias and
                  The PedPy Development Team},
  title        = {PedPy - Pedestrian Trajectory Analyzer},
  month        = may,
  year         = 2025,
  publisher    = {Zenodo},
  version      = {v1.3.2},
  doi          = {10.5281/zenodo.15337052},
  url          = {https://doi.org/10.5281/zenodo.15337052},
}

If you used a different version, please use Zenodo to get the citation information.

Contributing

Contributions are welcome and we are looking forward to any contribution from the community! Take a look at our Developer Guide to check out different ways to contribute to PedPy. See the contributing guidelines and open an issue or pull request on GitHub.

Getting Help

If you find yourself in a position where you need assistance from us, don't hesitate to contact us.

• GitHub Issues: Report bugs or unexpected behavior
• GitHub Discussions: Ask questions, share ideas, request features

License

PedPy is released under the MIT License.