ParaView:Extend

Introduction

There are several ways to extend ParaView's capabilities:

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

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

• Include new reader, writer, source, or algorightm during run time

• Include arbitrary new code during compile time

• Include arbitrary new code during run time

• Include ParaView in some other project

Enable Existing VTK Class

Let 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, while the other describes the properties GUI. Let take as an example vtkCellDerivatives.

The first part is the server manager XML which we will call vtkCellDerivatives.pvsm:

<ServerManagerConfiguration>
  <ProxyGroup name="filters">
   <SourceProxy name="CellDerivatives" class="vtkCellDerivatives">
     <InputProperty
        name="Input"
        command="SetInput">
          <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 CellCenters -->
   </SourceProxy>
  </ProxyGroup>
</ServerManagerConfiguration

For more options to XML, please check the files in ParaView/Servers/ServerManager/Resources.

The second XML is the one that describes the GUI. Let us call it vtkCellDerivatives.xml:

<ModuleInterface>
  <ServerManagerFile name="vtkCellDerivatives.pvsm" />
  
  <Module name="CellDerivatives"
          menu_name="Cell Derivatives"
          root_name="Derivatives"
          module_type="Filter"
          long_help="Compute derivatives of scalars and vectors."
          short_help="Compute derivatives of scalars and vectors.">
    <Filter class="vtkCellCenters">
      <Input name="Input"
             class="vtkDataSet"/>
    </Filter>
    <InputMenu trace_name="Input" label="Input" property="Input"
               help="Set the input to this filter."
               input_name="Input"/>
    <SelectionList label="Vector Mode" property="VectorMode"
                   trace_name="VectorMode"
                   help="Control how the filter works to generate vector cell data.
                         You can choose to pass the input cell vectors, compute the gradient
                         of the input scalars, or extract the vorticity of the computed
                         vector gradient tensor. By default (VectorModeToComputeGradient),
                         the filter will take the gradient of the input scalar data.">
      <Item name="Pass Vectors" value="0"/>
      <Item name="Compute Gradients" value="1"/>
      <Item name="Compute Vorticity" value="2"/>
    </SelectionList>
    <Documentation>
vtkCellDerivatives is a filter that computes derivatives of scalars
and vectors at the center of cells. You can choose to generate
different output including the scalar gradient (a vector), computed
tensor vorticity (a vector), gradient of input vectors (a tensor),
and strain matrix of the input vectors (a tensor); or you may
choose to pass data through to the output.

Note that it is assumed that on input scalars and vector point data
is available, which are then used to generate cell vectors and tensors.
(The interpolation functions of the cells are used to compute the
derivatives which is why point data is required.)
    </Documentation>
  </Module>
</ModuleInterface>

Note that this XML refers to the previous one. This is the XML we will import into ParaView. For more GUI options, please check the XML files in ParaView/GUI/Client/Resources.

The XMLs can now be loaded into ParaView GUI using two options:

Load Module Into GUI

To load the XML file into the ParaView, we will go to menu File and select Import Package. This will popup a dialog in which we can select the apropriate XML file. Once we load the XML file, we can use the class in the ParaView.

Load Module Using Environment Variable

If we load custom modules into ParaView frequently, it is cumbersome to import package every single time. To load modules automatically, we set environment variable PV_INTERFACE_PATH to point to the directory that contains XML files with modules. Once ParaView is started, it will load all XML files (with extension .xml) in this directory.

Include Custom Class During Compile Time

Let say we have our file format called MyFancy and we require the reader for it. The file format is something completely new, so we cannot reuse any other class. So we write our own reader and we want to include it into the ParaView. Let 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

To make it work within the ParaView, we need to perform two tasks:

1. Build the reader as a part of ParaView
2. Register with the ParaView Server Manager and the GUI

Build Code As Part Of ParaView

The most obvious way to build particular code with the ParaView is to just put it in the ParaView source tree and modify the CMake lists 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.