# Quickstart

`cartographer_rviz` is a ROS 2 package built with `ament_cmake`. It is intended to be built as part of a Cartographer ROS 2 workspace.

## Dependencies

The package depends on the following ROS 2 and third-party packages (declared in `package.xml`):

- `cartographer` and `cartographer_ros` — core SLAM library and its ROS 2 bindings, which provide the submap texture data structures and the `FetchSubmapTextures()` helper.
- `cartographer_ros_msgs` — the `SubmapList`, `SubmapEntry`, and `SubmapQuery` messages and service.
- `rviz_common`, `rviz_rendering`, `rviz_ogre_vendor` — RViz display framework and the OGRE renderer.
- `rclcpp`, `pluginlib`, `eigen`, `libabsl-dev`, `tf2_ros`.

Build dependencies are declared through `ament_cmake` plus the Cartographer CMake helpers (from `$CARTOGRAPHER_CMAKE_DIR/functions.cmake`).

## Building

Build the package with `colcon` (or your usual `ament` tooling) inside a workspace that contains `cartographer`, `cartographer_ros`, and `cartographer_ros_msgs`:

```bash
mkdir -p ~/cartographer_ws/src
# ... checkout cartographer, cartographer_ros, cartographer_ros_msgs, and cartographer_rviz into src/
cd ~/cartographer_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-select cartographer_rviz
```

The package builds as a shared library and exports its plugin description (`rviz_plugin_description.xml`) so that RViz can discover the `SubmapsDisplay` plugin. The OGRE shader and material resources under `ogre_media/` are registered as RViz OGRE media exports and installed with the package.

## Usage in RViz

1. Launch RViz in a session where Cartographer (the `cartographer_ros` node) is running and publishing a `SubmapList` message and exposing the `/submap_query` service.
2. Add the **SubmapsDisplay** display to the RViz view. It appears as `cartographer_rviz/SubmapsDisplay`.
3. The display subscribes to the `SubmapList` topic and progressively fetches submap textures.
4. Use the display properties to control the view:
   - **Submap query service** — the service name used to fetch textures (default `/submap_query`).
   - **Tracking frame** — the frame used for z-distance fading (default `base_link`).
   - **High Resolution / Low Resolution** — toggle the two texture slices per submap.
   - **Submaps / All** — enable or disable all trajectories and submaps at once.
   - **All Submap Pose Markers** — toggle the pose axes and submap ID labels.
   - **Fade-out distance** — the z-distance (in meters) at which submaps begin to fade out.