### Start RViz Visualizer in ROS 2

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

This command launches the RViz visualizer application in ROS 2. It initiates the graphical interface used for robot visualization and debugging.

```bash
ros2 run rviz2 rviz2
```

--------------------------------

### RViz Visual Test Fixture and Display Interaction API

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/docs/README.md

Documentation for key methods provided by `VisualTestFixture` and methods available on display page objects for configuring and interacting with RViz displays during visual tests. This includes camera control, display addition, property modification, and screenshot capture/assertion.

```APIDOC
VisualTestFixture Methods:

setCamPose(Ogre::Vector3 pose)
  - Description: Sets the position of the camera for the test scene. Optional, if default position is sufficient.
  - Parameters:
    - pose: An Ogre::Vector3 representing the camera's position.
  - Returns: void

setCamLookAt(Ogre::Vector3 look_at)
  - Description: Sets the point the camera is looking at. Optional, if default sight vector is sufficient.
  - Parameters:
    - look_at: An Ogre::Vector3 representing the target point.
  - Returns: void

addDisplay<T>()
  - Description: Adds an RViz display of the specified type to the test scene.
  - Parameters:
    - T: The type of the desired display (e.g., GridDisplayPageObject, ImageDisplayPageObject).
  - Returns: std::shared_ptr<T> pointing to the newly created display object.

captureMainWindow()
  - Description: Takes a screenshot of the main RViz render window.
  - Parameters: None
  - Returns: void

captureRenderWindow(std::shared_ptr<PageObjectWithRenderWindow> display)
  - Description: Takes a screenshot of a secondary render window belonging to a specific display.
  - Parameters:
    - display: A shared pointer to the display object whose render window is to be captured.
  - Returns: void

assertScreenShotsIdentity()
  - Description: Compares all captured screenshots with their reference images. Must be called exactly once per test.
  - Parameters: None
  - Returns: void

assertMainWindowIdentity()
  - Description: Compares only the main window screenshot with its reference image. Alternative to assertScreenShotsIdentity().
  - Parameters: None
  - Returns: void

Display Page Object Methods (Examples for GridDisplayPageObject, ImageDisplayPageObject):

display->setOffset(double x, double y, double z)
  - Description: Sets the offset property of a display (e.g., GridDisplay).
  - Parameters:
    - x, y, z: Double values for the offset coordinates.
  - Returns: void

display->setColor(int r, int g, int b)
  - Description: Sets the color property of a display (e.g., GridDisplay).
  - Parameters:
    - r, g, b: Integer values (0-255) for red, green, and blue color components.
  - Returns: void

display->collapse()
  - Description: Collapses the display's menu in the RViz GUI. Useful for managing multiple displays.
  - Parameters: None
  - Returns: void

display->setQueueSize(int size)
  - Description: Sets the queue size property for displays that buffer data (e.g., ImageDisplay).
  - Parameters:
    - size: An integer representing the desired queue size.
  - Returns: void
```

--------------------------------

### RViz Visual Test Structure in C++

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/docs/README.md

Demonstrates the basic structure of an RViz visual test using `VisualTestFixture`. It shows how to set camera pose, add and configure displays (`GridDisplayPageObject`, `ImageDisplayPageObject`), capture screenshots of main and secondary render windows, and assert screenshot identity for visual regression testing.

```cpp
TEST_F(VisualTestFixture, example_test_structure) {
  /// Set the position of the camera and its sight vector (optional):
  setCamPose(Ogre::Vector3(0, 3, 16));
  setCamLookAt(Ogre::Vector3(0, 2, 0));

  /// Add displays:
  auto grid_display = addDisplay<GridDisplayPageObject>();
  auto image_display = addDisplay<ImageDisplayPageObject>();

  /// Modify their properties:
  grid_display->setOffset(0.3, 2, 0.4);
  grid_display->setColor(0, 255, 0);
  grid_display->collapse();
  image_display->setQueueSize(10);

  /// Take the screenshots of the desired render windows:
  captureMainWindow();
  captureRenderWindow(image_display);

  /// Compare test screenshots with the reference ones:
  assertScreenShotsIdentity();
}
```

--------------------------------

### Build and Run RViz Visual Tests with Colcon

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/docs/README.md

Provides shell commands to build RViz visual tests with CMake flags enabled and then execute them using `colcon test`. It also notes the caching behavior of CMake flags and how to update reference images by setting an environment variable.

```shell
colcon build --cmake-args -DEnableVisualTests=True -DBUILD_TESTING=1

colcon test
```

--------------------------------

### Execute RViz Display Tests on Windows

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

This command enables and runs RViz display tests specifically on Windows. These tests require a physical display or a specialized testing setup to execute correctly.

```Shell
ament test --cmake-args -DEnableDisplayTests=True
```

--------------------------------

### RViz Visualizer Tools

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

Documentation for the basic interactive tools available in the RViz visualizer toolbar, including 'Move Camera' and 'Interact'.

```APIDOC
RViz Visualizer Tools:
  Move Camera Tool:
    Description: The default tool. When selected, the current View controller's actions are enabled when clicking inside the 3D view.
    Keyboard Shortcut: 'm'
  Interact Tool:
    Description: Allows the use of Interactive Marker displays, enabling interaction with specific elements in the visualization.
    Keyboard Shortcut: 'i'
```

--------------------------------

