# VSLAM-LAB: one command per baseline, dataset, sequence and sensor mode

> VSLAM-LAB wraps visual SLAM baselines and datasets behind a pixi task interface, so an experiment is a YAML file and a run is one line. The frame-selection flags are the sharpest part of the design, and the lack of releases is the sharpest part of the packaging.

**VSLAM-LAB/VSLAM-LAB** — A Comprehensive Framework for Visual SLAM Systems and Datasets

- Repository: https://github.com/VSLAM-LAB/VSLAM-LAB
- Stars: 558 · Forks: 72
- Language: Python
- License: GPL-3.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/vslam-lab-vslam-lab

## One command takes four positional arguments, including the sensor mode

The headline feature is that any baseline can run on any sequence of any dataset through a single command, and the argument order is fixed: baseline, dataset, sequence, mode.

```bash
pixi run demo mast3rslam eth table_3 mono
pixi run demo droidslam rgbdtum rgbd_dataset_freiburg1_xyz rgbd
pixi run demo orbslam2 kitti 04 stereo
pixi run demo pycuvslam euroc MH_01_easy stereo-vi
```

Reading the four examples tells you what the vocabulary is. Baseline names include mast3rslam, droidslam, orbslam2 and pycuvslam; datasets include eth, rgbdtum, kitti and euroc; sequences are the dataset's own identifiers such as table_3, 04 or MH_01_easy. The fourth argument is the one that catches people out, because it is the sensor configuration rather than a flag: mono, rgbd, stereo, and stereo-vi for visual-inertial. Nothing in the synopsis marks it optional, so a mistyped mode is a failed run rather than a default.

The mode is also the compatibility check. A baseline built for monocular input and one built for stereo-inertial are different executables under the same directory, so the demo command is where an unsupported combination surfaces first, before any configuration file is read.

## Frame selection stacks in a fixed order, and VPR runs a command of its own

Experiments are YAML files, and the `Parameters` mapping carries four optional flags that control which RGB frames reach the baseline. They are independent and stack in a defined order. `rgb_idx` slices the frame range first, `rgb_step` then keeps one frame every n of whatever remains, `rgb_max` truncates that result to at most n frames, and `rgb_vpr` finishes by downsampling to at most n frames chosen by visual dissimilarity rather than a fixed stride. Set none of them and every frame of the sequence is used.

```yaml
exp_vslamlab:
  Config: config_vslamlab.yaml
  NumRuns: 1
  Parameters: {verbose: 1, rgb_idx: [0, 250], rgb_step: 3, rgb_max: 50, rgb_vpr: 30}
  Module: droidslam
```

The order is the part worth writing down, because `rgb_max` truncating before `rgb_vpr` re-selects means the visual pass only ever sees the frames the cheaper passes left behind. `rgb_vpr` also has a hidden dependency: it computes the sequence's VPR distance matrix with `pixi run vpr <dataset> <sequence>` first, unless that matrix is already cached. So a parameter that looks like a number in a YAML file can trigger a separate computation before the experiment starts.

The visible-similarity pass is the interesting choice for benchmark work, since visually redundant frames are dropped preferentially instead of on a fixed stride, which changes what a sequence length means across runs with different parameters.

## Two YAML files split the what from the where

An experiment entry names a Config file, and the two are different kinds of object. The experiment file holds one entry per run, each with `Config` pointing at a sequence list, `NumRuns` as the maximum number of executions per sequence, `Parameters` passed into the baseline executable, and `Module` naming the baseline. The `Module` comment lists the accepted values as droidslam, monogs, orbslam2, mast3rslam, dpvo and others.

The config file is the shorter one: dataset names as keys, sequence names as list items, nothing else.

The reason for the split is repeatability. The sequence list is shared between experiments, so two experiment files can run the same data with different parameters or different baselines and stay comparable, which is what the claim about standardized evaluation rests on. The entry name itself is free-form, and the examples use `exp_demo_droidslam`, `exp_demo_orbslam2` and `exp_demo_colmap`, so the naming convention is a convention rather than a schema.

Running one is `pixi run vslamlab configs/exp_vslamlab.yaml`, with an optional `--overwrite`. What that flag does is not spelled out in the visible documentation, so treat it as destructive until you have read the command reference for it.

## Data paths are rewritten by two commands, not by environment variables

Benchmark data and evaluation output do not live inside the checkout. Two commands move them:

```bash
pixi run set-benchmark-path /media/${USER}/data
pixi run set-evaluation-path /media/${USER}/data
```

The example path, `/media/${USER}/data`, is a literal hint at the intended scale, since that layout is what you build when datasets outgrow a home directory. The two paths are separate because the benchmark data (sequences to be run) and the evaluation data (results to be written) grow on different schedules, and the wording allows for setting one, the other, or both.

The tree explains where those values end up: `path_constants.py` sits at the repository root beside `utilities.py` and `vslamlab_utilities.py`, which is the shape a generated path file takes when a tool rewrites a constant in place. That also means the paths are checked-in configuration rather than per-shell environment, so a second clone on the same machine inherits whatever the first clone was pointed at unless someone runs the setter again.

## pixi owns the environment, and the installer is a curl pipe

Every command in the project is a pixi task, so the environment manager is a hard dependency rather than a convenience. Installing it is a pipe to a shell script:

```bash
curl -fsSL https://pixi.sh/install.sh | bash
```

