# mit-spark/hydra-ros architecture

> Architecture diagram of the GitHub repository mit-spark/hydra-ros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mit-spark/hydra-ros
- Repository: https://github.com/mit-spark/hydra-ros

## Overview

##### Project Type and Purpose
- This is a full‐stack robotics perception application built on ROS Noetic.
- Its goal: wrap the MIT‐SPARK Hydra real‐time 3D scene‐graph construction/optimization library into ROS nodes (hydra_ros), define custom ROS messages/services (hydra_msgs), and provide a standalone visualizer (hydra_visualizer).

##### File Structure to Find Major Components
- Top‐level packages:
- hydra_msgs: custom ROS messages (msg/) and services (srv/).
- hydra_ros: the ROS interface to Hydra – C++/Python nodes, organized into modules (input, frontend, backend, loop_closing, odometry, openset, utils), launch files, configs, and tests.
- hydra_visualizer: standalone ROS-based visualizer with plugins, graph I/O wrappers, and RViz configs.
- Support directories:
- dev/: linting and formatting scripts.
- doc/: user guides.
- .github/: contribution templates.

##### Out the Main Components
a. ROS Master (central broker)
b. hydra_msgs package
– Topics: ActiveLayer, DsgUpdate
– Services: GetDsg, QueryFreespace
c. hydra_ros nodes (group them):
- Input Modules
– ros_sensors, bag_reader, pointcloud_receiver, image_receiver – subscribe to raw sensor data / bags.
- Hydra Pipeline Orchestrator
– hydra_ros_pipeline node (coordinates frontend → backend).
- Frontend Modules
– GVD occupancy publisher, object_visualizer, places_visualizer – process raw data into intermediate representations.
- Backend Modules
– ros_backend_publisher – performs optimization, publishes final scene graph.
- Loop Closure & Odometry
– ros_lcd_registration, ros_pose_graph_tracker – detect loops, maintain pose graph.
- Openset Module
– ros_embedding_group – handles embeddings for open‐set recognition.
- Utilities
– TF lookups, lazy publisher, scene_graph_logger – shared helpers.
d. hydra_visualizer nodes:
- hydra_visualizer_node – subscribes to DsgUpdate and raw graph I/O via ROS or ZMQ.
- Config manager & I/O wrappers – graph_ros_wrapper, graph_file_wrapper, graph_zmq_wrapper.
e. External Services / Tools
– RViz (via .rviz files), bag playback, dataset launch files.

##### Relationships and Data Flow
- Sensor data → Input Modules (subscribe on /camera/…, /velodyne/…)
- Input Modules → Frontend (publish intermediate topics or feed directly into pipeline node)
- Frontend → Backend (intermediate GVD/places → final scene graph)
- Backend → hydra_msgs topics (DsgUpdate published)
- hydra_visualizer_node subscribes to DsgUpdate → passes graph to plugins → renders in RViz.
- Services (GetDsg, QueryFreespace) called by external clients to query current graph or freespace.
- Loop closure & odometry modules feed back into the pipeline to refine the graph.

