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.

In MyToolBarActions.h, 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 build the plugin, the CMakeLists.txt file is:

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.

Adding an object panel

Object Panels are the panels for editing object properties.

ParaView3 contains automatic panel generation code which is suitable for most objects. If you find your object doesn't have a good auto-generated panel, you can make your own. There are different classes you can derive from depending on how much customization you need to do, or how much existing code you can leverage.

• pqObjectPanel - the base class for all object panels with limited functionality.
• pqNamedObjectPanel - if your widgets (line edit, combo boxes, etc..) have names corresponding with the server manager XML, then this class will automatically hook those widgets up with the server manager.
• pqLoadedFormObjectPanel - if you want to design your form in the Qt Designer, you get a .ui file as a result. You can use this class to load the .ui file. If the names of widgets created in the Qt Designer correspond with server manager objects, they will automatically be hooked up.
• pqAutoGeneratedObjectPanel - a panel that has widgets automatically created based on the properties of server manager objects. You can extend this if you have small adjustments to make or small features to add.

Now let's say we have our own panel we want to make for a ConeSource. In this example, we'll just add a simple label saying that this panel came from the plugin. In ConePanel.h:

#include "pqAutoGeneratedObjectPanel.h"
#include <QLabel>
#include <QLayout>

class ConePanel : public pqAutoGeneratedObjectPanel
{
  Q_OBJECT
public:
  ConePanel(pqProxy* pxy, QWidget* p)
    : pqAutoGeneratedObjectPanel(pxy, p)
  {
    this->layout()->addWidget(new QLabel("This is from a plugin", this));
  }
};

Then in our CMakeLists.txt file:

FIND_PACKAGE(ParaView REQUIRED)
INCLUDE(${PARAVIEW_USE_FILE})
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)
ADD_PARAVIEW_OBJECT_PANEL(IFACES IFACE_SRCS CLASS_NAME ConePanel
                         XML_NAME ConeSource XML_GROUP sources)
ADD_PARAVIEW_PLUGIN(GUIConePanel "1.0"
                    GUI_INTERFACES ${IFACES}
                    SOURCES ${MOC_SRCS} ${IFACE_SRCS})