epica 0.1.6

Trajectory alignment and evaluation toolkit

EPICA: Epic Trajectory Alignment and Evaluation Toolkit

EPICA is a trajectory alignment and evaluation toolkit.

It provides:

• 3-step alignment pipeline (time offset, extrinsic, world alignment)
• a set of CLI tools (traj, ape, rpe, res, config)
• OpenVINS compatibility entrypoints
• optional plotting and rerun-based visualization

Installation

Create and activate a virtual environment first (recommended):

conda create -n epa python=3.10 -y
conda activate epa

Then install:

pip install epica

Optional extras:

pip install "epica[rerun]"  # rerun visualization
pip install "epica[ros]"    # bag / bag2 / mcap support
pip install "epica[geo]"    # map-related tools

Quick Start

For General Workspace:

epa --gt-csv <gt_file> --gt-format <gt_format> --est-path <est_file> --est-format <est_format> --plot

Example:

epa \
  --gt-csv ./example_data/example_groundtruth.csv --gt-format csv \
  --est-path ./example_data/example_estimation.txt --est-format tum \
  --plot

Single-case full workflow:

epa_all --gt <gt_file> --est <est_file> --format tum

Multi-case benchmark:

epa_bench --cases-root /path/to/cases_root

Multi-case full workflow:

epa_benchall --cases-root /path/to/cases_root

OpenVINS examples:

Single case:

epa_openvins /path/to/case_dir se3 --keep-output

Multiple cases:

epa_openvins /path/to/case_a /path/to/case_b --align-mode se3

Run from OpenVINS repo root:

epa_openvins ./ov_eval/example none --keep-output

Each case directory should contain:

• stamped_groundtruth.txt
• stamped_traj_estimate.txt

Outputs

Single epa run:

• creates one outputs/run_YYYYMMDD_HHMMSS/ folder
• typical files inside:
• plots/
• metrics.json
• metrics_summary.csv
• report_en.md
• report_zh.md

Single-case full workflow with epa_all:

• creates one outputs/epa_all/run_YYYYMMDD_HHMMSS/ folder
• typical subfolders inside:
• main_workspace/
• ape/
• rpe/
• traj/
• openvins/ if --case-dir is provided

Multi-case benchmark with epa_bench:

• creates outputs/<cases_root_name>_bench/run_YYYYMMDD_HHMMSS/
• typical files and folders inside:
• summary.csv
• summary.md
• paper_tables/
• cases/
• logs/
• prepared_tum/
• unresolved_cases.csv if some GT mappings cannot be resolved

Common CLI Toolchain

• epa / epica: run the main 3-step EPA pipeline for one GT/EST pair
• epa_all: run the single-case full workflow in one command
• epa_bench: run the multi-case benchmark harness over a cases root
• epa_benchall: run the multi-case full workflow, including summary plots and LaTeX tables
• epa_ape: compute APE for one trajectory pair
• epa_rpe: compute RPE for one trajectory pair
• epa_traj: inspect, align, sync, and visualize trajectories
• epa_openvins: run EPA on one or multiple OpenVINS case folders

Documentation Link

For more commands and detailed usage, see the docs:

• EPIC-Alignment Docs

Maintenance and Contact

This project is still actively maintained.

If you run into any issues, please open an issue at:

• EPIC-Alignment Issues

Or contact:

• [e-mail]