Trajectopy - Trajectory Evaluation in Python

Trajectopy is a Python package with an optional graphical user interface for empirical trajectory evaluation.

Key Features

• Interactive GUI: Load, plot, align and compare trajectories without writing code. Every action explains itself in the context menus, and trajectories can be aligned interactively if an automatic alignment is not possible.
• Alignment: A spatio-temporal least squares alignment that can be tailored to the application: similarity transformation, leverarm and time shift, each of them optional.
• Comparison: Absolute and relative trajectory error (ATE and RPE), computed with various pose-matching methods.
• Data Import/Export: ASCII files with configurable columns, time formats and coordinate systems (any EPSG code), and ROS bags.
• Fast, Interactive Visualization: Powered by pyqtgraph, the same plots are available in the GUI and in Python scripts, stay fluid for large trajectories, and can be exported to PNG, JPG or SVG. Georeferenced trajectories and ATE results can be exported to Google Earth, colored by speed, height or deviations, on the terrain or at their own heights, with playback.

Installation

Windows App

Download Trajectopy-<version>-setup.exe from the latest release and run it. No Python installation or administrator rights are needed. The installer adds Trajectopy to the Start menu and, optionally, opens .traj files with it on double-click. The app reports new versions (Help → Check for Updates); installing a newer version over an existing one updates it.

As the installer is not signed, Windows SmartScreen may warn about an unknown publisher: choose More info → Run anyway.

Python Package

Command	Contents
pip install "trajectopy[gui]"	Python package and GUI (recommended)
pip install "trajectopy[plot]"	Python package with plotting, without the GUI
pip install trajectopy	Python package only

Trajectopy requires Python 3.10 or newer.

Faster loading of large files: trajectory files with millions of poses load several times faster with the optional fast extra, which installs pyarrow for reading. It can be combined with the other extras:

pip install "trajectopy[gui,fast]"

Quick Start

Python

Load two trajectories and compute the absolute and relative trajectory error. The example files are in the example_data folder of the repository.

import trajectopy as tpy

reference = tpy.Trajectory.from_file("./example_data/KITTI_gt.traj")
estimate = tpy.Trajectory.from_file("./example_data/KITTI_ORB.traj")

# ATE: the estimate is aligned to the reference first (similarity transformation)
ate_result = tpy.ate(trajectory=estimate, other=reference)
print(f"Position ATE: {ate_result.pos_ate:.3f} m")

# RPE: drift per 100 m to 800 m (see the relative comparison settings)
rpe_result = tpy.rpe(trajectory=estimate, other=reference)
print(f"Position RPE: {rpe_result.pos_rpe:.3f} {rpe_result.pos_drift_unit}")

The User Guide covers alignment, evaluation, plots and the GUI in detail.

GUI

Start the Windows app from the Start menu, or run:

trajectopy

Drop trajectory files onto the trajectory table, right-click the ground truth and choose Set as Reference, then right-click another trajectory and choose Compare with Reference. See Using the GUI.

Command Line

trajectopy [-h] [--version] [--single-thread] [--plot-settings PLOT_SETTINGS] [files ...]

Argument	Description
files	Project (.tpy), trajectory (.traj, .bag) or result (.result) files to open at start. Trajectories and results are added to the project.
--version, -v	Show the version and exit.
--single-thread	Process in the GUI thread instead of a background thread, e.g. for debugging. The GUI does not respond while processing.
--plot-settings PLOT_SETTINGS	JSON file with plot settings; settings missing in the file keep their default values.
-h, --help	Show the help and exit.

Examples:

trajectopy ground_truth.traj slam.traj
trajectopy flight.tpy
trajectopy --plot-settings plot_settings.json

A project contains its own plot settings, which replace those given with --plot-settings when it is opened.

The Windows app has no console window, so --version and --help print nothing there; the version is shown in Help → About. Messages of the running GUI are shown in its log (View → Log).

Citation

If you use Trajectopy for academic work, please cite our paper:

@article{Tombrink2024,
  title = {Spatio-temporal trajectory alignment for trajectory evaluation},
  author = {Gereon Tombrink and Ansgar Dreier and Lasse Klingbeil and Heiner Kuhlmann},
  journal = {Journal of Applied Geodesy},
  year = {2024},
  doi = {10.1515/jag-2024-0040},
  url = {https://doi.org/10.1515/jag-2024-0040},
  codeurl = {https://github.com/gereon-t/trajectopy}
}

License

Trajectopy is released under the GNU General Public License v3.0.

Contributing

Contributions are welcome! Please see our GitHub repository for details.

---

Developed at the Institute of Geodesy and Geoinformation, University of Bonn