# cartographer_rviz

`cartographer_rviz` is the RViz integration package for Cartographer (ROS 2). It provides a visualization plugin that displays the map built by Cartographer as a collection of submaps inside RViz.

Cartographer represents the environment as a set of trajectory-local submaps. Each submap stores occupancy information that can be rendered as a grayscale intensity image with an associated alpha (opacity) channel. The plugin fetches per-submap textures from the running Cartographer node and composites them into a single "X-ray" view of the map inside the 3D scene.

## Role in the system

This package is a consumer of the other Cartographer packages:

- It depends on the `cartographer` core library, which provides the `SubmapId` type, the `SubmapTextures`/`SubmapTexture` rendering data structures, and the submap painting machinery used to produce the textures.
- It depends on `cartographer_ros` for the `FetchSubmapTextures()` helper that queries the Cartographer node over the `SubmapQuery` service, and on `cartographer_ros_msgs` for the `SubmapList`, `SubmapEntry`, and `SubmapQuery` messages and service used by that RPC.
- It is a plugin for `rviz_common`, `rviz_rendering`, and `rviz_ogre_vendor`, which provide the RViz display infrastructure and the OGRE rendering engine.

## How it works

1. The `SubmapsDisplay` plugin subscribes to the `SubmapList` topic published by Cartographer.
2. For every submap in the list, it creates a `DrawableSubmap` object that owns two `OgreSlice` objects (one high-resolution and one low-resolution slice).
3. On every render update, submaps that have a newer metadata version issue an asynchronous `SubmapQuery` service call through `FetchSubmapTextures()`.
4. The returned texture is uploaded to OGRE as raw RGB pixel data and drawn as a textured quad in the scene, positioned and oriented by the submap pose.
5. Submaps are alpha-blended together, and submap opacity fades with the distance between the submap and the tracking frame in the z direction.

## Contents

- **Overview** — this page.
- **Quickstart** — build and usage instructions.
- **File-by-file documentation**:
  - Build and package metadata: `CMakeLists.txt`, `package.xml`, `rviz_plugin_description.xml`.
  - Headers under `include/cartographer_rviz/`: `submaps_display.h`, `drawable_submap.h`, `ogre_slice.h`.
  - Implementations under `src/`: `submaps_display.cpp`, `drawable_submap.cpp`, `ogre_slice.cpp`.
  - OGRE shader and material files under `ogre_media/materials/`: `glsl120.program`, `submap.vert`, `submap.frag`, `submap.material`.

## Cross-References

- [cartographer_ros](../cartographer_ros/overview.md) — Main ROS 2 integration package
- [cartographer_ros_msgs](../cartographer_ros_msgs/index.md) — ROS message and service definitions
- [Cartographer Core Library](../../index.md) — Underlying SLAM library (submap types, rendering)

```{toctree}
:maxdepth: 2
:caption: Contents

quickstart
CMakeLists
package.xml
rviz_plugin_description
include/cartographer_rviz/submaps_display.h
include/cartographer_rviz/drawable_submap.h
include/cartographer_rviz/ogre_slice.h
src/submaps_display.cpp
src/drawable_submap.cpp
src/ogre_slice.cpp
ogre_media/materials/glsl120/glsl120.program
ogre_media/materials/glsl120/submap.vert
ogre_media/materials/glsl120/submap.frag
ogre_media/materials/scripts/submap.material
```