rviz_plugin_tutorials: Added sphinx-based tutorial documentation write-up.

Author: hershwg

rviz_plugin_tutorials/CMakeLists.txt

@@ -1,33 +1,29 @@
+## BEGIN_TUTORIAL
+## This CMakeLists.txt file for rviz_plugin_tutorials builds both the TeleopPanel tutorial and the ImuDisplay tutorial.
+##
+## First start with some standard ROS stuff.
 cmake_minimum_required(VERSION 2.4.6)
 include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)
-
-# Set the build type.  Options are:
-#  Coverage       : w/ debug symbols, w/o optimization, w/ code-coverage
-#  Debug          : w/ debug symbols, w/o optimization
-#  Release        : w/o debug symbols, w/ optimization
-#  RelWithDebInfo : w/ debug symbols, w/ optimization
-#  MinSizeRel     : w/o debug symbols, w/ optimization, stripped binaries
 set(ROS_BUILD_TYPE RelWithDebInfo)
-
 rosbuild_init()
 
-# This plugin includes Qt widgets, so we must include Qt like so:
+## This plugin includes Qt widgets, so we must include Qt like so:
 find_package(Qt4 COMPONENTS QtCore QtGui REQUIRED)
 include(${QT_USE_FILE})
 
-# I prefer the Qt signals and slots to avoid defining "emit", "slots",
-# etc because they can conflict with boost signals.
+## I prefer the Qt signals and slots to avoid defining "emit", "slots",
+## etc because they can conflict with boost signals, so define QT_NO_KEYWORDS here.
 add_definitions(-DQT_NO_KEYWORDS)
 
-# Here we specify which header files need to be run through "moc",
-# Qt's meta-object compiler.
+## Here we specify which header files need to be run through "moc",
+## Qt's meta-object compiler.
 qt4_wrap_cpp(MOC_FILES
   src/drive_widget.h
   src/teleop_panel.h
 )
 
