Expanded and documented PlantFlagTool.

Also updated docs with github links and did a little updating for the latest version of the RViz API.

Author: hershwg

rviz_plugin_tutorials/CMakeLists.txt

@@ -19,18 +19,19 @@ add_definitions(-DQT_NO_KEYWORDS)
 ## Qt's meta-object compiler.
 qt4_wrap_cpp(MOC_FILES
   src/drive_widget.h
-  src/teleop_panel.h
   src/imu_display.h
+  src/plant_flag_tool.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}``.
 set(SOURCE_FILES
   src/drive_widget.cpp
-  src/teleop_panel.cpp 
-  src/plant_flag_tool.cpp
   src/imu_display.cpp
   src/imu_visual.cpp
+  src/plant_flag_tool.cpp
+  src/teleop_panel.cpp 
   ${MOC_FILES}
 )
 

rviz_plugin_tutorials/icons/classes/PlantFlag.png

@@ -40,6 +40,13 @@ The contents of plugin_description.xml then look like this:
         Displays direction and scale of accelerations from sensor_msgs/Imu messages.
       </description>
     </class>
+    <class name="rviz_plugin_tutorials/PlantFlag"
+           type="rviz_plugin_tutorials::PlantFlagTool"
+           base_class_type="rviz::Tool">
+      <description>
+        Tool for planting flags on the ground plane in rviz.
+      </description>
+    </class>
   </library>
 
 The first line says that the compiled library lives in
@@ -67,13 +74,14 @@ 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.
+name" for the class.  The "display name" is the name used for the
+class in the user interface.
 
 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 *base_class_type* is usually one of ``rviz::Panel``,
+``rviz::Display``, ``rviz::Tool``, or ``rviz::ViewController``.
 
 The *description* subsection is a simple text description of the
 class, which is shown in the class-chooser dialog and in the Displays

rviz_plugin_tutorials/src/doc/building_and_exporting.rst

@@ -22,4 +22,4 @@
 # 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', '')}
+extlinks = {'srcdir': ('https://github.com/ros-visualization/visualization_tutorials/tree/groovy-devel/rviz_plugin_tutorials/%s', '')}

rviz_plugin_tutorials/src/doc/conf.py

@@ -25,36 +25,36 @@ 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`.
+:srcdir:`src/imu_display.h`,
+:srcdir:`src/imu_display.cpp`,
+:srcdir:`src/imu_visual.h`, and
+:srcdir:`src/imu_visual.cpp`.
 
 imu_display.h
 ^^^^^^^^^^^^^
 
-The full text of imu_display.h is here: :svndir:`src/imu_display.h`
+The full text of imu_display.h is here: :srcdir:`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`
+The full text of imu_display.cpp is here: :srcdir:`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`
+The full text of imu_visual.h is here: :srcdir:`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`
+The full text of imu_visual.cpp is here: :srcdir:`src/imu_visual.cpp`
 
 .. tutorial-formatter:: ../imu_visual.cpp
 
@@ -90,7 +90,7 @@ 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`.
+:srcdir:`scripts/send_test_msgs.py`.
 
 The script publishes on the "/test_imu" topic, so enter that.
 
@@ -122,11 +122,7 @@ This ImuDisplay is not yet a terribly useful Display class.  Extensions to make
 
 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.
+- Add a new ``rviz::BoolProperty`` to ImuDisplay to store whether the option is on or off.
 - 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

rviz_plugin_tutorials/src/doc/display_plugin_tutorial.rst

@@ -10,3 +10,6 @@ containing two main classes: ImuDisplay and TeleopPanel.
 - :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.
+
+- :doc:`tool_plugin_tutorial` is an example of an rviz::Tool
+  subclass which lets you plant flag markers on the Z=0 plane.

rviz_plugin_tutorials/src/doc/flags.png

@@ -35,36 +35,36 @@ The Plugin Code
 ---------------
 
 The code for TeleopPanel is in these files: 
-:svndir:`src/teleop_panel.h`,
-:svndir:`src/teleop_panel.cpp`,
-:svndir:`src/drive_widget.h`, and
-:svndir:`src/drive_widget.cpp`.
+:srcdir:`src/teleop_panel.h`,
+:srcdir:`src/teleop_panel.cpp`,
+:srcdir:`src/drive_widget.h`, and
+:srcdir:`src/drive_widget.cpp`.
 
 teleop_panel.h
 ^^^^^^^^^^^^^^
 