### Build RViz ROS 2 Packages with Colcon

Source: https://github.com/ros2/rviz/blob/rolling/README.md

This command uses Colcon, the ROS 2 build tool, to compile all packages within the current workspace, including RViz. The `--merge-install` flag ensures a cleaner installation by merging install spaces, which is beneficial for development.

```bash
colcon build --merge-install
```

--------------------------------

### CMake Conditional Qt Windows Deployment Tool Setup

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/CMakeLists.txt

This conditional block is specifically for Windows builds using Qt. It attempts to locate the `windeployqt` tool's installation prefix using `qmake` to assist with deployment, though the comment indicates it might be removed in the future.

```CMake
# TODO(wjwwood): this block is to setup the windeployqt tool, could be removed later.
if(Qt${QT_VERSION_MAJOR}_FOUND AND WIN32 AND TARGET Qt${QT_VERSION_MAJOR}::qmake AND NOT TARGET Qt${QT_VERSION_MAJOR}::windeployqt)
  get_target_property(_qt_qmake_location Qt${QT_VERSION_MAJOR}::qmake IMPORTED_LOCATION)

  execute_process(
    COMMAND "${_qt_qmake_location}" -query QT${QT_VERSION_MAJOR}_INSTALL_PREFIX
    RESULT_VARIABLE return_code
    OUTPUT_VARIABLE qt_install_prefix
    OUTPUT_STRIP_TRAILING_WHITESPACE
  )
endif()
```

--------------------------------

### Automate Qt Deployment and Installation on Windows

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/CMakeLists.txt

This block conditionally executes `windeployqt` as a post-build step for the RViz2 executable on Windows, if the `windeployqt` target was successfully configured. It cleans a temporary directory, runs `windeployqt` to collect necessary Qt DLLs, and then defines installation rules to copy these deployed files into the `bin` and `lib` directories of the installation prefix. This ensures the deployed application has all its Qt dependencies.

```CMake
if(TARGET Qt${QT_VERSION_MAJOR}::windeployqt)
  # execute windeployqt in a tmp directory after build
  add_custom_command(TARGET ${PROJECT_NAME}
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E remove_directory "${CMAKE_CURRENT_BINARY_DIR}/windeployqt"
    COMMAND set PATH=%PATH%$<SEMICOLON>${qt_install_prefix}/bin
    COMMAND
    Qt${QT_VERSION_MAJOR}::windeployqt
    --dir "${CMAKE_CURRENT_BINARY_DIR}/windeployqt"
    "$<TARGET_FILE_DIR:${PROJECT_NAME}>/$<TARGET_FILE_NAME:${PROJECT_NAME}>"
  )

  # copy deployment directory during installation
  install(
    DIRECTORY
    "${CMAKE_CURRENT_BINARY_DIR}/windeployqt/"
    DESTINATION bin
  )
  install(
    DIRECTORY
    "${CMAKE_CURRENT_BINARY_DIR}/windeployqt/"
    DESTINATION lib/${PROJECT_NAME}
  )
endif()
```

--------------------------------

### rviz_rendering API Changes

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

Documentation of key API modifications within the `rviz_rendering` module, detailing changes to `BillboardLine`, `PointCloud`, and `CovarianceVisual` classes, and providing guidance for adapting existing implementations.

```APIDOC
BillboardLine:
  - `newLine()` -> `finishLine()`
    - Functionality: Identical, but `finishLine()` can be called exactly `n` times (where `n` is the number of lines), while `newLine()` could only be called `n-1` times.

PointCloud:
  - `addPoints(...)`
    - Change: Now takes vector iterators as arguments instead of a raw pointer and size.

CovarianceVisual:
  - Inheritance: Does not inherit from `rviz_rendering::Object` anymore.
  - Interface: Has a much restricted interface compared to previous versions.
  - Usage: Previously used by `rviz_common::properties::CovarianceProperty`.
  - New Handling: Visuals must now be handled directly within the display. Set up a slot to fetch data from the covariance property and pass it to `CovarianceVisual` (e.g., see `OdometryDisplay`).
```

--------------------------------

### CMake Export and Installation Rules for RViz Visual Testing Framework

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/CMakeLists.txt

This section defines how the `rviz_visual_testing_framework` and its dependencies are exported for use by other downstream packages. It also specifies the installation rules for the compiled library, public include directories, and configuration files, ensuring they are placed correctly during installation.

```CMake
ament_export_dependencies(
  geometry_msgs
  Qt${QT_VERSION_MAJOR}
  rclcpp
  rcutils
  rviz_common
  rviz_ogre_vendor
  rviz_rendering
  std_msgs
  tf2
  tf2_ros
)

# Export old-style CMake variables
ament_export_include_directories("include/${PROJECT_NAME}")

# Export modern CMake targets
ament_export_targets(rviz_visual_testing_framework)

install(
  TARGETS rviz_visual_testing_framework
  EXPORT rviz_visual_testing_framework
  ARCHIVE DESTINATION lib
  LIBRARY DESTINATION lib
  RUNTIME DESTINATION bin
)

install(
  DIRECTORY include/
  DESTINATION include/${PROJECT_NAME}
)

install(
  DIRECTORY config
  DESTINATION share/${PROJECT_NAME}
)
```

--------------------------------

### Create RViz ROS 2 Development Workspace

