{"repo":"MichaelGrupp/evo","free":true,"listed":false,"github":"https://github.com/MichaelGrupp/evo","clone":"git clone https://github.com/MichaelGrupp/evo.git","description":"Python package for the evaluation of odometry and SLAM","language":"Python","stars":4298,"topics":["benchmark","euroc","evaluation","kitti","mapping","metrics","odometry","robotics","ros","ros2","slam","trajectory","trajectory-analysis","trajectory-evaluation","tum"],"license":"GPL-3.0","category":"dev_tool","readme_excerpt":"# evo \n\n***Python package for the evaluation of odometry and SLAM***\n\n| Linux / macOS / Windows / ROS / ROS2 |\n| :---: |\n| [![CI](https://github.com/MichaelGrupp/evo/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/MichaelGrupp/evo/actions/workflows/ci.yml) |\n\nThis package provides executables and a small library for handling, evaluating and comparing the trajectory output of odometry and SLAM algorithms.\n\nSupported trajectory formats:\n\n* 'TUM' trajectory files\n* 'KITTI' pose files\n* 'EuRoC MAV' (.csv groundtruth and TUM trajectory file)\n* ROS and ROS2 bagfile with `geometry_msgs/PoseStamped`, `geometry_msgs/TransformStamped`, `geometry_msgs/PoseWithCovarianceStamped`, `geometry_msgs/PointStamped` or `nav_msgs/Odometry` topics or [TF messages](https://github.com/MichaelGrupp/evo/wiki/Formats#bag---ros-bagfile)\n\nSee [here](https://github.com/MichaelGrupp/evo/wiki/Formats) for more infos about the formats.\n\n\n \"evo\"\n\n\n \"evo\"\n\n\n \"evo\"\n\n\n \"evo\"\n\n\n---\n\n## Why?\n\nevo has several advantages over other public benchmarking tools:\n\n* common tools for different formats\n* algorithmic options for association, alignment, scale adjustment for monocular SLAM etc.\n* flexible options for output, [plotting](https://github.com/MichaelGrupp/evo/wiki/Plotting), [visualization](https://github.com/MichaelGrupp/evo/wiki/Rerun-integration) or export (e.g. LaTeX plots or Excel tables)\n* a powerful, configurable CLI that can cover many use cases\n* modular `core` and `tools` libraries for custom extensions\n* faster than other established Python-based tools ([see here](https://github.com/MichaelGrupp/evo/blob/master/doc/performance.md))\n\n**What it's not:** a 1-to-1 re-implementation of a particular evaluation protocol tailored to a specific dataset. \n\n---\n\n## Installation / Upgrade\n\nInstallation is easy-peasy if you're familiar with this: https://xkcd.com/1987/#\n\nThe latest version of evo supports **Python 3.10+**.\n\nPlease use `pip` only in a proper environment (e.g. `uv`/`uvx`, `pipx`, `venv`, Pixi or a classic [virtual environment](https://github.com/MichaelGrupp/evo/blob/master/doc/install_in_virtualenv.md)).\n> ⚠️ ☠️☠️☠️ ⚠️\n>\n> Whatever you do, don't use: `pip install --user` / anything with `--break-system-packages` / or worst: `sudo pip install`\n\n### From PyPi\nIf you just want to use the executables of the latest release version, the easiest way is to run:\n```bash\npip install evo\n```\nThis will download the package and its dependencies from [PyPI](https://pypi.org/project/evo/) and install or upgrade them. If you want, you can subscribe to new releases via https://libraries.io/pypi/evo.\n\nTo upgrade to a newer version: `pip install --upgrade evo`\n\n### From Source\nRun this in the repository's base folder:\n```bash\npip install --editable .\n```\n\n### Pixi\n\n[Pixi](https://prefix.dev) is an easy-to-use alternative if you want to have an isolated development environment. Run `pixi add evo` if you have an existing environment, or clone this repository and run `pixi shell` to open a dev shell.\n\n### Tab completion\n\nTab completion is supported via the [argcomplete](https://github.com/kislyuk/argcomplete/) package. Run `activate-global-python-argcomplete` after the installation to use it.\n\n### Dependencies\n\n**Python packages**\n\nevo has some required dependencies that are ***automatically resolved*** during installation with pip.\nSee the `pyproject.toml` file for all details.\n\n**PyQt6 (optional)**\n\n[PyQt6](https://pypi.org/project/PyQt6/) will give you the enhanced GUI for plot figures from the \"*qtagg*\" matplotlib backend (otherwise: \"*TkAgg*\"). If PyQt6 is already installed when installing this package, it will be used as a default (see `evo_config show`). To change the plot backend afterwards, run `evo_config set plot_backend qtagg`.\n\nIf you run into issues with installing tkinter, trying PyQt6 is a good idea. \n\n**ROS (optional)**\n\nSome ROS-related features require a ROS installation, see [here](http://www.ros.org/). We are testing this package with ROS Lyrical.\n\n> Reading ROS bag files works also without a ROS installation thanks to the great [rosbags](https://pypi.org/project/rosbags/) package that is installed together with evo. This allows you also to read ROS 1 & 2 bags even if you don't have one of those ROS distros installed. (except for reading `/tf` topics, because there we need the buffer implementation from ROS)\n\n**contextily (optional)**\n\n[contextily](https://contextily.readthedocs.io/en/latest/index.html) is required for [adding map tiles](https://github.com/MichaelGrupp/evo/wiki/Plotting#geographic-map-tiles) to plots of geo-referenced data.\n\n**Rerun (optional)**\n\nYou can send data also to the [rerun](https://rerun.io/) viewer. Just `pip install rerun-sdk` and add `--rerun` to your command. See the related [Wiki page](https://github.com/MichaelGrupp/evo/wiki/Rerun-integration) for more details.\n\n\n \"evo\"\n\n\n \"evo\"\n\n\n---\n\n## Command Line Interface\n\nAfter installation with pip, the following executables can be called globally from your command-line:\n\n**Metrics:**\n\n* `evo_ape` - absolute pose error\n* `evo_rpe` - relative pose error\n\n**Tools:**\n\n* `evo_traj` - tool for analyzing, plotting or exporting one or more trajectories\n* `evo_res` - tool for comparing one or multiple result files from `evo_ape` or `evo_rpe`\n* `evo_config` - tool for global settings and config file manipulation\n\nCall the commands with `--help` to see the options, e.g. `evo_ape --help`. Tab-completion of command line parameters is available on UNIX-like systems.\n\n**More documentation**\nCheck out the [Wiki on GitHub](https://github.com/MichaelGrupp/evo/wiki).\n\n---\n\n## Example Workflow\n\nThere are some example trajectories in the source folder in `test/data`.\n\n\n### 1.) Plot multiple trajectories\n\n Here, we plot two KITTI pose files and the ground truth using `evo_traj`:\n ```\n cd test/data\n evo_traj kitti KITTI_00_ORB.txt KITTI_00_SPTAM.txt --ref=KITTI_00_gt.txt -p --plot_mode=xz\n ```\n\n \n \"evo\"\n \n \n \"evo\"\n \n\n### 2.) Run a metric on trajectories\n\n For example, here we calculate the absolute pose error for two trajectories from ORB-SLAM and S-PTAM using `evo_ape` (`KITTI_00_gt.txt` is the reference (ground truth)) and plot and save the individual results to .zip files for `evo_res`:\n\n *First trajectory (ORB Stereo):*\n\n ```\n mkdir results\n evo_ape kitti KITTI_00_gt.txt KITTI_00_ORB.txt -va --plot --plot_mode xz --save_results results/ORB.zip\n ```\n\n \n \"evo\"\n \n \n \"evo\"\n \n\n *Second trajectory (S-PTAM):*\n \n ```\n evo_ape kitti KITTI_00_gt.txt KITTI_00_SPTAM.txt -va --plot --plot_mode xz --save_results results/SPTAM.zip\n ```\n\n \n \"evo\"\n \n \n \"evo\"\n \n\n\n### 3.) Process multiple results from a metric\n\n `evo_res` can be used to compare multiple result files from the metrics, i.e.:\n * print infos and statistics (default)\n * plot the results\n * save the statistics in a table\n\n Here, we use the results from above to generate a plot and a table:\n ```\n evo_res results/*.zip -p --save_table results/table.csv\n ```\n\n