The Problem

Robotic perception pipelines need to fuse heterogeneous sensor streams (RGB‑D, LiDAR, IMU) into a coherent, queryable 3‑D scene graph while running on‑board. Existing solutions either batch‑process offline or lack a unified API for semantic, geometric, and topological information, making downstream planning and mapping difficult to integrate.

What This Does

Hydra incrementally builds a hierarchical scene graph from raw sensor data and updates it in real time. Core C++ modules in include/hydra/ define the graph data structures (dsg_types.h, graph_update.h) and the processing pipeline (backend/, frontend/, loop_closure/). Python bindings (python/src/hydra_python/) expose the same functionality to scripts and the Habitat simulator. Evaluation tools under eval/ compute metrics on place and room reconstruction, while the config/ folder supplies ready‑made sensor‑dataset configurations (e.g., datasets/kitti_360.yaml).

How It Is Wired

Execution starts at the Python entry point python/src/hydra_python/__main__.py, which parses CLI arguments and constructs a HydraPipeline object (defined in python/src/hydra_python/pipeline). The pipeline loads configuration files (config/*.yaml) via hydra/common/config_utilities.h and instantiates the C++ backend through the pybind11 wrapper generated in python/src/hydra_python/__init__.py.

The main processing loop lives in include/hydra/backend/backend_module.h → src/backend/backend_module.cpp. Incoming sensor packets (input/data_receiver.h) are routed to the appropriate frontend extractor (frontend/graph_builder.h, frontend/gvd_place_extractor.h). Extracted geometric primitives are merged into the global DSG (backend/dsg_updater.h). Loop‑closure proposals are generated by loop_closure/loop_closure_module.h and validated using the GNN interface (gnn/gnn_interface.h).

When the pipeline terminates, hydra/common/hydra_pipeline.h triggers a final graph export that can be consumed by the evaluation suite (eval/python/hydra_eval/__main__.py). The evaluation tools read the exported graph, compute place/room metrics (eval/include/hydra/eval/place_metrics.h), and print results. No circular dependencies were detected in the static import graph; the most connected Python module is python/src/hydra_python/__init__ (imports 4 internal modules).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Hydra
cd Hydra

# Build C++ core (requires CMake, a C++14 compiler, and ONNX runtime)
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Install Python bindings (uses the pyproject.toml in the repo root)
pip install -e .

Configuration files live under config/. A typical run on the KITTI‑360 dataset:

python -m hydra_python \
    --config config/datasets/kitti_360.yaml \
    --output_dir /tmp/hydra_output

For offline evaluation:

python -m hydra_eval \
    --graph /tmp/hydra_output/graph.pb \
    --metrics_dir /tmp/hydra_metrics

All commands are documented in the repository README and the eval/README.md.

Real‑World Use

A mobile robot equipped with a LiDAR and RGB‑D camera can launch the above Python command at startup. As sensor frames arrive, Hydra updates the DSG, providing immediate queries such as graph.get_nearest_room(pose) or graph.get_semantic_label(node_id). Planning modules can then request a path that respects room categories or avoids dynamic obstacles, all without a separate mapping service.

Code Health & Issues

  • High – No lockfile for eval/pyproject.toml. Unpinned dependencies risk non‑reproducible builds.
  • Medium – GitHub Actions workflow (.github/workflows/ci.yaml) lacks explicit permissions for GITHUB_TOKEN.
  • Medium – No automated dependency updater (Dependabot/Renovate).
  • Medium – CI does not run a dependency‑vulnerability scan.
  • Medium – Large binary (doc/media/hydra.GIF, 15.9 MB) stored directly in the repo; should be moved to Git LFS.
  • Low – Workflow jobs have no timeout-minutes setting, risking runaway CI runs.

All findings come from the deterministic static analysis pipeline; no additional issues were inferred.

The Bottom Line

Hydra delivers a well‑structured, real‑time 3‑D scene‑graph system with both C++ performance and Python accessibility. The codebase is sizable but modular, and the entry points are clearly defined. Health concerns are limited to CI hygiene and reproducibility (missing lockfile, CI permissions, large assets). Teams needing an extensible perception stack for robotics or simulation can adopt Hydra, provided they address the modest CI and dependency‑management gaps.