From 10278947bf47c6672d65ac38e917346e1448bce5 Mon Sep 17 00:00:00 2001
From: Joseph Mirabel <jmirabel@laas.fr>
Date: Fri, 9 Feb 2018 12:00:30 +0100
Subject: [PATCH] Update documentation
---
doc/Doxyfile.extra.in | 3 +-
doc/main.hh | 14 ++
idl/gepetto/viewer/graphical-interface.idl | 209 ++++++++++++--------
include/gepetto/gui/bodytreewidget.hh | 2 +-
include/gepetto/gui/mainwindow.hh | 3 +-
include/gepetto/gui/plugin-interface.hh | 8 +
include/gepetto/gui/pythonwidget.hh | 6 +-
plugins/pluginskeleton/plugin.hh | 1 +
plugins/pyqgv/plugin.hh | 6 +
pyplugins/gepetto/gui/blenderexport.py | 15 +-
pyplugins/gepetto/gui/matplotlib_example.py | 6 +-
pyplugins/gepetto/gui/matplotlibwidget.py | 8 +-
12 files changed, 182 insertions(+), 99 deletions(-)
diff --git a/doc/Doxyfile.extra.in b/doc/Doxyfile.extra.in
index d2cdbf7..4cd3540 100644
--- a/doc/Doxyfile.extra.in
+++ b/doc/Doxyfile.extra.in
@@ -1,8 +1,9 @@
-FILE_PATTERNS = *.idl *.hh
+FILE_PATTERNS = *.idl *.hh *.py *.idl
INPUT = @CMAKE_SOURCE_DIR@/include \
@CMAKE_SOURCE_DIR@/idl \
@CMAKE_SOURCE_DIR@/plugins \
+ @CMAKE_SOURCE_DIR@/pyplugins \
@CMAKE_SOURCE_DIR@/doc
GENERATE_TREEVIEW = NO
diff --git a/doc/main.hh b/doc/main.hh
index 678090e..a0d5236 100644
--- a/doc/main.hh
+++ b/doc/main.hh
@@ -3,3 +3,17 @@
/// This package provides two compatible interfaces to vizualise robots:
/// \li a \ref gepetto_viewer_corba_introduction "command line interface in Python"
/// \li a \ref gepetto_gui_introduction "graphical user interface" which is fully compatible with the Python interface.
+///
+/// \defgroup pluginlist List of available plugins
+///
+/// \defgroup plugin Plugin interfaces
+/// Interface of C++ and Python plugins.
+///
+/// \ingroup plugin
+/// \{
+/// \defgroup plugin_cpp C++ Plugin API
+/// Descriptions of the available interfaces.
+///
+/// \defgroup plugin_python Python plugin API
+/// These slots are available for Python scripting in plugins.
+/// \}
diff --git a/idl/gepetto/viewer/graphical-interface.idl b/idl/gepetto/viewer/graphical-interface.idl
index 420c1df..a589289 100644
--- a/idl/gepetto/viewer/graphical-interface.idl
+++ b/idl/gepetto/viewer/graphical-interface.idl
@@ -25,40 +25,40 @@ typedef sequence <string> Names_t; /// Sequence of names
typedef sequence<float> floatSeq;
typedef sequence<Position> PositionSeq;
- /// Corba exception travelling through the Corba channel
+ /// IDL of the graphical interface.
+ /// It contains the following groups:
+ /// \li \ref idl_windows_and_scenes "Windows and scenes"
+ /// \li \ref idl_node_creation "Node creation"
+ /// \li \ref idl_node_tree_manipulation "Node tree manipulation"
+ /// \li \ref idl_node_configuration "Node configuration"
+ /// \li \ref idl_node_properties "Node properties"
+ /// \li \ref idl_export_of_scenes_to_images_or_to_blender "Export of scenes to images or to blender"
+ /// \li \ref idl_camera_manipulation "Camera manipulation"
interface GraphicalInterface {
+ /// \name Windows and scenes
+ /// \anchor idl_windows_and_scenes
+ /// \{
+
/// Set time between window frames
/// \param input rate : waiting time (ms) between two frames.
boolean setRate(in long rate) raises (Error);
- /// Change configurations according to the last applyConfigurations.d
- void refresh() raises (Error);
-
-
/// Create a new window.
/// \param input name : name of the new window.
/// return the ID of the newly create window.
unsigned long createWindow(in string name) raises (Error);
unsigned long getWindowID (in string name) raises (Error);
-
-
- /// Print names of nodes on the SceneViewer-corbaserver terminal
- /// and return them in an array
- /// \return the list of node names contained in the scene
- Names_t getNodeList() raises (Error);
-
- /// Print names of a group nodes on the SceneViewer-corbaserver terminal
- /// and return them in an array
- /// \param input name : name of the new window.
- /// \return the list of node names contained in the group
- Names_t getGroupNodeList(in string group) raises (Error);
-
- /// Get the list of group (i.e. scene) nodes
- Names_t getSceneList() raises (Error);
-
- /// Print names of windows on the SceneViewer-corbaserver terminal.
- Names_t getWindowList() raises (Error);
+
+ /// change the background color1
+ /// \param input windowId : ID of the window
+ /// \param input RGBAcolor : desired color
+ boolean setBackgroundColor1(in unsigned long windowId,in Color RGBAcolor);
+
+ /// change the background color2
+ /// \param input windowId : ID of the window
+ /// \param input RGBAcolor : desired color
+ boolean setBackgroundColor2(in unsigned long windowId,in Color RGBAcolor);
/// Create a group node.
/// \param input sceneName : name of the group.
@@ -74,21 +74,11 @@ typedef sequence<Position> PositionSeq;
/// \param input windowId : ID of rhe window.
boolean addSceneToWindow(in string sceneName, in unsigned long windowId) raises (Error);
- /// Attach the camera to the Node nodeName in the WindowManager
- /// pointed by windowId
- /// If already attached, detach from the other node
- /// \param input nodeName : name of the node
- /// \param input windowId : ID of the window
- boolean attachCameraToNode(in string nodeName, in unsigned long windowId) raises (Error);
-
- /// Detach the camera of WindowManager pointed by windowId
- /// from any node
- /// \param input windowId : ID of the window
- boolean detachCamera(in unsigned long windowId) raises (Error);
+ /// \}
- /// Check if nodeName is an existing node.
- /// \param nodeName name of the node
- boolean nodeExists(in string nodeName) raises (Error);
+ /// \name Node creation
+ /// \anchor idl_node_creation
+ /// \{
/// create a floor called floorName.
/// \param input floorName : name of the floor.
@@ -305,6 +295,38 @@ typedef sequence<Position> PositionSeq;
/// \param input groupName : name of the group.
boolean createGroup(in string groupName) raises (Error);
+ /// \}
+
+ /// \name Node tree manipulation
+ /// \anchor idl_node_tree_manipulation
+ /// \{
+
+ /// Check if nodeName is an existing node.
+ /// \param nodeName name of the node
+ boolean nodeExists(in string nodeName) raises (Error);
+
+ /// Delete node from visualiser
+ /// \param all if nodeName is a group node and all is True, nodes
+ /// are deleted recursively.
+ void deleteNode (in string nodeName, in boolean all) raises (Error);
+
+ /// Print names of nodes on the SceneViewer-corbaserver terminal
+ /// and return them in an array
+ /// \return the list of node names contained in the scene
+ Names_t getNodeList() raises (Error);
+
+ /// Print names of a group nodes on the SceneViewer-corbaserver terminal
+ /// and return them in an array
+ /// \param input name : name of the new window.
+ /// \return the list of node names contained in the group
+ Names_t getGroupNodeList(in string group) raises (Error);
+
+ /// Get the list of group (i.e. scene) nodes
+ Names_t getSceneList() raises (Error);
+
+ /// Print names of windows on the SceneViewer-corbaserver terminal.
+ Names_t getWindowList() raises (Error);
+
/// set a node as child to a group node.
/// \param input nodeName : name of the child node.
/// \param input groupName : name of the mother node (=group node).
@@ -315,11 +337,31 @@ typedef sequence<Position> PositionSeq;
/// \param input groupName : name of the mother node (=group node).
boolean removeFromGroup(in string nodeName, in string groupName) raises (Error);
+ /// \}
+
+ /// \name Node configuration
+ /// \anchor idl_node_configuration
+ /// \{
+
/// Set a new configuration to a node. THIS CONFIGURATION WILL AFFECTIVE ONLY AFTER CALLING REFRESH FUNCTION!!!
/// \param input nodeName : name of the node.
/// \param input configuration : Float[7] new configuration.
boolean applyConfiguration(in string nodeName, in Transform configuration) raises (Error);
+ /// Change configurations according to the last applyConfigurations.d
+ void refresh() raises (Error);
+
+ /// Return the Position + Quaternion orientation of an object in the global frame
+ /// \param input nodeName : name of the node.
+ /// \return a length 7 array
+ Transform getNodeGlobalTransform(in string nodeName) raises (Error);
+
+ /// \}
+
+ /// \name Node properties
+ /// \anchor idl_node_properties
+ /// \{
+
/// Add Landmark at the center of a node
/// The colors are x=red, y=green, z=blue (xyz=RGB).
/// \param input nodeName : name of the node
@@ -369,6 +411,34 @@ typedef sequence<Position> PositionSeq;
/// \param input state : 0 for off, 1 or 2 for other things.
boolean setHighlight (in string nodeName, in long state) raises (Error);
+ Names_t getPropertyNames(in string nodeName) raises (Error);
+ Names_t getPropertyTypes(in string nodeName) raises (Error);
+
+ void setStringProperty(in string nodeName, in string propName, in string value) raises (Error);
+ string getStringProperty(in string nodeName, in string propName) raises (Error);
+
+ void setColorProperty(in string nodeName, in string propName, in Color value) raises (Error);
+ Color getColorProperty(in string nodeName, in string propName) raises (Error);
+
+ void setVector3Property(in string nodeName, in string propName, in Position value) raises (Error);
+ Position getVector3Property(in string nodeName, in string propName) raises (Error);
+
+ void setFloatProperty(in string nodeName, in string propName, in float value) raises (Error);
+ float getFloatProperty(in string nodeName, in string propName) raises (Error);
+
+ void setBoolProperty(in string nodeName, in string propName, in boolean value) raises (Error);
+ boolean getBoolProperty(in string nodeName, in string propName) raises (Error);
+
+ void setIntProperty(in string nodeName, in string propName, in long value) raises (Error);
+ long getIntProperty(in string nodeName, in string propName) raises (Error);
+
+ /// \}
+
+ /// \name Export of scenes to images or to blender
+ /// \anchor idl_export_of_scenes_to_images_or_to_blender
+ /// See \ref gepetto.gui.Plugin
+ /// \{
+
void captureFrame (in WindowID wid, in string imageFilename) raises (Error);
/// Start capturing a window into image files.
@@ -412,56 +482,35 @@ typedef sequence<Position> PositionSeq;
/// Write the nodes contained in the window to filename
boolean writeWindowFile (in unsigned long windowId, in string filename) raises (Error);
-
- /// Return the Position + Quaternion orientation of an object in the global frame
- /// \param input nodeName : name of the node.
- /// \return a length 7 array
- Transform getNodeGlobalTransform(in string nodeName) raises (Error);
- /// Delete node from visualiser
- /// \param all if nodeName is a group node and all is True, nodes
- /// are deleted recursively.
- void deleteNode (in string nodeName, in boolean all) raises (Error);
-
- /// change the background color1
- /// \param input windowId : ID of the window
- /// \param input RGBAcolor : desired color
- boolean setBackgroundColor1(in unsigned long windowId,in Color RGBAcolor);
-
- /// change the background color2
- /// \param input windowId : ID of the window
- /// \param input RGBAcolor : desired color
- boolean setBackgroundColor2(in unsigned long windowId,in Color RGBAcolor);
+ /// \}
- /// get the matrix transform of the current position of the camera
- /// \param input windowId : ID of the window
- Transform getCameraTransform(in unsigned long windowId) raises (Error);
+ /// \name Camera manipulation
+ /// \anchor idl_camera_manipulation
+ /// \{
- /// set the matrix transform of the current camera
- /// \param input windowId : ID of the window
- /// \param input configuration : the desired configuration of the camera
- boolean setCameraTransform(in unsigned long windowId,in Transform configuration) raises (Error);
-
- Names_t getPropertyNames(in string nodeName) raises (Error);
- Names_t getPropertyTypes(in string nodeName) raises (Error);
-
- void setStringProperty(in string nodeName, in string propName, in string value) raises (Error);
- string getStringProperty(in string nodeName, in string propName) raises (Error);
-
- void setColorProperty(in string nodeName, in string propName, in Color value) raises (Error);
- Color getColorProperty(in string nodeName, in string propName) raises (Error);
+ /// Attach the camera to the Node nodeName in the WindowManager
+ /// pointed by windowId
+ /// If already attached, detach from the other node
+ /// \param input nodeName : name of the node
+ /// \param input windowId : ID of the window
+ boolean attachCameraToNode(in string nodeName, in unsigned long windowId) raises (Error);
- void setVector3Property(in string nodeName, in string propName, in Position value) raises (Error);
- Position getVector3Property(in string nodeName, in string propName) raises (Error);
+ /// Detach the camera of WindowManager pointed by windowId
+ /// from any node
+ /// \param input windowId : ID of the window
+ boolean detachCamera(in unsigned long windowId) raises (Error);
- void setFloatProperty(in string nodeName, in string propName, in float value) raises (Error);
- float getFloatProperty(in string nodeName, in string propName) raises (Error);
+ /// get the matrix transform of the current position of the camera
+ /// \param input windowId : ID of the window
+ Transform getCameraTransform(in unsigned long windowId) raises (Error);
- void setBoolProperty(in string nodeName, in string propName, in boolean value) raises (Error);
- boolean getBoolProperty(in string nodeName, in string propName) raises (Error);
+ /// set the matrix transform of the current camera
+ /// \param input windowId : ID of the window
+ /// \param input configuration : the desired configuration of the camera
+ boolean setCameraTransform(in unsigned long windowId,in Transform configuration) raises (Error);
- void setIntProperty(in string nodeName, in string propName, in long value) raises (Error);
- long getIntProperty(in string nodeName, in string propName) raises (Error);
+ /// \}
};
};
};
diff --git a/include/gepetto/gui/bodytreewidget.hh b/include/gepetto/gui/bodytreewidget.hh
index c6a49a9..579d21a 100644
--- a/include/gepetto/gui/bodytreewidget.hh
+++ b/include/gepetto/gui/bodytreewidget.hh
@@ -65,7 +65,7 @@ namespace gepetto {
void bodySelected (SelectionEvent* event);
public slots:
- /// \addtogroup available_in_python Python API
+ /// \ingroup plugin_python
/// \{
/// Triggered when an item is selected in the body tree view.
diff --git a/include/gepetto/gui/mainwindow.hh b/include/gepetto/gui/mainwindow.hh
index 8a03368..6103b13 100644
--- a/include/gepetto/gui/mainwindow.hh
+++ b/include/gepetto/gui/mainwindow.hh
@@ -107,8 +107,7 @@ signals:
void logErrorString(QString msg);
public slots:
- /// \addtogroup available_in_python Python API
- /// These slots are available for Python scripting in plugins
+ /// \ingroup plugin_python
/// \{
/// Get the body tree widget.
diff --git a/include/gepetto/gui/plugin-interface.hh b/include/gepetto/gui/plugin-interface.hh
index b4ace08..0228cfd 100644
--- a/include/gepetto/gui/plugin-interface.hh
+++ b/include/gepetto/gui/plugin-interface.hh
@@ -14,6 +14,8 @@ namespace gepetto {
namespace gui {
const int DockKeyShortcutBase = Qt::CTRL + Qt::ALT;
+ /// \ingroup plugin_cpp
+ /// Base interface for C++ plugins.
class PluginInterface {
public:
PluginInterface ()
@@ -53,6 +55,8 @@ namespace gepetto {
bool isInit_;
};
+ /// \ingroup plugin_cpp
+ /// Interface to add actions to the joint tree.
class JointModifierInterface {
public:
virtual ~JointModifierInterface () {}
@@ -60,6 +64,8 @@ namespace gepetto {
virtual QAction* action (const std::string& jointName) const = 0;
};
+ /// \ingroup plugin_cpp
+ /// Interface to load robot models.
class ModelInterface {
public:
virtual ~ModelInterface () {}
@@ -71,6 +77,8 @@ namespace gepetto {
virtual std::string getBodyFromJoint (const std::string& jointName) const = 0;
};
+ /// \ingroup plugin_cpp
+ /// You must implement this interface is you have corba clients.
class CorbaInterface {
public:
virtual ~CorbaInterface () {}
diff --git a/include/gepetto/gui/pythonwidget.hh b/include/gepetto/gui/pythonwidget.hh
index 79aae19..1adafa3 100644
--- a/include/gepetto/gui/pythonwidget.hh
+++ b/include/gepetto/gui/pythonwidget.hh
@@ -18,9 +18,6 @@ class PythonQtScriptingConsole;
namespace gepetto {
namespace gui {
- /// \defgroup plugin Plugin interfaces
-
-
/// \ingroup plugin
/// Python plugin interface
///
@@ -68,7 +65,8 @@ namespace gepetto {
/// MainWindow::logJobFailed to inform users when
/// starting and finishing (Done or Failed) actions that may take some time.
///
- /// \sa See example \ref pyplugins/gepetto/gui/pythonwidget.py
+ /// \sa See examples \ref pyplugins/gepetto/gui/pythonwidget.py and
+ /// \ref pyplugins/gepetto/gui/matplotlib_example.py
class PythonWidget : public QDockWidget
{
Q_OBJECT
diff --git a/plugins/pluginskeleton/plugin.hh b/plugins/pluginskeleton/plugin.hh
index b35833d..326a8b1 100644
--- a/plugins/pluginskeleton/plugin.hh
+++ b/plugins/pluginskeleton/plugin.hh
@@ -20,6 +20,7 @@
#include <gepetto/gui/plugin-interface.hh>
+/// \ingroup plugin
/// C++ skeleton plugin.
/// To add your own plugin, copy paste code in directory plugins/pluginskeleton.
class PluginSkeleton : public QObject, public gepetto::gui::PluginInterface {
diff --git a/plugins/pyqgv/plugin.hh b/plugins/pyqgv/plugin.hh
index 4229e82..3b4f8e8 100644
--- a/plugins/pyqgv/plugin.hh
+++ b/plugins/pyqgv/plugin.hh
@@ -21,7 +21,13 @@
#include <gepetto/gui/plugin-interface.hh>
namespace PyQgv {
+ /// \ingroup pluginlist
/// Provide bindings of QGV library in PythonQt terminal.
+ /// Add the following to your settings file to activate it.
+ ///
+ /// [plugins]
+ /// libpyqgv.so=true
+ ///
class Plugin : public QObject, public gepetto::gui::PluginInterface {
Q_OBJECT
Q_INTERFACES (gepetto::gui::PluginInterface)
diff --git a/pyplugins/gepetto/gui/blenderexport.py b/pyplugins/gepetto/gui/blenderexport.py
index 908f502..71e4895 100644
--- a/pyplugins/gepetto/gui/blenderexport.py
+++ b/pyplugins/gepetto/gui/blenderexport.py
@@ -7,7 +7,7 @@ def separator():
line.frameShadow = QtGui.QFrame.Sunken
return line
-### This class represents one special tab of the new QDockWidget
+### \cond
class _Widget (QtGui.QWidget):
def __init__(self, parent, plugin):
super(_Widget, self).__init__ (parent)
@@ -77,11 +77,16 @@ class _Widget (QtGui.QWidget):
button.text = buttonLabel
button.connect ('clicked(bool)', func)
return button
-
+### \endcond
+
+### \ingroup pluginlist
+### Python plugin to export scene to Blender.
+### Add the following to your settings file to activate it.
+###
+### [pyplugins]
+### gepetto.gui.blenderexport=true
+###
class Plugin(QtGui.QDockWidget):
- """
- Blender export helper plugin
- """
def __init__ (self, mainWindow, flags = None):
if flags is None:
super(Plugin, self).__init__ ("Blender export plugin", mainWindow)
diff --git a/pyplugins/gepetto/gui/matplotlib_example.py b/pyplugins/gepetto/gui/matplotlib_example.py
index b80b29e..bfe308d 100644
--- a/pyplugins/gepetto/gui/matplotlib_example.py
+++ b/pyplugins/gepetto/gui/matplotlib_example.py
@@ -4,10 +4,10 @@ import numpy as np
from gepetto.gui.matplotlibwidget import MatplotlibWidget
+### \ingroup pluginlist
+### Example of Python plugin using \ref matplotlibwidget.MatplotlibWidget "MatplotlibWidget".
+### This example uses \ref matplotlibwidget.MatplotlibWidget to plot matplotlib figures.
class Plugin(QtGui.QDockWidget):
- """
- Example of plugin using matplotlib
- """
def __init__ (self, mainWindow, flags = None):
if flags is None:
super(Plugin, self).__init__ ("Matplotlib example plugin", mainWindow)
diff --git a/pyplugins/gepetto/gui/matplotlibwidget.py b/pyplugins/gepetto/gui/matplotlibwidget.py
index 1c8c6e7..e7e5d06 100644
--- a/pyplugins/gepetto/gui/matplotlibwidget.py
+++ b/pyplugins/gepetto/gui/matplotlibwidget.py
@@ -7,15 +7,17 @@ from gepetto.corbaserver import Client
import numpy as np
-### This class represents one special tab of the new QDockWidget
+### Python QWidget that allows to draw matplotlib figures within the interface.
+###
+### Create an instance and populate member MatplotlibWidget.figure.
class MatplotlibWidget (QtGui.QWidget):
def __init__(self, parent, withToolbar = False):
super(MatplotlibWidget, self).__init__ (parent)
box = QtGui.QVBoxLayout(self)
- # Create a figure
+ ## The matplotlib figure
self.figure = Figure(figsize=(5,5), dpi=96)
- # self.figure = Figure()
+ ## The figure canvas
self.canvas = FigureCanvasQTAgg (self.figure)
box.addWidget(self.canvas)
--
GitLab