-The full text of teleop_panel.h is here: :svndir:`src/teleop_panel.h`
+The full text of teleop_panel.h is here: :srcdir:`src/teleop_panel.h`
 
 .. tutorial-formatter:: ../teleop_panel.h
 
 teleop_panel.cpp
 ^^^^^^^^^^^^^^^^
 
-The full text of teleop_panel.cpp is here: :svndir:`src/teleop_panel.cpp`
+The full text of teleop_panel.cpp is here: :srcdir:`src/teleop_panel.cpp`
 
 .. tutorial-formatter:: ../teleop_panel.cpp
 
 drive_widget.h
 ^^^^^^^^^^^^^^
 
-The full text of drive_widget.h is here: :svndir:`src/drive_widget.h`
+The full text of drive_widget.h is here: :srcdir:`src/drive_widget.h`
 
 .. tutorial-formatter:: ../drive_widget.h
 
 drive_widget.cpp
 ^^^^^^^^^^^^^^^^
 
-The full text of drive_widget.cpp is here: :svndir:`src/drive_widget.cpp`
+The full text of drive_widget.cpp is here: :srcdir:`src/drive_widget.cpp`
 
 .. tutorial-formatter:: ../drive_widget.cpp
 

rviz_plugin_tutorials/src/doc/index.rst

@@ -0,0 +1,88 @@
+PlantFlagTool
+=============
+
+Overview
+--------
+
+This tutorial shows how to write a new tool for RViz.
+
+In RViz, a tool is a class that determines how mouse events interact
+with the visualizer.  In this example we describe PlantFlagTool which
+lets you place "flag" markers in the 3D scene.
+
+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 an example of what the new PlantFlagTool can do:
+
+.. image:: flags.png
+
+The Plugin Code
+---------------
+
+The code for PlantFlagTool is in these files: 
+:srcdir:`src/plant_flag_tool.h`, and
+:srcdir:`src/plant_flag_tool.cpp`.
+
+plant_flag_tool.h
+^^^^^^^^^^^^^^^^^
+
+The full text of plant_flag_tool.h is here: :srcdir:`src/plant_flag_tool.h`
+
+.. tutorial-formatter:: ../plant_flag_tool.h
+
+plant_flag_tool.cpp
+^^^^^^^^^^^^^^^^^^^
+
+The full text of plant_flag_tool.cpp is here: :srcdir:`src/plant_flag_tool.cpp`
+
+.. tutorial-formatter:: ../plant_flag_tool.cpp
+
+.. include:: building_and_exporting.rst
+
+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 a PlantFlag tool by clicking on the "+" button in the toolbar and
+selecting "PlantFlag" from the list under your plugin package name
+(here it is "rviz_plugin_tutorials").
+
+Once "PlantFlag" is in your toolbar, click it or press "l" (the
+shortcut key) to start planting flags.  Open the "Tool Properties"
+panel to see the positions of the flags you have planted.
+
+Currently the only way to remove the flags is to delete the PlantFlag
+tool, which you do by pressing the "-" (minus sign) button in the
+toolbar and selecting "PlantFlag".
+
+Next Steps
+----------
+
+PlantFlag as shown here is not terribly useful yet.  Some extensions to make it more useful might be:
+
+- Add the ability to delete, re-position, and re-name existing flags.
+- Publish ROS messages with the names and locations of the flags.
+
+To modify existing flags, you might:
+
+- Change processMouseEvent() to notice when the mouse is pointing near an existing flag.
+- When it is:
+
+  - make the flag highlight.
+  - If the right button is pressed, show a context menu with delete and rename options.
+  - If the left button is pressed, begin dragging the existing flag around.
+
+Conclusion
+----------
+
+There are many possibilities for new types of interaction with RViz.
+We look forward to seeing what you make.

rviz_plugin_tutorials/src/doc/panel_plugin_tutorial.rst

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2012, Willow Garage, Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of the Willow Garage, Inc. nor the names of its
+ *       contributors may be used to endorse or promote products derived from
+ *       this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+#ifndef FLAG_H
+#define FLAG_H
+
+namespace rviz_plugin_tutorials
+{
+
+class Flag: public rviz::Property
+{
+Q_OBJECT
+public:
+  Flag();
+};
+
+}
+
+#endif // FLAG_H