Metadata-Version: 2.4
Name: epica
Version: 0.1.6
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"

# 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):

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

For General Workspace:

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

Example:

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

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

Multi-case benchmark:

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

Multi-case full workflow:

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

OpenVINS examples:

Single case:

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

Multiple cases:

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

Run from OpenVINS repo root:

```bash
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](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)