Source: https://github.com/ros2/rviz/blob/rolling/README.md

This command sequence creates a new directory structure for a ROS 2 RViz development workspace, preparing it for cloning repositories and subsequent building.

```bash
mkdir -p ~/rviz2_ws/src
cd ~/rviz2_ws/src
```

--------------------------------

### Installing RViz Default Plugins and Assets

Source: https://github.com/ros2/rviz/blob/rolling/rviz_default_plugins/CMakeLists.txt

This section specifies the installation rules for the compiled `rviz_default_plugins` library, its public header files, and associated icon resources. It ensures that the built artifacts are placed in the correct locations within the ROS2 install space, making them discoverable and usable by other packages and the RViz application itself.

```CMake
install(
  TARGETS rviz_default_plugins
  EXPORT rviz_default_plugins
  ARCHIVE DESTINATION lib
  LIBRARY DESTINATION lib
  RUNTIME DESTINATION bin
)

install(
  DIRECTORY include/
  DESTINATION include/${PROJECT_NAME}
)

install(
  DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/icons"
  DESTINATION "share/${PROJECT_NAME}"
)
```

--------------------------------

### Windows Compatibility and Visibility Control

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

This snippet addresses considerations for making RViz plugins compatible with Windows, specifically focusing on visibility control for exported symbols to prevent linking errors.

```APIDOC
Windows Compatibility:
- Visibility Control: Classes or methods from `rviz_rendering` and/or `rviz_common` that are intended for use in other plugins must be marked with `RVIZ_RENDERING_PUBLIC` or `RVIZ_COMMON_PUBLIC` modifiers.
- Failure to apply these modifiers will result in missing symbols during linking on Windows.
```

--------------------------------

### RViz Package Structure and Base Class Migration

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

This snippet outlines the changes in RViz's package structure and the migration of core base classes for displays and tools. It details where user-facing functionality, rendering components, and default plugins are now located, and the replacement of `MessageFilterDisplay` with `RosTopicDisplay`.

```APIDOC
Package Structure Changes:
- `rviz_common`: Contains most user-facing functionality, base classes for displays/tools (e.g., `rviz_common/Display`), and the selection mechanism (moved to `rviz_common/interaction`).
- `rviz_rendering`: Contains `ogre_helpers` and classes related to rendering, including subfolder `objects`.
- `rviz_default_plugins`: Contains default plugins and the robot.

Class Migrations:
- `MessageFilterDisplay` -> `RosTopicDisplay`: For display plugins that subscribe to ROS topics. `RosTopicDisplay` automatically handles subscription/unsubscription.
- `ViewPicker`: Object picking behavior, exposed via the display context.

Pluginlib:
- `plugin_description.xml`: General mechanism unchanged.
- Base classes (e.g., `rviz_common/Display`) have moved; ensure `plugin_description.xml` refers to correct class names and namespaces.
```

--------------------------------

### RViz FPS (First-Person Shooter) View Controller Controls

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

Documentation for the FPS camera in RViz, which provides a first-person perspective. This controller simulates head movements for navigation.

```APIDOC
RViz FPS (First-Person Shooter) View Controller:
  Description: A first-person camera that rotates as if you're looking with your head.
  Controls:
    - Left mouse button: Click and drag to rotate. Control-click to pick the object under the mouse and look directly at it.
    - Middle mouse button: Click and drag to move along the plane formed by the camera's up and right vectors.
    - Right mouse button: Click and drag to move along the camera's forward vector. Dragging up moves forward, down moves backward.
    - Scrollwheel: Move forward/backward.
```

--------------------------------

### RViz Plugin Base Classes and Development Guidelines

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

This section outlines the base classes and key considerations for developing various types of plugins in RViz, including panels, tools, view controllers, and transformation libraries. It covers derivation, property management, and resource loading.

```APIDOC
Panel Plugin:
  - Derive from `rviz_common::Panel`

Tool Plugin:
  - Derive from `rviz_common::Tool`
  - `shortcut_key_`: Set to a char to define hotkey for activation/deactivation.
  - `getPropertyContainer()`: Use its return value as parent for properties to add them to the "Tool Properties" panel.
  - Resources: Use `rviz_common/load_resource` for custom cursors, icons, etc.

View Controller Plugin:
  - Independent of TF frames: Derive from `rviz_common::ViewController`
  - Track TF frames: Derive from `rviz_common::FramePositionTrackingViewController` (provides convenience for tracking target frames).
  - Orbiting focal point: Derive from `rviz_default_plugins::OrbitViewController`.

Transformation Library Plugin:
  - Implement `rviz_common::transformation::FrameTransformer` (refer to API documentation in header file).
  - For extra functionality or direct library access: Implement a subclass of `rviz_common::transformation::TransformerLibraryConnector` (e.g., `rviz_default_plugins::transformation::TFWrapper`).
```

--------------------------------

### CMake Project Setup and Visual Test Configuration

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/CMakeLists.txt

This snippet initializes the CMake project, sets the minimum required CMake version, and defines options for enabling visual tests. It also sets up build and source directory paths for managing test artifacts like screenshots.