##### Architectural Patterns
- ROS publisher/subscriber pattern for data flow.
- Modular pipeline: clear separation of input → front-end → back-end → visualization.
- Launch files configure and wire up entire graph per dataset.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Master
    ROSMaster["ROS Master"]:::master

    %% hydra_ros package
    subgraph "hydra_ros" 
        subgraph "Input Modules"
            ros_sensors["ros_sensors"]:::input
            bag_reader["bag_reader"]:::input
            pointcloud_receiver["pointcloud_receiver"]:::input
            image_receiver["image_receiver"]:::input
        end

        hydra_ros_pipeline["hydra_ros_pipeline"]:::pipeline

        subgraph "Frontend Modules"
            gvd_occupancy_publisher["gvd_occupancy_publisher"]:::pipeline
            object_visualizer["object_visualizer"]:::pipeline
            places_visualizer["places_visualizer"]:::pipeline
        end

        ros_backend_publisher["ros_backend_publisher"]:::pipeline

        subgraph "LoopClosure & Odometry"
            ros_lcd_registration["ros_lcd_registration"]:::pipeline
            ros_pose_graph_tracker["ros_pose_graph_tracker"]:::pipeline
        end

        ros_embedding_group["ros_embedding_group"]:::pipeline

        subgraph "Utilities"
            scene_graph_logger["scene_graph_logger"]:::pipeline
            dsg_streaming_interface["dsg_streaming_interface"]:::pipeline
            tf_lookup["tf_lookup"]:::pipeline
            lazy_publisher_group["lazy_publisher_group"]:::pipeline
        end
    end

    %% hydra_msgs package
    subgraph "hydra_msgs" 
        ActiveLayer[(ActiveLayer)]:::msgs
        DsgUpdate[(DsgUpdate)]:::msgs
        GetDsg[(GetDsg)]:::msgs
        QueryFreespace[(QueryFreespace)]:::msgs
    end

    %% hydra_visualizer package
    subgraph "hydra_visualizer"
        hydra_visualizer_node["hydra_visualizer_node"]:::viz
        subgraph "Plugins & Renderer"
            mesh_plugin["mesh_plugin"]:::viz
            footprint_plugin["footprint_plugin"]:::viz
            scene_graph_renderer["scene_graph_renderer"]:::viz
        end
        subgraph "I/O Wrappers & Config"
            graph_ros_wrapper["graph_ros_wrapper"]:::viz
            graph_file_wrapper["graph_file_wrapper"]:::viz
            graph_zmq_wrapper["graph_zmq_wrapper"]:::viz
            config_manager["config_manager"]:::viz
        end
    end

    %% Data Flow
    ROSMaster --> ros_sensors
    ROSMaster --> bag_reader
    ROSMaster --> pointcloud_receiver
    ROSMaster --> image_receiver

    ros_sensors --> hydra_ros_pipeline
    bag_reader --> hydra_ros_pipeline
    pointcloud_receiver --> hydra_ros_pipeline
    image_receiver --> hydra_ros_pipeline

    hydra_ros_pipeline --> gvd_occupancy_publisher
    hydra_ros_pipeline --> object_visualizer
    hydra_ros_pipeline --> places_visualizer

    gvd_occupancy_publisher --> ros_backend_publisher
    object_visualizer --> ros_backend_publisher
    places_visualizer --> ros_backend_publisher

    ros_lcd_registration --> hydra_ros_pipeline
    ros_pose_graph_tracker --> hydra_ros_pipeline
    ros_embedding_group --> hydra_ros_pipeline

    ros_backend_publisher --> DsgUpdate
    ros_backend_publisher --> ActiveLayer

    hydra_visualizer_node --> DsgUpdate
    DsgUpdate --> mesh_plugin
    DsgUpdate --> footprint_plugin
    DsgUpdate --> scene_graph_renderer

    hydra_visualizer_node --> graph_ros_wrapper
    hydra_visualizer_node --> graph_file_wrapper
    hydra_visualizer_node --> graph_zmq_wrapper
    graph_ros_wrapper --> scene_graph_renderer
    graph_file_wrapper --> scene_graph_renderer
    graph_zmq_wrapper --> scene_graph_renderer

    ROSMaster --> GetDsg
    ROSMaster --> QueryFreespace
    GetDsg -.->|service call| hydra_ros_pipeline
    QueryFreespace -.->|service call| ros_backend_publisher

    %% Click Events
    click ros_sensors "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/input/ros_sensors.cpp"
    click bag_reader "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/utils/bag_reader.cpp"
    click pointcloud_receiver "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/input/pointcloud_receiver.cpp"
    click image_receiver "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/input/image_receiver.cpp"
    click hydra_ros_pipeline "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/hydra_ros_pipeline.cpp"
    click gvd_occupancy_publisher "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/frontend/gvd_occupancy_publisher.cpp"
    click object_visualizer "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/frontend/object_visualizer.cpp"
    click places_visualizer "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/frontend/places_visualizer.cpp"
    click ros_backend_publisher "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/backend/ros_backend_publisher.cpp"
    click ros_lcd_registration "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/loop_closure/ros_lcd_registration.cpp"
    click ros_pose_graph_tracker "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/odometry/ros_pose_graph_tracker.cpp"
    click ros_embedding_group "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/openset/ros_embedding_group.cpp"
    click scene_graph_logger "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/utils/scene_graph_logger.cpp"
    click dsg_streaming_interface "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/utils/dsg_streaming_interface.cpp"
    click tf_lookup "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/utils/tf_lookup.cpp"
    click lazy_publisher_group "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/src/utils/lazy_publisher_group.cpp"
    click ActiveLayer "https://github.com/mit-spark/hydra-ros/blob/main/hydra_msgs/msg/ActiveLayer.msg"
    click DsgUpdate "https://github.com/mit-spark/hydra-ros/blob/main/hydra_msgs/msg/DsgUpdate.msg"
    click GetDsg "https://github.com/mit-spark/hydra-ros/blob/main/hydra_msgs/srv/GetDsg.srv"
    click QueryFreespace "https://github.com/mit-spark/hydra-ros/blob/main/hydra_msgs/srv/QueryFreespace.srv"
    click hydra_visualizer_node "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/app/hydra_visualizer_node.cpp"
    click mesh_plugin "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/plugins/mesh_plugin.cpp"
    click footprint_plugin "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/plugins/footprint_plugin.cpp"
    click scene_graph_renderer "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/scene_graph_renderer.cpp"
    click graph_ros_wrapper "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/io/graph_ros_wrapper.cpp"
    click graph_file_wrapper "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/io/graph_file_wrapper.cpp"
    click graph_zmq_wrapper "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/io/graph_zmq_wrapper.cpp"
    click config_manager "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/src/utils/config_manager.cpp"
    click hydra_launch "https://github.com/mit-spark/hydra-ros/blob/main/hydra_ros/launch/hydra.launch"
    click hviz_launch "https://github.com/mit-spark/hydra-ros/blob/main/hydra_visualizer/launch/hydra_visualizer.launch"

    %% Styles
    classDef master fill:#FFEF9F,stroke:#333,stroke-width:1px
    classDef input fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef pipeline fill:#D0F5D0,stroke:#333,stroke-width:1px
    classDef msgs fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef viz fill:#FFE0B2,stroke:#333,stroke-width:1px
```
