ParaView/Plugin HowTo

Overview

This wiki page is under construction, so plugins are not limited to the examples you see here.

Plugins can be used to extend ParaView in several ways

• Add new VTK objects (readers, writers, filters, etc...)
• Add custom Qt widgets
• Add custom toolbars
• Add custom views in addition to the existing render view, line chart and bar chart.

Types of plugins

• Server plugins - extend the paraview server
• Client plugins - extend the paraview client
• A plugin may contain both client and server extensions and work if the appropriate client side libraries are on the server.

Building Plugins

To create a plugin, one must have their own build of ParaView3. Binary downloads do not include header files or import libraries (on applicable platforms).

The beginning of a CMakeLists.txt file contains

FIND_PACKAGE(ParaView REQUIRED)
INCLUDE(${PARAVIEW_USE_FILE})

Where CMake will ask for the ParaView_DIR which you point to your ParaView build. The PARAVIEW_USE_FILE includes build parameters and macros for building plugins.

Adding a custom filter, reader or writer

Standard VTK procedure is followed for writing these classes. XML for ParaView must also be written, and an example of that can be found at ParaView:Extend. If we have a class vtkMyFilter with MyFilter.xml, we put that in a server plugin as follows:

FIND_PACKAGE(ParaView REQUIRED)
INCLUDE(${PARAVIEW_USE_FILE})
ADD_PARAVIEW_PLUGIN(MyFilterSMPlugin "1.0" 
                    SERVER_MANAGER_XML MyFilter.xml
                    SERVER_MANAGER_SOURCES vtkMyFilter.cxx )

The plugin library will be named MyFilterSMPlugin.dll, libMyFilterSMPlugin.so or named as appropriate for the platform. The name is arbitrary. The XML, though client-side, is embedded into the plugin. When the ParaView server loads the plugin, the XML will be given to the client.

For readers and writers, we also need to make a client plugin. We create an XML file defining the reader or writer information.

<ParaViewReaders>
  <Reader name="MyReader"
          extensions="myreader mr"
          file_description="My Reader Files">
  </Reader>
</ParaViewReaders>

The name corresponds with the name found in the server manager XML. The extensions is to define what file extensions for file types and is used by the file dialog for filtering. The file_description is also used by the file dialog to give a friendly name for filtering.

We can have multiple client side XML files for different readers, writers, etc... We embed those into a Qt resource in an qrc file as follows:

<RCC>
  <qresource prefix="/ParaViewResources" >
    <file>MyReader.xml</file>
  </qresource>
<RCC>

Then we create the CMakeLists.txt file to build the client side plugin for the reader.

FIND_PACKAGE(ParaView REQUIRED)
INCLUDE(${PARAVIEW_USE_FILE})
ADD_PARAVIEW_PLUGIN(MyFilterGUIPlugin "1.0" 
                    GUI_RESOURCE MyReader.qrc )

Adding a ToolBar

New toolbars can be added from plugins to do virtually any operation. Let's make a toolbar with two buttons to create a sphere and cylinder source.

We derive a class from QActionGroup, which is a class to hold a group of actions. Each action can have an icon and text.

#include <QActionGroup>
#include <QApplication>
#include <QStyle>
#include "pqApplicationCore.h"
#include "pqServerManagerModel.h"

class MyToolBarActions : public QActionGroup
{
   Q_OBJECT
 public:
   MyToolBarActions(QObject* p) : QActionGroup(p)
   {
     // let's use a Qt icon (we could make our own)
     QIcon icon = qApp->style()->standardIcon(QStyle::SP_MessageBoxCritical);
     QAction* a = new QAction(icon, "Create Sphere", this);
     a->setData("SphereSource");
     this->addAction(a);
     a = new QAction(icon, "Create Cylinder", this);
     a->setData("CylinderSource");
     this->addAction(a);
     QObject::connect(this, SIGNAL(triggered(QAction*)), this, SLOT(onAction(QAction*)));
   }
 public slots:
   void onAction(QAction* a)
   {
     pqApplicationCore* core = pqApplicationCore::instance();
     pqServerManagerModel* sm = core->getServerManagerModel();
     if(sm->getNumberOfServers())
       {
       pqServer* s = sm->getServerByIndex(0);
       QString source_type = a->data().toString();
       core->createSourceOnServer(source_type.toAscii().data(), s);
       }
   }
};

To create the plugin, we do the following:

FIND_PACKAGE(ParaView REQUIRED)
INCLUDE(${PARAVIEW_USE_FILE})
QT4_WRAP_CPP(MOC_SRCS MyToolBarActions.h)
ADD_PARAVIEW_ACTION_GROUP(IFACES IFACE_SRCS CLASS_NAME MyToolBarActions
                         GROUP_NAME "ToolBar/MyActions")
ADD_PARAVIEW_PLUGIN(MyToolBar "1.0"
                    GUI_INTERFACES ${IFACES}
                    SOURCES ${MOC_SRCS} ${IFACE_SRCS})

For "ToolBar/MyActions," "ToolBar" is a keyword that means the action action group goes in a ToolBar called "MyActions." When the plugin is loaded, an extra toolbar will show up with two buttons.