```CMake
cmake_minimum_required(VERSION 3.10)

project(rviz_visual_testing_framework)

# Options to decide whether or not the visual test will run.
option(EnableVisualTests "decides whether or not enable the tests")

# Path variables needed to save and find screenshots for image comparison.
add_definitions(-D_BUILD_DIR_PATH="${CMAKE_CURRENT_BINARY_DIR}")
add_definitions(-D_SRC_DIR_PATH="${CMAKE_CURRENT_SOURCE_DIR}")

# Creates a directory where the test and reference screenshots will be saved.
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/test_images)
file(MAKE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/test/reference_images)
```

--------------------------------

### Install RViz Ogre Media Assets

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering/CMakeLists.txt

This CMake command installs the `ogre_media` directory, which contains assets used by RViz's Ogre rendering engine, into the package's shared directory. It preserves source permissions during installation, ensuring proper access to media files.

```CMake
install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/ogre_media"
  DESTINATION "share/${PROJECT_NAME}"
  USE_SOURCE_PERMISSIONS)
```

--------------------------------

### Install RViz2 Executable and Python Script

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/CMakeLists.txt

Defines the installation rules for the RViz2 executable and a Python script. The executable is installed to both the `bin` and `lib/${PROJECT_NAME}` directories, while the `rviz1_to_rviz2.py` script is installed to `lib/${PROJECT_NAME}`. This ensures the application and its utility scripts are placed in standard locations during installation.

```CMake
install(TARGETS ${PROJECT_NAME} DESTINATION bin)
install(TARGETS ${PROJECT_NAME} DESTINATION lib/${PROJECT_NAME})
install(PROGRAMS scripts/rviz1_to_rviz2.py DESTINATION lib/${PROJECT_NAME})
```

--------------------------------

### Basic CMake Project Setup for RViz Ogre Vendor

Source: https://github.com/ros2/rviz/blob/rolling/rviz_ogre_vendor/CMakeLists.txt

Initializes the CMake project, sets the minimum required CMake version, defines the project name, and finds necessary ament packages for vendor support. It also defines a CMake option to control library name mangling.

```CMake
cmake_minimum_required(VERSION 3.10)
project(rviz_ogre_vendor)

find_package(ament_cmake REQUIRED)
find_package(ament_cmake_vendor_package REQUIRED)

option(RVIZ_OGRE_VENDOR_MANGLE_NAME_OF_LIBRARIES_USED_BY_RVIZ "If enabled, append a unique name to OgreMain, OgreOverlay and OgreGLSupport." FALSE)
```

--------------------------------

### C++14 Migration Guidelines for RViz Plugins

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

This snippet provides guidelines for updating plugin code to C++14 standards, focusing on modern C++ practices like C++ style casts, smart pointers, range-based for loops, and `nullptr` usage.

```APIDOC
C++14 Migration:
- Replace C-style casts with C++-style casts (e.g., `static_cast`, `dynamic_cast`).
- Replace raw pointers with smart pointers (e.g., `std::shared_ptr`, `std::unique_ptr`) wherever possible.
  - Exceptions: Ogre and Qt objects that assume ownership of raw pointers (e.g., `Ogre::SceneNode`, `Ogre::SceneManager`, `rviz_common::properties` when parented) should remain raw pointers to avoid double deletion.
- Replace index-based for loops with range-based for loops or iterator-based loops where applicable.
- Replace pointer assignments of `0` or `NULL` with `nullptr`.
- Delete superfluous includes.
```

--------------------------------

### Configure and Install RViz Common CMake Targets and Files

Source: https://github.com/ros2/rviz/blob/rolling/rviz_common/CMakeLists.txt

This CMake code exports the `rviz_common` target and installs its components (libraries, binaries, headers) along with various resource directories (icons, images, help) and a default RViz configuration file. It ensures the `rviz_common` package is properly installed and discoverable within the ROS2 environment.

```CMake
ament_export_targets(rviz_common)

install(
  TARGETS rviz_common
  EXPORT rviz_common
  ARCHIVE DESTINATION lib
  LIBRARY DESTINATION lib
  RUNTIME DESTINATION bin
)

install(
  DIRECTORY include/
  DESTINATION include/${PROJECT_NAME}
)

install(FILES default.rviz
  DESTINATION share/${PROJECT_NAME}
)

install(
  DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/icons"
  DESTINATION "share/${PROJECT_NAME}"
)

install(
  DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/images"
  DESTINATION "share/${PROJECT_NAME}"
)

install(
  DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/help"
  DESTINATION "share/${PROJECT_NAME}"
)
```

--------------------------------

### CMake Project Setup and C++ Standard Configuration

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering_tests/CMakeLists.txt

This snippet initializes the CMake project, sets the minimum required CMake version, and configures the C++ standard to C++17 if not already defined. It ensures modern C++ features are available for the project.

```CMake
cmake_minimum_required(VERSION 3.10)

project(rviz_rendering_tests)

# Default to C++17
if(NOT CMAKE_CXX_STANDARD)
  set(CMAKE_CXX_STANDARD 17)
  set(CMAKE_CXX_STANDARD_REQUIRED ON)
endif()
```

--------------------------------

### Registering Ogre Media Files for RViz

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

The `register_rviz_ogre_media_exports` CMake macro, defined in `rviz_rendering`, allows custom Ogre media files (e.g., meshes, scripts) to be made available to RViz at runtime. It's important to note that each folder within a hierarchy needs to be exported separately, as subfolders are not automatically included.

```CMake
register_rviz_ogre_media_exports(DIRECTORIES "test_folder/scripts")
```

