QGIS MATSim Reader

A QGIS Processing plugin for importing standard MATSim XML files as spatial layers and related tables.

Features

The plugin adds nine algorithms under Processing Toolbox > MATSim:

Importer	Outputs
Network	Nodes and links
Plans	Persons, plans, activities, and legs
Events	Event records, with point geometry when available
Facilities	Facilities and activity options
Vehicles	Vehicle types and vehicles
Transit schedule	Stops, lines, routes, route stops, and departures
Households	Households, members, and household vehicles
Counts	Count stations and hourly volumes
Config	Flattened module parameters

All importers support plain .xml and compressed .xml.gz files. No third-party Python packages are required.

Additional features:

• Network nodes become points and links become lines.
• Plans and transit routes can use network geometry.
• Link-based events, activities, facilities, stops, and counts can be located when a matching network is supplied.
• Unknown event properties and custom MATSim attributes are preserved as JSON.
• Large XML files are parsed incrementally to reduce memory use.

Install for development

Clone the repository and enter its directory:

git clone https://github.com/tpapaz/qgis-matsim-reader.git
Set-Location qgis-matsim-reader

QGIS must see the inner qgis_matsim_reader directory in the active profile's plugin directory:

<QGIS profile>\python\plugins\qgis_matsim_reader

For the default Windows profile, create a directory junction:

$plugins = Join-Path $env:APPDATA 'QGIS\QGIS3\profiles\default\python\plugins'
$source = (Resolve-Path '.\qgis_matsim_reader').Path
New-Item -ItemType Directory -Force -Path $plugins
New-Item -ItemType Junction `
    -Path (Join-Path $plugins 'qgis_matsim_reader') `
    -Target $source

Then restart QGIS and:

1. Open Plugins > Manage and Install Plugins.
2. Enable MATSim Reader under Installed.
3. Open Processing > Toolbox > MATSim.

After changing the code, restart QGIS or reload the plugin with Plugin Reloader.

Usage

1. Open Processing Toolbox > MATSim.
2. Select the required importer.
3. Choose a MATSim .xml or .xml.gz file.
4. Choose the correct scenario CRS for spatial outputs.
5. Keep outputs temporary or save them to files or a GeoPackage.

Supplying the matching network is optional for plans, events, facilities, transit, and counts. It enables link positioning and route geometry.

MATSim files may declare a CRS name that QGIS does not recognize. Assign the CRS that actually describes the scenario coordinates. Assigning EPSG:4326 does not transform MATSim coordinates; it only labels them as longitude/latitude.

MATSim analysis CSV files such as output_trips.csv, output_legs.csv, and output_persons.csv can be opened directly with QGIS's Add Delimited Text Layer tool, using a semicolon delimiter.

Supported scope

Version 0.2.0 supports standard MATSim network, population v6, facilities v2, vehicle definitions v2, transit schedule v2, households v1, counts v1, events, and config v2 structures.

MATSim contribs can define additional XML formats. Those custom formats are outside the current scope unless explicitly added and tested.

Validated with QGIS 3.44.12, all nine Processing algorithms, focused parser tests, and representative MATSim input and output files.

License

QGIS MATSim Reader is licensed under the GNU General Public License, version 2 or any later version (GPL-2.0-or-later).

Future work

• Add importers for commonly requested MATSim contrib formats.
• Improve CRS detection and scenario configuration guidance.
• Add optional QGIS styles and automatic layer grouping.
• Package releases for installation from ZIP and the QGIS Plugin Repository.

Run tests

python -m unittest discover -s tests -v