# v4rl-ucy/decoSLAM: one process per agent, with descriptors computed offline > The official implementation of cross-agent relocalization for decentralized collaborative SLAM, presented at ICRA 2023, where each agent is its own process configured entirely from files and relocalization looks up NetVLAD descriptors that were extracted before the run. Sharing maps is optional, and shared runs need a postprocessing step before the trajectories mean anything. **v4rl-ucy/decoSLAM** — decoSLAM - Repository: https://github.com/v4rl-ucy/decoSLAM - Stars: 100 · Forks: 7 - Language: C++ - License: BSD-3-Clause - Published: 2026-08-17 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/v4rl-ucy-decoslam ## One agent is one process, started from a config file The runtime unit is a single agent, and starting one is a command with a path. ``` ./build/main ``` That is the whole entry point for running your own data. To run the full system you repeat that command once per agent, and the README is explicit that the agents can sit on different machines. So the decentralisation here is literal rather than internal to a single binary: there is no scheduler, no multi-agent mode and no thread pool, just several copies of the same executable that find each other over the network configuration they all share. Starting points for configuration files are already provided under `evaluation/euroc/configs`, so the practical route is to copy one of those rather than author one from nothing. ## Descriptors are extracted before the run, not computed in it Relocalization does not run a neural network during the experiment. The system relies on pre-extracted NetVLAD descriptors, 128 floats each, which are looked up at runtime. Producing them is a separate offline step: the network from the netvlad_tf_open repository is used to generate a CSV file of timestamped descriptors from the rosbag, and an example of the resulting layout sits under `evaluation/euroc/descriptors/MH01/`. The path to that CSV is set in the `descriptor_path` field of the main configuration, and the file is loaded once at startup. The practical consequence is that a new dataset means a new extraction pass before anything can run, and the quality of the relocalization is bounded by what that offline step produced. ## The sensor setup is a second file in another format Sensors are not configured in the main file. A separate configuration follows the format required by HyperSensors, with `evaluation/euroc/configs/euroc_stereo.yaml` given as the example, and its location is set through the `sensor_config_file` field. Only stereo setups are supported, with `cam0` taken as the left camera and `cam1` the right. The `topic` field must name the rostopic your images are published on, and there is a catch for anyone running more than one instance on a single machine: the field is prefixed internally with a namespace of the form `/agent_`, where the id comes from the main configuration. The README states the consequence in bold, since the topics in your rosbag have to be remapped to match. ## Every agent loads the same network file The peer-to-peer layer is described in one sentence that contains the whole requirement: to spin up the network, agents must load the same network configuration file. That file holds one entry per agent, giving its IP address together with a list of ports. Two constraints follow. You need as many ports per agent as there are agents in the system, since each pairing needs its own. And the combination of port and address has to be unique across the whole configuration. An example is provided for five agents at `evaluation/euroc/configs/network_5.yaml`. There is no discovery mechanism and no fallback address, so a wrong entry is a wrong network rather than a degraded one. ## Map sharing runs need their trajectories combined afterwards The evaluation path is the one that explains how the paper's numbers were produced. You download the Machine Hall rosbags from the dataset website, adapt the paths in the roslaunch file `evaluation/euroc/full_euroc.launch` to wherever you saved them, and run the launcher. ``` python evaluation/euroc/launcher_euroc.py ``` That runs the five Machine Hall sequences concurrently at a reduced speed, and the whole experiment is run twice, once with map sharing among the team and once without it. Results land in `evaluation/euroc/configs//result_` and contain trajectory estimates, map data and communication data. The catch is that the trajectories from a map-sharing run are not directly usable: they need a postprocessing pass. ``` ./build/combine_poses ``` That produces a `combined_poses.csv`, which is the file you would then compare against ground truth with a tool such as EVO. ## Seven frameworks from source, plus an ecosystem fetched for you The dependency list is the longest part of the setup. Seven frameworks are expected to be built and installed from source with CMake: OpenCV, Ceres at version 2.0 or higher, OpenGV, yaml-cpp, Eigen3, cppzmq and glog. The README sends you to the installation instructions for the base system, which was tested on Ubuntu 20.04 LTS with the matching ROS distribution, Noetic Ninjemys. The remaining pieces come from the Hyper ecosystem, which supplies sensor classes and Lie Groups, and those are fetched automatically at configuration time rather than installed by hand. Once the dependencies are in place the build itself is ordinary. ``` mkdir build && cd build cmake .. make -j8 ``` ## An ICRA 2023 paper, quiet since May 2023 This is the official implementation of a paper titled Cross-Agent Relocalization for Decentralized Collaborative SLAM, which the README says was to be presented at ICRA 2023, and it is distributed under the BSD-3-Clause license with a contact address given for Philipp Bänninger at ETH Zurich. The repository is not archived, but the last push to main is dated 2023-05-23 and there are no GitHub releases, so there is no version to track and the code is pinned to the era of the paper. The tree itself has a few things the README never mentions: a committed `thirdparty/` directory, a `test/` directory with no description of what it covers or how to run it, and `visualization_config.rviz`, which is an RViz configuration implying the system is inspected in that tool. There is also a clang-format configuration at the root, so the code follows a defined style. ## Conclusion Use this code if you want to reproduce the paper's decentralized experiments or extend cross-agent relocalization, and if you are willing to run one process per agent, possibly across several machines. Three things to plan for. The descriptors are an offline artifact, so a dataset run is a three-stage job of extraction, configuration and launch, not a single command. Every agent must load the identical network file with unique address and port combinations. And the trajectories from a map-sharing run are not final until you run the pose combiner on the result folder. The last push to main is dated 2023-05-23 and no releases are published. ## FAQ ### What is SLAM used for? In this project SLAM is run in a decentralised, collaborative form, and the specific contribution is cross-agent relocalization so that agents can share maps. The evaluation runs the five EuRoC Machine Hall sequences twice, once with map sharing among the team and once without. ### How do I run one DecoSLAM agent? Build the project, then run ./build/main with the path to a configuration file. That spins up a single agent, so the full system means repeating the command per agent, possibly on different machines. Starting configuration files are provided under evaluation/euroc/configs. ### Where do the NetVLAD descriptors come from? They are pre-extracted before the run, 128 floats each, generated as a CSV of timestamped descriptors from the rosbag using the network from netvlad_tf_open. The CSV path goes in the descriptor_path field of the main config and is loaded at startup. ### What does the network configuration file need? Every agent must load the same file, which holds an entry per agent with its IP address and a list of ports. You need as many ports per agent as there are agents, and each combination of port and IP must be unique. A five-agent example is given in evaluation/euroc/configs/network_5.yaml. ### Why do I need combine_poses after a map-sharing run? Because the trajectory files written during a map-sharing run are not directly usable. Running ./build/combine_poses with the result folder produces a combined_poses.csv, which is the file to compare against ground truth with a tool such as EVO. ## Sources - [Official README](https://github.com/v4rl-ucy/decoSLAM#readme) - [Project repository](https://github.com/v4rl-ucy/decoSLAM) - [README](https://github.com/v4rl-ucy/decoSLAM/blob/main/README.md) - [Releases](https://github.com/v4rl-ucy/decoSLAM/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/v4rl-ucy-decoslam