Metadata-Version: 2.4
Name: epica
Version: 0.1.8
Summary: Trajectory alignment and evaluation toolkit
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.8
Requires-Dist: matplotlib>=3.5
Provides-Extra: rerun
Requires-Dist: rerun-sdk>=0.20; extra == "rerun"
Provides-Extra: ros
Requires-Dist: rosbags>=0.11.0; extra == "ros"
Provides-Extra: geo
Requires-Dist: contextily>=1.5; extra == "geo"
Requires-Dist: pyyaml>=6.0; extra == "geo"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: ipython
Requires-Dist: ipython>=8.0; extra == "ipython"
Provides-Extra: analysis
Requires-Dist: jupyter>=1.0; extra == "analysis"
Requires-Dist: pandas>=2.0; extra == "analysis"

# 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

## Architecture

High-level system view:

<p align="center">
  <img src="docs/images/architecture_system_diagram_v2.png" alt="EPA architecture diagram" width="900">
</p>

`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

<p align="center">
  <img src="docs/images/readme_step23_alignment_3d.png" alt="Step 1 to Step 3 trajectory alignment" width="88%">
</p>

<p align="center">
  <img src="docs/images/readme_ape_translation_part_se3_raw.png" alt="APE translation error curve" width="52%">
  <img src="docs/images/rerun.gif" alt="Rerun demo animation" width="46%">
</p>

## Installation

Create and activate a virtual environment first (recommended):

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

Then install:

```bash
pip install epica
```

Optional extras:

```bash
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:

```bash
epa <gt_file> <est_file>
```

Example:

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

Run a multi-case benchmark:

```bash
epa_bench /path/to/cases_root
```

`epa` detects trajectory formats automatically, writes plots by default, caps post-time-alignment solve/evaluation to 100 Hz, and exports compact metrics. Step-1 time alignment still uses the full input trajectory. `epa_bench` discovers cases, runs them in parallel by default, and removes temporary prepared files unless `--keep-prepared` is set.

## 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/`:

```text
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.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:

```bash
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 3-step 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

## Documentation Link

For more commands and detailed usage, see the docs:

- [EPIC-Alignment Docs](https://epic-lab-gwu.github.io/EPIC-Alignment/)

## Maintenance and Contact

This project is still actively maintained.

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

- [EPIC-Alignment Issues](https://github.com/epic-lab-gwu/EPIC-Alignment/issues)

Or contact:

- [josepht@gwu.edu](mailto:josepht@gwu.edu)
