Make transformation framework pluggable

README.md

@@ -58,8 +58,24 @@ In case you wished to see those features in RViz for ROS 2, feel free to add a p
 Make sure to read the developer guide below and the migration guide.
 
 ### New features
+#### Pluggable transformation library
 
-None, yet.
+In RViz for ROS 1 the frames transformation library used is tf2 (detailed information about it can be found [here](http://wiki.ros.org/tf2)).
+In RViz for ROS 2 the frames transformation library is now pluggable, meaning that different transformation library plugins can be loaded and changed dynamically in the gui.
+Developers can create and use their own plugins to provide custom transformation behavior.
+
+Two plugins are bundled with RViz:
+- a plugin for tf2 (`TFFrameTransformer`, in `rviz_default_plugins`), which provides the standard tf2 functionality and which is used as a default
+- a trivial plugin (`IdentityFrameTransformer`, in `rviz_common`), which always performs identity transforms.
+  This plugin is used by default if the tf2 plugin is not available and no other valid plugin is specified.
+
+As anticipated, in order for the user to choose the plugin to use, RViz provides a dedicated panel: the `Transformation` panel.
+
+Note: Not all transformation plugins are necessarily compatible with all RViz displays (e.g. some of the default displays, like the TF display, can only work with tf2).
+In order to take this possibility into account, the `TransformerGuard` class is provided.
+Adding it to a display ensures that the display will be disabled and won't function in case the wrong transformer is used.
+
+More detailed information on how to write a transformation plugin and on how to handle transformation specific displays can be found in the [plugin development guide](docs/plugin_development.md).
 
 ## Developer Guide
 
@@ -72,7 +88,7 @@ https://github.com/ros2/ros2/wiki/Installation
 
 #### Building RViz in a separate workspace
 
-When developing for RViz, it can be beneficial to build it in a separate workspace. 
+When developing for RViz, it can be beneficial to build it in a separate workspace.
 
 **Note:** When building the current ros2 branch from source, the latest ROS 2 release for all dependencies might not be sufficient: it could be necessary to build the ROS 2 master branch.
 Make sure to have a source build of ROS 2 available (see installation procedure above).
@@ -122,6 +138,7 @@ Plugins can extend RViz at different extension points:
 - Displays
 - Panels
 - Tools
+- Frames transformation library
 - View Controllers
 
 More information on writing plugins can be found in the [plugin development guide](docs/plugin_development.md).

docs/plugin_development.md

@@ -9,21 +9,22 @@ This is intended as a guide for people wishing to develop custom plugins.
 
 Plugins can extend RViz at different extension points:
 
-| plugin type     | base type                     |
-| --------------- | ----------------------------- |
-| Display         | `rviz_common::Display`        |
-| Panel           | `rviz_common::Panel`          |
-| Tool            | `rviz_common::Tool`           |
-| View Controller | `rviz_common::ViewController` |
+| plugin type                   | base type                                       |
+| ----------------------------- | ----------------------------------------------- |
+| Display                       | `rviz_common::Display`                          |
+| Panel                         | `rviz_common::Panel`                            |
+| Tool                          | `rviz_common::Tool`                             |
+| Frames transformation library | `rviz_common::transformation::FrameTransformer` |
+| View Controller               | `rviz_common::ViewController`                   |
 
 Every plugin must be of the corresponding base type in order to be recognized by RViz.
 Refer to the documentation of the relevant base class for a detailed API description.
 
 ### Plugin Basics
 
 * In order to write your own plugin, set up a regular ROS 2 workspace (see the [official documentation]("https://github.com/ros2/ros2/wiki/Colcon-Tutorial") for further help).
-* You will need to link your program against `rviz_common` and probably also against `rviz_rendering` and `rviz_default_plugins`. 
-* To let the plugin loader find your plugin, you will need to invoke the `PLUGINLIB_EXPORT_CLASS` macro. 
+* You will need to link your program against `rviz_common` and probably also against `rviz_rendering` and `rviz_default_plugins`.
+* To let the plugin loader find your plugin, you will need to invoke the `PLUGINLIB_EXPORT_CLASS` macro.
   For instance, if your plugin is called "myplugin::Plugin" with base class `rviz_common::Dispay`, you will need to include the following into your `.cpp` file:
 ```
     #include <pluginlib/class_list_macros.hpp>
@@ -36,7 +37,7 @@ target_compile_definitions(rviz_default_plugins PUBLIC "PLUGINLIB__DISABLE_BOOST
 # Causes the visibility macros to use dllexport rather than dllimport (for Windows, when your plugin should be used as library)
 target_compile_definitions(rviz_default_plugins PRIVATE "RVIZ_DEFAULT_PLUGINS_BUILDING_LIBRARY")
 ```
-* You need to write a `plugin_description.xml` file which contains the information necessary for the pluginlib to load your plugin at runtime. 
+* You need to write a `plugin_description.xml` file which contains the information necessary for the pluginlib to load your plugin at runtime.
   See `rviz_default_plugins/plugins_description.xml` for an example (the syntax is the same as for the old RViz)
 * Export the plugin description file via
 ```
@@ -50,15 +51,15 @@ This should make sure that your plugins are found at runtime
 
 #### Writing a display without ros subscription
 
-When writing a display without subscription to ros, derive from `rviz_common::Display`. 
+When writing a display without subscription to ros, derive from `rviz_common::Display`.
 
 * The Display class provides an `Ogre::SceneNode`, which can be used to add visual objects.
 * It provides convenience methods to set and delete Status messages
 * When you need any Ogre or SceneNode setup, override the `onInitilize()` method.
 
 #### Writing a display with subscription
 
-When writing a display for a topic type, derive from `rviz_common::RosTopicDisplay<MessageType>`. 
+When writing a display for a topic type, derive from `rviz_common::RosTopicDisplay<MessageType>`.
 The RosTopicDisplay is templated on the message type of this display:
 
 * RosTopicDisplay derives from Display and thereby contains all of the functionality described in the previous section
@@ -68,14 +69,35 @@ The RosTopicDisplay is templated on the message type of this display:
 
 #### Providing Ogre media files
 
-It is possible to add your own meshes, scripts, etc. to RViz. 
+It is possible to add your own meshes, scripts, etc. to RViz.
 To make them available at runtime, use the cmake macro `register_rviz_ogre_media_exports` defined in `rviz_rendering`
 For instance, if you want to register a folder `test_folder/scripts` which resides in your project's source folder, write
 ```
 register_rviz_ogre_media_exports(DIRECTORIES "test_folder/scripts")
 ```
 *Note:* If you want to export folder hierarchies, each folder needs to be exported separately. Folders within exported folders are not automatically available.
 
+#### Writing a display which can only work with one transformation plugin
+
+Some of the default displays (e.g. TF display or LaserScan display) can only work with tf2 as transformation framework.
+Similarly, as a developer, you may have written your own transformation plugin which cannot work with every display, or your own display which cannot work with every transformation plugin.
+The class `rviz_default_plugins::transformation::TransformerGuard` helps you to handle these possibilities.
+
+As explained below, every transformation plugin implements the base class `rviz_common::transformation::FrameTransformer`.
+The `TransformerGuard` class is templated on the type of this implementation and will make sure that the display by which it is owned will be disabled if the transformer currently in use is of a different type.
+
+When writing a display that is supposed to be working only with a specific transformation plugin, you can add a templated instance of `TransformerGuard` as a display member.
+The constructor of this class takes two argument: a raw pointer to the display that owns it, and the name of the transformer it is supposed to work with (needed to correctly set the error status).
+Ideally the `TransformerGuard` object is initialized in the constructor of the display.
+
+In order to make the `TransformerGuard` object work correctly, you need to call the method `TransformerGuard::initialize(rviz_common::DisplayContext * context)` inside the display `onInitialize()` method, passing as parameter the `context_` member of the display.
+Doing this will make sure that every time the current transformer plugin is of the wrong type, the display will be disabled and an appropriate error message will be shown in the display status.
+
+In addition to this, the `TransformerGuard` class also provides the `checkTransformer()` method, which returns `true` if the currently usd transformer is of the allowed type, and `false` otherwise.
+This method can be used by the display every time you want it to behave differently according to what kind of transformation plugin is used at the moment.
+
+For a concrete example of how all this is done, you can have a look, for example, at the TF or the LaserScan display, in `rviz_default_plugins` which, as said, only work with tf2.
+
 ### Writing a panel plugin
 
 To write a custom panel, derive from `rviz_common::Panel`.
@@ -89,10 +111,14 @@ To write a custom panel, derive from `rviz_common::Panel`.
 
 ### Writing a view controller plugin
 
-* In order to write a custom view controller which should be independent of tf frames, derive from `rviz_common::ViewController` 
+* In order to write a custom view controller which should be independent of tf frames, derive from `rviz_common::ViewController`
 * If your view controller should be able to track tf frames in a scene, derive from `rviz_common::FramePositionTrackingViewController`, which already contains convenience functionality for tracking target frames
 * If your custom view controller orbits a focal point, it might also be beneficial to derive from `rviz_default_plugins::OrbitViewController`
 
+### Writing a transformation library plugin
+
+- To write a transformer plugin, you must implement the `rviz_common::transformation::FrameTransformer` class (refer to the API documentation contained in the header file).
+- If for your plugin you also need extra functionality, or you want to offer direct access to some parts of the library itself, you can also implement a subclass of `rviz_common::transformation::TransformerLibraryConnector` (see, for example, `rviz_default_plugins::transformation::TFWrapper`).
 
 ## Overview of RViz API
 
@@ -101,7 +127,7 @@ To write a custom panel, derive from `rviz_common::Panel`.
 The `rviz_rendering` package is supposed to contain all functionality referring to rendering:
 
 * Visuals and objects to be added to the scene graph such as arrows, shapes or text objects in the subfolder `objects` (many of those objects were ported from the folder `ogre_helpers`)
-* The render window, including functions exposing some of its internals (RenderWindowOgreAdapter). 
+* The render window, including functions exposing some of its internals (RenderWindowOgreAdapter).
   If possible, refrain from using the RenderWindowOgreAdapter, as it might be deprecated and deleted in the future
 * Convenience functions to work with materials (`material_manager.hpp`) or other ogre related functionality (e.g. ray tracing in `viewport_projection_finder.hpp`)
 * Convenience classes for testing, allowing to set up a working ogre environment and helpers for scene graph introspection
@@ -114,20 +140,20 @@ The `rviz_common` package contains the bulk of RViz useful for doing plugin deve
 * Main entry points for plugin development - base classes for panels, view controllers, displays and tools
 * Convenience classes to work with properties in the various views (such as the display panel) located in `rviz_common/properties`
 * Main classes for selectable types, the SelectionHandlers (located in `rviz_common/interaction`)
-* Access points to ROS 2. 
-  Currently, RViz uses only one node, which can be accessed via `ros_integration`. 
+* Access points to ROS 2.
+  Currently, RViz uses only one node, which can be accessed via `ros_integration`.
   In the future, further changes may be necessary to fully abstract ROS 2 access into `ros_integration`
 
 ### rviz_default_plugins
 
-The `rviz_default_plugins` contains all plugins (view controllers, tools, displays and in the future, panels) shipped with RViz (most of them ported from the `default_plugins` folder of RViz). 
+The `rviz_default_plugins` contains all plugins (view controllers, tools, displays and in the future, panels) shipped with RViz (most of them ported from the `default_plugins` folder of RViz).
 
 * When developing simple plugins it is not necessary to use anything in this package.
 * When developing more complex plugins similar to existing plugins it might be beneficial to use or even derive from classes contained in this package to simplify your development.
 
 ### rviz_visual_testing_framework
 
-The `rviz_visual_testing_framework` contains the backbone to writing visual tests for plugins. 
+The `rviz_visual_testing_framework` contains the backbone to writing visual tests for plugins.
 It will only ever be necessary to use this package as a test dependency if you want to write automated screenshot tests.
 Please see the documentation in the package for further help.
 

rviz2/package.xml

@@ -17,12 +17,12 @@
   <url type="bugtracker">https://github.com/ros2/rviz/issues</url>
 
   <buildtool_depend>ament_cmake</buildtool_depend>
-  
+
   <build_depend>qtbase5-dev</build_depend>
 
   <!-- this ensures some basic plugins are available when installing just rviz2 -->
   <exec_depend>rviz_default_plugins</exec_depend>
-  
+
   <depend>rviz_common</depend>
   <depend>rviz_ogre_vendor</depend>
 

rviz_common/CMakeLists.txt

@@ -88,6 +88,7 @@ set(rviz_common_headers_to_moc
   src/rviz_common/displays_panel.hpp
   src/rviz_common/failed_panel.hpp
   src/rviz_common/frame_manager.hpp
+  include/rviz_common/transformation/frame_transformer.hpp
   include/rviz_common/frame_manager_iface.hpp
   src/rviz_common/loading_dialog.hpp
   src/rviz_common/new_object_dialog.hpp
@@ -104,6 +105,8 @@ set(rviz_common_headers_to_moc
   include/rviz_common/properties/editable_enum_property.hpp
   include/rviz_common/properties/float_edit.hpp
   include/rviz_common/properties/float_property.hpp
+  include/rviz_common/properties/grouped_checkbox_property.hpp
+  include/rviz_common/properties/grouped_checkbox_property_group.hpp
   include/rviz_common/properties/int_property.hpp
   include/rviz_common/properties/line_edit_with_button.hpp
   include/rviz_common/properties/property.hpp
@@ -125,9 +128,13 @@ set(rviz_common_headers_to_moc
   include/rviz_common/interaction/selection_renderer.hpp
   src/rviz_common/splash_screen.hpp
   # src/rviz_common/time_panel.hpp
+  src/rviz_common/transformation/identity_frame_transformer.hpp
+  include/rviz_common/transformation/structs.hpp
   include/rviz_common/tool.hpp
   src/rviz_common/tool_manager.hpp
   src/rviz_common/tool_properties_panel.hpp
+  include/rviz_common/transformation/transformation_manager.hpp
+  src/rviz_common/transformation_panel.hpp
   include/rviz_common/view_controller.hpp
   include/rviz_common/view_manager.hpp
   src/rviz_common/views_panel.hpp
@@ -176,6 +183,8 @@ set(rviz_common_source_files
   src/rviz_common/properties/file_picker_property.cpp
   src/rviz_common/properties/float_edit.cpp
   src/rviz_common/properties/float_property.cpp
+  src/rviz_common/properties/grouped_checkbox_property.cpp
+  src/rviz_common/properties/grouped_checkbox_property_group.cpp
   src/rviz_common/properties/int_property.cpp
   src/rviz_common/properties/line_edit_with_button.cpp
   src/rviz_common/properties/parse_color.cpp
@@ -206,9 +215,14 @@ set(rviz_common_source_files
   src/rviz_common/interaction/view_picker.cpp
   src/rviz_common/splash_screen.cpp
   # src/rviz_common/time_panel.cpp
+  src/rviz_common/transformation/identity_frame_transformer.cpp
+  src/rviz_common/transformation/structs.cpp
+  src/rviz_common/transformation/ros_helpers/ros_conversion_helpers.cpp
   src/rviz_common/tool_manager.cpp
   src/rviz_common/tool_properties_panel.cpp
   src/rviz_common/tool.cpp
+  src/rviz_common/transformation_panel.cpp
+  src/rviz_common/transformation/transformation_manager.cpp
   src/rviz_common/uniform_string_stream.cpp
   src/rviz_common/view_controller.cpp
   src/rviz_common/view_manager.cpp
@@ -326,8 +340,21 @@ if(BUILD_TESTING)
   ament_lint_cmake()
   ament_uncrustify()
 
+  ament_add_gmock(frame_manager_test
+    test/frame_manager_test.cpp
+    src/rviz_common/frame_manager.cpp
+  )
+  if(TARGET frame_manager_test)
+    target_link_libraries(frame_manager_test
+      rviz_common
+      rviz_ogre_vendor::OgreMain
+      rviz_ogre_vendor::OgreOverlay
+    )
+  endif()
+
   ament_add_gtest(rviz_common_config_test
-    test/config_test.cpp)
+    test/config_test.cpp
+  )
   if(TARGET rviz_common_config_test)
     target_link_libraries(rviz_common_config_test
       rviz_common
@@ -337,7 +364,8 @@ if(BUILD_TESTING)
   endif()
 
   ament_add_gtest(rviz_common_uniform_string_stream_test
-    test/uniform_string_stream_test.cpp)
+    test/uniform_string_stream_test.cpp
+  )
   if(TARGET rviz_common_uniform_string_stream_test)
     target_link_libraries(rviz_common_uniform_string_stream_test
       rviz_common
@@ -348,23 +376,38 @@ if(BUILD_TESTING)
 
   ament_add_gtest(rviz_common_property_test
     test/property_test.cpp
-    test/mock_property_change_receiver.cpp)
+    test/mock_property_change_receiver.cpp
+  )
   if(TARGET rviz_common_property_test)
     target_link_libraries(rviz_common_property_test rviz_common)
   endif()
 
-  ament_add_gmock(rviz_common_visualizer_app_test
-    test/visualizer_app_test.cpp)
+  ament_add_gmock(rviz_common_visualizer_app_test test/visualizer_app_test.cpp)
   if(TARGET rviz_common_visualizer_app_test)
     target_link_libraries(rviz_common_visualizer_app_test rviz_common)
   endif()
 
   ament_add_gmock(rviz_common_ros_node_abstraction_test
-    test/ros_node_abstraction_test.cpp)
+    test/ros_node_abstraction_test.cpp
+  )
   if(TARGET rviz_common_ros_node_abstraction_test)
     target_link_libraries(rviz_common_ros_node_abstraction_test rviz_common)
   endif()
 
+  ament_add_gmock(identity_transformer_test
+    test/transformation/identity_frame_transformer_test.cpp
+  )
+  if(TARGET identity_transformer_test)
+    target_link_libraries(identity_transformer_test rviz_common)
+  endif()
+
+  ament_add_gmock(ros_conversion_helpers_test
+    test/transformation/ros_conversion_helpers_test.cpp
+  )
+  if(TARGET ros_conversion_helpers_test)
+    target_link_libraries(ros_conversion_helpers_test rviz_common)
+  endif()
+
   ament_add_gmock(selection_manager_test
     test/interaction/selection_manager_test.cpp
     test/interaction/mock_selection_renderer.hpp
@@ -375,7 +418,8 @@ if(BUILD_TESTING)
     target_link_libraries(selection_manager_test
       rviz_common
       rviz_ogre_vendor::OgreMain
-      rviz_ogre_vendor::OgreOverlay)
+      rviz_ogre_vendor::OgreOverlay
+    )
   endif()
 
   ament_add_gmock(selection_handler_test
@@ -387,7 +431,8 @@ if(BUILD_TESTING)
     target_link_libraries(selection_handler_test
       rviz_common
       rviz_ogre_vendor::OgreMain
-      rviz_ogre_vendor::OgreOverlay)
+      rviz_ogre_vendor::OgreOverlay
+    )
   endif()
 
   ament_add_gtest(rviz_common_display_test
@@ -396,11 +441,8 @@ if(BUILD_TESTING)
     test/mock_display_group.cpp
     ${SKIP_DISPLAY_TESTS})
   if(TARGET rviz_common_display_test)
-    target_link_libraries(rviz_common_display_test
-      rviz_common
-      Qt5::Widgets)
-  ament_target_dependencies(rviz_common_display_test
-    rviz_yaml_cpp_vendor)
+    target_link_libraries(rviz_common_display_test rviz_common Qt5::Widgets)
+    ament_target_dependencies(rviz_common_display_test rviz_yaml_cpp_vendor)
   endif()
 endif()