--------------------------------

### Export and Install ROS2 RViz Rendering Library and Assets

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering/CMakeLists.txt

This CMake snippet exports the `rviz_rendering` target for use by other packages and defines its installation paths for libraries, archives, runtime binaries, include directories, and CMake configuration files. It ensures the core rendering library and its associated assets are correctly placed during package installation.

```CMake
ament_export_targets(rviz_rendering)

install(
  TARGETS rviz_rendering
  EXPORT rviz_rendering
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
  RUNTIME DESTINATION bin
)

install(
  DIRECTORY include/
  DESTINATION include/${PROJECT_NAME}
)

set(rviz_rendering_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/cmake")
include(${CMAKE_CURRENT_SOURCE_DIR}/src/cmake/register_rviz_ogre_media_exports_hook-extras.cmake)

install(DIRECTORY src/cmake
  DESTINATION share/${PROJECT_NAME})
```

--------------------------------

### rviz_common API Changes

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

Comprehensive documentation of significant API changes within the `rviz_common` module, covering modifications to `SelectionManager`, `ViewPicker`, `SelectionHandler`, `CovarianceProperty`, and the `Display Context`. This includes moved functionalities, new registration requirements, and interface adjustments.

```APIDOC
SelectionManager:
  - `get3DPoint(...)`
    - Moved To: `ViewPicker::get3DPoint(...)` (obtainable from `DisplayContext`).
  - `addHandler(...)` and similar selection handle functionalities
    - Moved To: `HandlerManager`.
    - Note: When extending `SelectionHandler`, registration and obtaining handles are still automatic, so no changes should be necessary for basic usage.

SelectionHandler:
  - Registration: Needs to register its handle manually now.
  - Factory Function: Use the factory function defined in `selection_handler.hpp` for creation instead of the constructor.
  - Post-Creation: After creation, the handler must call `SelectionHandler::registerHandle()`.
  - Automatic Registration: To automate `registerHandle()`, make the `createSelectionHandler(...)` factory method (from `selection_handler.hpp`) a friend of the new `SelectionHandler` class (e.g., see `PointCloudSelectionHandler`).

SelectionManager and ViewPicker (General):
  - Private API: Several functions within these classes have been moved to private API.
  - Requesting Access: If needed, provide a pull request to the RViz repository explaining the necessity of the functionality.

CovarianceProperty:
  - Previous Usage: Previously used `CovarianceVisual`.
  - Current State: Now contains only a number of properties.
  - Integration: Refer to `rviz_rendering::CovarianceVisual` for details and `OdometryDisplay` in `rviz_default_plugins` for example usage.

Display Context:
  - New Methods: Provides a host of new methods, particularly useful for writing custom panels.
  - API Change: The API has changed overall, but the functionality is primarily extended.
```

--------------------------------

### Clone RViz ROS 2 Repository

Source: https://github.com/ros2/rviz/blob/rolling/README.md

This command clones the official RViz repository for ROS 2 into the current workspace's source directory, making the RViz source code available for local development and modification.

```bash
git clone https://github.com/ros2/rviz.git
```

--------------------------------

### Configure Qt Deployment Tool for Windows

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/CMakeLists.txt

This conditional block is specifically for Windows builds and aims to locate and set up the `windeployqt.exe` tool. It queries the Qt installation prefix to find the tool's location and then creates an imported executable target for `Qt::windeployqt`, making it available for post-build deployment steps. This is crucial for distributing Qt applications on Windows without requiring the full Qt SDK.

```CMake
if(Qt${QT_VERSION_MAJOR}_FOUND AND WIN32 AND TARGET Qt${QT_VERSION_MAJOR}::qmake AND NOT TARGET Qt${QT_VERSION_MAJOR}::windeployqt)
  get_target_property(_qt_qmake_location Qt${QT_VERSION_MAJOR}::qmake IMPORTED_LOCATION)

  execute_process(
    COMMAND "${_qt_qmake_location}" -query QT${QT_VERSION_MAJOR}_INSTALL_PREFIX
    RESULT_VARIABLE return_code
    OUTPUT_VARIABLE qt_install_prefix
    OUTPUT_STRIP_TRAILING_WHITESPACE
  )

  set(imported_location "${qt_install_prefix}/bin/windeployqt.exe")

  if(EXISTS ${imported_location})
    add_executable(Qt${QT_VERSION_MAJOR}::windeployqt IMPORTED)

    set_target_properties(Qt${QT_VERSION_MAJOR}::windeployqt PROPERTIES
      IMPORTED_LOCATION ${imported_location}
    )
  endif()
endif()
```

--------------------------------

### RViz Plugin Extension Points and Base Types

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

This section lists the different types of plugins that can extend RViz and their corresponding C++ base classes. Custom plugins must inherit from these base types to be recognized and loaded by RViz's plugin system.

```APIDOC
RViz Plugin Extension Points:
- Display: rviz_common::Display
- Panel: rviz_common::Panel
- Tool: rviz_common::Tool
- Frames transformation library: rviz_common::transformation::FrameTransformer
- View Controller: rviz_common::ViewController

Each plugin type requires inheritance from its specified base type for RViz recognition.
```

--------------------------------

### ROS 2 API Migration for RViz Plugins

Source: https://github.com/ros2/rviz/blob/rolling/docs/migration_guide.md

