EPICA: Epic Trajectory Alignment and Evaluation Toolkit

EPICA is a trajectory alignment and evaluation toolkit.

It provides:

• trajectory alignment pipeline with public modes se3, posyaw, and sim3
• a set of CLI tools (traj, ape, rpe, res, config)
• OpenVINS compatibility entrypoints
• optional plotting and rerun-based visualization

Architecture

High-level system view:

EPA has three main surfaces:

• the main epa / epica pipeline for one GT/EST pair
• the epa_bench harness for multi-case benchmark runs
• the ov_eval compatibility layer for legacy-style summaries

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

Run one trajectory pair:

epa <gt_file> <est_file>

Example:

epa ./example_data/example_groundtruth.csv ./example_data/example_estimation.txt

Choose an evaluation mode explicitly when needed:

epa ./gt.tum ./estimate.tum --mode se3
epa ./gt.tum ./estimate.tum --mode posyaw
epa ./gt.tum ./estimate.tum --mode sim3

Run a multi-case benchmark:

epa_bench /path/to/cases_root

Input Formats

For one-pair runs, epa <gt_file> <est_file> uses format auto-detection by default.

Supported trajectory inputs:

• csv / euroc: header-based pose CSV with timestamp, position, and quaternion columns
• tum: text rows in t tx ty tz qx qy qz qw
• kitti: text rows with a 3x4 pose matrix
• bag, bag2, mcap: ROS log inputs; pass --gt-topic and --est-topic

For benchmarks, the cases root should contain benchmark/ and GT/:

cases_root/
├── benchmark/<dataset>/pose/<method>/<sequence>/*_poses.txt
├── benchmark/<dataset>/<method>/<sequence>/trajectory.txt
├── benchmark/<dataset>/<method>/<sequence>_poses.txt
└── GT/**/<sequence>.txt

One <method> directory can contain many sequences, either as sequence files or sequence subdirectories.

GT files can use .txt, .tum, or .csv. The pose/ directory is optional.

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

Multi-case benchmark with epa_bench:

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

metrics.json is compact by default. Default EPA metrics include the configured RPE, 1-second time RPE drift, and drift-valid success-rate metrics. Drift-valid segments are detected from local 1-second RPE and positive APE growth/jump checks, with a global accept gate (p05 <= 30 m) to avoid treating globally failed cases as partially valid. Use --save-full-metrics for full per-sample APE/RPE arrays. Use --no-downsample only when you need full-rate solve/evaluation. Benchmark prepared_tum/ files are removed by default; use --keep-prepared when you need them for later case reruns.

Analysis Notebook

For exploratory benchmark analysis, install the analysis extra and open the notebook:

pip install "epica[analysis]"
jupyter notebook notebooks/benchmark_analysis.ipynb

The notebook reads an existing summary.csv, summarizes datasets and methods, ranks suspicious cases, and shows the plots already generated by the benchmark workflow.

Common CLI Toolchain

• epa / epica: run the main EPA pipeline for one GT/EST pair
• epa_bench: run the multi-case benchmark harness over a cases root
• 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_benchall: run the extended multi-case workflow, including summary plots
• epa_all: run the extended single-case workflow
• epa_openvins: run EPA on one or multiple OpenVINS case folders