-# Here we specify the list of source files, including the output of
-# the previous command which is stored in ${MOC_FILES}.
+## Here we specify the list of source files, including the output of
+## the previous command which is stored in ``${MOC_FILES}``.
 set(SOURCE_FILES
   src/drive_widget.cpp
   src/teleop_panel.cpp 
@@ -36,15 +32,23 @@ set(SOURCE_FILES
   ${MOC_FILES}
 )
 
-#set the default path for built executables to the "bin" directory
-set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
-
-#set the default path for built libraries to the "lib" directory
+## Set the default path for built libraries to the "lib" directory
 set(LIBRARY_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/lib)
 
-# An rviz plugin is just a shared library, so here we declare the
-# library and specify the list of source files we collected above.
+## An rviz plugin is just a shared library, so here we declare the
+## library to be called ``${PROJECT_NAME}`` (which is
+## "rviz_plugin_tutorials", or whatever your version of this project
+## is called) and specify the list of source files we collected above
+## in ``${SOURCE_FILES}``.
 rosbuild_add_library(${PROJECT_NAME} ${SOURCE_FILES})
 
-# Link the library
+## Link the library with whatever Qt libraries have been defined by
+## the ``find_package(Qt4 ...)`` line above.
+##
+## Although this puts "rviz_plugin_tutorials" (or whatever you have
+## called the project) as the name of the library, cmake knows it is a
+## library and names the actual file something like
+## "librviz_plugin_tutorials.so", or whatever is appropriate for your
+## particular OS.
 target_link_libraries(${PROJECT_NAME} ${QT_LIBRARIES})
+## END_TUTORIAL

rviz_plugin_tutorials/manifest.xml

@@ -10,6 +10,7 @@
   <url>http://ros.org/wiki/rviz_plugin_tutorials</url>
   <depend package="rviz"/>
   <export>
-      <rviz plugin="${prefix}/plugin_description.xml"/>
+      <rosdoc config="${prefix}/rosdoc.yaml"/>
+      <rviz plugin="${prefix}/foo/plugin_description.xml"/>
   </export>
 </package>

rviz_plugin_tutorials/rosdoc.yaml

@@ -0,0 +1,2 @@
+- builder: sphinx
+  sphinx_root_dir: src/doc

rviz_plugin_tutorials/src/doc/conf.py

@@ -0,0 +1,25 @@
+import sys, os
+
+sys.path += [ os.path.abspath( '.' )]
+
+extensions = [ 'sphinx.ext.extlinks',
+               'rviz_plugin_tutorials.tutorialformatter' ]
+
+# The master toctree document.
+master_doc = 'index'
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+project = u'rviz_plugin_tutorials'
+
+copyright = u'2012,  Willow Garage, Inc'
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+extlinks = {'svndir': ('https://code.ros.org/svn/ros-pkg/stacks/visualization_tutorials/branches/visualization_tutorials-0.6/rviz_plugin_tutorials/%s', '')}

rviz_plugin_tutorials/src/doc/display_plugin_tutorial.rst

@@ -0,0 +1,231 @@
+ImuDisplay
+==========
+
+The RViz plugin API and library API are preliminary in Fuerte. We
+welcome feedback about how to make them more powerful and easier to
+program with. We expect the APIs to change (possibly significantly)
+between Fuerte and Groovy.
+
+Overview
+--------
+
+This tutorial shows how to write a simple Display plugin for RViz.
+
+RViz does not currently have a way to display sensor_msgs/Imu messages
+directly. The code in this tutorial implements a subclass of
+rviz::Display to do so.
+
+The source code for this tutorial is in the rviz_plugin_tutorials
+package. You can check out the source directly or (if you use Ubuntu)
+you can just apt-get install the pre-compiled Debian package like so::
+
+    sudo apt-get install ros-fuerte-visualization-tutorials
+
+Here is what the new ImuDisplay output looks like, showing a sequence of
+sensor_msgs/Imu messages from the test script:
+
+.. image:: imu_arrows.png
+
+The Plugin Code
+---------------
+
+The code for ImuDisplay is in these files: 
+:svndir:`src/imu_display.h`,
+:svndir:`src/imu_display.cpp`,
+:svndir:`src/imu_visual.h`, and
+:svndir:`src/imu_visual.cpp`.
+
+imu_display.h
+^^^^^^^^^^^^^
+
+The full text of imu_display.h is here: :svndir:`src/imu_display.h`
+
+.. tutorial-formatter:: ../imu_display.h
+
+imu_display.cpp
+^^^^^^^^^^^^^^^
+
+The full text of imu_display.cpp is here: :svndir:`src/imu_display.cpp`
+
+.. tutorial-formatter:: ../imu_display.cpp
+
+imu_visual.h
+^^^^^^^^^^^^
+
+The full text of imu_visual.h is here: :svndir:`src/imu_visual.h`
+
+.. tutorial-formatter:: ../imu_visual.h
+
+imu_visual.cpp
+^^^^^^^^^^^^^^
+
+The full text of imu_visual.cpp is here: :svndir:`src/imu_visual.cpp`
+
+.. tutorial-formatter:: ../imu_visual.cpp
+
+Building the Plugin
+-------------------
+
+.. tutorial-formatter:: ../../CMakeLists.txt
+
+To build the plugin, just do the normal "rosmake" thing::
+
+    rosmake rviz_plugin_tutorials
+
+Exporting the Plugin
+--------------------
+
+For the plugin to be found and understood by other ROS packages (in
+this case, rviz), it needs a "plugin_description.xml" file.  This file
+can be named anything you like, as it is specified in the plugin
+package's "manifest.xml" file like so:
+
+.. code-block:: xml
+
+  <export>
+      <rviz plugin="${prefix}/plugin_description.xml"/>
+  </export>
+
+The contents of plugin_description.xml then look like this:
+
+.. code-block:: xml
+
+  <library path="lib/librviz_plugin_tutorials">
+    <class name="rviz_plugin_tutorials/Teleop"
+           type="rviz_plugin_tutorials::TeleopPanel"
+           base_class_type="rviz::Panel">
+      <description>
+        A panel widget allowing simple diff-drive style robot base control.
+      </description>
+    </class>
+    <class name="rviz_plugin_tutorials/Imu"
+           type="rviz_plugin_tutorials::ImuDisplay"
+           base_class_type="rviz::Display">
+      <description>
+        Displays direction and scale of accelerations from sensor_msgs/Imu messages.
+      </description>
+    </class>
+  </library>
+
+The first line says that the compiled library lives in
+lib/librviz_plugin_tutorials (the ".so" ending is appended by
+pluginlib according to the OS).  This path is relative to the top
+directory of the package:
+
+.. code-block:: xml
+
+  <library path="lib/librviz_plugin_tutorials">
+
+The next section is a ``class`` entry describing the TeleopPanel:
+
+.. code-block:: xml
+
+    <class name="rviz_plugin_tutorials/Teleop"
+           type="rviz_plugin_tutorials::TeleopPanel"
+           base_class_type="rviz::Panel">
+      <description>
+        A panel widget allowing simple diff-drive style robot base control.
+      </description>
+    </class>
+
+This specifies the name, type, base class, and description of the
+class.  The *name* field must be a combination of the first two
+strings given to the ``PLUGINLIB_DECLARE_CLASS()`` macro in the source
+file.  It must be the "package" name, a "/" slash, then the "display
+name" for the class.
+
+The *type* entry must be the fully-qualified class name, including any
+namespace(s) it is inside.
+
+The *base_class_type* is either ``rviz::Panel`` for a panel class, or
+``rviz::Display`` for a display class.
+
+The *description* subsection is a simple text description of the
+class, which is shown in the class-chooser dialog and in the Displays
+panel help area.  This section can contain HTML, including hyperlinks,
+but the markup must be escaped to avoid being interpreted as XML
+markup.  For example a link tag might look like: ``&lt;a
+href="my-web-page.html"&gt;``.
+
+Trying It Out
+-------------
+
+Once your RViz plugin is compiled and exported, simply run rviz normally::
+
+    rosrun rviz rviz
+
+and rviz will use pluginlib to find all the plugins exported to it.
+
+Add an ImuDisplay by clicking the "Add" button at the bottom of the
+"Displays" panel (or by typing Control-N), then scrolling down through
+the available displays until you see "Imu" under your plugin package
+name (here it is "rviz_plugin_tutorials").
+
+.. image:: imu_plugin.png
+
+If "Imu" is not in your list of Display Types, look through RViz's
+console output for error messages relating to plugin loading.  Some common
+problems are:
+
+- not having a plugin_description.xml file,
+- not exporting it in the manifest.xml file, or
+- not properly referencing the library file (like
+  librviz_plugin_tutorials.so) from plugin_description.xml.
+
+Once you've added the Imu display to RViz, you just need to set the
+topic name of the display to a source of sensor_msgs/Imu messages.
+
+If you don't happen to have an IMU or other source of sensor_msgs/Imu
+messages, you can test the plugin with a Python script like this:
+:svndir:`scripts/send_test_msgs.py`.
+
+The script publishes on the "/test_imu" topic, so enter that.
+
+The script publishes both Imu messages and a moving TF frame
+("/base_link" relative to "/map"), so make sure your "Fixed Frame" is
+set to "/map".
+
+Finally, adjust the "History Length" parameter of the Imu display to
+10 and you should see something like the picture at the top of this
+page.
+
+Note: If you use this to visualize messages from an *actual* IMU, the
+arrows are going to be huge compared to most robots:
+
+.. image:: real_imu.png
+
+(Note the PR2 robot at the base of the purple arrow.) This is because
+the Imu acceleration units are meters per second squared, and gravity
+is 9.8 m/s^2, and we haven't applied any scaling or gravity
+compensation to the acceleration vectors.
+
+Next Steps
+----------
+
+This ImuDisplay is not yet a terribly useful Display class.  Extensions to make it more useful might be:
+
+- Add a gravity-compensation option to the acceleration vector.
+- Visualize more of the data in the Imu messages.
+
+To add a gravity compensation option, you might take steps like these:
+
+- Add a new ``bool gravity_compensation_on_`` property to ImuDisplay to store whether the option is on or off.
+- Add getter and setter functions for it.
+- Add a new ``rviz::BoolPropertyWPtr`` to ImuDisplay to show the property in the property editor.
+- Add a new ``setGravityCompensation(bool)`` function to
+  ImuVisual to tell the visual whether to subtract out gravity or not.
+- Compute the direction of gravity relative to the Imu frame
+  orientation (as set in ImuVisual::setFrameOrientation()) and
+  subtract it from the acceleration vector each time in
+  ImuVisual::setMessage().
+
+Since ImuVisual takes complete Imu messages as input, adding
+visualizations of more of the Imu data only needs modifications to
+ImuVisual.  Imu data displays might look like:
+
+- orientation: An rviz::Axes object at the Imu reference frame, turned to show the orientation.
+- angular_velocity: Maybe a line to show the axis of rotation and a 3D arrow curving around it to show the speed of rotation?
+- orientation_covariance: Maybe this is an ellipse at the end of each of the X, Y, and Z axes showing the orientation?
+- linear_acceleration_covariance: Maybe this is an ellipsoid at the end of the acceleration arrow?
+
+As all this might be visually cluttered, it may make sense to include boolean options to enable or disable some of them.

rviz_plugin_tutorials/src/doc/imu_arrows.png

@@ -0,0 +1,18 @@
+RViz Plugin Tutorials
+=====================
+
+The RViz plugin API and library API are preliminary in Fuerte. We
+welcome feedback about how to make them more powerful and easier to
+program with. We expect the APIs to change (possibly significantly)
+between Fuerte and Groovy.
+
+The rviz_plugin_tutorials package builds a plugin library for rviz
+containing two main classes: ImuDisplay and TeleopPanel.
+
+- :doc:`display_plugin_tutorial` is an example of an rviz::Display
+  subclass allowing rviz to show data from sensor_msgs::Imu messages.
+
+- :doc:`panel_plugin_tutorial` is an example of an rviz::Panel
+  subclass which shows a simple control input for sending velocities
+  to a mobile base.
+

rviz_plugin_tutorials/src/doc/imu_plugin.png

@@ -0,0 +1,12 @@
+TeleopPanel
+===========
+
+This is an haitch file:
+
+.. tutorial-formatter:: ../imu_display.h
+
+This is a cpp file:
+
+.. tutorial-formatter:: ../imu_display.cpp
+
+This is the end.