This snippet covers essential API changes when migrating RViz plugins to ROS 2, including logging macros, time handling, assertion replacement, and the exclusive use of TF2.

```APIDOC
ROS 2 API Changes:
- `rviz_common::RosTopicDisplay`: Automatically subscribes/unsubscribes to ROS topics; no need for manual node handler interaction (e.g., spinning).
- `ROS_ASSERT` -> `assert`: Replace ROS 1 assertions with standard C++ `assert`.
- Logging:
  - `RVIZ_COMMON_LOG_ERROR`
  - `RVIZ_COMMON_LOG_INFO`
  - Use these macros as ROS 1 error logging has not been ported.
- Time Handling:
  - `ros::time` -> `rclcpp::Clock` and `rclcpp::Time`: Use the new ROS 2 time API.
- TF:
  - RViz now uses `tf2` exclusively.
```

--------------------------------

### Define and Configure Grid Display Visual Test in CMake

Source: https://github.com/ros2/rviz/blob/rolling/rviz_default_plugins/CMakeLists.txt

This CMake snippet defines the `grid_display_visual_test` GTest executable, including its source files and a timeout. It then configures the target by adding private include directories and linking it to Qt Test and the `rviz_visual_testing_framework`. This setup is essential for validating the visual rendering and behavior of the grid display in Rviz.

```CMake
ament_add_gtest(grid_display_visual_test
  test/rviz_default_plugins/displays/grid/grid_display_visual_test.cpp
  test/rviz_default_plugins/page_objects/grid_display_page_object.cpp
  ${SKIP_VISUAL_TESTS}
  TIMEOUT 180)
if(TARGET grid_display_visual_test)
  target_include_directories(grid_display_visual_test PRIVATE test)
  target_link_libraries(grid_display_visual_test
    Qt${QT_VERSION_MAJOR}::Test
    rviz_visual_testing_framework::rviz_visual_testing_framework
  )
endif()
```

--------------------------------

### Exporting RViz Plugins with PLUGINLIB_EXPORT_CLASS

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

To enable `pluginlib` to discover and load a custom RViz plugin, the `PLUGINLIB_EXPORT_CLASS` macro must be invoked in the plugin's source file. This macro registers the plugin class with its base type, making it available to the RViz application at runtime.

```C++
#include <pluginlib/class_list_macros.hpp>
PLUGINLIB_EXPORT_CLASS(myplugin::Plugin, rviz_common::Display)
```

--------------------------------

### Configure Google Mock Tests for RViz Tools and View Controllers in CMake

Source: https://github.com/ros2/rviz/blob/rolling/rviz_default_plugins/CMakeLists.txt

This CMake snippet illustrates the setup for Google Mock tests targeting RViz tools and view controllers. It defines test executables using `ament_add_gmock`, specifies their source files, and conditionally links required libraries such as `rviz_default_plugins`, `ogre_testing_environment`, and Qt widgets for GUI-related tests.

```CMake
ament_add_gmock(measure_tool_test
  test/rviz_default_plugins/tools/measure/measure_tool_test.cpp
  ${TEST_FIXTURE_SOURCES_WITH_MOCK}
  ${SKIP_DISPLAY_TESTS})
if(TARGET measure_tool_test)
  target_include_directories(measure_tool_test PRIVATE test)
  target_link_libraries(measure_tool_test ${TEST_FIXTURE_WITH_MOCK_LIBRARIES} rviz_default_plugins ogre_testing_environment)
endif()

ament_add_gmock(orbit_view_controller_test
  test/rviz_default_plugins/view_controllers/orbit/orbit_view_controller_test.cpp
  ${TEST_FIXTURE_SOURCES_WITH_MOCK}
  ${SKIP_DISPLAY_TESTS})
if(TARGET orbit_view_controller_test)
  target_include_directories(orbit_view_controller_test PRIVATE test)
  target_link_libraries(orbit_view_controller_test
    ${TEST_FIXTURE_WITH_MOCK_LIBRARIES}
    Qt${QT_VERSION_MAJOR}::Widgets
    rviz_default_plugins
    ogre_testing_environment
  )
endif()

ament_add_gmock(ortho_view_controller_test
  test/rviz_default_plugins/view_controllers/ortho/ortho_view_controller_test.cpp
  ${TEST_FIXTURE_SOURCES_WITH_MOCK}
  ${SKIP_DISPLAY_TESTS})
if(TARGET ortho_view_controller_test)
  target_include_directories(ortho_view_controller_test PRIVATE test)
  target_link_libraries(ortho_view_controller_test
    ${TEST_FIXTURE_WITH_MOCK_LIBRARIES}
    Qt${QT_VERSION_MAJOR}::Widgets
    rviz_default_plugins
    ogre_testing_environment
  )
endif()
```

--------------------------------

### RViz Top-down Orthographic View Controller Controls

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

Documentation for the Top-down Orthographic view controller in RViz. This camera always looks down along the Z axis (in the robot frame) and provides an orthographic view, meaning objects do not get smaller with distance.

```APIDOC
RViz Top-down Orthographic View Controller:
  Description: The camera always looks down along the Z axis (in the robot frame) and uses an orthographic projection, so objects do not get smaller as they get farther away.
  Controls:
    - Left mouse button: Click and drag to rotate around the Z axis.
    - Middle mouse button: Click and drag to move the camera along the XY plane.
    - Right mouse button: Click and drag to zoom the image.
    - Scrollwheel: Zoom the image.
```

