Skip to content

README.md

Latest commit

 

History

History
106 lines (79 loc) · 6.41 KB

README.md

File metadata and controls

106 lines (79 loc) · 6.41 KB

MA3DSG: Multi-Agent 3D Scene Graph Generation for Large-Scale Indoor Environments

ICRA 2025 arXiv PDF

Overview

This repository provides the official implementation of a system in which multiple agents collaborate to generate a 3D Scene Graph of large-scale indoor environments. Instead of relying on a single agent to cover a wide area, several agents explore the scene in parallel and combine the objects and relationships they observe into a single, consistent Scene Graph.

Setup

Prerequisites

Please start by following the SGF instructions to configure your CMake environment and install the required libraries. Since this project is built on top of SceneGraphFusion, these dependencies need to be in place before the build will succeed.

BUILD

Once the prerequisites are ready, you can build the system with the commands below. If you don't need the GUI or graph prediction modules, feel free to turn those options off (e.g., -DBUILD_GUI=OFF) to keep the build lighter.

cd MA3DSG
mkdir build
cd build
cmake -DBUILD_GRAPHPRED=ON -DBUILD_GUI=ON ..
make
cd ..

Dataset

Please download the 3RScan dataset by following the 3DSSG instructions. You can find more detailed instructions in 3RScan. After downloading, place the dataset under the parent directory (e.g.,MA3DSG/3RScan/).

Model

The 3D scene graph generation model assigned to each agent was trained following an earlier version of the 3DSSG repository. You may either train a new model using the same setting or use the pre-trained model provided by the original repository.

Run

After a successful build, you can launch the system as shown below. Internally, the executable forks one child process per agent and pins each one to a dedicated CPU core, so the agents truly explore the scene in parallel. The agents share a single Hierarchical Scene Graph (HSG) through POSIX shared memory protected by a process-shared read/write lock, so each agent's observations are merged into one consistent graph as it runs.

Quick start

cd bin
./exe_MA3DSG --num_agents 5 --overlap 0.2 \
             --pth_in   /path/to/3RScan \
             --pth_out  /path/to/output/ \
             --pth_model /path/to/models \
             --traj_path /path/to/trajectories/

The trajectory file is auto-resolved from --traj_path based on the other flags — traj_<num_agents>_<overlap>.json when --test_all true, otherwise traj_ref_<num_agents>_<overlap>.json. The merged HSG is written to either result_all/ or result_onlyref/ under --pth_out.

Main options

Flag Default Description
--num_agents 0 Number of agents to spawn in parallel. Each agent runs as its own process.
--overlap — Overlap ratio between agents' trajectories (used as a string suffix when locating the trajectory file).
--cpu_index 1 Starting CPU index for agent affinity. With cpu_index=65 and 3 agents, agents are pinned to CPUs 65, 66, 67.
--test_all false If true, evaluate on both reference and rescan scenes; otherwise reference only.
--use_gm false Enable the graph merging process when integrating each agent's local graph into the shared HSG.
--th_align — Node-count threshold used for graph alignment during merging.
--load_hsg false If true, load an initial HSG from --hsg into shared memory before agents start (currently a stub — keep false).
--hsg — Path to an existing HSG JSON file (only used when --load_hsg true).
--pth_in — Root directory of the input dataset.
--pth_out — Root directory where the merged HSG and per-agent error logs are written.
--pth_model — Folder containing the pretrained graph-prediction models.
--traj_path — Folder containing the trajectory JSON files.
--verbose false Print verbose logs (also forced on when num_agents=0).

What you'll see

  • A line per agent on startup, e.g. [Agent 3] assigned to CPU 67.
  • Progress logs from each child process; the parent waits for every child via waitpid and reports exit status.
  • Total wall-clock time at the end (TIME: ... milliseconds (... min)).
  • The final merged HSG saved as HSG_<num_agents>_<overlap>[_<th_align>].json under the appropriate result_* folder.
  • If any agent hit per-room failures, a consolidated summary file is written under --pth_out/tmp/.

Acknowledgements

This codebase is built upon SFG and 3DSSG. We sincerely thank the authors for releasing such excellent work.

Citation

If you find our work helpful, we would really appreciate it if you could cite the paper below. You can also read the full paper here.

@InProceedings{Kim2026MA3DSG,
    title     = {MA3DSG: Multi-Agent 3D Scene Graph Generation for Large-Scale Indoor Environments},
    author    = {Yirum Kim and Jaewoo Kim and Uehwan Kim},
    booktitle = {IEEE International Conference on Robotics and Automation (ICRA)},
    month     = {June},
    year      = {2026},
}

License

This project is released under the BSD 2-Clause License, so you are free to use, modify, and distribute it under those terms. Click the badge below for the full license text.

License

Troubleshooting

Here are a few common issues you might run into during build or runtime, along with pointers to their fixes. If you hit something similar, check these first before digging deeper.

Assimp

Depending on your environment, the CMake config for Assimp may be exposed under a different name, which sometimes requires a small integration step to resolve. The following issues describe the problem and the workarounds in detail: