openspoor 0.3.4

Open source project to allow translations between different spoor referential systems

Openspoor

Introduction

The Openspoor package provides an easy way to transform between different geographical and topological systems commonly used in the Dutch railway network. It prepares this data for analysis and visualization. The goal is to make Openspoor publicly available as an open-source package.

Supported Transformations

Input Data:

• Point data

Geographical Systems:

• WGS84 (GPS coordinates)
• EPSG:28992 (Rijksdriehoek)

Topological Systems:

• Geocode and geocode kilometrering
• Spoortak and spoortak kilometrering (unavailable on switches)
• Spoortakken of different historical versions

Installation

Openspoor can be installed using different package management methods. Before proceeding, ensure you have created a virtual environment.

pip install openspoor

Development

To contribute to Openspoor, follow these steps to set up a development environment.

Step 1: Clone repository:

git clone https://github.com/ProRail-DataLab/openspoor.git
cd openspoor

Step 2: Create virtual environment:

uv venv --python=3.11
source .venv/bin/activate # linux/mac
.venv\Scripts\activate # windows

Step 3: Install dependencies

uv sync

Step 4: Run tests to verify setup

uv run pytest --nbmake --nbmake-kernel=python3

Step 5: install pre-commit hooks

Openspoor uses pre-commit hooks to enforce code quality. To install them:

pre-commit install

To run hooks manually on all files:

pre-commit run --all-files

Step 6: generating documentation

Openspoor uses pdoc to generate documentation. To generate and serve documentation locally:

pdoc --http : openspoor

Demonstration Notebook

A demonstration notebook is available in the demo_notebook folder, showcasing Openspoor's functionality.

Dependencies

Openspoor relies on data and APIs from mapservices.prorail.nl. Be aware of possible issues such as:

• Changes in API endpoints
• Modifications in output data format

Package Structure

1. Mapservices

Provides an interface to ProRail's map services API to retrieve railway topology data.

• PUICMapservices: General railway track and switch data, including Geocode and Spoortak information.
• SpoortakMapservices: Data for Spoortak identification and local kilometrering.

2. Transformers

Convert geographical and topological data.

• TransformerCoordinatesToSpoor: WGS84/EPSG:28992 → Spoortak, Geocode
• TransformerGeocodeToCoordinates: Geocode → WGS84/EPSG:28992
• TransformerSpoorToCoordinates: Spoortak → WGS84/EPSG:28992

3. Spoortakmodel

Provides historical railway topology to enable transformations on historical data.

4. Visualisations

Allows plotting railway-related data on maps. Supports pandas and geopandas dataframes containing points or linestrings. With the TrackMap class, you can plot the railway network on a interactive map.

Release History

• 0.3.1: Update for improved code quality.
• 0.3.0: Added the railway network feautures (shortest path and visualization).
• 0.1.10: Added support for historical spoortakken.
• 0.1.9: Added spoortakmodel and visualization features.
• 0.1.0: First stable release.
• 0.0.1: Work in progress.

Contributing

We welcome contributions! Follow these steps:

1. Fork the repository.
2. Set up the development environment. See the Development section for details.
3. Create a feature branch:

   git checkout -b feature/your-feature
   

4. Commit changes:

   git commit -am "Add your feature"
   

5. Push changes:

   git push origin feature/your-feature
   

6. Create a pull request and assign at least three reviewers.

Alternatively, contribute by working on open issues listed on the GitHub repository.

---

For further details, visit the Openspoor GitHub repository.