View source for 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 algorithm during compile time

* Include new reader, writer, source, or algorithm 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'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, 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:

<pre><nowiki>
<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>
</nowiki></pre>

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:

<pre><nowiki>
<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="vtkCellDerivatives">
      <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>
</nowiki></pre>

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 appropriate 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 the package every single time we run ParaView. To load modules automatically, we set the environment variable '''PV_INTERFACE_PATH''' to point to the directory that contains XML files with modules. When ParaView is started, it will load all XML files (with extension ''.xml'') in this directory.

= 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:

<pre><nowiki>#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</nowiki></pre>

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

# Build the reader as a part of ParaView
# Register with the ParaView Server Manager and the GUI

=== Build Code As Part Of ParaView ===

The most obvious way to put new code into ParaView is to just put 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 ''<nowiki><Module-Name></nowiki>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:

<pre><nowiki>
SET (MYFANCY_SRCS 
  ${MYFANCY_SOURCE_DIR}/vtkMyFancyReader.cxx
  )

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

PARAVIEW_INCLUDE_WRAPPED_SOURCES("${MYFANCY_SRCS}")
</nowiki></pre>

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 ''<nowiki><Module-Name></nowiki>_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 a custom widget:

 PARAVIEW_INCLUDE_CLIENT_SOURCES("${MYFANCY_SOURCE_DIR}/vtkPVMyFancyWidget.cxx")

* 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")

=== Register Code With The ParaView Server Manager And The GUI ===

Once ParaView is built, we can use the new module in ParaView by following the instructions in [[ParaView:Extend#Enable_Existing_VTK_Class|Enable Existing VTK Class]].

If we want the code to be permanently available in ParaView after compiling (without having to setup environment variable or loading XML file), we must use PARAVIEW_INCLUDE_SERVERMANAGER_RESOURCES and 
PARAVIEW_INCLUDE_GUI_RESOURCES macros in the ParaView module import file.

{{ParaView/Template/Footer}}