# swri-robotics/mapviz architecture

> Architecture diagram of the GitHub repository swri-robotics/mapviz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swri-robotics/mapviz
- Repository: https://github.com/swri-robotics/mapviz

## Overview

##### Project type and purpose
- This is a desktop “full-stack” visualization application built on ROS (Robot Operating System).

##### File structure
- Top-level packages:
- mapviz – the core GUI application, plugin loader, Qt UI definitions
- mapviz_interfaces – custom ROS services (e.g. AddMapvizDisplay)
- mapviz_plugins – a collection of visualization plugins (attitude, grid, path, point click, etc.)
- multires_image – multi-resolution image loader: Qt plugin + standalone tile loader node
- tile_map – tile-map source plugin for mapviz
- docs & GitHub CI/build files
- Each package has its own CMakeLists.txt and package.xml, indicating they are ROS2 packages built with ament/CMake.
- Qt .ui files define plugin configuration dialogs; plugin.xml and mapviz_plugins.xml register plugins with the core.

##### Architecture insights from README
- Core is a ROS node (“mapviz_main”) that hosts plugins.
- Plugins subscribe to ROS topics (Image, Pose, Path, PointCloud2, etc.) and render into a 2D canvas.
- There are also standalone helper nodes (e.g., mapviz_tile_loader, multires_view_node) launched via ROS launch files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ROS Infrastructure
    subgraph "ROS Infrastructure"
        ROSMaster("ROS Master / DDS"):::external
    end

    %% Core GUI (mapviz)
    subgraph "Core GUI (mapviz)" 
        direction TB
        MapvizNode("mapviz_main ROS Node"):::core
        
        subgraph "Qt Application"
            direction TB
            MVMain["mapviz_main.cpp"]:::core
            MVApp["mapviz_application.cpp"]:::core
            MVCore["mapviz.cpp"]:::core
            MVUI["mapviz.ui"]:::core
            MPkg["package.xml"]:::core
            MPluginXML["plugin.xml"]:::core
        end

        subgraph "Plugin Manager"
            direction TB
            PMH["mapviz_plugin.h"]:::core
            PMCPP["mapviz.cpp (plugin loader)"]:::core
            PMH2["mapviz.hpp"]:::core
        end
    end

    %% Custom Services
    subgraph "Custom Services (mapviz_interfaces)"
        direction TB
        Srv["AddMapvizDisplay.srv"]:::service
        SPkg["package.xml"]:::service
        SCMake["CMakeLists.txt"]:::service
    end

    %% Visualization Plugins
    subgraph "Visualization Plugins (mapviz_plugins)"
        direction TB
        GPS["gps_plugin.cpp"]:::plugin
        Odometry["odometry_plugin.cpp"]:::plugin
        ImageP["image_plugin.cpp"]:::plugin
        GridP["grid_plugin.cpp"]:::plugin
        UIPlug["*_config.ui"]:::plugin
        PPkg["package.xml"]:::plugin
        PReg["mapviz_plugins.xml"]:::plugin
    end

    %% Tile Map Source Plugin
    subgraph "Tile Map Source Plugin (tile_map)"
        direction TB
        TMCPP["tile_map_plugin.cpp"]:::plugin
        TMH["tile_map_plugin.h"]:::plugin
        TMUI["tile_map_config.ui"]:::plugin
        TPPkg["package.xml"]:::plugin
        TPReg["mapviz_plugins.xml"]:::plugin
    end

    %% Multi-Resolution Imagery Plugin
    subgraph "Multi-Resolution Imagery (multires_image)"
        direction TB
        MRCPP["multires_image_plugin.cpp"]:::plugin
        MRH["multires_image_plugin.h"]:::plugin
        MRUI["multires_config.ui"]:::plugin
        MRPkg["package.xml"]:::plugin
        MRReg["mapviz_plugins.xml"]:::plugin
    end

    %% Stand-alone Nodes
    subgraph "Standalone Nodes"
        direction TB
        STLoader["mapviz_tile_loader (node)"]:::node
        STLaunch["mapviz_tile_loader.launch"]:::node
        MRView["multires_view_node.cpp"]:::node
        MRLaunch["multires.launch"]:::node
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        TileServer["External Tile Server"]:::external
        LocalCache["Local Tile Cache"]:::external
    end

    %% Connections
    ROSMaster -->|pub/sub| MapvizNode
    ROSMaster -->|pub/sub| STLoader
    ROSMaster -->|pub/sub| MRView
    MapvizNode -->|loads| PMCPP
    PMCPP -->|manages| GPS
    PMCPP -->|manages| Odometry
    PMCPP -->|manages| ImageP
    PMCPP -->|manages| GridP
    PMCPP -->|manages| TMCPP
    PMCPP -->|manages| MRCPP
    MapvizNode -->|service call| Srv
    STLoader -->|publishes tiles| ROSMaster
    ROSMaster -->|subscribes| MRCPP
    TileServer -->|fetch tiles| LocalCache
    LocalCache -->|serves tiles| STLoader

    %% UI Configs
    UIPlug --> GPS
    UIPlug --> Odometry
    UIPlug --> ImageP
    UIPlug --> GridP

    %% Click Events
    click MVMain "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/src/mapviz_main.cpp"
    click MVApp "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/src/mapviz_application.cpp"
    click MVCore "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/src/mapviz.cpp"
    click MVUI "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/ui/mapviz.ui"
    click MPkg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/package.xml"
    click MPluginXML "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/plugin.xml"
    click PMH "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/include/mapviz/mapviz_plugin.h"
    click PMCPP "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/src/mapviz.cpp"
    click PMH2 "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz/include/mapviz/mapviz.hpp"
    click Srv "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_interfaces/srv/AddMapvizDisplay.srv"
    click SPkg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_interfaces/package.xml"
    click SCMake "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_interfaces/CMakeLists.txt"
    click GPS "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/src/gps_plugin.cpp"
    click Odometry "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/src/odometry_plugin.cpp"
    click ImageP "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/src/image_plugin.cpp"
    click GridP "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/src/grid_plugin.cpp"
    click UIPlug "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/ui/gps_config.ui"
    click PPkg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/package.xml"
    click PReg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/mapviz_plugins/mapviz_plugins.xml"
    click TMCPP "https://github.com/swri-robotics/mapviz/blob/ros2-devel/tile_map/src/tile_map_plugin.cpp"
    click TMH "https://github.com/swri-robotics/mapviz/blob/ros2-devel/tile_map/include/tile_map/tile_map_plugin.h"
    click TMUI "https://github.com/swri-robotics/mapviz/blob/ros2-devel/tile_map/src/tile_map_config.ui"
    click TPPkg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/tile_map/package.xml"
    click TPReg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/tile_map/mapviz_plugins.xml"
    click MRCPP "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/src/multires_image_plugin.cpp"
    click MRH "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/include/multires_image/multires_image_plugin.h"
    click MRUI "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/src/multires_config.ui"
    click MRPkg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/package.xml"
    click MRReg "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/mapviz_plugins.xml"
    click STLoader "https://github.com/swri-robotics/mapviz/tree/ros2-devel/multires_image/nodes/mapviz_tile_loader"
    click STLaunch "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/launch/mapviz_tile_loader.launch"
    click MRView "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/src/nodes/multires_view_node.cpp"
    click MRLaunch "https://github.com/swri-robotics/mapviz/blob/ros2-devel/multires_image/launch/multires.launch"

    %% Styles
    classDef core fill:#FFD580,stroke:#333,stroke-width:1px
    classDef plugin fill:#A0E7E5,stroke:#333,stroke-width:1px
    classDef service fill:#B4F8C8,stroke:#333,stroke-width:1px
    classDef node fill:#FFAEBC,stroke:#333,stroke-width:1px
    classDef external fill:#CDB4DB,stroke:#333,stroke-width:1px
```
