ExtendingParaView

Introduction

There are several ways to extend ParaView's capabilities:

• Enable existing VTK reader, writer, source, or algorithm.

• Include new reader, writer, source, or algorithm during compile time

• Include arbitrary new code during compile time

• Include ParaView in some other project

Enable Existing VTK Class

Let's say we require a class in ParaView that already exists in VTK, but is not available in the ParaView GUI. To enable this filter we need to provide two XML files. One describes the use of class in the ParaView server manager, the other adds it to the GUI menu. Let take as an example vtkCellDerivatives.

This is the server manager XML which we will call vtkCellDerivatives.xml:

<ServerManagerConfiguration>
  <ProxyGroup name="filters">
   <SourceProxy name="CellDerivatives" class="vtkCellDerivatives">
     <InputProperty
        name="Input"
        command="SetInputConnection">
          <ProxyGroupDomain name="groups">
            <Group name="sources"/>
            <Group name="filters"/>
          </ProxyGroupDomain>
          <DataTypeDomain name="input_type">
            <DataType value="vtkDataSet"/>
          </DataTypeDomain>
     </InputProperty>

     <IntVectorProperty 
        name="VectorMode" 
        command="SetVectorMode" 
        number_of_elements="1"
        default_values="0" >
       <EnumerationDomain name="enum">
         <Entry value="0" text="PassVectors"/>
         <Entry value="1" text="ComputeGradient"/>
         <Entry value="2" text="ComputeVorticity"/>
       </EnumerationDomain>
     </IntVectorProperty>
   <!-- End CellDerivatives -->
   </SourceProxy>
  </ProxyGroup>
</ServerManagerConfiguration>

For more options to XML, please check the files in ParaView/Servers/ServerManager/Resources. Extra options could include GUI labels, documentation, etc...

This is the GUI XML:

<ParaViewFilters>
  <Filter name="CellDerivatives" />
</ParaViewFilters>

The server manager XML can be used to create a plugin, or can be built into Paraview as described below, or loaded at run time as described below. The GUI XML is not required when building as a plugin.

Loading XML at runtime

Server Manager XML can be loaded at runtime by going to Tools -> Manage Plugins/Extensions...

They can be loaded on the client side only, and the .xml and .bqrc extensions can be chosen in the file dialog.

.xml is a file containing server manager xml. .bqrc is a binary file containing resources as described elsewhere in this document.

A .bqrc can be made from a .qrc by running the rcc utility which comes with Qt:

rcc -binary -o myfile.bqrc myfile.qrc.

Include Custom Class During Compile Time

Let's say we have a file format called MyFancy and we require a reader for it. The file format is something completely new, so we cannot reuse any other class. So we write our own VTK reader and now we want to use it in the ParaView. Let's say the header file for the reader looks like this:

#ifndef __vtkMyFancyReader_h
#define __vtkMyFancyReader_h

#include "vtkUnstructuredGridAlgorithm.h"

...

class VTK_EXPORT vtkMyFancyReader : public vtkUnstructuredGridAlgorithm 
{
public:
  static vtkMyFancyReader *New();
  vtkTypeMacro(vtkMyFancyReader,vtkUnstructuredGridAlgorithm);
  void PrintSelf(ostream& os, vtkIndent indent);

  // Description:
  // Specify file name of the MyFancy file.
  vtkSetStringMacro(FileName);
  vtkGetStringMacro(FileName);

  // Description:
  // Which TimeStep to read.    
  vtkSetMacro(TimeStep, int);
  vtkGetMacro(TimeStep, int);

  vtkGetVector2Macro(TimeStepRange, int);

  ...

protected:
  vtkMyFancyReader();
  ~vtkMyFancyReader();

  ...

private:
  vtkMyFancyReader(const vtkMyFancyReader&); // Not implemented
  void operator=(const vtkMyFancyReader&); // Not implemented
};

#endif

Creating the server manager XML is also necessary, and can be done as described above. Readers, Writers, and Filters also require additional GUI side XML to describe file extensions associated with those file types.

<ParaViewReaders>
  <Reader name="MyFancyReader"
          extensions="myfan"
          file_description="My Fancy Files">
  </Reader>
</ParaViewReaders>

<ParaViewFilters>
  <Filter name="MyFancyFilter" />
</ParaViewFilters>

More examples can be found in ParaView3/Qt/Components/Resources/XML.

Build Code As a ParaView Plugin

See Plugin_HowTo for how to do this.

Build Code As Part Of ParaView

One can also put new code into ParaView by just putting it in the ParaView source tree and modify the CMake lists files to compile its source files. The drawbacks of this approach are that we have to now maintain our own modifications to ParaView code, and we cannot use versioning software to maintain the history of our code. Well, at least not without some problems. The solution to this is to import the code to the ParaView build process using ParaView External Modules.

ParaView External Modules are collections of code that are included during the ParaView build process, but reside somewhere outside the ParaView source tree. To generate a ParaView External Module, we need to create a file called <Module-Name>ParaViewImport.cmake. Let's say our module will be called MYFANCY, so the file needs to be called MYFANCYParaViewImport.cmake. It will look like this:

SET (MYFANCY_SRCS 
  ${MYFANCY_SOURCE_DIR}/vtkMyFancyReader.cxx
  )

INCLUDE_DIRECTORIES(${MYFANCY_SOURCE_DIR})
INCLUDE_DIRECTORIES(${MYFANCY_SOURCE_DIR}/..)

PARAVIEW_INCLUDE_WRAPPED_SOURCES("${MYFANCY_SRCS}")

To load this file into ParaView, we have to run the CMake GUI on ParaView and find an advanced option called PARAVIEW_EXTRA_EXTERNAL_MODULE. We should set it to MYFANCY. If it is already set to something, we should add MYFANCY to the list. For example: MYFANCY;ULTRASPECIAL. Once we run Configure, a new option will appear called: PARAVIEW_USE_MYFANCY. To actually include the module, we need to set that option to ON. After running Configure, CMake will attemt to find the MYFANCY source directory. If it cannot find the file MYFANCYParaViewImport.cmake, it will produce an error that the source directory was not found. The CMake variable that specifies the location of the module source directory will be called <Module-Name>_SOURCE_DIR. In our case this is MYFANCY_SOURCE_DIR. Note that this is the same variable used in the MYFANCYParaViewImport.cmake file. This variable should be set to the directory containing the MYFANCYParaViewImport.cmake file and not to the actual file.

At this point ParaView is all set to build. If all the locations are correct and the MYFANCYParaViewImport.cmake file is without errors, ParaView will be built with the reader included.

Additionally, you can use the following macros:

• To include Server manager XML:

 PARAVIEW_INCLUDE_SERVERMANAGER_RESOURCES("${MYFANCY_SOURCE_DIR}/ServerManagerXML.xml")

• To include GUI Client XML:

 PARAVIEW_INCLUDE_GUI_RESOURCES("${MYFANCY_SOURCE_DIR}/GUIXML.xml")

---

ParaView: [Welcome | Site Map]

---