The README then says to restart the terminal or source the shell for the changes to take effect, and reminds existing users to run `pixi self-update`. The clone step is one line, `git clone https://github.com/VSLAM-LAB/VSLAM-LAB.git && cd VSLAM-LAB`, after which the tasks resolve through the `pixi.toml` manifest and `pixi.lock` at the top of the repository. That is what backs the reproducibility claim: the environment is locked, not described.

The trade is that you inherit the whole toolchain, including the lock file's platform coverage, in exchange for not managing a conda or venv setup yourself. For a benchmark framework whose baselines each have their own C++ and CUDA dependencies, that is a reasonable exchange; for a quick single run it is more machinery than the alternative, and there is no pip or conda path documented as a fallback.

## The pipeline also exposes the individual stages as separate commands

The one-line demo is the front door, but the stages behind it are addressable on their own, which is what makes the framework usable for work that is not a full experiment:

```bash
pixi run install-baseline <baseline>                     # Example: pixi run install-baseline droidslam
pixi run download-sequence <dataset> <sequence>          # Example: pixi run download-sequence eth table_3
pixi run run-exp <exp_yaml>                              # Example: pixi run run-exp configs/exp_vslamlab.yaml
pixi run evaluate-exp <exp_yaml>                         # Example: pixi run evaluate-exp configs/exp_vslamlab.yaml
```

Installing a baseline, downloading one sequence, running an experiment, evaluating it and comparing experiments are five separate tasks rather than one opaque pipeline, and each takes the identifiers you already have. `compare-exp` taking an experiment file rather than two result directories is the detail that matters for regression work, since comparisons stay attached to the experiment definition.

The full command list lives in the project wiki rather than in the repository, on a page titled with a misspelling of Command-line Interface. The modular surface also extends past what the visible examples show: the tree carries `Baselines/`, `Datasets/`, `Evaluate/`, `Run/`, `Gym/`, `Utilities/` and `Capabilities/` directories, plus `vslamlab_gui.py` and `git-clone.sh` at the root. The documented path through all of it is the command line; the wiki page is where the rest is enumerated.

## No releases, and the header calls itself frameworks and systems in two places

The repository has no GitHub releases, so version pinning is a commit rather than a tag, while the last push to main is 2026-09-29 and the lock file is what actually fixes the environment. The licence is GPL-3.0 in `LICENSE.txt`, with a separate `.github/CONTRIBUTING.md` for contributions, and the work is tied to arXiv 2504.04457 with eight named authors, from Alejandro Fontan and Tobias Fischer through to Javier Civera and Michael Milford.

The naming drifted once already. The repository description calls the project a framework for visual SLAM systems and datasets, while the heading in the README calls it a framework for visual SLAM baselines and datasets. Same project, two words for the thing it wraps, and the command vocabulary follows the second one: `install-baseline`, and a `Module` field listing droidslam, monogs, orbslam2, mast3rslam and dpvo.

That drift is small, but it is the kind of thing that matters when you are grepping a wiki page or writing a script against the directory names. The consistent part is the interface: baseline, dataset, sequence, mode, then a YAML experiment that says how many runs and which frames.

## Conclusion

VSLAM-LAB fits a research group that evaluates many visual SLAM baselines on the same public sequences and wants the environment locked rather than assembled, especially anyone who cares about which frames a run actually consumed. It does not fit a single quick evaluation on one dataset, or a deployment that needs a pinned release, because the repository has none. Before adopting it, install pixi and accept it as the only documented entry point, set the benchmark and evaluation paths deliberately since they are rewritten in place, decide which of the four frame filters you need and in what order you want them applied, and check that your baseline names match the Module values the framework expects.

## FAQ

### How do I run a visual SLAM baseline in VSLAM-LAB?

Through one pixi task taking four positional arguments, for example pixi run demo orbslam2 kitti 04 stereo. The arguments are baseline, dataset, sequence and mode, where the mode names the sensor configuration such as mono, rgbd, stereo or stereo-vi.

### What does VSLAM-LAB need installed before anything runs?

The pixi package manager, installed with curl -fsSL https://pixi.sh/install.sh | bash, after which you clone the repository. Every documented command is a pixi task resolved through pixi.toml and pixi.lock, and no pip or conda path is offered.

### How do I choose which frames an experiment uses in VSLAM-LAB?

Four independent flags in the Parameters mapping stack in a fixed order: rgb_idx slices the range, rgb_step keeps every nth frame, rgb_max truncates the count, and rgb_vpr downsamples by visual dissimilarity. With none set, every frame of the sequence is used.

### Where does VSLAM-LAB store datasets and evaluation results?

Outside the checkout, in paths rewritten by pixi run set-benchmark-path and pixi run set-evaluation-path, with /media/${USER}/data given as the example. The values land in path_constants.py at the repository root rather than in shell environment variables.

### Which visual SLAM baselines can VSLAM-LAB run?

The documented examples cover mast3rslam, droidslam, orbslam2 and pycuvslam, and the Module field in an experiment lists droidslam, monogs, orbslam2, mast3rslam and dpvo among the accepted values. The complete list of systems and datasets is kept in a section of the README and in the project wiki.

## Sources

- [Issues](https://github.com/VSLAM-LAB/VSLAM-LAB/issues)
- [License: GPL-3.0](https://github.com/VSLAM-LAB/VSLAM-LAB/blob/main/LICENSE)
- [README](https://github.com/VSLAM-LAB/VSLAM-LAB/blob/main/README.md)
- [VSLAM-LAB/VSLAM-LAB on GitHub](https://github.com/VSLAM-LAB/VSLAM-LAB)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vslam-lab-vslam-lab