--------------------------------

### RViz VisualTestFixture Methods for Test Execution and Assertion

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/docs/documentation.md

The `VisualTestFixture` class provides a structured environment for RViz visual tests, encapsulating an instance of `QApplication`, `VisualizerApp`, `DisplayHandler`, and `Executor`. It offers convenience methods for managing RViz startup/shutdown, display handling, and crucial visual comparison assertions.

```APIDOC
VisualTestFixture
  - Purpose: A test fixture class that sets up and tears down the environment for RViz visual tests, managing core components like QApplication and VisualizerApp.
  - Members: Owns instances of QApplication, VisualizerApp, DisplayHandler, and Executor to handle RViz lifecycle, display management, and GUI interactions.

assertScreenShotsIdentity()
  - Purpose: Compares screenshots of both the main and any secondary render windows to assert visual identity.
  - Usage: Must be called at the end of a test. Suitable when interested in secondary render windows or when multiple screenshots have been taken.

assertMainWindowIdentity()
  - Purpose: Captures a screenshot of the main render window and immediately performs an image comparison.
  - Usage: Must be called at the end of a test. Suitable when only the main render window's visual identity is of interest. This method implicitly handles the screenshot capture, making a prior call to `captureMainWindow()` unnecessary.

captureMainWindow()
  - Purpose: Captures a screenshot of the main render window.
  - Usage: Typically used when screenshots need to be taken explicitly before a comparison method like `assertScreenShotsIdentity()` is called. Not required if `assertMainWindowIdentity()` is used, as it includes capture functionality.
```

--------------------------------

### Qt GUI Interaction for RViz Visual Tests

Source: https://github.com/ros2/rviz/blob/rolling/rviz_visual_testing_framework/docs/documentation.md

This section describes the fundamental Qt mechanisms employed to enable interaction with the RViz graphical user interface during visual tests. It addresses the challenge posed by `QApplication::exec()` blocking the main thread and how `QTimer::singleShot` is utilized to schedule interactions within the event loop.

```APIDOC
QApplication::exec()
  - Purpose: Starts the Qt event loop, making the application responsive to user input and system events.
  - Behavior: This method blocks the calling thread until QApplication::quit() is invoked, making direct interaction from the same thread after its call difficult.

QTimer::singleShot(int delay, QObject * context, Func1 slot)
  - Purpose: Schedules a function (slot) to be executed once after a specified delay.
  - Parameters:
    - delay: The time in milliseconds before the slot is invoked.
    - context: An optional QObject whose destruction will cancel the timer.
    - slot: The function or lambda to be executed. Can be a Q_SLOT or a C++11 lambda.
  - Usage: By calling this method before QApplication::exec() with an appropriate delay, actions can be scheduled to run while the QApplication is active in its main event loop, allowing interaction with the GUI.
```

--------------------------------

### Export Dependencies and Installation Targets

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering/CMakeLists.txt

This final section uses `ament_export_dependencies` to declare the build and runtime dependencies of the `rviz_rendering` package for other ROS2 packages. It also exports include directories and the library itself using `ament_export_include_directories` and `ament_export_libraries`, making them available for installation and use by other projects.

```CMake
ament_export_dependencies(
  Eigen3
  Qt${QT_VERSION_MAJOR}
  rviz_ogre_vendor
)

# Export old-style CMake variables
ament_export_include_directories("include/${PROJECT_NAME}")
ament_export_libraries(rviz_rendering)
```

--------------------------------

### Register RViz Ogre Media Exports and Install Test Meshes

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering_tests/CMakeLists.txt

This CMake code registers directories containing Ogre media resources (scripts and meshes) with RViz, making them discoverable at runtime. It also installs test meshes to a specified destination for use in testing scenarios.

```CMake
  # Adds shallow folders containing ogre_media such as meshes and scripts to Rviz
  # so that they can be found at runtime. Requires rviz_rendering.
  register_rviz_ogre_media_exports(
    DIRECTORIES
    "ogre_media_resources/scripts"
    "ogre_media_resources/meshes"
  )

  install(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/ogre_media_resources/test_meshes"
    DESTINATION "share/rviz_rendering_tests"
    USE_SOURCE_PERMISSIONS)
```

--------------------------------

### Set RPATH for Installation and Ament Package

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/CMakeLists.txt

Sets the `INSTALL_RPATH_USE_LINK_PATH` property for the RViz2 executable, which helps ensure that the runtime search path for shared libraries includes the paths where linked libraries are found during installation. Finally, `ament_package()` declares the project as an ament package, integrating it into the ROS2 build system.

```CMake
set_target_properties(${PROJECT_NAME} PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)

ament_package()
```

--------------------------------

### Configure Pose Display Page Object Library

Source: https://github.com/ros2/rviz/blob/rolling/rviz_default_plugins/CMakeLists.txt

This CMake snippet defines a static library for pose display page objects, which are helper components for Rviz visual tests. It ensures the library links against Qt widgets and the Rviz visual testing framework.

```CMake
add_library(pose_display_page_object STATIC test/rviz_default_plugins/page_objects/pose_display_page_object.cpp)
target_link_libraries(pose_display_page_object
  PRIVATE
    Qt${QT_VERSION_MAJOR}::Widgets
    rviz_visual_testing_framework::rviz_visual_testing_framework
)
```

--------------------------------

### RViz Orbit View Controller Controls

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

Documentation for the default Orbit view controller in RViz, which allows rotation around a focal point. This controller is ideal for general 3D scene navigation.

```APIDOC
RViz Orbit View Controller:
  Description: The orbital camera rotates around a focal point, always looking at that point. The focal point is visualized as a small disc.
  Controls:
    - Left mouse button: Click and drag to rotate around the focal point.
    - Middle mouse button: Click and drag to move the focal point in the plane formed by the camera's up and right vectors. Distance moved depends on the focal point.
    - Right mouse button: Click and drag to zoom in/out of the focal point. Dragging up zooms in, down zooms out.
    - Scrollwheel: Zoom in/out of the focal point.
    - 'f' key: Move the focal point to whatever 3D object is currently under the mouse.
```

--------------------------------

### Using rviz_default_plugins::transformation::TransformerGuard

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

The `TransformerGuard` class ensures that a display only works with a specific transformation plugin. It disables the display and shows an error if the currently active transformer is of a different type. This is crucial for displays with strict transformation framework dependencies.

```APIDOC
rviz_default_plugins::transformation::TransformerGuard<T>:
  - Purpose: Ensures a display works only with a specific transformation plugin (templated on the plugin type T).
  - Constructor:
    `TransformerGuard(rviz_common::Display* owner, const std::string& transformer_name)`
      - `owner`: Raw pointer to the display that owns this guard.
      - `transformer_name`: Name of the transformer the display is supposed to work with (for error status).
      - Usage: Ideally initialized in the display's constructor.
  - Method:
    `initialize(rviz_common::DisplayContext * context)`
      - `context`: The display's `context_` member.
      - Usage: Call inside the display's `onInitialize()` method.
      - Effect: Disables the display and shows an error if the current transformer plugin is of the wrong type.
  - Method:
    `checkTransformer()`
      - Returns: `true` if the currently used transformer is of the allowed type, `false` otherwise.
      - Usage: Can be used by the display to behave differently based on the active transformation plugin.
```

--------------------------------

### Exporting Plugin Description File in CMake

Source: https://github.com/ros2/rviz/blob/rolling/docs/plugin_development.md

The `pluginlib_export_plugin_description_file` CMake function is used to make the plugin's XML description file discoverable by `rviz_common` at runtime. This ensures that `pluginlib` can correctly parse the plugin's metadata and load it into RViz.

```CMake
pluginlib_export_plugin_description_file(rviz_common plugins_description.xml)
```

--------------------------------

### Declaring Ament Package Configuration in CMake

Source: https://github.com/ros2/rviz/blob/rolling/rviz_rendering/CMakeLists.txt

The `ament_package` command is used in ROS 2 to declare a package and specify its configuration extras. In this case, it includes `rviz_rendering-extras.cmake`, which might contain additional build or install rules specific to the `rviz_rendering` component.

```CMake
ament_package(
  CONFIG_EXTRAS "rviz_rendering-extras.cmake"
)
```

--------------------------------

### Configure Pose With Covariance Display Visual Test

Source: https://github.com/ros2/rviz/blob/rolling/rviz_default_plugins/CMakeLists.txt

This snippet sets up a GTest for the Pose With Covariance display. It includes the test source and page object files, defines a timeout, and links necessary libraries such as the visual testing framework, Qt, and ROS2 message types including tf2_ros.

```CMake
ament_add_gtest(pose_with_covariance_display_visual_test
  test/rviz_default_plugins/displays/pose_covariance/pose_with_covariance_display_visual_test.cpp
  test/rviz_default_plugins/page_objects/pose_with_covariance_display_page_object.cpp
  ${SKIP_VISUAL_TESTS}
  TIMEOUT 180)
if(TARGET pose_with_covariance_display_visual_test)
  target_include_directories(pose_with_covariance_display_visual_test PRIVATE test)
  target_link_libraries(pose_with_covariance_display_visual_test
    rviz_visual_testing_framework::rviz_visual_testing_framework
    Qt${QT_VERSION_MAJOR}::Widgets
    ${geometry_msgs_TARGETS}
    rclcpp::rclcpp
    ${std_msgs_TARGETS}
    tf2_ros::tf2_ros
  )
endif()
```

--------------------------------

### RViz XYOrbit View Controller Controls

Source: https://github.com/ros2/rviz/blob/rolling/rviz2/doc/index.rst

Documentation for the XYOrbit view controller in RViz, a variant of the Orbit controller where the focal point is constrained to move only in the XY plane. The focal point is also kept lower in the window and is cyan colored.

```APIDOC
RViz XYOrbit View Controller:
  Description: Similar to Orbit, but the focal point is constrained to move only in the XY plane. The focal point is kept lower in the window and is cyan colored.
  Controls:
    - Left mouse button: Click and drag to rotate around the focal point.
    - Middle mouse button: Click and drag to move the focal point in the XY plane. Distance moved depends on the focal point.
    - Right mouse button: Click and drag to zoom in/out of the focal point. Dragging up zooms in, down zooms out.
    - Scrollwheel: Zoom in/out of the focal point.
    - 'f' key: Move the focal point to whatever 3D object is currently under the mouse.
```