https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=DWilches&feedformat=atomKitwarePublic - User contributions [en]2024-03-28T09:48:05ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57325ParaView:Build And Install2015-01-08T02:17:04Z<p>DWilches: /* Build ParaView */</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external dependencies, typical for plugin developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are '''not''' supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
Some considerations about the size of the final build (measuring the folders size after compiling with Visual Studio 2010):<br />
* '''Total "Build" folder's size:''' 7.1 GB<br />
* '''Total "Build/bin/Debug" folder's size:''' 1.8 GB<br />
* '''Total "Build/bin/Release" folder's size:''' 96 MB (as you are developing plugins it is recommended to build for Debug though)<br />
<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
*CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
*You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to set the build type is set to '''Debug''' (you can also set it to "Release" but it's recommended to use "Debug" as it will give you more information in case of errors, while on "Release" Paraview is more likely to just crash).<br />
<br />
*To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57324ParaView:Build And Install2015-01-08T02:08:07Z<p>DWilches: /* Using Visual Studio */</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external dependencies, typical for plugin developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are '''not''' supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
*CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
*You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to set the build type is set to '''Debug''' (you can also set it to "Release" but it's recommended to use "Debug" as it will give you more information in case of errors, while on "Release" Paraview is more likely to just crash).<br />
<br />
*To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57266Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:45:05Z<p>DWilches: /* Step 7: Extra debugging */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", value);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that Paraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 8: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="cpp"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", value);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57265Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:44:33Z<p>DWilches: /* Step 3: Create the C++ file with the code for the plugin */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", value);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that Paraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 7: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="cpp"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", value);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57264Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:44:21Z<p>DWilches: /* Step 7: Extra debugging */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that Paraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 7: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="cpp"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", value);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57263Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:43:27Z<p>DWilches: /* Step 7: Load the plugin from inside Paraview */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that Paraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 7: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="cpp"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57262Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:43:12Z<p>DWilches: /* Step 7: Extra debugging */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that PAraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 7: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="cpp"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57261Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:42:40Z<p>DWilches: /* Step 6: compile the plugin */</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: Compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.<br />
<br />
== Step 7: Load the plugin from inside Paraview ==<br />
In Paraview go to "Tools" -> "Manage plugins..." adn add the DLL file created in the Step 6.<br />
Now add a "Sphere" source and go to "Filters" -> "Alphabetical" and find your filter called "CPPFilter" (note that PAraview orders first upper-cases and then lower-cases so your filter will be before the filter "Calculator".<br />
<br />
As you load your filter you will get this message printed out to the console:<br />
<pre>Sizz value is: 245</pre><br />
<br />
If you change in the GUI the value of "Sizz"and click the "Apply" button you will see the message of the console changing as well:<br />
<pre>Sizz value is: 24</pre><br />
<br />
Note that the script of this filter has been pre-filled with this value (we did it in the XML file):<br />
<pre>print 'Sizz value is: %s' % (sizz)</pre><br />
<br />
So that is the reason of that message being printed to the output console, but you can use the value of "sizz" in any way you want.<br />
<br />
== Step 7: Extra debugging ==<br />
<br />
You may have noticed that we had the following lines commented in vtkCPPFilter.cxx:<br />
<br />
<source lang="xml"><br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
</source><br />
<br />
If you uncomment them you will be able to see a popup message each time the value of the variable is updated.<br />
This is not recommended besides debugging as a message of this time can be disruptive for the user of your plugin.<br />
<br />
<br />
That's all for this tutorial !</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Python_Filters_Tutorials&diff=57260Python Filters Tutorials2015-01-07T04:34:18Z<p>DWilches: /* Creating a plugin subclass of PythonProgrammableFilter */</p>
<hr />
<div><br />
== Creating a plugin subclass of PythonProgrammableFilter==<br />
<br />
Follow this link to the tutorial for creating vtkCPPFilter, a simple plugin that subclasses PythonProgrammableFilter and shows how to pass custom parameters from the GUI to a Python script:<br />
* [[Plugin Tutorial: Subclassing PythonProgrammableFilter]]</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Python_Filters_Tutorials&diff=57259Python Filters Tutorials2015-01-07T04:33:19Z<p>DWilches: /* Creating a plugin subclass of PythonProgrammableFilter= */</p>
<hr />
<div><br />
== Creating a plugin subclass of PythonProgrammableFilter==<br />
<br />
Follow [[Plugin Tutorial: Subclassing PythonProgrammableFilter|this link]] to the tutorial for creating vtkCPPFilter, a simple plugin that subclasses PythonProgrammableFilter and shows how to pass custom parameters from the GUI to a Python script.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Plugin_Tutorial:_Subclassing_PythonProgrammableFilter&diff=57258Plugin Tutorial: Subclassing PythonProgrammableFilter2015-01-07T04:32:47Z<p>DWilches: Created first tutorial</p>
<hr />
<div><br />
In this tutorial we show step-by-step how to create a simple subclass of PythonProgrammableFilter.<br />
This plugin that shows how to subclass it and pass custom parameters from the GUI to a Python script.<br />
<br />
== Step 1: Create a CMakeLists.txt ==<br />
<br />
Create a file CMakeLists.txt with the following contents:<br />
<br />
<source lang="xml"><br />
cmake_minimum_required(VERSION 2.8.8 FATAL_ERROR)<br />
<br />
if (NOT ParaView_BINARY_DIR)<br />
find_package(ParaView REQUIRED)<br />
include(${PARAVIEW_USE_FILE})<br />
endif()<br />
<br />
include(ParaViewPlugins)<br />
<br />
# create a paraview plugin containing server manager xml and the server<br />
# manager classes to build<br />
# this plugin can be loaded on the server side<br />
<br />
ADD_PARAVIEW_PLUGIN(CPPFilter "1.0"<br />
SERVER_MANAGER_XML vtkCPPFilter.xml<br />
SERVER_MANAGER_SOURCES vtkCPPFilter.cxx)<br />
</source><br />
<br />
== Step 2: Create the XML file describing the plugin and its GUI ==<br />
<br />
In the Step 1 we are referencing the file "vtkCPPFilter.xml", so you need to create it with the following contents:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="CPPFilter" class="vtkCPPFilter" label="CPPFilter"><br />
<InputProperty name="Input" command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
<IntVectorProperty name="OutputDataSetType" command="SetOutputDataSetType" <br />
number_of_elements="1" default_values="0"> <br />
</IntVectorProperty><br />
<br />
<StringVectorProperty name="Script" command="SetScript" number_of_elements="1"<br />
default_values="print 'Sizz value is: %s' % (sizz)"><br />
<Hints> <Widget type="multi_line"/> </Hints><br />
</StringVectorProperty><br />
<br />
<!-- Sizz is the name of the variable that we will set in our plugin<br />
using the value of the GUI. This name here can be anything, but<br />
the "SetSizz" method should exist in the C++ class --><br />
<DoubleVectorProperty name="Sizz" command="SetSizz" number_of_elements="1"<br />
default_values="245"><br />
</DoubleVectorProperty><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
== Step 3: Create the C++ file with the code for the plugin ==<br />
<br />
Here we will create the C++ file referenced in the Step 1: "vtkCPPFilter.cxx"<br />
<br />
<source lang="cpp"><br />
#include "vtkCPPFilter.h"<br />
#include "vtkObjectFactory.h"<br />
#include <QMessageBox><br />
<br />
vtkStandardNewMacro(vtkCPPFilter);<br />
<br />
vtkCPPFilter::vtkCPPFilter() {}<br />
<br />
vtkCPPFilter::~vtkCPPFilter() {}<br />
<br />
void vtkCPPFilter::PrintSelf(ostream& os, vtkIndent indent)<br />
{<br />
this->Superclass::PrintSelf(os,indent);<br />
}<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void vtkCPPFilter::SetSizz(double value)<br />
{<br />
/*<br />
char s[255];<br />
sprintf(s, "SetSizz was invoked %f\n", d);<br />
QMessageBox::information(NULL, "MyAction", s);<br />
*/<br />
<br />
// Create a new variable for Python called 'sizz'<br />
SetParameter("sizz", value);<br />
}<br />
</source><br />
<br />
== Step 4: Create the H file with the header of the plugin ==<br />
<br />
Here we will create the H file referenced in the Step 3: "vtkCPPFilter.h"<br />
<br />
<source lang="cpp"><br />
#ifndef __vtkMyElevationFilter_h<br />
#define __vtkMyElevationFilter_h<br />
<br />
#include "vtkPythonProgrammableFilter.h"<br />
<br />
class VTK_EXPORT vtkCPPFilter : public vtkPythonProgrammableFilter<br />
{<br />
public:<br />
static vtkCPPFilter* New();<br />
vtkTypeMacro(vtkCPPFilter, vtkPythonProgrammableFilter);<br />
void PrintSelf(ostream& os, vtkIndent indent);<br />
<br />
// Method that creates a variable for Python using SetParameter<br />
void SetSizz(double);<br />
<br />
protected:<br />
vtkCPPFilter();<br />
~vtkCPPFilter();<br />
<br />
private:<br />
vtkCPPFilter(const vtkCPPFilter&); // Not implemented.<br />
void operator=(const vtkCPPFilter&); // Not implemented.<br />
};<br />
<br />
#endif<br />
</source><br />
<br />
== Step 5: Generate the rest of the plugin code ==<br />
Now, you should have 4 files in your working directory:<br />
<br />
<pre><br />
CMakeLists.txt<br />
vtkCPPFilter.xml<br />
vtkCPPFilter.cxx<br />
vtkCPPFilter.h<br />
</pre><br />
<br />
The next step is to open CMake and point it to our working folder and specify the build directory.<br />
For this example the build directory will be <tt>C:/vtkCPPFilter/build</tt>.<br />
<br />
After you have clicked in "Configure" and then on "Generate" you will have a new file called: <tt>C:/vtkCPPFilter/build/Project.sln</tt>.<br />
You can open this file with Visual Studio 2010 (if you are using other compiler this file may vary).<br />
<br />
== Step 6: compile the plugin ==<br />
In VisualStudio build the solution. After this process finishes the following file will be created:<br />
<pre>C:/vtkCPPFilter/build/Debug/CPPFilter.dll</pre><br />
or if you set the default configuration to "Release"then the file will be located in:<br />
<pre>C:/vtkCPPFilter/build/Release/CPPFilter.dll</pre><br />
<br />
Note this configuration should match the one used when you compiled your version of Paraview.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Python_Filters_Tutorials&diff=57256Python Filters Tutorials2015-01-07T04:15:53Z<p>DWilches: /* Python filter Tutorials */</p>
<hr />
<div><br />
== Creating a plugin subclass of PythonProgrammableFilter===<br />
<br />
Follow [[Plugin Tutorial: Subclassing PythonProgrammableFilter|this link]] to the tutorial for creating vtkCPPFilter, a simple plugin that subclasses PythonProgrammableFilter and shows how to pass custom parameters from the GUI to a Python script.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Python_Filters_Tutorials&diff=57255Python Filters Tutorials2015-01-07T04:13:49Z<p>DWilches: Created first tutorial</p>
<hr />
<div>== Python filter Tutorials ==<br />
<br />
=== Creating a subclass of PythonProgrammableFilter ===<br />
<br />
Follow [[Tutorial: Subclassing PythonProgrammableFilter|this link]] to the tutorial for creating vtkCPPFilter, a simple PythonProgrammableFilter that shows how to subclass it and pass custom parameters from the GUI to a Python script.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57254ParaView/Plugin HowTo2015-01-07T04:10:39Z<p>DWilches: /* Tutorials for creating filters */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
===== Drop down list with values from input file =====<br />
<br />
If you need to populate a list with values from a file and be able to select/deselect list entries<br />
(e.g., to pick which variables are loaded from the file), use a XML similar to this:<br />
<br />
<source lang="xml"><br />
<!-- Array Selection GUI Component --> <br />
<StringVectorProperty information_only="1" <br />
name="CellArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Cell" /> <br />
</StringVectorProperty> <br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArraySelectionDomain name="array_list"> <br />
<RequiredProperties> <br />
<Property function="ArrayList" <br />
name="CellArrayInfo" /> <br />
</RequiredProperties> <br />
</ArraySelectionDomain> <br />
<Documentation>This property lists which cell-centered arrays to <br />
read.</Documentation> <br />
</StringVectorProperty> <br />
<StringVectorProperty information_only="1" <br />
name="PointArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Point" /> <br />
</StringVectorProperty> <br />
</source><br />
<br />
You can see an example in use in the following file:<br />
<br />
ParaView/ParaViewCore/ServerManager/SMApplication/Resources/readers.xml<br />
<br />
You can also do it in the following manner:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
In which case the result will look like this:<br />
<br />
[[Image:DropdownListFromFile.jpg|thumb|center|300px|Drop down list with values from input file]]<br />
<br />
==== Tutorials for creating filters ====<br />
<br />
Go to this page for the main article for the tutorials: [[Python Filters Tutorials]]<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57253ParaView/Plugin HowTo2015-01-07T04:09:53Z<p>DWilches: /* Adding a Filter */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
===== Drop down list with values from input file =====<br />
<br />
If you need to populate a list with values from a file and be able to select/deselect list entries<br />
(e.g., to pick which variables are loaded from the file), use a XML similar to this:<br />
<br />
<source lang="xml"><br />
<!-- Array Selection GUI Component --> <br />
<StringVectorProperty information_only="1" <br />
name="CellArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Cell" /> <br />
</StringVectorProperty> <br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArraySelectionDomain name="array_list"> <br />
<RequiredProperties> <br />
<Property function="ArrayList" <br />
name="CellArrayInfo" /> <br />
</RequiredProperties> <br />
</ArraySelectionDomain> <br />
<Documentation>This property lists which cell-centered arrays to <br />
read.</Documentation> <br />
</StringVectorProperty> <br />
<StringVectorProperty information_only="1" <br />
name="PointArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Point" /> <br />
</StringVectorProperty> <br />
</source><br />
<br />
You can see an example in use in the following file:<br />
<br />
ParaView/ParaViewCore/ServerManager/SMApplication/Resources/readers.xml<br />
<br />
You can also do it in the following manner:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
In which case the result will look like this:<br />
<br />
[[Image:DropdownListFromFile.jpg|thumb|center|300px|Drop down list with values from input file]]<br />
<br />
==== Tutorials for creating filters ====<br />
<br />
Go to this page for the main article for the tutorials: [Python Filters Tutorials]<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=File:DropdownListFromFile.jpg&diff=57252File:DropdownListFromFile.jpg2015-01-06T20:38:43Z<p>DWilches: Drop down list with values from input file</p>
<hr />
<div>Drop down list with values from input file</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57251ParaView/Plugin HowTo2015-01-06T20:38:08Z<p>DWilches: /* Drop down list with values from input file */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
===== Drop down list with values from input file =====<br />
<br />
If you need to populate a list with values from a file and be able to select/deselect list entries<br />
(e.g., to pick which variables are loaded from the file), use a XML similar to this:<br />
<br />
<source lang="xml"><br />
<!-- Array Selection GUI Component --> <br />
<StringVectorProperty information_only="1" <br />
name="CellArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Cell" /> <br />
</StringVectorProperty> <br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArraySelectionDomain name="array_list"> <br />
<RequiredProperties> <br />
<Property function="ArrayList" <br />
name="CellArrayInfo" /> <br />
</RequiredProperties> <br />
</ArraySelectionDomain> <br />
<Documentation>This property lists which cell-centered arrays to <br />
read.</Documentation> <br />
</StringVectorProperty> <br />
<StringVectorProperty information_only="1" <br />
name="PointArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Point" /> <br />
</StringVectorProperty> <br />
</source><br />
<br />
You can see an example in use in the following file:<br />
<br />
ParaView/ParaViewCore/ServerManager/SMApplication/Resources/readers.xml<br />
<br />
You can also do it in the following manner:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
In which case the result will look like this:<br />
<br />
[[Image:DropdownListFromFile.jpg|thumb|center|300px|Drop down list with values from input file]]<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57250ParaView/Plugin HowTo2015-01-06T20:37:27Z<p>DWilches: /* Drop down list with values from input file */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
===== Drop down list with values from input file =====<br />
<br />
If you need to populate a list with values from a file and be able to select/deselect list entries<br />
(e.g., to pick which variables are loaded from the file), use a XML similar to this:<br />
<br />
<source lang="xml"><br />
<!-- Array Selection GUI Component --> <br />
<StringVectorProperty information_only="1" <br />
name="CellArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Cell" /> <br />
</StringVectorProperty> <br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArraySelectionDomain name="array_list"> <br />
<RequiredProperties> <br />
<Property function="ArrayList" <br />
name="CellArrayInfo" /> <br />
</RequiredProperties> <br />
</ArraySelectionDomain> <br />
<Documentation>This property lists which cell-centered arrays to <br />
read.</Documentation> <br />
</StringVectorProperty> <br />
<StringVectorProperty information_only="1" <br />
name="PointArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Point" /> <br />
</StringVectorProperty> <br />
</source><br />
<br />
You can see an example in use in the following file:<br />
<br />
ParaView/ParaViewCore/ServerManager/SMApplication/Resources/readers.xml<br />
<br />
You can also do it in the following manner:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
In which case the result will look like this:<br />
<br />
[[Image:DropdownListFromFile.jpg]]<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57249ParaView/Plugin HowTo2015-01-06T20:27:11Z<p>DWilches: /* Drop down list with values from input file */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
===== Drop down list with values from input file =====<br />
<br />
If you need to populate a list with values from a file and be able to select/deselect list entries<br />
(e.g., to pick which variables are loaded from the file), use a XML similar to this:<br />
<br />
<source lang="xml"><br />
<!-- Array Selection GUI Component --> <br />
<StringVectorProperty information_only="1" <br />
name="CellArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Cell" /> <br />
</StringVectorProperty> <br />
<StringVectorProperty command="SetCellArrayStatus" <br />
element_types="2 0" <br />
information_property="CellArrayInfo" <br />
label="Cell Arrays" <br />
name="CellArrayStatus" <br />
number_of_elements="0" <br />
number_of_elements_per_command="2" <br />
repeat_command="1"> <br />
<ArraySelectionDomain name="array_list"> <br />
<RequiredProperties> <br />
<Property function="ArrayList" <br />
name="CellArrayInfo" /> <br />
</RequiredProperties> <br />
</ArraySelectionDomain> <br />
<Documentation>This property lists which cell-centered arrays to <br />
read.</Documentation> <br />
</StringVectorProperty> <br />
<StringVectorProperty information_only="1" <br />
name="PointArrayInfo"> <br />
<ArraySelectionInformationHelper attribute_name="Point" /> <br />
</StringVectorProperty> <br />
</source><br />
<br />
You can see an example in use in the following file:<br />
<br />
ParaView/ParaViewCore/ServerManager/SMApplication/Resources/readers.xml<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57227ParaView/Plugin HowTo2015-01-06T00:52:26Z<p>DWilches: /* Adding GUI Parameters */</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
<br />
===== Drop down list with values from input arrays =====<br />
This creates a list that lets you choose among the input arrays of the input of a ProgrammableFilter:<br />
<br />
<source lang="xml"><br />
<StringVectorProperty name="SelectInputScalars"<br />
label="Array"<br />
command="SetInputArrayToProcess"<br />
number_of_elements="5"<br />
element_types="0 0 0 0 2"<br />
animateable="0"><br />
<ArrayListDomain name="array_list"<br />
attribute_type="Scalars"<br />
input_domain_name="inputs_array"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</ArrayListDomain><br />
<FieldDataDomain name="field_list"><br />
<RequiredProperties><br />
<Property name="Input"<br />
function="Input" /><br />
</RequiredProperties><br />
</FieldDataDomain><br />
</StringVectorProperty><br />
</source><br />
<br />
This will look like the following image:<br />
<br />
[[Image:DropboxWithInputArrays.jpg|thumb|center|300px|Drop down list with values from input arrays]]<br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=File:DropboxWithInputArrays.jpg&diff=57226File:DropboxWithInputArrays.jpg2015-01-06T00:49:28Z<p>DWilches: Drop down list with values from input arrays for a ProgrammableFilter:</p>
<hr />
<div>Drop down list with values from input arrays for a ProgrammableFilter:</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Talk:ParaView/Plugin_HowTo&diff=57225Talk:ParaView/Plugin HowTo2015-01-06T00:12:01Z<p>DWilches: Added suggestion for improvement in this page</p>
<hr />
<div>===About: "To create a plugin, one must have their own build of ParaView3."===<br />
* Building Paraview takes hours, more than 24 in my case. A packaged build of Paraview's resources needed for plugin development would be very welcomed by plugin developers. For example, there could be a git repository containing all headers, libs and everything else needed.<br />
<br />
===Adding GUI Parameters===<br />
* There are parts where more documentation would be useful. For example when you say that in the XML one can write <tt>command="SetbStartByMatchingCentroids"</tt>. The question unresolved there is "what is that command?" because the reader cannot know if it needs to be the name of a function inside the class or if it can be something else.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ServerManager_XML_Hints&diff=57224ServerManager XML Hints2015-01-05T23:44:43Z<p>DWilches: Improved formatting</p>
<hr />
<div><font color="blue">NOTE: This is under development and may not cover all available hints</font><br />
==Proxy Hints==<br />
<br />
These are hints added to proxies.<br />
<br />
===Mark proxy as a reader===<br />
<br />
* Used to mark a proxy under the "sources" group as a reader.<br />
* ''extensions'' attribute is used to list the supported extensions e.g. "foo foo.bar" for files named as somename.foo or somename.foo.bar.<br />
* ''filename_patterns'' attribute is used to list the filename patterns to match. The format is similar to what one would use for "ls" using wildcards e.g. spcth* to match spcta, spctb etc.<br />
<br />
<source lang="xml"><br />
<Hints><br />
<ReaderFactory extensions="[space separated extensions w/o leading '.']"<br />
filename_patterns="[space separated filename patters (using wildcards)]"<br />
file_description="[user-friendly description]" /><br />
</Hints><br />
</source><br />
<br />
===Hide/Show a property===<br />
<br />
The <tt>panel_visibility</tt> attribute can be used to change the visibility of a property in the properties panel. <br />
<br />
Valid values are:<br />
<br />
* <tt>"default"</tt> - always shown on the panel<br />
* <tt>"advanced"</tt> - only shown when the advanced button is clicked<br />
* <tt>"never"</tt> - never shown on the panel<br />
<br />
For example, the following property will only be shown when the user clicks the advanced button in the properties panel: <br />
<br />
<source lang="xml"><br />
<IntVectorProperty name="PhiResolution" panel_visibility="advanced"><br />
</IntVectorProperty><br />
</source><br />
<br />
Since almost all editable properties are by default shown in the automatically generated object inspector panel, this is most often used to hide the property. The need for this can occur when the property must be declared in the XML so that the default value for the VTK object's ivar is wrong or when the value needs to be changed programmatically, but allowing the user to directly change it is either confusing or could invalidate the state.<br />
<br />
One example where this attribute is used relatively frequently is for the vtkFileSeriesReader, which is reused for several readers and has a state switch called UseMetaFile that toggles between reading a list of files and reading a single text case file listing the actual files to read. The XML proxy definition must declare a UseMetaFile property to set it to the appropriate state, but you don't want the user to ever change the value because it would invalidate the reader. Thus, you get proxy code like the following.<br />
<br />
<source lang="xml"><br />
<IntVectorProperty name="UseMetaFile"<br />
command="SetUseMetaFile"<br />
number_of_elements="1"<br />
default_values="1"<br />
panel_visibility="never"><br />
<BooleanDomain name="bool" /><br />
<Documentation><br />
This hidden property must always be set to 1 for this proxy to work.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
===Default View===<br />
<br />
* Used to pick a default view type.<br />
* Does not support picking a view type for multiple output-ports just yet.<br />
<br />
<source lang="xml"><br />
<Hints><br />
<!-- View can be used to specify the preferred view for the proxy --><br />
<View type="XYChartView" /><br />
</Hints><br />
</source><br />
<br />
<br />
===Mark Data Plotable===<br />
<br />
* ParaView charts can support plotting any type of data, however since plotting is client-side, we don't want the user to accidentally try to plot really large datasets.<br />
* So we mark certain filters/sources are plot-able.<br />
* A source/filter producing vtkTable is always plot-able by default.<br />
<br />
<source lang="xml"><br />
<Hints><br />
<Plotable /><br />
</Hints><br />
</source><br />
<br />
===Don't hide input dataset===<br />
<br />
* When a filter is applied, ParaView hides the input dataset(s) by default in the active view.<br />
* In some cases, this is not the expected behavior e.g. Slice filter. In that case, use this hint.<br />
* Accepted values:<br />
0 ==> don't replace the input at all<br />
1 ==> replace the input (default behavior)<br />
2 ==> replace the input only if it is "Surface" or "Surface With Edges" and is totally opaque.<br />
<source lang="xml"><br />
<Hints><br />
<Visibility replace_input="0" /><br />
</Hints><br />
</source><br />
<br />
==Property Hints==<br />
<br />
These are hints added to Properties.<br />
<br />
===Selection Input===<br />
<br />
* If a filter needs to use the "active selection", one can use this hint.<br />
* Only used by auto-generated Properties panel.<br />
* Specified on a Input property that can take in a vtkSelection.<br />
<br />
<source lang="xml"><br />
<InputProperty name="Selection"<br />
command="SetSelectionConnection"><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkSelection"/><br />
</DataTypeDomain><br />
<Documentation><br />
The input that provides the selection object.<br />
</Documentation><br />
<Hints><br />
<!-- This tag alerts the auto-generated panels and input selection<br />
that this input is a selection. It should use the special<br />
selection GUI. --><br />
<SelectionInput /><br />
</Hints><br />
</InputProperty><br />
</source><br />
<br />
===Widget Height===<br />
<br />
* If a filter uses a tree widget (ArrayListDomain, ArraySelectionDomain, EnumerationDomain, CompositeTreeDomain), the height of the widget can be set with this hint.<br />
<br />
<source lang="xml"><br />
<IntVectorProperty command="..." name="..."><br />
<CompositeTreeDomain mode="all" name="tree"><br />
<RequiredProperties><br />
<Property function="Input" name="Input" /><br />
</RequiredProperties><br />
</CompositeTreeDomain><br />
<Hints><br />
<!-- This tag sets the height of the CompositeTreeDomain --><br />
<WidgetHeight number_of_rows="20" /><br />
</Hints><br />
</IntVectorProperty><br />
</source><br />
<br />
===Grouping Properties===<br />
<br />
So you can use widget input.<br />
<br />
<source lang="xml"><br />
<PropertyGroup type="Line" label="Elevation Widget"><br />
<Property function="Point1WorldPosition" name="LowPoint" /><br />
<Property function="Point2WorldPosition" name="HighPoint" /><br />
</PropertyGroup><br />
</source><br />
<br />
== ParaView 3.12 XML update ==<br />
<br />
=== Expose proxy in GUI menu ===<br />
<br />
To show a source proxy or a filter inside the menu of ParaView we use a hint.<br />
The category attribute allow to specify in which sub-menu this proxy should be in but it is totally optional.<br />
<br />
<source lang="xml"><br />
<SourceProxy ...><br />
<Hints><br />
<ShowInMenu category="PersoFilter"/><br />
</Hints><br />
</SourceProxy><br />
</source><br />
<br />
=== TimeSeries readers ===<br />
<br />
Previously we use to have TimeSerieReader proxy, now we can simply deal with regular source proxy and custom server side code.<br />
The following code snippet show what should be done now.<br />
<br />
<source lang="xml"><br />
<SourceProxy si_class="vtkSIFileSeriesReaderProxy" [same attrs as before]><br />
...<br />
</SourceProxy><br />
</source><br />
<br />
instead of <br />
<br />
<source lang="xml"><br />
<FileSeriesReaderProxy [some params]><br />
...<br />
</FileSeriesReaderProxy><br />
</source><br />
<br />
=== Disable property for UndoRedo states ===<br />
<br />
Now properties can be escaped from the GetFullState() method that is used for the undo/redo state by providing an extra attribute inside xml proxy definition.<br />
<br />
<source lang="xml"><br />
<Proxy name="ComparativeViewBase"><br />
<DoubleVectorProperty name="ViewTime"<br />
command="SetViewTime"<br />
number_of_elements="1"<br />
state_ignored="1" <---------------------- NEW FLAG<br />
default_values="none"><br />
<DoubleRangeDomain name="range"/><br />
<Documentation><br />
The pipeline update time for this view.<br />
This gets passed to all representations added to this view.<br />
</Documentation><br />
</DoubleVectorProperty><br />
...<br />
</source><br />
<br />
== ParaView 4.x XML ==<br />
<br />
=== Adding a button to call a method with no argument ===<br />
<br />
<source lang="xml"><br />
<Property name="Refresh" command="Modified" panel_widget="command_button"/><br />
</source></div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/EnvironmentSetup&diff=57218ParaView/EnvironmentSetup2014-12-30T21:15:32Z<p>DWilches: Hopefully improve google search results where someone searches for those errors.</p>
<hr />
<div>== Before starting ==<br />
<br />
Ensure that you have performed the steps from the "Getting Started" section of [[ParaView/Python Scripting]]. More concretely, you must have setup the environment variable <tt>PYTHONPATH</tt> to the indicated initial value to avoid some missing packages when using [[Python Programmable Filter|Programmable Filters]].<br />
<br />
==Linux==<br />
You must add this to your .bashrc to run anything in a ProgrammableFilter.<br />
<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping/site-packages #fixes "no module named paraview"<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/bin #fixes "ImportError: No module named libvtkCommonPython"<br />
<br />
Note that for older versions of ParaView the first line may need to be replaced by:<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping<br />
<br />
==Windows==<br />
<br />
If you get one of this errors:<br />
<br />
ImportError: No module named paraview<br />
ImportError: No module named vtkCommonCorePython<br />
<br />
Ensure that you have these three folders in your <tt>PYTHONPATH</tt> environment variable:<br />
<br />
C:\ParaView-v4.2.0-build\lib<br />
C:\ParaView-v4.2.0-build\lib\site-packages<br />
C:\ParaView-v4.2.0-build\bin<br />
<br />
Depending on your build, the folder '' C:\ParaView-v4.2.0-build\lib '' may not contain the *.libs files, in those cases the folder you need to add is the one corresponding to the configuration you used when building ParaView:<br />
<br />
C:\ParaView-v4.2.0-build\lib\'''Release'''<br />
<br />
or<br />
<br />
C:\ParaView-v4.2.0-build\lib\'''Debug'''</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Python_Scripting&diff=57217ParaView/Python Scripting2014-12-30T21:10:54Z<p>DWilches: missing space ...</p>
<hr />
<div>'''Katie O adding to ParaView Guide LaTex'''<br />
<br />
Note: This document if based on ParaView 3.6 or higher. If you are using 3.4, go to the history page and select the version from May 13, 2009.<br />
<br />
=ParaView and Python=<br />
ParaView offers rich scripting support through Python. This support is available as part of the ParaView client (paraview), an MPI-enabled batch application (pvbatch), the ParaView python client (pvpython), or any other Python-enabled application. Using Python, users and developers can gain access to the ParaView engine called Server Manager.<br />
<br />
Note: Server Manager is a library that is designed to make it easy to build distributed client-server applications.<br />
<br />
This document is a short introduction to ParaView's Python interface. You may also visit the [[Python recipes]] page for some examples.<br />
<br />
=Quick Start - a Tutorial=<br />
==Getting Started==<br />
<br />
To start interacting with the Server Manager, you have to load the "simple" module. This module can be loaded from any python interpreter as long as the necessary files are in PYTHONPATH. These files are the shared libraries located in the paraview binary directory and python modules in the paraview directory: ''paraview/simple.py'', ''paraview/vtk.py'' etc. You can also use either pvpython (for stand-alone or client/server execution), pvbatch (for non-interactive, distributed batch processing) or the python shell invoked from '''Tools'''|Python Shell using the ParaView client to execute Python scripts. You do not have to set PYTHONPATH when using these.<br />
<br />
This tutorial will be using the python integrated development environment IDLE. PYTHONPATH is set to the following: <br />
<br />
/Users/berk/work/paraview3-build/lib:/Users/berk/work/paraview3-build/lib/site-packages<br />
<br />
Note that depending on your build configuration, your *.libs files may not be under "lib" but under one of its sub-folders, like "lib/Release" or "lib/Debug". In those cases add the correct folder where the *.libs reside:<br />
<br />
/Users/berk/work/paraview3-build/lib/'''Release''':/Users/berk/work/paraview3-build/lib/site-packages<br />
<br />
Note: For older versions of ParaView this was '' /Users/berk/work/paraview3-build/bin:/Users/berk/work/paraview3-build/Utilities/VTKPythonWrapping/site-packages'' --[[User:Andy.bauer|Andy.bauer]] 24 January 2013, or<br />
''/Users/berk/work/paraview3-build/bin:/Users/berk/work/paraview3-build/Utilities/VTKPythonWrapping'' --[[User:Andy.bauer|Andy.bauer]] 23 July 2010.<br />
<br />
You may also need to set your path variable for searching for shared libraries (i.e. PATH on Windows and LD_LIBRARY_PATH on Unix/Linux/Mac). The corresponding LD_LIBRARY_PATH would be:<br />
/Users/berk/work/paraview3-build/lib (/Users/berk/work/paraview3-build/bin for versions before 3.98)<br />
<br />
(Under WindowsXP for a debug build of paraview, set both PATH and PYTHONPATH environment variables to include ${BUILD}/lib/Debug and ${BUILD}/lib/site-packages to make it work.)<br />
<br />
When using a Mac to use the build tree in IDLE, start by loading the servermanager module:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
</source><br />
<br />
Note: Importing the paraview module directly is deprecated, although still possible for backwards compatibility. This document refers to the simple module alone. <br />
<br />
In this example, we will use ParaView in the stand-alone mode. Connecting to a ParaView server running on a cluster is covered later in this document.<br />
<br />
===Tab-completion===<br />
<br />
The Python shell in the ParaView Qt client provides auto-completion. One can also use IDLE, for example to enable auto-completion. To use auto-completion in pvpython, one can use the tips provided at [http://www.razorvine.net/blog/user/irmen/article/2004-11-22/17].<br />
<br />
In summary, you need to create a variable PYTHONSTARTUP as (in bash):<br />
<br />
export PYTHONSTARTUP = /home/<username>/.pythonrc<br />
<br />
where .pythonrc is:<br />
<source lang="python"><br />
# ~/.pythonrc<br />
# enable syntax completion<br />
try:<br />
import readline<br />
except ImportError:<br />
print "Module readline not available."<br />
else:<br />
import rlcompleter<br />
readline.parse_and_bind("tab: complete")<br />
</source><br />
<br />
That is it. Tab completion works just as in any other shell.<br />
<br />
==Creating a Pipeline==<br />
<br />
The simple module contains many functions to instantiate sources, filters, and other related objects. You can get a list of objects this module can create from ParaView's online help (from help menu or here: http://paraview.org/OnlineHelpCurrent/)<br />
<br />
Start by creating a Cone object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone()<br />
</source><br />
<br />
You can get some documentation about the cone object using help().<br />
<br />
<source lang="python"><br />
>>> help(cone)<br />
Help on Cone in module paraview.servermanager object:<br />
<br />
class Cone(SourceProxy)<br />
| The Cone source can be used to add a polygonal cone to the 3D scene. The output of the <br />
Cone source is polygonal data.<br />
| <br />
| Method resolution order:<br />
| Cone<br />
| SourceProxy<br />
| Proxy<br />
| __builtin__.object<br />
| <br />
| Methods defined here:<br />
| <br />
| Initialize = aInitialize(self, connection=None)<br />
| <br />
| ----------------------------------------------------------------------<br />
| Data descriptors defined here:<br />
| <br />
| Capping<br />
| If this property is set to 1, the base of the cone will be capped with a filled polygon. <br />
Otherwise, the base of the cone will be open.<br />
| <br />
| Center<br />
| This property specifies the center of the cone.<br />
| <br />
| Direction<br />
| Set the orientation vector of the cone. The vector does not have to be normalized. The cone <br />
will point in the direction specified.<br />
| <br />
| Height<br />
| This property specifies the height of the cone.<br />
| <br />
| Radius<br />
| This property specifies the radius of the base of the cone.<br />
| <br />
| Resolution<br />
| This property indicates the number of divisions around the cone. The higher this number, the <br />
closer the polygonal approximation will come to representing a cone, and the more polygons it will <br />
contain.<br />
| <br />
|... <br />
</source><br />
<br />
This gives you a full list of properties. Check what the resolution property is set to:<br />
<br />
<source lang="python"><br />
>>> cone.Resolution<br />
6<br />
</source><br />
<br />
You can increase the resolution as shown below:<br />
<br />
<source lang="python"><br />
>>> cone.Resolution = 32<br />
</source><br />
<br />
Alternatively, we could have specified a value for resolution when creating the object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone(Resolution=32)<br />
</source><br />
<br />
You can assign values to any number of properties during construction using keyword arguments:<br />
You can also change the center.<br />
<br />
<source lang="python"><br />
>>> cone.Center<br />
[0.0, 0.0, 0.0]<br />
>>> cone.Center = [1, 2, 3]<br />
</source><br />
<br />
Vector properties such as this one support setting and retrieval of individual elements, as well as slices (ranges of elements):<br />
<br />
<source lang="python"><br />
>>> cone.Center[0:2] = [2, 4]<br />
>>> cone.Center<br />
[2.0, 4.0, 3.0]<br />
</source><br />
<br />
Next, apply a shrink filter to the cone:<br />
<br />
<source lang="python"><br />
>>> shrinkFilter = Shrink(cone)<br />
>>> shrinkFilter.Input<br />
<paraview.servermanager.Cone object at 0xaf701f0><br />
</source><br />
<br />
At this point, if you are interested in getting some information about the output of the shrink filter, you can force it to update (which will also cause the execution of the cone source). For details about VTK's demand-driven pipeline model used by ParaView, see one of the VTK books.<br />
<br />
<source lang="python"><br />
>>> shrinkFilter.UpdatePipeline()<br />
>>> shrinkFilter.GetDataInformation().GetNumberOfCells()<br />
33L<br />
>>> shrinkFilter.GetDataInformation().GetNumberOfPoints()<br />
128L<br />
</source><br />
<br />
We will cover the DataInformation class in more detail later.<br />
<br />
==Rendering==<br />
<br />
Now that you've created a small pipeline, render the result. You will need two objects to render the output of an algorithm in a scene: a representation and a view. A representation is responsible for taking a data object and rendering it in a view. A view is responsible for managing a render context and a collection of representations. Simple creates a view by default. The representation object is created automatically with Show().<br />
<br />
<source lang="python"><br />
>>> Show(shrinkFilter)<br />
>>> Render()<br />
</source><br />
<br />
Et voila:<br />
<br />
[[File:Servermanager_snapshot.png|thumb|center|800px|'''Figure 14.1''' Server manager snapshot]]<br />
<br />
In example Figure 14.1, the value returned by Cone() and Shrink() was assigned to Python variables and used to build the pipeline. ParaView keeps track of the last pipeline object created by the user. This allows you to accomplish everything you did above using the following code:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Create a cone and assign it as the active object<br />
>>> Cone()<br />
<paraview.servermanager.Cone object at 0x2910f0><br />
# Set a property of the active object<br />
>>> SetProperties(Resolution=32)<br />
# Apply the shrink filter to the active object<br />
# Shrink is now active<br />
>>> Shrink() <br />
<paraview.servermanager.Shrink object at 0xaf64050><br />
# Show shrink<br />
>>> Show() <br />
<paraview.servermanager.UnstructuredGridRepresentation object at 0xaf57f90><br />
# Render the active view<br />
>>> Render() <br />
<paraview.servermanager.RenderView object at 0xaf57ff0><br />
</source><br />
<br />
This was a quick introduction to the paraview.simple module. In the following sections, we will discuss the Python interface in more detail and introduce more advanced concepts.<br />
<br />
=paraview.simple Module=<br />
<br />
The simple module is a ParaView component written using Python on top of the Server Manager C++ library. Its purpose is to make it easier to create ParaView data analysis and visualization pipelines using Python. The simple module can be loaded from Python interpreters running in several applications.<br />
<br />
* '''pvpython''': The pvpython application, distributed with the ParaView application suite, is a Python client to the ParaView servers. It supports interactive execution as well as batch execution.<br />
<br />
* '''pvbatch''': The pvbatch application, also distributed with the ParaView application suite, is a Python application designed to run batch scripts on distributed servers. When ParaView is compiled with MPI, pvbatch can be launched as an MPI program. In this mode, the first node will load a Python script specified as a command-line argument and execute it using a special built-in connection on all nodes. This application does not support interactive execution.<br />
<br />
* '''paraview''': Python scripts can be run from the paraview client using the Python shell that is invoked from '''Tools'''|Python Shell. The Python shell supports interactive mode as well as loading of scripts from file.<br />
<br />
* '''External Python interpreter''': Any Python-capable application can load the paraview.simple module if the right environment is configured. For this to work, you either have to install the paraview Python modules (including the right shared libraries) somewhere in sys.path or you have to set PYTHONPATH to point to the right locations. <br />
<br />
==Overview==<br />
<br />
The paraview.simple module contains several Python classes designed to be Python-friendly, as well as all classes wrapped from the C++ Server Manager library. The following sections cover the usage of this module and occasionally the paraview.servermanager module, which is lower level.<br />
<br />
==Connecting to a Server==<br />
<br />
ParaView can run in two modes: stand-alone and client/server where the server is usually a visualization cluster. In this section, we discuss how to establish a connection to a server when using ParaView in the client/server mode. If you are using the ParaView graphical interface, you should use Connect from the File menu to connect to a server. If you are using ParaView from a Python shell (not the Python console that is part of the graphical interface), you need to use ''servermanager.Connect()'' to connect a server. <em>Note: you cannot connect to the ParaView application from a stand-alone Python shell. You can only connect to a server.</em> This method takes four arguments, all of which have default values.<br />
<br />
<source lang="python"><br />
def Connect(ds_host=None, ds_port=11111, rs_host=None, rs_port=11111)<br />
</source><br />
<br />
When connecting to a server (pvserver), specify only the first two arguments. These are the server name (or IP address) and port number.<br />
<br />
When connecting to a data-server/render-server pair, you have to specify all four arguments. The first two are the host name (or IP address) and port number of the data server, the last two those of the render server.<br />
Here are some examples:<br />
<br />
<source lang="python"><br />
# Connect to pvserver running on amber1 (first node of our test cluster)<br />
# using the default port 11111<br />
>>> Connect(‘amber1’)<br />
<br />
# Connect to pvdataserver running on the amber cluster, pvrenderserver <br />
# running on Berk’s desktop<br />
>>> Connect(‘amber1’, 12000, ‘kamino’, 11111)<br />
</source><br />
<br />
Note: Connect() will return None on failure. To be safe, you should check the return value of Connect().<br />
<br />
==Getting Help==<br />
<br />
You can access the documentation of all Proxy types by using Python's built-in help.<br />
<br />
<source lang="python"><br />
>>> help(paraview.simple.Cone)<br />
Help on function CreateObject in module paraview.simple:<br />
<br />
CreateObject(*input, **params)<br />
The Cone source can be used to add a polygonal cone to the 3D scene. The output of the <br />
Cone source is polygonal data.<br />
</source><br />
<br />
To get the full documentation, you have to create an instance.<br />
<br />
<source lang="python"><br />
>>> c = Cone()<br />
>>> help(c)<br />
</source><br />
<br />
This documentation is automatically generated from the Server Manager configuration files. It is identical to the class documentation found under the ParaView Help menu, as well as here: http://paraview.org/OnlineHelpCurrent/. <br />
Beyond this document and the online help, there are a few useful documentation sources:<br />
<br />
* The ParaView Guide: http://www.kitware.com/products/paraviewguide.html<br />
<br />
* The ParaView Wiki: http://paraview.org/Wiki/ParaView<br />
<br />
* The ParaView source documentation: http://www.paraview.org/doc/ <br />
<br />
<br />
If you are interested in learning more about the Visualization Toolkit that is at the foundation of ParaView, visit http://vtk.org.<br />
<br />
=Proxies and Properties=<br />
==Proxies==<br />
<br />
The VTK Server Manager design uses the Proxy design pattern (''See Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides for details''). Quoting from Wikipedia: “A proxy, in its most general form, is a class functioning as an interface to another thing. The other thing could be anything: a network connection, a large object in memory, a file, or some other resource that is expensive or impossible to duplicate”. In the case of Server Manager, a Proxy object acts as a proxy to one-or-more VTK objects. Most of the time, these are server-side objects and are distributed to the server nodes. Proxy objects allow you to interact with these objects as if you directly have access to them, manipulate them, and obtain information about them. When creating visualization pipelines, you create proxies instead of VTK objects. <br />
<br />
<source lang="python"><br />
>>> sphereSource = vtk.vtkSphereSource() # VTK-Python script<br />
<br />
>>> sphereSourceP = Sphere() # ParaView script<br />
</source><br />
<br />
A proxy also provides an interface to modify the properties of the objects it maintains. For example, instead of:<br />
<br />
<source lang="python"><br />
>>> sphereSource.SetCenter(1.0, 1.0, 0.0)<br />
</source><br />
<br />
you can write the following:<br />
<br />
<source lang="python"><br />
>>> sphere.Center = [1.0, 1.0, 0.0]<br />
</source><br />
<br />
When a pipeline object proxy is created, it is set as the active object. You can also set an object as the active one. This is equivalent to clicking-on an object in the pipeline browser.<br />
<br />
<source lang="python"><br />
>>> c = Cone()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> GetActiveSource()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> Shrink()<br />
<paraview.servermanager.Shrink object at 0xb4f8610><br />
# Make the cone active<br />
>>> SetActiveSource(c)<br />
</source><br />
<br />
When dealing with objects created through the graphical interface or by loading a state, it is useful to be able to search through existing pipeline objects. To accomplish this, you can use GetSources() and FindSource(). GetSources() returns a dictionary of (name, id) object pairs. Since multiple objects can have the same name, the (name,id) pair identifies objects uniquely. FindSource() returns an object given its name. If there are more than one objects with the same name, the first one is returned.<br />
<br />
<source lang="python"><br />
>>> Cone()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> GetActiveSource()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> Shrink()<br />
<paraview.servermanager.Shrink object at 0xb4f8610><br />
>>> SetActiveSource(c)<br />
</source><br />
<br />
To delete pipeline objects, you need to use the Delete() function. Simply letting a Python variable go out of scope is not enough to delete the object. Following the example above:<br />
<br />
<source lang="python"><br />
# Delete the cone source<br />
>>> Delete(c)<br />
# To fully remove the cone from memory, get rid of the<br />
# variable too<br />
>>> del c<br />
</source><br />
<br />
==Properties==<br />
<br />
Property objects are used to read and modify the properties of pipeline objects. Each proxy has a list of properties defined in the Server Manager configuration files. The property interface of the Server Manager C++ library is somewhat cumbersome. Here is how you can set the radius property of a sphere source:<br />
<br />
<source lang="python"><br />
>>> rp = sphere.GetProperty("Radius")<br />
>>> rp.SetElement(0, 2)<br />
1<br />
>>> sphere.UpdateProperty("Radius")<br />
</source><br />
<br />
The servermanager module makes property access much easier by defining Python property accessors for property objects:<br />
<br />
<source lang="python"><br />
>>> sphere.Radius = 3<br />
</source><br />
<br />
Here, Radius is a Python property which, when a value is assigned to it, calls sphere.SetPropertyWithName("Radius",3). Properties can also passed to the function creating the object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone(Radius=0.5, Center=[1, 0.5, 0])<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
</source><br />
<br />
You can also use the SetProperties() function to set property values.<br />
<br />
<source lang="python"><br />
>>> SetProperties(cone, Radius=0.2, Center=[2, 0.5, 0])<br />
</source><br />
<br />
If the first argument is not specified, the active object is used. You also use SetDisplayProperties() and SetViewProperties() to set display (representation) and view properties respectively.<br />
<br />
All Property classes define the following methods:<br />
<br />
* __len__() <br />
* __getitem__()<br />
* __setitem__()<br />
* __getslice__()<br />
* __setslice__()<br />
* GetData()<br />
* SetData(). <br />
<br />
Therefore, all of the following are supported:<br />
<br />
<source lang="python"><br />
>>> sphere.Center<br />
[0.0, 0.0, 0.0]<br />
>>> sphere.Center[0] = 1<br />
>>> sphere.Center[0:3] = [1,2,3]<br />
>>> sphere.Center[0:3]<br />
[1.0, 2.0, 3.0]<br />
>>> len(sphere.Center)<br />
3<br />
</source><br />
<br />
ProxyProperty and InputProperty also define<br />
<br />
* append()<br />
* __delitem__()<br />
* __delslice__()<br />
<br />
to support del() and append(), similar to Python list objects.<br />
<br />
VectorProperty is used for scalars, vectors and lists of integer and floating point numbers as well as <br />
strings. Most properties of this type are simple. Examples include ''Sphere.Radius'' (double scalar), ''Sphere.Center'' (vector of doubles), ''a2DGlyph.Filled'' (boolean), ''a2DGlyph.GlyphType'' (enumeration), ''a3DText.Text'' (string), and ''Contour.Isosurfaces'' (list of doubles). Some properties may be more complicated because they map to C++ methods with mixed argument types. Two good examples of this case are ''Glyph.Scalars'' and ''ExodusIIReader.PointVariables''.<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName='.../can.ex2')<br />
# These variables are currently selected<br />
>>> reader.PointVariables<br />
['DISPL', 'VEL', 'ACCL']<br />
# These are available in the file<br />
>>> reader.PointVariables.Available<br />
['DISPL', 'VEL', 'ACCL']<br />
# Enable the DISPL array only<br />
>>> reader.PointVariables = ['DISPL']<br />
# Force read<br />
>>> reader.UpdatePipeline()<br />
# Now check the output. Note: GlobalNodeId is generated automatically by the reader.<br />
>>> reader.PointData[:]<br />
[Array: GlobalNodeId, Array: PedigreeNodeId, Array: DISPL]<br />
</source><br />
<br />
This example demonstrates the use of ''ExodusIIReader.PointVariables''. This is a VectorProperty that represents a list of array names. The underlying C++ function has a signature of SetPointResultArrayStatus(const char* name, int flag). This method is usually called once per array to enable or disable it (i.e. to set whether the reader will read a particular array).<br />
<br />
Glyph.Scalars is a bit more complicated. This property allows the developer to select the scalar array with which to scale the glyphs.<br />
<br />
<source lang="python"><br />
>>> sph = Sphere()<br />
>>> elev=Elevation(sph)<br />
# Glyph the points of the sphere with spheres<br />
>>> glyph=Glyph(elev, GlyphType='Sphere')<br />
# Scale the glyph with the Elevation array<br />
>>> glyph.Scalars = 'Elevation'<br />
>>> glyph.Scalars<br />
['POINTS', 'Elevation']<br />
# The above shows the association of the array as well as its name.<br />
# In this case, the array is associated with POINTS as it has to be<br />
# since Glyph cannot scale by cell arrays. We could have done:<br />
>>> glyph.Scalars = ['POINTS', 'Elevation']<br />
# Enable scaling by scalars<br />
>>> glyph.ScaleMode = 'scalar'<br />
</source><br />
<br />
Here the property Scalars maps to SetInputArrayToProcess(int idx, int port, int connection, int fieldAssociation, const char *name), which has four integer arguments (some of which are enumeration) and one string argument (''see vtkAlgorithm documentation for details'').<br />
<br />
Properties are either regular (push) or information (pull) properties. Information properties do not have a VTK method associated with them and are responsible for getting information from the server. A good example of an information property is TimestepValues, which returns all time steps available in a file (if the reader supports time).<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName='.../can.ex2')<br />
>>> reader.TimestepValues<br />
[0.0, 0.00010007373930420727, 0.00019990510190837085, 0.00029996439116075635, 0.00040008654468692839,<br />
0.00049991923151537776, 0.00059993512695655227, 0.00070004, ...]<br />
</source><br />
<br />
You can obtain a list of properties a proxy supports by using ''help()''. However, this does not allow introspection programmatically. If you need to obtain information about a proxy’s properties programmatically, you can use a property iterator:<br />
<br />
<source lang="python"><br />
>>> for prop in glyph:<br />
print type(prop), prop.GetXMLLabel()<br />
<br />
<class 'paraview.servermanager.InputProperty'> Input<br />
<class 'paraview.servermanager.VectorProperty'> Maximum Number of Points<br />
<class 'paraview.servermanager.VectorProperty'> Random Mode<br />
<class 'paraview.servermanager.ArraySelectionProperty'> Scalars<br />
<class 'paraview.servermanager.ArraySelectionProperty'> Vectors<br />
<class 'paraview.servermanager.VectorProperty'> Orient<br />
<class 'paraview.servermanager.VectorProperty'> Set Scale Factor<br />
<class 'paraview.servermanager.EnumerationProperty'> Scale Mode<br />
<class 'paraview.servermanager.InputProperty'> Glyph Type<br />
<class 'paraview.servermanager.VectorProperty'> Mask Points<br />
</source><br />
<br />
The XMLLabel is the text display by the graphical user-interface. Note that there is a direct mapping from the XMLLabel to the property name. If you remove all spaces from the label, you get the property name. You can use the ''PropertyIterator'' object directly.<br />
<br />
<source lang="python"><br />
>>> it = iter(s)<br />
>>> for i in it:<br />
print it.GetKey(), it.GetProperty()<br />
</source><br />
<br />
==Domains==<br />
<br />
The Server Manager provides information about values that are valid for properties. The main use of this information is for the user-interface to provide good ranges and choices in enumeration. However, some of this information is also very useful for introspection. For example, enumeration properties look like simple integer properties unless a (value, name) pair is associated with them. The Server Manager uses Domain objects to store this information. The contents of domains may be loaded from xml configuration files or computed automatically. For example:<br />
<br />
<source lang="python"><br />
>>> s = Sphere()<br />
>>> Show(s)<br />
>>> dp = GetDisplayProperties(s)<br />
>>> dp.Representation<br />
'Surface'<br />
# The current representation type is Surface. What other types<br />
# are available?<br />
>>> dp.GetProperty("Representation").Available<br />
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']<br />
# Choose outline<br />
>>> dp.Representation = 'Outline'<br />
</source><br />
<br />
==Source Proxies==<br />
<br />
Source proxies are proxies that represent pipeline objects (''For more information about VTK pipelines, see the VTK books: http://vtk.org/buy-books.php''). They have special properties to connect them as well as special method to query the meta-data of their output. To connect a source proxy to another, use one of its input properties.<br />
<br />
<source lang="python"><br />
# Either<br />
>>> glyph = Glyph(elev)<br />
# or<br />
>>> glyph.Input = elev<br />
</source><br />
<br />
The SourceProxy class provides several additional properties and methods that are specific to pipelines (See vtkSMSourceProxy documentation for a full list).<br />
* '''UpdatePipelineInformation()''': This method calls UpdateInformation() on the VTK algorithm. It also calls UpdatePropertyInformation() to update any information properties.<br />
* '''UpdatePipeline()''': This method calls Update() on the VTK algorithm causing a pipeline execution if the pipeline changed. Another way of causing pipeline updates is to render. The render view updates all connected pipelines.<br />
* '''GetDataInformation()''': This method is used to obtain meta-data about one output. It is discussed further below.<br />
* PointData and CellData properties discussed below.<br />
<br />
There are two common ways of getting meta-data information from a proxy: information properties and DataInformation. Information properties are updated automatically every time UpdatePropertyInformation() and UpdatePipelineInformation() are called. All you have to do is read the data from the property as usual. To get a DataInformation object from a source proxy use ''GetDataInformation(port=0''). By default, this method returns data information for the first output. You can pass an optional port number to get information for another output. You can get detailed documentation on DataInformation by using help() and by reading online documentation for vtkPVDataInformation (''http://www.paraview.org/doc/nightly/html/classvtkPVDataInformation.html''). Here are the use of some common methods:<br />
<br />
<source lang="python"><br />
>>> di = glyph.GetDataInformation(0)<br />
>>> di<br />
<paraview.servermanager.DataInformation object at 0x2d0920d0><br />
>>> glyph.UpdatePipeline()<br />
# Get the data type.<br />
>>> di.GetDataClassName()<br />
'vtkPolyData'<br />
# Get information about point data. <br />
>>> pdi = glyph.PointData<br />
# We are now directly accessing the wrapper for a VTK class<br />
>>> len(pdi)<br />
2<br />
# Get information for a point array<br />
>>> ai = pdi[0]<br />
>>> ai.GetRange(0)<br />
(0.0, 0.5)<br />
</source><br />
<br />
When meta-data is not enough and you need access to the raw data, you can use Fetch() to bring it to the client side. Note that this function is provided by the servermanager module. Fetch() has three modes:<br />
<br />
*Append all of the data together and bring it to the client (only available for polygonal and unstructured datasets). Note: Do not do this if data is large otherwise the client will run out of memory.<br />
<br />
*Bring data from a given process to the client.<br />
<br />
*Use a reduction algorithm and bring its output to the client. For example, find the minimum value of an attribute.<br />
<br />
Here is a demonstration:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
>>> Connect("kamino")<br />
Connection (kamino:11111)<br />
>>> s = Sphere()<br />
# Get the whole sphere. DO NOT DO THIS IF THE DATA IS LARGE otherwise<br />
# the client will run out of memory.<br />
>>> allsphere = servermanager.Fetch(s)<br />
getting appended<br />
use append poly data filter<br />
>>> allsphere.GetNumberOfPolys()<br />
96<br />
# Get the piece of the sphere on process 0.<br />
>>> onesphere = servermanager.Fetch(s, 0)<br />
getting node 0<br />
>>> onesphere.GetNumberOfPolys()<br />
48<br />
# Apply the elevation filter so that we have a useful scalar array.<br />
>>> elev = Elevation(s)<br />
# We will use the MinMax algorithm to compute the minimum value of<br />
# elevation. MinMax will be first applied on each processor. The results<br />
# will then be gathered to the first node. MinMax will be then applied<br />
# to the gathered results.<br />
# We first create MinMax without an input.<br />
>>> mm = MinMax(None)<br />
# Set it to compute min<br />
>>> mm.Operation = "MIN"<br />
# Get the minimum<br />
>>> mindata = servermanager.Fetch(elev, mm, mm)<br />
applying operation<br />
# The result is a vtkPolyData with one point<br />
>>> mindata.GetPointData().GetNumberOfArrays()<br />
2<br />
>>> a0 = mindata.GetPointData().GetArray(1)<br />
>>> a0.GetName()<br />
'Elevation'<br />
>>> a0.GetTuple1(0)<br />
0.0<br />
</source><br />
<br />
==Representations and Views==<br />
<br />
Once a pipeline is created, it can be rendered using representations and views. A view is essentially a “window” in which multiple representations can be displayed. When the view is a VTK view (such as RenderView), this corresponds to a collection of objects including vtkRenderers and a vtkRenderWindow. However, there is no requirement for a view to be a VTK view or to render anything. A representation is a collection of objects, usually a pipeline, that takes a data object, converts it to something that can be rendered, and renders it. When the view is a VTK view, this corresponds to a collection of objects including geometry filters, level-of-detail algorithms, vtkMappers and vtkActors. The simple module automatically creates a view after connecting to a server (including the built-in connection when using the stand-alone mode). Furthermore, the simple module creates a representation the first time a pipeline object is displayed with Show().<br />
It is easy to create new views.<br />
<br />
<source lang="python"><br />
>>> view = CreateRenderView()<br />
</source><br />
<br />
CreateRenderView() is a special method that creates the render view appropriate for the ActiveConnection (or for another connection specified as an argument). It returns a sub-class of Proxy. Like the constructor of Proxy, it can take an arbitrary number of keyword arguments to set initial values for properties. Note that ParaView makes the view that was created last the active view. When using Show() without a view argument, the pipeline is shown in the active view. You can get a list of views as well as the active view as follows:<br />
<br />
<source lang="python"><br />
>>> GetRenderViews()<br />
[<paraview.servermanager.RenderView object at 0xaf64ef0>, <paraview.servermanager.RenderView object at 0xaf64b70>]<br />
>>> GetActiveView()<br />
<paraview.servermanager.RenderView object at 0xaf64b70><br />
</source><br />
<br />
You can also change the active view using SetActiveView().<br />
<br />
Once you have a render view, you can use pass it to Show in order to select in which view a pipeline object is displayed. You can also pass it to Render() to select which view is rendered.<br />
<br />
<source lang="python"><br />
>>> Show(elev, GetRenderViews()[1])<br />
<paraview.servermanager.GeometryRepresentation object at 0xaf64e30><br />
>>> Render(GetRenderViews()[1])<br />
</source><br />
<br />
Notice that Show() returns a representation object (aka DisplayProperties in the simple module). This object can be used to manipulate how the pipeline object is displayed in the view. You can also access the display properties of an object using GetDisplayProperties().<br />
<br />
<source lang="python"><br />
>>> dp = GetDisplayProperties(elev)<br />
>>> dp<br />
<paraview.servermanager.GeometryRepresentation object at 0xaf649d0><br />
</source><br />
<br />
Display properties and views have a large number of properties some of which are poorly documented. We will cover some them here.<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Create a simple pipeline<br />
>>> sph = Sphere()<br />
>>> elev = Elevation(sph)<br />
>>> Show(elev)<br />
>>> Render()<br />
# Set the representation type of elev<br />
>>> dp = GetDisplayProperties(elev)<br />
>>> dp.Representation = 'Points'<br />
# Here is how you get the list of representation types<br />
>>> dp.GetProperty("Representation").Available<br />
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']<br />
>>> Render()<br />
# Change the representation to wireframe<br />
>>> dp.Representation = 'Wireframe'<br />
>>> Render()<br />
# Let’s get some information about the output of the elevation<br />
# filter. We want to color the representation by one of it’s<br />
# arrays.<br />
# Second array = Elevation. Interesting. Let’s use this one.<br />
>>> ai = elev.PointData[1]<br />
>>> ai.GetName()<br />
'Elevation'<br />
# What is its range?<br />
>>> ai.GetRange()<br />
(0.0, 0.5)<br />
# To color the representation by an array, we need to first create<br />
# a lookup table. We use the range of the Elevation array<br />
>>> dp.LookupTable = MakeBlueToRedLT(0, 0.5)<br />
>>> dp.ColorAttributeType = 'POINT_DATA'<br />
>>> dp.ColorArrayName = 'Elevation' # color by Elevation<br />
>>> Render()<br />
</source><br />
<br />
Here is the result:<br />
[[Image:SMView.png|thumb|center|800px|'''Figure 14.2''' Object displayed in a view]]<br />
<br />
<br />
Once you create a scene, you will probably want to interact with the camera and ResetCamera() is likely to be insufficient. In this case, you can directly get the camera from the view and manipulate it. GetActiveCamera() returns a VTK object (not a proxy) with which you can interact.<br />
<br />
<source lang="python"><br />
>>> camera = GetActiveCamera()<br />
>>> camera<br />
<libvtkCommonPython.vtkCamera vtkobject at 0xe290><br />
>>> camera.Elevation(45)<br />
>>> Render()<br />
</source><br />
<br />
Another common thing to do is to save the view as an image. For this purpose, you can use the WriteImage() method provided by the view:<br />
<br />
<source lang="python"><br />
>> WriteImage("/Users/berk/image.png")<br />
</source><br />
<br />
The resulting image.png looks like this. See the documentation for WriteImage() for details on choosing file type, as well as a magnification factor to save images larger than the view size.<br />
<br />
[[Image:Image.jpg|thumb|center|800px|'''Figure 14.3''' Saving a view as an image]]<br />
<br />
=Advanced Concepts=<br />
<br />
==Dealing with lookup tables==<br />
In v4.1 LUT manipulation was simplified so that the LUTs found in the GUI may be assigned to arrays by name. See [[ParaView/Python/Lookup_tables | Lookup tables recipe]] for more information. <br />
<br />
As shown earlier, you can use MakeBlueToRedLt(min, max) to create a lookup table. However, this simply creates a new lookup table that the GUI won't be aware of. In the ParaView Qt application, we have special lookup table management that ensures that the same lookup table is used for all arrays with same name and number of components. To reproduce the same behavior in Python, use GetLookupTableForArray().<br />
<br />
<source lang="python"><br />
def GetLookupTableForArray(arrayname, num_components, **params):<br />
"""Used to get an existing lookuptable for a array or to create one if none<br />
exists. Keyword arguments can be passed in to initialize the LUT if a new<br />
one is created. Returns the lookup table."""<br />
....<br />
</source><br />
<br />
This will create a new lookup table and associate it with that array, if none already exists. Any default arguments to be passed to the lookup table if a new one is created, can be specified as additional parameters. You can always change the properties on the lookup table returned by this function.<br />
<br />
<br />
<source lang="python"><br />
# To color the representation by an array, we need to first create<br />
# a lookup table. We use the range of the Elevation array<br />
>>> dp.LookupTable = GetLookupTableForArray("Elevation", 1,<br />
RGBPoints = [min, 0, 0, 1, max, 1, 0, 0],<br />
ColorSpace = "HSV")<br />
>>> dp.ColorAttributeType = 'POINT_DATA'<br />
>>> dp.ColorArrayName = 'Elevation' # color by Elevation<br />
>>> Render()<br />
</source><br />
<br />
==Loading State and Manipulating It==<br />
<br />
Let’s say you created a complicated visualization using the paraview application and now you want to make slight changes to it and run it in a loop as a batch script. What do you do? The best way of dealing with this is to save your visualization state and then load it from Python. Let’s say you have a state file saved as myteststate.pvsm:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Load the state<br />
>>> servermanager.LoadState("/Users/berk/myteststate.pvsm")<br />
# Make sure that the view in the state is the active one<br />
>>> SetActiveView(GetRenderView())<br />
# Now render<br />
>>> Render()<br />
# Get the list of sources<br />
>>> GetSources()<br />
{('Sphere1', '5'): <paraview.servermanager.Sphere object at 0xaf80e30>, <br />
('Shrink1', '11'): <paraview.servermanager.Shrink object at 0xaf80df0>, <br />
('Cone1', '8'): <paraview.servermanager.Cone object at 0xaf80cf0>}<br />
# Change the resolution of the cone and render again<br />
>>> FindSource("Cone1").Resolution = 32<br />
>>> Render()<br />
</source><br />
<br />
You can also save state.<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
>>> sph = Sphere()<br />
>>> Render()<br />
>>> servermanager.SaveState("/Users/berk/pythonstate.pvsm")<br />
</source><br />
<br />
==Dealing with Time==<br />
<br />
If a reader or a filter supports time, it is easy to request a certain time step from Python. All time requests are set on views that then propagate them to the representations which then propagate them to the visualization pipeline. Here is an example demonstrating how a time request can be made:<br />
<br />
<source lang="python"><br />
>>> Show(ExodusIIReader(FileName=".../can.ex2"))<br />
>>> Render()<br />
# Get a nice view angle<br />
>>> cam = GetActiveCamera()<br />
>>> cam.Elevation(45)<br />
>>> Render()<br />
# Check the current view time<br />
>>> view = GetActiveView()<br />
>>> view.ViewTime<br />
0.0<br />
>>> reader = GetActiveSource()<br />
>>> reader.TimestepValues<br />
[0.0, 0.00010007373930420727, 0.00019990510190837085, <br />
0.00029996439116075635, 0.00040008654468692839, <br />
...]<br />
>>> tsteps = reader.TimestepValues<br />
# Let’s be fancy and use a time annotation filter. This will show the<br />
# current time value of the reader as text in the corner of the view.<br />
>>> annTime = AnnotateTimeFilter(reader)<br />
# Show the filter<br />
>>> Show(annTime)<br />
# Look at a few time steps. Note that the time value is requested not<br />
# the time step index.<br />
>>> view.ViewTime = tsteps[2]<br />
>>> Render()<br />
>>> view.ViewTime = tsteps[4]<br />
>>> Render()<br />
</source><br />
<br />
==Animating==<br />
<br />
Server Manager has a complicated animation engine based on keyframes and scenes. This section will introduce a few simple ways of animating your visualization. <br />
If you have a time-aware reader, you can animate it with AnimateReader().<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName=“.../can.ex2”)<br />
>>> Show(reader)<br />
>>> Render()<br />
>>> c = GetActiveCamera()<br />
>>> c.Elevation(95)<br />
# Animate over all time steps. Note that we are not passing the optional<br />
# 3rd argument here. If you pass a filename as the 3rd argument, <br />
# AnimateReader will create a movie.<br />
>>> AnimateReader(reader)<br />
# Save the animation to an avi file<br />
>>> AnimateReader(reader, filename=".../movie.avi")<br />
</source><br />
<br />
To animate properties other than time, you can use regular keyframes.<br />
<br />
'''''ParaView 3.8.0 and earlier'''''<br />
----<br />
<font color="blue">Although the following script will work with 3.8.1 and later, it's not the recommended way since the changes done so will not be reflected in the GUI. Refer to the following sub-section for the recommended style for 3.8.1 and later versions.</font><br />
<br />
<source lang="python"><br />
>>> Sphere()<br />
>>> Show()<br />
>>> Render()<br />
<br />
# Create an animation scene<br />
>>> scene = servermanager.animation.AnimationScene()<br />
# Add one view<br />
>>> scene.ViewModules = [GetActiveView()]<br />
<br />
# Create a cue to animate the StartTheta property<br />
>>> cue = servermanager.animation.KeyFrameAnimationCue()<br />
>>> cue.AnimatedProxy = GetActiveSource()<br />
>>> cue.AnimatedPropertyName = "StartTheta"<br />
# Add it to the scene's cues<br />
>>> scene.Cues = [cue]<br />
<br />
# Create 2 keyframes for the StartTheta track<br />
>>> keyf0 = servermanager.animation.CompositeKeyFrame()<br />
>>> keyf0.Interpolation = 'Ramp'<br />
# At time = 0, value = 0<br />
>>> keyf0.KeyTime = 0<br />
>>> keyf0.KeyValues= [0]<br />
<br />
>>> keyf1 = servermanager.animation.CompositeKeyFrame()<br />
# At time = 1.0, value = 200<br />
>>> keyf1.KeyTime = 1.0<br />
>>> keyf1.KeyValues= [200]<br />
<br />
# Add keyframes.<br />
>>> cue.KeyFrames = [keyf0, keyf1]<br />
<br />
>>> scene.Play()<br />
<br />
# Some properties you can change<br />
#<br />
# Number of frames used in Sequence mode<br />
# scene.NumberOfFrames = 100<br />
#<br />
# Or you can use real time mode<br />
# scene.PlayMode = 'Real Time'<br />
# scene.Duration = 20<br />
</source><br />
<br />
<br />
'''ParaView 3.8.1 onwards'''<br />
----<br />
<font color="blue">The following script will only work with ParaView versions 3.8.1 and later.<br />
It is now the recommended way for accessing animation scenes and tracks since the updates<br />
are reflected in the GUI when running through the Python shell from the ParaView application.<br />
</font><br />
<br />
<source lang="python"><br />
>>> Sphere()<br />
>>> Show()<br />
>>> Render()<br />
<br />
# Get the application-wide animation scene<br />
>>> scene = GetAnimationScene()<br />
<br />
# Get the animation track for animating "StartTheta" on the active source.<br />
# GetAnimationTrack() creates a new track if none exists.<br />
>>> cue = GetAnimationTrack("StartTheta")<br />
<br />
# Create 2 keyframes for the StartTheta track<br />
>>> keyf0 = CompositeKeyFrame()<br />
>>> keyf0.Interpolation = 'Ramp'<br />
# At time = 0, value = 0<br />
>>> keyf0.KeyTime = 0<br />
>>> keyf0.KeyValues= [0]<br />
<br />
>>> keyf1 = CompositeKeyFrame()<br />
# At time = 1.0, value = 200<br />
>>> keyf1.KeyTime = 1.0<br />
>>> keyf1.KeyValues= [200]<br />
<br />
# Add keyframes.<br />
>>> cue.KeyFrames = [keyf0, keyf1]<br />
<br />
>>> scene.Play()<br />
<br />
# Some properties you can change<br />
#<br />
# Number of frames used in Sequence mode<br />
# scene.NumberOfFrames = 100<br />
#<br />
# Or you can use real time mode<br />
# scene.PlayMode = 'Real Time'<br />
# scene.Duration = 20<br />
</source><br />
<br />
===GetAnimationTrack Usages===<br />
----<br />
<br />
<source lang="python"><br />
<br />
# Typical usage<br />
>>> track = GetAnimationTrack("Center", 0, sphere) or<br />
>>> track = GetAnimationTrack(sphere.GetProperty("Radius")) or<br />
<br />
# this returns the track to animate visibility of the active source in<br />
# all views.<br />
>>> track = GetAnimationTrack("Visibility")<br />
<br />
# For animating properties on implicit planes etc., use the following<br />
# signatures:<br />
>>> track = GetAnimationTrack(slice.SliceType.GetProperty("Origin"), 0) or<br />
>>> track = GetAnimationTrack("Origin", 0, slice.SliceType)<br />
<br />
</source><br />
<br />
==Loading Data Files==<br />
<br />
As seen throughout this document, you can always load a data file by explicitly creating the reader that can read the data file as follows:<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName=“.../can.ex2”)<br />
</source><br />
<br />
Alternatively, starting with ParaView 3.8, you can use OpenDataFile() function to let ParaView pick a reader using the extension of the file.<br />
<br />
<source lang="python"><br />
>>> reader = OpenDataFile(“.../can.ex2”)<br />
</source><br />
<br />
<br />
==Writing Data Files (ParaView 3.9 or later)==<br />
<br />
To create a writer to write the output from a source, one can use the following:<br />
<br />
<source lang="python"><br />
from paraview.simple import *<br />
<br />
# Specifying the source explicitly<br />
>>> writer= CreateWriter("/.../filename.vtk", source)<br />
<br />
# Using the active source<br />
>>> writer= CreateWriter("/.../filename.vtk")<br />
<br />
# Writing data from a particular output port<br />
>>> writer= CreateWriter("/.../filename.vtk", servermanager.OutputPort(source, 1))<br />
<br />
# Now one change change the ivars on the writer <br />
<br />
# To do the actual writing, use:<br />
>>> writer.UpdatePipeline()<br />
<br />
</source><br />
<br />
==Exporting CSV Data==<br />
<br />
To export a csv from the cell or point data associated with a source, one can use the following:<br />
<br />
<source lang="python"><br />
>>> writer = CreateWriter(".../foo.csv", source)<br />
>>> writer.FieldAssociation = "Points" # or "Cells"<br />
>>> writer.UpdatePipeline()<br />
>>> del writer<br />
</source><br />
<br />
==Updating View Layout==<br />
<br />
Starting with ParaView 3.14, Python scripts can be used to update view layout.<br />
<br />
Every tab in the central frame of the ParaView application is represented by '''layout''' proxy. To obtain a map of layout proxies present, use the GetLayouts().<br />
<br />
<source lang="python"><br />
>>> GetLayouts()<br />
{('ViewLayout1', '264'): <paraview.servermanager.ViewLayout object at 0x2e5b7d0>}<br />
</source><br />
<br />
To get the layout corresponding to the active view (or a particular view), use the GetLayout() function.<br />
<br />
<source lang="python"><br />
>>> GetLayout()<br />
<paraview.servermanager.ViewLayout object at 0x2e5b7d0><br />
>>><br />
>>> GetLayout(GetActiveView())<br />
<paraview.servermanager.ViewLayout object at 0x2e5b7d0><br />
</source><br />
<br />
To split the cell containing a particular view, either horizontally or vertically, use:<br />
<br />
<source lang="python"><br />
<br />
>>> layout.SplitViewVertical(view = GetActiveView())<br />
<br />
>>> layout.SplitViewHorizontal(view = GetActiveView(), fraction = 0.7)<br />
<br />
</source><br />
<br />
To resize a cell containing a particular view:<br />
<br />
<source lang="python"><br />
<br />
>>> location = layout.GetViewLocation(view)<br />
>>> layout.SetSplitFraction(location, 0.3)<br />
<br />
</source><br />
<br />
To maximize a particular view<br />
<source lang="python"><br />
<br />
>>> location = layout.GetViewLocation(view)<br />
>>> layout.MaximizeCell(location)<br />
<br />
</source><br />
<br />
There are a host of other methods that are available that can help with layout of the views. Refer to the API exposed by vtkSMViewLayoutProxy. The API is fully accessible through Python.<br />
<br />
To create a new tab, one can use the following piece of code:<br />
<br />
<source lang="python"><br />
<br />
new_layout = servermanager.misc.ViewLayout(registrationGroup="layouts")<br />
<br />
</source><br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Python_Scripting&diff=57216ParaView/Python Scripting2014-12-30T21:10:25Z<p>DWilches: In some cases the lib files are not in the folder specified here. Added the aclaration</p>
<hr />
<div>'''Katie O adding to ParaView Guide LaTex'''<br />
<br />
Note: This document if based on ParaView 3.6 or higher. If you are using 3.4, go to the history page and select the version from May 13, 2009.<br />
<br />
=ParaView and Python=<br />
ParaView offers rich scripting support through Python. This support is available as part of the ParaView client (paraview), an MPI-enabled batch application (pvbatch), the ParaView python client (pvpython), or any other Python-enabled application. Using Python, users and developers can gain access to the ParaView engine called Server Manager.<br />
<br />
Note: Server Manager is a library that is designed to make it easy to build distributed client-server applications.<br />
<br />
This document is a short introduction to ParaView's Python interface. You may also visit the [[Python recipes]] page for some examples.<br />
<br />
=Quick Start - a Tutorial=<br />
==Getting Started==<br />
<br />
To start interacting with the Server Manager, you have to load the "simple" module. This module can be loaded from any python interpreter as long as the necessary files are in PYTHONPATH. These files are the shared libraries located in the paraview binary directory and python modules in the paraview directory: ''paraview/simple.py'', ''paraview/vtk.py'' etc. You can also use either pvpython (for stand-alone or client/server execution), pvbatch (for non-interactive, distributed batch processing) or the python shell invoked from '''Tools'''|Python Shell using the ParaView client to execute Python scripts. You do not have to set PYTHONPATH when using these.<br />
<br />
This tutorial will be using the python integrated development environment IDLE. PYTHONPATH is set to the following: <br />
<br />
/Users/berk/work/paraview3-build/lib:/Users/berk/work/paraview3-build/lib/site-packages<br />
<br />
Note that depending on your build configuration, your *.libs files may not be under "lib"but under one of its sub-folders, like "lib/Release" or "lib/Debug". In those cases add the correct folder where the *.libs reside:<br />
<br />
/Users/berk/work/paraview3-build/lib/'''Release''':/Users/berk/work/paraview3-build/lib/site-packages<br />
<br />
Note: For older versions of ParaView this was '' /Users/berk/work/paraview3-build/bin:/Users/berk/work/paraview3-build/Utilities/VTKPythonWrapping/site-packages'' --[[User:Andy.bauer|Andy.bauer]] 24 January 2013, or<br />
''/Users/berk/work/paraview3-build/bin:/Users/berk/work/paraview3-build/Utilities/VTKPythonWrapping'' --[[User:Andy.bauer|Andy.bauer]] 23 July 2010.<br />
<br />
You may also need to set your path variable for searching for shared libraries (i.e. PATH on Windows and LD_LIBRARY_PATH on Unix/Linux/Mac). The corresponding LD_LIBRARY_PATH would be:<br />
/Users/berk/work/paraview3-build/lib (/Users/berk/work/paraview3-build/bin for versions before 3.98)<br />
<br />
(Under WindowsXP for a debug build of paraview, set both PATH and PYTHONPATH environment variables to include ${BUILD}/lib/Debug and ${BUILD}/lib/site-packages to make it work.)<br />
<br />
When using a Mac to use the build tree in IDLE, start by loading the servermanager module:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
</source><br />
<br />
Note: Importing the paraview module directly is deprecated, although still possible for backwards compatibility. This document refers to the simple module alone. <br />
<br />
In this example, we will use ParaView in the stand-alone mode. Connecting to a ParaView server running on a cluster is covered later in this document.<br />
<br />
===Tab-completion===<br />
<br />
The Python shell in the ParaView Qt client provides auto-completion. One can also use IDLE, for example to enable auto-completion. To use auto-completion in pvpython, one can use the tips provided at [http://www.razorvine.net/blog/user/irmen/article/2004-11-22/17].<br />
<br />
In summary, you need to create a variable PYTHONSTARTUP as (in bash):<br />
<br />
export PYTHONSTARTUP = /home/<username>/.pythonrc<br />
<br />
where .pythonrc is:<br />
<source lang="python"><br />
# ~/.pythonrc<br />
# enable syntax completion<br />
try:<br />
import readline<br />
except ImportError:<br />
print "Module readline not available."<br />
else:<br />
import rlcompleter<br />
readline.parse_and_bind("tab: complete")<br />
</source><br />
<br />
That is it. Tab completion works just as in any other shell.<br />
<br />
==Creating a Pipeline==<br />
<br />
The simple module contains many functions to instantiate sources, filters, and other related objects. You can get a list of objects this module can create from ParaView's online help (from help menu or here: http://paraview.org/OnlineHelpCurrent/)<br />
<br />
Start by creating a Cone object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone()<br />
</source><br />
<br />
You can get some documentation about the cone object using help().<br />
<br />
<source lang="python"><br />
>>> help(cone)<br />
Help on Cone in module paraview.servermanager object:<br />
<br />
class Cone(SourceProxy)<br />
| The Cone source can be used to add a polygonal cone to the 3D scene. The output of the <br />
Cone source is polygonal data.<br />
| <br />
| Method resolution order:<br />
| Cone<br />
| SourceProxy<br />
| Proxy<br />
| __builtin__.object<br />
| <br />
| Methods defined here:<br />
| <br />
| Initialize = aInitialize(self, connection=None)<br />
| <br />
| ----------------------------------------------------------------------<br />
| Data descriptors defined here:<br />
| <br />
| Capping<br />
| If this property is set to 1, the base of the cone will be capped with a filled polygon. <br />
Otherwise, the base of the cone will be open.<br />
| <br />
| Center<br />
| This property specifies the center of the cone.<br />
| <br />
| Direction<br />
| Set the orientation vector of the cone. The vector does not have to be normalized. The cone <br />
will point in the direction specified.<br />
| <br />
| Height<br />
| This property specifies the height of the cone.<br />
| <br />
| Radius<br />
| This property specifies the radius of the base of the cone.<br />
| <br />
| Resolution<br />
| This property indicates the number of divisions around the cone. The higher this number, the <br />
closer the polygonal approximation will come to representing a cone, and the more polygons it will <br />
contain.<br />
| <br />
|... <br />
</source><br />
<br />
This gives you a full list of properties. Check what the resolution property is set to:<br />
<br />
<source lang="python"><br />
>>> cone.Resolution<br />
6<br />
</source><br />
<br />
You can increase the resolution as shown below:<br />
<br />
<source lang="python"><br />
>>> cone.Resolution = 32<br />
</source><br />
<br />
Alternatively, we could have specified a value for resolution when creating the object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone(Resolution=32)<br />
</source><br />
<br />
You can assign values to any number of properties during construction using keyword arguments:<br />
You can also change the center.<br />
<br />
<source lang="python"><br />
>>> cone.Center<br />
[0.0, 0.0, 0.0]<br />
>>> cone.Center = [1, 2, 3]<br />
</source><br />
<br />
Vector properties such as this one support setting and retrieval of individual elements, as well as slices (ranges of elements):<br />
<br />
<source lang="python"><br />
>>> cone.Center[0:2] = [2, 4]<br />
>>> cone.Center<br />
[2.0, 4.0, 3.0]<br />
</source><br />
<br />
Next, apply a shrink filter to the cone:<br />
<br />
<source lang="python"><br />
>>> shrinkFilter = Shrink(cone)<br />
>>> shrinkFilter.Input<br />
<paraview.servermanager.Cone object at 0xaf701f0><br />
</source><br />
<br />
At this point, if you are interested in getting some information about the output of the shrink filter, you can force it to update (which will also cause the execution of the cone source). For details about VTK's demand-driven pipeline model used by ParaView, see one of the VTK books.<br />
<br />
<source lang="python"><br />
>>> shrinkFilter.UpdatePipeline()<br />
>>> shrinkFilter.GetDataInformation().GetNumberOfCells()<br />
33L<br />
>>> shrinkFilter.GetDataInformation().GetNumberOfPoints()<br />
128L<br />
</source><br />
<br />
We will cover the DataInformation class in more detail later.<br />
<br />
==Rendering==<br />
<br />
Now that you've created a small pipeline, render the result. You will need two objects to render the output of an algorithm in a scene: a representation and a view. A representation is responsible for taking a data object and rendering it in a view. A view is responsible for managing a render context and a collection of representations. Simple creates a view by default. The representation object is created automatically with Show().<br />
<br />
<source lang="python"><br />
>>> Show(shrinkFilter)<br />
>>> Render()<br />
</source><br />
<br />
Et voila:<br />
<br />
[[File:Servermanager_snapshot.png|thumb|center|800px|'''Figure 14.1''' Server manager snapshot]]<br />
<br />
In example Figure 14.1, the value returned by Cone() and Shrink() was assigned to Python variables and used to build the pipeline. ParaView keeps track of the last pipeline object created by the user. This allows you to accomplish everything you did above using the following code:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Create a cone and assign it as the active object<br />
>>> Cone()<br />
<paraview.servermanager.Cone object at 0x2910f0><br />
# Set a property of the active object<br />
>>> SetProperties(Resolution=32)<br />
# Apply the shrink filter to the active object<br />
# Shrink is now active<br />
>>> Shrink() <br />
<paraview.servermanager.Shrink object at 0xaf64050><br />
# Show shrink<br />
>>> Show() <br />
<paraview.servermanager.UnstructuredGridRepresentation object at 0xaf57f90><br />
# Render the active view<br />
>>> Render() <br />
<paraview.servermanager.RenderView object at 0xaf57ff0><br />
</source><br />
<br />
This was a quick introduction to the paraview.simple module. In the following sections, we will discuss the Python interface in more detail and introduce more advanced concepts.<br />
<br />
=paraview.simple Module=<br />
<br />
The simple module is a ParaView component written using Python on top of the Server Manager C++ library. Its purpose is to make it easier to create ParaView data analysis and visualization pipelines using Python. The simple module can be loaded from Python interpreters running in several applications.<br />
<br />
* '''pvpython''': The pvpython application, distributed with the ParaView application suite, is a Python client to the ParaView servers. It supports interactive execution as well as batch execution.<br />
<br />
* '''pvbatch''': The pvbatch application, also distributed with the ParaView application suite, is a Python application designed to run batch scripts on distributed servers. When ParaView is compiled with MPI, pvbatch can be launched as an MPI program. In this mode, the first node will load a Python script specified as a command-line argument and execute it using a special built-in connection on all nodes. This application does not support interactive execution.<br />
<br />
* '''paraview''': Python scripts can be run from the paraview client using the Python shell that is invoked from '''Tools'''|Python Shell. The Python shell supports interactive mode as well as loading of scripts from file.<br />
<br />
* '''External Python interpreter''': Any Python-capable application can load the paraview.simple module if the right environment is configured. For this to work, you either have to install the paraview Python modules (including the right shared libraries) somewhere in sys.path or you have to set PYTHONPATH to point to the right locations. <br />
<br />
==Overview==<br />
<br />
The paraview.simple module contains several Python classes designed to be Python-friendly, as well as all classes wrapped from the C++ Server Manager library. The following sections cover the usage of this module and occasionally the paraview.servermanager module, which is lower level.<br />
<br />
==Connecting to a Server==<br />
<br />
ParaView can run in two modes: stand-alone and client/server where the server is usually a visualization cluster. In this section, we discuss how to establish a connection to a server when using ParaView in the client/server mode. If you are using the ParaView graphical interface, you should use Connect from the File menu to connect to a server. If you are using ParaView from a Python shell (not the Python console that is part of the graphical interface), you need to use ''servermanager.Connect()'' to connect a server. <em>Note: you cannot connect to the ParaView application from a stand-alone Python shell. You can only connect to a server.</em> This method takes four arguments, all of which have default values.<br />
<br />
<source lang="python"><br />
def Connect(ds_host=None, ds_port=11111, rs_host=None, rs_port=11111)<br />
</source><br />
<br />
When connecting to a server (pvserver), specify only the first two arguments. These are the server name (or IP address) and port number.<br />
<br />
When connecting to a data-server/render-server pair, you have to specify all four arguments. The first two are the host name (or IP address) and port number of the data server, the last two those of the render server.<br />
Here are some examples:<br />
<br />
<source lang="python"><br />
# Connect to pvserver running on amber1 (first node of our test cluster)<br />
# using the default port 11111<br />
>>> Connect(‘amber1’)<br />
<br />
# Connect to pvdataserver running on the amber cluster, pvrenderserver <br />
# running on Berk’s desktop<br />
>>> Connect(‘amber1’, 12000, ‘kamino’, 11111)<br />
</source><br />
<br />
Note: Connect() will return None on failure. To be safe, you should check the return value of Connect().<br />
<br />
==Getting Help==<br />
<br />
You can access the documentation of all Proxy types by using Python's built-in help.<br />
<br />
<source lang="python"><br />
>>> help(paraview.simple.Cone)<br />
Help on function CreateObject in module paraview.simple:<br />
<br />
CreateObject(*input, **params)<br />
The Cone source can be used to add a polygonal cone to the 3D scene. The output of the <br />
Cone source is polygonal data.<br />
</source><br />
<br />
To get the full documentation, you have to create an instance.<br />
<br />
<source lang="python"><br />
>>> c = Cone()<br />
>>> help(c)<br />
</source><br />
<br />
This documentation is automatically generated from the Server Manager configuration files. It is identical to the class documentation found under the ParaView Help menu, as well as here: http://paraview.org/OnlineHelpCurrent/. <br />
Beyond this document and the online help, there are a few useful documentation sources:<br />
<br />
* The ParaView Guide: http://www.kitware.com/products/paraviewguide.html<br />
<br />
* The ParaView Wiki: http://paraview.org/Wiki/ParaView<br />
<br />
* The ParaView source documentation: http://www.paraview.org/doc/ <br />
<br />
<br />
If you are interested in learning more about the Visualization Toolkit that is at the foundation of ParaView, visit http://vtk.org.<br />
<br />
=Proxies and Properties=<br />
==Proxies==<br />
<br />
The VTK Server Manager design uses the Proxy design pattern (''See Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides for details''). Quoting from Wikipedia: “A proxy, in its most general form, is a class functioning as an interface to another thing. The other thing could be anything: a network connection, a large object in memory, a file, or some other resource that is expensive or impossible to duplicate”. In the case of Server Manager, a Proxy object acts as a proxy to one-or-more VTK objects. Most of the time, these are server-side objects and are distributed to the server nodes. Proxy objects allow you to interact with these objects as if you directly have access to them, manipulate them, and obtain information about them. When creating visualization pipelines, you create proxies instead of VTK objects. <br />
<br />
<source lang="python"><br />
>>> sphereSource = vtk.vtkSphereSource() # VTK-Python script<br />
<br />
>>> sphereSourceP = Sphere() # ParaView script<br />
</source><br />
<br />
A proxy also provides an interface to modify the properties of the objects it maintains. For example, instead of:<br />
<br />
<source lang="python"><br />
>>> sphereSource.SetCenter(1.0, 1.0, 0.0)<br />
</source><br />
<br />
you can write the following:<br />
<br />
<source lang="python"><br />
>>> sphere.Center = [1.0, 1.0, 0.0]<br />
</source><br />
<br />
When a pipeline object proxy is created, it is set as the active object. You can also set an object as the active one. This is equivalent to clicking-on an object in the pipeline browser.<br />
<br />
<source lang="python"><br />
>>> c = Cone()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> GetActiveSource()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> Shrink()<br />
<paraview.servermanager.Shrink object at 0xb4f8610><br />
# Make the cone active<br />
>>> SetActiveSource(c)<br />
</source><br />
<br />
When dealing with objects created through the graphical interface or by loading a state, it is useful to be able to search through existing pipeline objects. To accomplish this, you can use GetSources() and FindSource(). GetSources() returns a dictionary of (name, id) object pairs. Since multiple objects can have the same name, the (name,id) pair identifies objects uniquely. FindSource() returns an object given its name. If there are more than one objects with the same name, the first one is returned.<br />
<br />
<source lang="python"><br />
>>> Cone()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> GetActiveSource()<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
>>> Shrink()<br />
<paraview.servermanager.Shrink object at 0xb4f8610><br />
>>> SetActiveSource(c)<br />
</source><br />
<br />
To delete pipeline objects, you need to use the Delete() function. Simply letting a Python variable go out of scope is not enough to delete the object. Following the example above:<br />
<br />
<source lang="python"><br />
# Delete the cone source<br />
>>> Delete(c)<br />
# To fully remove the cone from memory, get rid of the<br />
# variable too<br />
>>> del c<br />
</source><br />
<br />
==Properties==<br />
<br />
Property objects are used to read and modify the properties of pipeline objects. Each proxy has a list of properties defined in the Server Manager configuration files. The property interface of the Server Manager C++ library is somewhat cumbersome. Here is how you can set the radius property of a sphere source:<br />
<br />
<source lang="python"><br />
>>> rp = sphere.GetProperty("Radius")<br />
>>> rp.SetElement(0, 2)<br />
1<br />
>>> sphere.UpdateProperty("Radius")<br />
</source><br />
<br />
The servermanager module makes property access much easier by defining Python property accessors for property objects:<br />
<br />
<source lang="python"><br />
>>> sphere.Radius = 3<br />
</source><br />
<br />
Here, Radius is a Python property which, when a value is assigned to it, calls sphere.SetPropertyWithName("Radius",3). Properties can also passed to the function creating the object:<br />
<br />
<source lang="python"><br />
>>> cone = Cone(Radius=0.5, Center=[1, 0.5, 0])<br />
<paraview.servermanager.Cone object at 0xaf73090><br />
</source><br />
<br />
You can also use the SetProperties() function to set property values.<br />
<br />
<source lang="python"><br />
>>> SetProperties(cone, Radius=0.2, Center=[2, 0.5, 0])<br />
</source><br />
<br />
If the first argument is not specified, the active object is used. You also use SetDisplayProperties() and SetViewProperties() to set display (representation) and view properties respectively.<br />
<br />
All Property classes define the following methods:<br />
<br />
* __len__() <br />
* __getitem__()<br />
* __setitem__()<br />
* __getslice__()<br />
* __setslice__()<br />
* GetData()<br />
* SetData(). <br />
<br />
Therefore, all of the following are supported:<br />
<br />
<source lang="python"><br />
>>> sphere.Center<br />
[0.0, 0.0, 0.0]<br />
>>> sphere.Center[0] = 1<br />
>>> sphere.Center[0:3] = [1,2,3]<br />
>>> sphere.Center[0:3]<br />
[1.0, 2.0, 3.0]<br />
>>> len(sphere.Center)<br />
3<br />
</source><br />
<br />
ProxyProperty and InputProperty also define<br />
<br />
* append()<br />
* __delitem__()<br />
* __delslice__()<br />
<br />
to support del() and append(), similar to Python list objects.<br />
<br />
VectorProperty is used for scalars, vectors and lists of integer and floating point numbers as well as <br />
strings. Most properties of this type are simple. Examples include ''Sphere.Radius'' (double scalar), ''Sphere.Center'' (vector of doubles), ''a2DGlyph.Filled'' (boolean), ''a2DGlyph.GlyphType'' (enumeration), ''a3DText.Text'' (string), and ''Contour.Isosurfaces'' (list of doubles). Some properties may be more complicated because they map to C++ methods with mixed argument types. Two good examples of this case are ''Glyph.Scalars'' and ''ExodusIIReader.PointVariables''.<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName='.../can.ex2')<br />
# These variables are currently selected<br />
>>> reader.PointVariables<br />
['DISPL', 'VEL', 'ACCL']<br />
# These are available in the file<br />
>>> reader.PointVariables.Available<br />
['DISPL', 'VEL', 'ACCL']<br />
# Enable the DISPL array only<br />
>>> reader.PointVariables = ['DISPL']<br />
# Force read<br />
>>> reader.UpdatePipeline()<br />
# Now check the output. Note: GlobalNodeId is generated automatically by the reader.<br />
>>> reader.PointData[:]<br />
[Array: GlobalNodeId, Array: PedigreeNodeId, Array: DISPL]<br />
</source><br />
<br />
This example demonstrates the use of ''ExodusIIReader.PointVariables''. This is a VectorProperty that represents a list of array names. The underlying C++ function has a signature of SetPointResultArrayStatus(const char* name, int flag). This method is usually called once per array to enable or disable it (i.e. to set whether the reader will read a particular array).<br />
<br />
Glyph.Scalars is a bit more complicated. This property allows the developer to select the scalar array with which to scale the glyphs.<br />
<br />
<source lang="python"><br />
>>> sph = Sphere()<br />
>>> elev=Elevation(sph)<br />
# Glyph the points of the sphere with spheres<br />
>>> glyph=Glyph(elev, GlyphType='Sphere')<br />
# Scale the glyph with the Elevation array<br />
>>> glyph.Scalars = 'Elevation'<br />
>>> glyph.Scalars<br />
['POINTS', 'Elevation']<br />
# The above shows the association of the array as well as its name.<br />
# In this case, the array is associated with POINTS as it has to be<br />
# since Glyph cannot scale by cell arrays. We could have done:<br />
>>> glyph.Scalars = ['POINTS', 'Elevation']<br />
# Enable scaling by scalars<br />
>>> glyph.ScaleMode = 'scalar'<br />
</source><br />
<br />
Here the property Scalars maps to SetInputArrayToProcess(int idx, int port, int connection, int fieldAssociation, const char *name), which has four integer arguments (some of which are enumeration) and one string argument (''see vtkAlgorithm documentation for details'').<br />
<br />
Properties are either regular (push) or information (pull) properties. Information properties do not have a VTK method associated with them and are responsible for getting information from the server. A good example of an information property is TimestepValues, which returns all time steps available in a file (if the reader supports time).<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName='.../can.ex2')<br />
>>> reader.TimestepValues<br />
[0.0, 0.00010007373930420727, 0.00019990510190837085, 0.00029996439116075635, 0.00040008654468692839,<br />
0.00049991923151537776, 0.00059993512695655227, 0.00070004, ...]<br />
</source><br />
<br />
You can obtain a list of properties a proxy supports by using ''help()''. However, this does not allow introspection programmatically. If you need to obtain information about a proxy’s properties programmatically, you can use a property iterator:<br />
<br />
<source lang="python"><br />
>>> for prop in glyph:<br />
print type(prop), prop.GetXMLLabel()<br />
<br />
<class 'paraview.servermanager.InputProperty'> Input<br />
<class 'paraview.servermanager.VectorProperty'> Maximum Number of Points<br />
<class 'paraview.servermanager.VectorProperty'> Random Mode<br />
<class 'paraview.servermanager.ArraySelectionProperty'> Scalars<br />
<class 'paraview.servermanager.ArraySelectionProperty'> Vectors<br />
<class 'paraview.servermanager.VectorProperty'> Orient<br />
<class 'paraview.servermanager.VectorProperty'> Set Scale Factor<br />
<class 'paraview.servermanager.EnumerationProperty'> Scale Mode<br />
<class 'paraview.servermanager.InputProperty'> Glyph Type<br />
<class 'paraview.servermanager.VectorProperty'> Mask Points<br />
</source><br />
<br />
The XMLLabel is the text display by the graphical user-interface. Note that there is a direct mapping from the XMLLabel to the property name. If you remove all spaces from the label, you get the property name. You can use the ''PropertyIterator'' object directly.<br />
<br />
<source lang="python"><br />
>>> it = iter(s)<br />
>>> for i in it:<br />
print it.GetKey(), it.GetProperty()<br />
</source><br />
<br />
==Domains==<br />
<br />
The Server Manager provides information about values that are valid for properties. The main use of this information is for the user-interface to provide good ranges and choices in enumeration. However, some of this information is also very useful for introspection. For example, enumeration properties look like simple integer properties unless a (value, name) pair is associated with them. The Server Manager uses Domain objects to store this information. The contents of domains may be loaded from xml configuration files or computed automatically. For example:<br />
<br />
<source lang="python"><br />
>>> s = Sphere()<br />
>>> Show(s)<br />
>>> dp = GetDisplayProperties(s)<br />
>>> dp.Representation<br />
'Surface'<br />
# The current representation type is Surface. What other types<br />
# are available?<br />
>>> dp.GetProperty("Representation").Available<br />
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']<br />
# Choose outline<br />
>>> dp.Representation = 'Outline'<br />
</source><br />
<br />
==Source Proxies==<br />
<br />
Source proxies are proxies that represent pipeline objects (''For more information about VTK pipelines, see the VTK books: http://vtk.org/buy-books.php''). They have special properties to connect them as well as special method to query the meta-data of their output. To connect a source proxy to another, use one of its input properties.<br />
<br />
<source lang="python"><br />
# Either<br />
>>> glyph = Glyph(elev)<br />
# or<br />
>>> glyph.Input = elev<br />
</source><br />
<br />
The SourceProxy class provides several additional properties and methods that are specific to pipelines (See vtkSMSourceProxy documentation for a full list).<br />
* '''UpdatePipelineInformation()''': This method calls UpdateInformation() on the VTK algorithm. It also calls UpdatePropertyInformation() to update any information properties.<br />
* '''UpdatePipeline()''': This method calls Update() on the VTK algorithm causing a pipeline execution if the pipeline changed. Another way of causing pipeline updates is to render. The render view updates all connected pipelines.<br />
* '''GetDataInformation()''': This method is used to obtain meta-data about one output. It is discussed further below.<br />
* PointData and CellData properties discussed below.<br />
<br />
There are two common ways of getting meta-data information from a proxy: information properties and DataInformation. Information properties are updated automatically every time UpdatePropertyInformation() and UpdatePipelineInformation() are called. All you have to do is read the data from the property as usual. To get a DataInformation object from a source proxy use ''GetDataInformation(port=0''). By default, this method returns data information for the first output. You can pass an optional port number to get information for another output. You can get detailed documentation on DataInformation by using help() and by reading online documentation for vtkPVDataInformation (''http://www.paraview.org/doc/nightly/html/classvtkPVDataInformation.html''). Here are the use of some common methods:<br />
<br />
<source lang="python"><br />
>>> di = glyph.GetDataInformation(0)<br />
>>> di<br />
<paraview.servermanager.DataInformation object at 0x2d0920d0><br />
>>> glyph.UpdatePipeline()<br />
# Get the data type.<br />
>>> di.GetDataClassName()<br />
'vtkPolyData'<br />
# Get information about point data. <br />
>>> pdi = glyph.PointData<br />
# We are now directly accessing the wrapper for a VTK class<br />
>>> len(pdi)<br />
2<br />
# Get information for a point array<br />
>>> ai = pdi[0]<br />
>>> ai.GetRange(0)<br />
(0.0, 0.5)<br />
</source><br />
<br />
When meta-data is not enough and you need access to the raw data, you can use Fetch() to bring it to the client side. Note that this function is provided by the servermanager module. Fetch() has three modes:<br />
<br />
*Append all of the data together and bring it to the client (only available for polygonal and unstructured datasets). Note: Do not do this if data is large otherwise the client will run out of memory.<br />
<br />
*Bring data from a given process to the client.<br />
<br />
*Use a reduction algorithm and bring its output to the client. For example, find the minimum value of an attribute.<br />
<br />
Here is a demonstration:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
>>> Connect("kamino")<br />
Connection (kamino:11111)<br />
>>> s = Sphere()<br />
# Get the whole sphere. DO NOT DO THIS IF THE DATA IS LARGE otherwise<br />
# the client will run out of memory.<br />
>>> allsphere = servermanager.Fetch(s)<br />
getting appended<br />
use append poly data filter<br />
>>> allsphere.GetNumberOfPolys()<br />
96<br />
# Get the piece of the sphere on process 0.<br />
>>> onesphere = servermanager.Fetch(s, 0)<br />
getting node 0<br />
>>> onesphere.GetNumberOfPolys()<br />
48<br />
# Apply the elevation filter so that we have a useful scalar array.<br />
>>> elev = Elevation(s)<br />
# We will use the MinMax algorithm to compute the minimum value of<br />
# elevation. MinMax will be first applied on each processor. The results<br />
# will then be gathered to the first node. MinMax will be then applied<br />
# to the gathered results.<br />
# We first create MinMax without an input.<br />
>>> mm = MinMax(None)<br />
# Set it to compute min<br />
>>> mm.Operation = "MIN"<br />
# Get the minimum<br />
>>> mindata = servermanager.Fetch(elev, mm, mm)<br />
applying operation<br />
# The result is a vtkPolyData with one point<br />
>>> mindata.GetPointData().GetNumberOfArrays()<br />
2<br />
>>> a0 = mindata.GetPointData().GetArray(1)<br />
>>> a0.GetName()<br />
'Elevation'<br />
>>> a0.GetTuple1(0)<br />
0.0<br />
</source><br />
<br />
==Representations and Views==<br />
<br />
Once a pipeline is created, it can be rendered using representations and views. A view is essentially a “window” in which multiple representations can be displayed. When the view is a VTK view (such as RenderView), this corresponds to a collection of objects including vtkRenderers and a vtkRenderWindow. However, there is no requirement for a view to be a VTK view or to render anything. A representation is a collection of objects, usually a pipeline, that takes a data object, converts it to something that can be rendered, and renders it. When the view is a VTK view, this corresponds to a collection of objects including geometry filters, level-of-detail algorithms, vtkMappers and vtkActors. The simple module automatically creates a view after connecting to a server (including the built-in connection when using the stand-alone mode). Furthermore, the simple module creates a representation the first time a pipeline object is displayed with Show().<br />
It is easy to create new views.<br />
<br />
<source lang="python"><br />
>>> view = CreateRenderView()<br />
</source><br />
<br />
CreateRenderView() is a special method that creates the render view appropriate for the ActiveConnection (or for another connection specified as an argument). It returns a sub-class of Proxy. Like the constructor of Proxy, it can take an arbitrary number of keyword arguments to set initial values for properties. Note that ParaView makes the view that was created last the active view. When using Show() without a view argument, the pipeline is shown in the active view. You can get a list of views as well as the active view as follows:<br />
<br />
<source lang="python"><br />
>>> GetRenderViews()<br />
[<paraview.servermanager.RenderView object at 0xaf64ef0>, <paraview.servermanager.RenderView object at 0xaf64b70>]<br />
>>> GetActiveView()<br />
<paraview.servermanager.RenderView object at 0xaf64b70><br />
</source><br />
<br />
You can also change the active view using SetActiveView().<br />
<br />
Once you have a render view, you can use pass it to Show in order to select in which view a pipeline object is displayed. You can also pass it to Render() to select which view is rendered.<br />
<br />
<source lang="python"><br />
>>> Show(elev, GetRenderViews()[1])<br />
<paraview.servermanager.GeometryRepresentation object at 0xaf64e30><br />
>>> Render(GetRenderViews()[1])<br />
</source><br />
<br />
Notice that Show() returns a representation object (aka DisplayProperties in the simple module). This object can be used to manipulate how the pipeline object is displayed in the view. You can also access the display properties of an object using GetDisplayProperties().<br />
<br />
<source lang="python"><br />
>>> dp = GetDisplayProperties(elev)<br />
>>> dp<br />
<paraview.servermanager.GeometryRepresentation object at 0xaf649d0><br />
</source><br />
<br />
Display properties and views have a large number of properties some of which are poorly documented. We will cover some them here.<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Create a simple pipeline<br />
>>> sph = Sphere()<br />
>>> elev = Elevation(sph)<br />
>>> Show(elev)<br />
>>> Render()<br />
# Set the representation type of elev<br />
>>> dp = GetDisplayProperties(elev)<br />
>>> dp.Representation = 'Points'<br />
# Here is how you get the list of representation types<br />
>>> dp.GetProperty("Representation").Available<br />
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']<br />
>>> Render()<br />
# Change the representation to wireframe<br />
>>> dp.Representation = 'Wireframe'<br />
>>> Render()<br />
# Let’s get some information about the output of the elevation<br />
# filter. We want to color the representation by one of it’s<br />
# arrays.<br />
# Second array = Elevation. Interesting. Let’s use this one.<br />
>>> ai = elev.PointData[1]<br />
>>> ai.GetName()<br />
'Elevation'<br />
# What is its range?<br />
>>> ai.GetRange()<br />
(0.0, 0.5)<br />
# To color the representation by an array, we need to first create<br />
# a lookup table. We use the range of the Elevation array<br />
>>> dp.LookupTable = MakeBlueToRedLT(0, 0.5)<br />
>>> dp.ColorAttributeType = 'POINT_DATA'<br />
>>> dp.ColorArrayName = 'Elevation' # color by Elevation<br />
>>> Render()<br />
</source><br />
<br />
Here is the result:<br />
[[Image:SMView.png|thumb|center|800px|'''Figure 14.2''' Object displayed in a view]]<br />
<br />
<br />
Once you create a scene, you will probably want to interact with the camera and ResetCamera() is likely to be insufficient. In this case, you can directly get the camera from the view and manipulate it. GetActiveCamera() returns a VTK object (not a proxy) with which you can interact.<br />
<br />
<source lang="python"><br />
>>> camera = GetActiveCamera()<br />
>>> camera<br />
<libvtkCommonPython.vtkCamera vtkobject at 0xe290><br />
>>> camera.Elevation(45)<br />
>>> Render()<br />
</source><br />
<br />
Another common thing to do is to save the view as an image. For this purpose, you can use the WriteImage() method provided by the view:<br />
<br />
<source lang="python"><br />
>> WriteImage("/Users/berk/image.png")<br />
</source><br />
<br />
The resulting image.png looks like this. See the documentation for WriteImage() for details on choosing file type, as well as a magnification factor to save images larger than the view size.<br />
<br />
[[Image:Image.jpg|thumb|center|800px|'''Figure 14.3''' Saving a view as an image]]<br />
<br />
=Advanced Concepts=<br />
<br />
==Dealing with lookup tables==<br />
In v4.1 LUT manipulation was simplified so that the LUTs found in the GUI may be assigned to arrays by name. See [[ParaView/Python/Lookup_tables | Lookup tables recipe]] for more information. <br />
<br />
As shown earlier, you can use MakeBlueToRedLt(min, max) to create a lookup table. However, this simply creates a new lookup table that the GUI won't be aware of. In the ParaView Qt application, we have special lookup table management that ensures that the same lookup table is used for all arrays with same name and number of components. To reproduce the same behavior in Python, use GetLookupTableForArray().<br />
<br />
<source lang="python"><br />
def GetLookupTableForArray(arrayname, num_components, **params):<br />
"""Used to get an existing lookuptable for a array or to create one if none<br />
exists. Keyword arguments can be passed in to initialize the LUT if a new<br />
one is created. Returns the lookup table."""<br />
....<br />
</source><br />
<br />
This will create a new lookup table and associate it with that array, if none already exists. Any default arguments to be passed to the lookup table if a new one is created, can be specified as additional parameters. You can always change the properties on the lookup table returned by this function.<br />
<br />
<br />
<source lang="python"><br />
# To color the representation by an array, we need to first create<br />
# a lookup table. We use the range of the Elevation array<br />
>>> dp.LookupTable = GetLookupTableForArray("Elevation", 1,<br />
RGBPoints = [min, 0, 0, 1, max, 1, 0, 0],<br />
ColorSpace = "HSV")<br />
>>> dp.ColorAttributeType = 'POINT_DATA'<br />
>>> dp.ColorArrayName = 'Elevation' # color by Elevation<br />
>>> Render()<br />
</source><br />
<br />
==Loading State and Manipulating It==<br />
<br />
Let’s say you created a complicated visualization using the paraview application and now you want to make slight changes to it and run it in a loop as a batch script. What do you do? The best way of dealing with this is to save your visualization state and then load it from Python. Let’s say you have a state file saved as myteststate.pvsm:<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
# Load the state<br />
>>> servermanager.LoadState("/Users/berk/myteststate.pvsm")<br />
# Make sure that the view in the state is the active one<br />
>>> SetActiveView(GetRenderView())<br />
# Now render<br />
>>> Render()<br />
# Get the list of sources<br />
>>> GetSources()<br />
{('Sphere1', '5'): <paraview.servermanager.Sphere object at 0xaf80e30>, <br />
('Shrink1', '11'): <paraview.servermanager.Shrink object at 0xaf80df0>, <br />
('Cone1', '8'): <paraview.servermanager.Cone object at 0xaf80cf0>}<br />
# Change the resolution of the cone and render again<br />
>>> FindSource("Cone1").Resolution = 32<br />
>>> Render()<br />
</source><br />
<br />
You can also save state.<br />
<br />
<source lang="python"><br />
>>> from paraview.simple import *<br />
>>> sph = Sphere()<br />
>>> Render()<br />
>>> servermanager.SaveState("/Users/berk/pythonstate.pvsm")<br />
</source><br />
<br />
==Dealing with Time==<br />
<br />
If a reader or a filter supports time, it is easy to request a certain time step from Python. All time requests are set on views that then propagate them to the representations which then propagate them to the visualization pipeline. Here is an example demonstrating how a time request can be made:<br />
<br />
<source lang="python"><br />
>>> Show(ExodusIIReader(FileName=".../can.ex2"))<br />
>>> Render()<br />
# Get a nice view angle<br />
>>> cam = GetActiveCamera()<br />
>>> cam.Elevation(45)<br />
>>> Render()<br />
# Check the current view time<br />
>>> view = GetActiveView()<br />
>>> view.ViewTime<br />
0.0<br />
>>> reader = GetActiveSource()<br />
>>> reader.TimestepValues<br />
[0.0, 0.00010007373930420727, 0.00019990510190837085, <br />
0.00029996439116075635, 0.00040008654468692839, <br />
...]<br />
>>> tsteps = reader.TimestepValues<br />
# Let’s be fancy and use a time annotation filter. This will show the<br />
# current time value of the reader as text in the corner of the view.<br />
>>> annTime = AnnotateTimeFilter(reader)<br />
# Show the filter<br />
>>> Show(annTime)<br />
# Look at a few time steps. Note that the time value is requested not<br />
# the time step index.<br />
>>> view.ViewTime = tsteps[2]<br />
>>> Render()<br />
>>> view.ViewTime = tsteps[4]<br />
>>> Render()<br />
</source><br />
<br />
==Animating==<br />
<br />
Server Manager has a complicated animation engine based on keyframes and scenes. This section will introduce a few simple ways of animating your visualization. <br />
If you have a time-aware reader, you can animate it with AnimateReader().<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName=“.../can.ex2”)<br />
>>> Show(reader)<br />
>>> Render()<br />
>>> c = GetActiveCamera()<br />
>>> c.Elevation(95)<br />
# Animate over all time steps. Note that we are not passing the optional<br />
# 3rd argument here. If you pass a filename as the 3rd argument, <br />
# AnimateReader will create a movie.<br />
>>> AnimateReader(reader)<br />
# Save the animation to an avi file<br />
>>> AnimateReader(reader, filename=".../movie.avi")<br />
</source><br />
<br />
To animate properties other than time, you can use regular keyframes.<br />
<br />
'''''ParaView 3.8.0 and earlier'''''<br />
----<br />
<font color="blue">Although the following script will work with 3.8.1 and later, it's not the recommended way since the changes done so will not be reflected in the GUI. Refer to the following sub-section for the recommended style for 3.8.1 and later versions.</font><br />
<br />
<source lang="python"><br />
>>> Sphere()<br />
>>> Show()<br />
>>> Render()<br />
<br />
# Create an animation scene<br />
>>> scene = servermanager.animation.AnimationScene()<br />
# Add one view<br />
>>> scene.ViewModules = [GetActiveView()]<br />
<br />
# Create a cue to animate the StartTheta property<br />
>>> cue = servermanager.animation.KeyFrameAnimationCue()<br />
>>> cue.AnimatedProxy = GetActiveSource()<br />
>>> cue.AnimatedPropertyName = "StartTheta"<br />
# Add it to the scene's cues<br />
>>> scene.Cues = [cue]<br />
<br />
# Create 2 keyframes for the StartTheta track<br />
>>> keyf0 = servermanager.animation.CompositeKeyFrame()<br />
>>> keyf0.Interpolation = 'Ramp'<br />
# At time = 0, value = 0<br />
>>> keyf0.KeyTime = 0<br />
>>> keyf0.KeyValues= [0]<br />
<br />
>>> keyf1 = servermanager.animation.CompositeKeyFrame()<br />
# At time = 1.0, value = 200<br />
>>> keyf1.KeyTime = 1.0<br />
>>> keyf1.KeyValues= [200]<br />
<br />
# Add keyframes.<br />
>>> cue.KeyFrames = [keyf0, keyf1]<br />
<br />
>>> scene.Play()<br />
<br />
# Some properties you can change<br />
#<br />
# Number of frames used in Sequence mode<br />
# scene.NumberOfFrames = 100<br />
#<br />
# Or you can use real time mode<br />
# scene.PlayMode = 'Real Time'<br />
# scene.Duration = 20<br />
</source><br />
<br />
<br />
'''ParaView 3.8.1 onwards'''<br />
----<br />
<font color="blue">The following script will only work with ParaView versions 3.8.1 and later.<br />
It is now the recommended way for accessing animation scenes and tracks since the updates<br />
are reflected in the GUI when running through the Python shell from the ParaView application.<br />
</font><br />
<br />
<source lang="python"><br />
>>> Sphere()<br />
>>> Show()<br />
>>> Render()<br />
<br />
# Get the application-wide animation scene<br />
>>> scene = GetAnimationScene()<br />
<br />
# Get the animation track for animating "StartTheta" on the active source.<br />
# GetAnimationTrack() creates a new track if none exists.<br />
>>> cue = GetAnimationTrack("StartTheta")<br />
<br />
# Create 2 keyframes for the StartTheta track<br />
>>> keyf0 = CompositeKeyFrame()<br />
>>> keyf0.Interpolation = 'Ramp'<br />
# At time = 0, value = 0<br />
>>> keyf0.KeyTime = 0<br />
>>> keyf0.KeyValues= [0]<br />
<br />
>>> keyf1 = CompositeKeyFrame()<br />
# At time = 1.0, value = 200<br />
>>> keyf1.KeyTime = 1.0<br />
>>> keyf1.KeyValues= [200]<br />
<br />
# Add keyframes.<br />
>>> cue.KeyFrames = [keyf0, keyf1]<br />
<br />
>>> scene.Play()<br />
<br />
# Some properties you can change<br />
#<br />
# Number of frames used in Sequence mode<br />
# scene.NumberOfFrames = 100<br />
#<br />
# Or you can use real time mode<br />
# scene.PlayMode = 'Real Time'<br />
# scene.Duration = 20<br />
</source><br />
<br />
===GetAnimationTrack Usages===<br />
----<br />
<br />
<source lang="python"><br />
<br />
# Typical usage<br />
>>> track = GetAnimationTrack("Center", 0, sphere) or<br />
>>> track = GetAnimationTrack(sphere.GetProperty("Radius")) or<br />
<br />
# this returns the track to animate visibility of the active source in<br />
# all views.<br />
>>> track = GetAnimationTrack("Visibility")<br />
<br />
# For animating properties on implicit planes etc., use the following<br />
# signatures:<br />
>>> track = GetAnimationTrack(slice.SliceType.GetProperty("Origin"), 0) or<br />
>>> track = GetAnimationTrack("Origin", 0, slice.SliceType)<br />
<br />
</source><br />
<br />
==Loading Data Files==<br />
<br />
As seen throughout this document, you can always load a data file by explicitly creating the reader that can read the data file as follows:<br />
<br />
<source lang="python"><br />
>>> reader = ExodusIIReader(FileName=“.../can.ex2”)<br />
</source><br />
<br />
Alternatively, starting with ParaView 3.8, you can use OpenDataFile() function to let ParaView pick a reader using the extension of the file.<br />
<br />
<source lang="python"><br />
>>> reader = OpenDataFile(“.../can.ex2”)<br />
</source><br />
<br />
<br />
==Writing Data Files (ParaView 3.9 or later)==<br />
<br />
To create a writer to write the output from a source, one can use the following:<br />
<br />
<source lang="python"><br />
from paraview.simple import *<br />
<br />
# Specifying the source explicitly<br />
>>> writer= CreateWriter("/.../filename.vtk", source)<br />
<br />
# Using the active source<br />
>>> writer= CreateWriter("/.../filename.vtk")<br />
<br />
# Writing data from a particular output port<br />
>>> writer= CreateWriter("/.../filename.vtk", servermanager.OutputPort(source, 1))<br />
<br />
# Now one change change the ivars on the writer <br />
<br />
# To do the actual writing, use:<br />
>>> writer.UpdatePipeline()<br />
<br />
</source><br />
<br />
==Exporting CSV Data==<br />
<br />
To export a csv from the cell or point data associated with a source, one can use the following:<br />
<br />
<source lang="python"><br />
>>> writer = CreateWriter(".../foo.csv", source)<br />
>>> writer.FieldAssociation = "Points" # or "Cells"<br />
>>> writer.UpdatePipeline()<br />
>>> del writer<br />
</source><br />
<br />
==Updating View Layout==<br />
<br />
Starting with ParaView 3.14, Python scripts can be used to update view layout.<br />
<br />
Every tab in the central frame of the ParaView application is represented by '''layout''' proxy. To obtain a map of layout proxies present, use the GetLayouts().<br />
<br />
<source lang="python"><br />
>>> GetLayouts()<br />
{('ViewLayout1', '264'): <paraview.servermanager.ViewLayout object at 0x2e5b7d0>}<br />
</source><br />
<br />
To get the layout corresponding to the active view (or a particular view), use the GetLayout() function.<br />
<br />
<source lang="python"><br />
>>> GetLayout()<br />
<paraview.servermanager.ViewLayout object at 0x2e5b7d0><br />
>>><br />
>>> GetLayout(GetActiveView())<br />
<paraview.servermanager.ViewLayout object at 0x2e5b7d0><br />
</source><br />
<br />
To split the cell containing a particular view, either horizontally or vertically, use:<br />
<br />
<source lang="python"><br />
<br />
>>> layout.SplitViewVertical(view = GetActiveView())<br />
<br />
>>> layout.SplitViewHorizontal(view = GetActiveView(), fraction = 0.7)<br />
<br />
</source><br />
<br />
To resize a cell containing a particular view:<br />
<br />
<source lang="python"><br />
<br />
>>> location = layout.GetViewLocation(view)<br />
>>> layout.SetSplitFraction(location, 0.3)<br />
<br />
</source><br />
<br />
To maximize a particular view<br />
<source lang="python"><br />
<br />
>>> location = layout.GetViewLocation(view)<br />
>>> layout.MaximizeCell(location)<br />
<br />
</source><br />
<br />
There are a host of other methods that are available that can help with layout of the views. Refer to the API exposed by vtkSMViewLayoutProxy. The API is fully accessible through Python.<br />
<br />
To create a new tab, one can use the following piece of code:<br />
<br />
<source lang="python"><br />
<br />
new_layout = servermanager.misc.ViewLayout(registrationGroup="layouts")<br />
<br />
</source><br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/EnvironmentSetup&diff=57215ParaView/EnvironmentSetup2014-12-30T21:00:01Z<p>DWilches: </p>
<hr />
<div>== Before starting ==<br />
<br />
Ensure that you have performed the steps from the "Getting Started" section of [[ParaView/Python Scripting]]. More concretely, you must have setup the variable <tt>PYTHONPATH</tt> to the indicated initial value to avoid some missing packages when using [[Python Programmable Filter|Programmable Filters]].<br />
<br />
==Linux==<br />
You must add this to your .bashrc to run anything in a ProgrammableFilter.<br />
<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping/site-packages #fixes "no module named paraview"<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/bin #fixes "ImportError: No module named libvtkCommonPython"<br />
<br />
Note that for older versions of ParaView the first line may need to be replaced by:<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/EnvironmentSetup&diff=57214ParaView/EnvironmentSetup2014-12-30T20:58:57Z<p>DWilches: </p>
<hr />
<div>== Before starting ==<br />
<br />
Ensure that you have performed the steps from the "Getting Started" section of [[ParaView/Python Scripting]]. More concretely, you must have setup the variable <tt>PYTHONPATH</tt> to the indicated initial value to avoid some missing packages when using Programmable Filters.<br />
<br />
==Linux==<br />
You must add this to your .bashrc to run anything in a ProgrammableFilter.<br />
<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping/site-packages #fixes "no module named paraview"<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/bin #fixes "ImportError: No module named libvtkCommonPython"<br />
<br />
Note that for older versions of ParaView the first line may need to be replaced by:<br />
export PYTHONPATH=$PYTHONPATH:/home/doriad/bin/ParaView/Utilities/VTKPythonWrapping</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView/Plugin_HowTo&diff=57213ParaView/Plugin HowTo2014-12-30T04:44:05Z<p>DWilches: Added solution to a problem I found while compiling a plugin</p>
<hr />
<div>== Introduction ==<br />
ParaView comes with plethora of functionality bundled in: several readers, multitude of filters, quite a few different types of views etc. However, it is not uncommon for developers to want to add new functionality to ParaView for eg. to add support to their new file format, incorporate a new filter into paraview etc. ParaView makes it possible to add new functionlity by using an extensive plugin mechanism. <br />
<br />
Plugins can be used to extend ParaView in several ways:<br />
* Add new readers, writers, filters <br />
* Add custom GUI components such as toolbar buttons to perform common tasks<br />
* Add new views in for display data<br />
<br />
Examples for different types of plugins are provided with the ParaView source under '''Examples/Plugins/'''.<br />
<br />
This document has major sections:<br />
* First section covers how to use existing plugins in ParaView.<br />
* Second section contains information for developers about writing new plugins for ParaView.<br />
<br />
== Using Plugins ==<br />
<br />
Plugins are distributed as shared libraries (*.so on Unix, *.dylib on Mac, *.dll on Windows etc). For a plugin to be loadable in ParaView, it must be built with the same version of ParaView as it is expected to be deployed on. Plugins can be classified into two broad categories:<br />
* Server-side plugins<br />
: These are plugins that extend the algorithmic capabilities for ParaView eg. new filters, readers, writers etc. Since in ParaView data is processed on the server-side, these plugins need to be loaded on the server.<br />
* Client-side plugins<br />
: These are plugins that extend the ParaView GUI eg. property panels for new filters, toolbars, views etc. These plugins need to be loaded on the client.<br />
<br />
Oftentimes a plugin has both server-side as well as client-side components to it eg. a plugin that adds a new filter and a property panel that goes with that filter. Such plugins need to be loaded both on the server as well as the client. <br />
<br />
Generally, users don't have to worry whether a plugin is a server-side or client-side plugin. Simply load the plugin on the server as well as the client. ParaView will include relevant components from plugin on each of the processes.<br />
<br />
There are four ways for loading plugins:<br />
<br />
* Using the GUI ('''Plugin Manager''')<br />
: Plugins can be loaded into ParaView using the '''Plugin Manager''' accessible from '''Tools | Manage Plugins/Extensions''' menu. The Plugin Manager has two sections for loading local plugins and remote plugins (enabled only when connected to a server). To load a plugin on the local as well as remote side, simply browse to the plugin shared library. If the loading is successful, the plugin will appear in the list of loaded plugins. The Plugin manager also lists the paths it searched to load plugins automatically.<br />
: The Plugin Manager remembers all loaded plugins, so next time to load the plugin, simply locate it in the list and click "Load Selected" button. <br />
: You can set up ParaView to automatically load the plugin at startup (in case of client-side plugins) or on connecting to the server (in case of server-side plugins) by checking the "Auto Load" checkbox on a loaded plugin.<br />
<table><br />
<tr><br />
<td><br />
[[Image:LocalPlugin_Manager.png|thumb|300px|'''Figure 1:''' Plugin Manager when not connected to a remote server, showing loaded plugins on the local site.''']]<br />
</td><br />
<td><br />
[[Image:RemotePlugin_Manager.png|thumb|300px|'''Figure 2:''' Plugin Manager when connected to a server showing loaded plugins on the local as well as remote sites.''']]<br />
</td><br />
</table><br />
* Using environment variable (Auto-loading plugins)<br />
: If one wants ParaView to automatically load a set of plugins on startup, one can use the '''PV_PLUGIN_PATH''' environment variable. '''PV_PLUGIN_PATH''' can be used to list a set of directories (separated by colon (:) or semi-colon (;)) which ParaView will search on startup to load plugins. This environment variable needs to be set on both the client node to load local plugins as well as the remote server to load remote plugins. Note that plugins in PV_PLUGIN_PATH are always auto-loaded irrespective of the status of the "Auto Load" checkbox in the Plugin Manager.<br />
* Using the plugin file '''.plugins'''(Make plugins available and possibly Auto-load plugins)<br />
: Plugins that are listed in the '''.plugins''' file on the client computer and server cluster will automatically be listed in the Plugin Manager, and optionally can be auto loaded. The '''.plugins''' file is automatically created at ParaView build time and includes all plugins that ParaView built. The '''.plugins''' file should be in the same directory as '''pvserver'''. An example '''.plugins''' file, auto loading H5PartReader, looks like this:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0"?><br />
<Plugins><br />
<Plugin name="Moments" auto_load="0"/><br />
<Plugin name="PrismPlugin" auto_load="0"/><br />
<Plugin name="PointSprite_Plugin" auto_load="0"/><br />
<Plugin name="pvblot" auto_load="0"/><br />
<Plugin name="SierraPlotTools" auto_load="0"/><br />
<Plugin name="H5PartReader" auto_load="1"/><br />
</Plugins><br />
</source><br />
* Placing the plugins in a recognized location. Recognized locations are:<br />
** A plugins subdirectory beneath the directory containing the paraview client or server executables. This can be a system-wide location if installed as such.<br />
** A Plugins subdirectory in the user's home area. On Unix/Linux/Mac, $HOME/.config/ParaView/ParaView<version>/Plugins. On Windows %APPDATA$\ParaView\ParaView<version>\Plugins.<br />
<br />
==Debugging Plugins==<br />
If plugin loading failed, try setting the '''PV_PLUGIN_DEBUG''' environment variable for all processes that you were trying to load the plugin on. ParaView will then try to print verbose information about each step and causes for failure, as show below.<br />
<br />
----<br />
<br />
<source lang="python"><br />
<br />
***************************************************<br />
Attempting to load /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin/libSurfaceLIC.so<br />
Loaded shared library successfully. Now trying to validate that it's a ParaView plugin.<br />
Plugin's signature: paraviewplugin|GNU|3.7<br />
Plugin signature verification successful. This is definitely a ParaView plugin compiled with correct compiler for correct ParaView version.<br />
Updating Shared Library Paths: /home/utkarsh/Kitware/ParaView3/ParaView3Bin/bin<br />
Plugin instance located successfully. Now loading components from the plugin instance based on the interfaces it implements.<br />
----------------------------------------------------------------<br />
Plugin Information: <br />
Name : SurfaceLIC<br />
Version : 1.0<br />
ReqOnServer : 1<br />
ReqOnClient : 1<br />
ReqPlugins : <br />
ServerManager Plugin : Yes<br />
Python Plugin : No<br />
</source><br />
<br />
----<br />
<br />
<font color="magenta">Plugin debug information is not available for ParaView 3.6 or earlier</font><br />
<br />
== Writing Plugins ==<br />
This section covers writing and compiling different types of Plugins. To create a plugin, one must have their own build of ParaView3. Binaries downloaded from www.paraview.org do not include necessary header files or import libraries (where applicable) for compiling plugins.<br />
<br />
The beginning of a CMakeLists.txt file contains<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
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.<br />
<br />
=== Adding a Filter ===<br />
<br />
In this plugin, we want to add a new filter to ParaView. The filter has to be a VTK-based algorithm, written as following the standard procedures for writing VTK algorithms. Generally for such cases where we are adding a new VTK class to ParaView (be it a filter, reader or a writer), we need to do the following tasks:<br />
* Write a '''Server Manager Configuration XML''' which describes the ''Proxy'' interface for the new VTK class. Basically, this defines the interface for the client to create and modify instances of the new class on the server side. Please refer to the [http://www.kitware.com/products/books/paraview.html ParaView Guide] for details about writing these server-manager xmls.<br />
* Write a configuration XML for the GUI to make ParaView GUI aware of this new class, if applicable. For filters, this is optional, since ParaView automatically recognizes filters added through plugins and lists them in the '''Alphabetical''' sub-menu. One may use the GUI configuration xml to add the new filter to a specific category in the ''Filters'' menu, or add a new category etc. For readers and writers, this is required since ParaView GUI needs to know what extensions your reader/writer supports etc.<br />
<br />
==== Enabling an existing VTK filter ====<br />
<br />
Sometimes, the filter that one wants to add to ParaView is already available in VTK, it's just not exposed through the ParaView GUI. This is the easiest type of plugin to create. There are two options: 1) setup the plugin using only an XML file and 2) actually compile the plugin into a shared library. The first option is the easiest, but the second option will prepare you for creating a custom filter in the future as the process is nearly identical. <br />
<br />
===== XML Only =====<br />
If you have not built Paraview from source, using an xml plugin is your only option.<br />
<br />
We need to write the server manager configuration xml for the filter describing its API. The GUI xml to add the filter to any specific category is optional. <br />
<br />
For example, let's say we simply want to expose the '''vtkCellDerivatives''' in VTK. Then first, we'll write the server manager configuration XML (call it CellDerivatives.xml), similar to what we would have done for adding a new filter. <br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyCellDerivatives" class="vtkCellDerivatives" label="My Cell Derivatives"><br />
<Documentation<br />
long_help="Create point attribute array by projecting points onto an elevation vector."<br />
short_help="Create a point array representing elevation."><br />
</Documentation><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
At this point, we can stop and use the plugin in Paraview by loading the XML file directly into the plugin manager.<br />
<br />
Please note that if you are writing the XML for a filter that takes just one input, you *must* set the "name" attribute for the InputProperty XML element to "Input". If you do not, then the filter will not be displayed properly in ParaView's pipeline browser.<br />
<br />
===== Compiling into a Shared Library =====<br />
If you have built Paraview from source, it is possible to compile the plugin into into a shared library. To do this, we can use the following CMakeLists.txt<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(CellDerivatives "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> CellDerivatives.xml)<br />
<br />
We can now load the plugin through the plugin manager by selecting the .so file.<br />
<br />
Similarly compiled Qt resources (*.bqrc) can be loaded at runtime. *.bqrc is a binary file containing resources which can include icons, the GUI configuration xmls for adding catergories etc. A .bqrc can be made from a .qrc by running the rcc utility provided by Qt:<br />
<source lang="text"><br />
rcc -binary -o myfile.bqrc myfile.qrc.<br />
</source><br />
<br />
==== Adding a new VTK filter ====<br />
<br />
For this example, refer to '''Examples/Plugins/Filter''' in the ParaView source. Let's say we have written a new vtkMyElevationFilter (vtkMyElevationFilter.h|cxx), which extends the functionality of the vtkElevationFilter and we want to package that as a plugin for ParaView. For starters, we simply want to use this filter in ParaView (not doing anything fancy with Filters menu categories etc.). As described, we need to write the server manager configuration XML (MyElevationFilter.xml). Once that's done, we write a CMakeLists.txt file to package this into a plugin. <br />
<br />
This CMakeLists.txt simply needs to include the following lines:<br />
<br />
<font color="green"># Locate ParaView build and then import CMake configuration, <br />
# macros etc. from it.</font><br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="green"># Use the ADD_PARAVIEW_PLUGIN macro to build a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(<br />
MyElevation <font color="green">#<--Name for the plugin</font><br />
"1.0" <font color="green">#<--Version string</font><br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <font color="green">#<-- server manager xml</font><br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx <font color="green">#<-- source files for the new classes</font><br />
)<br />
<br />
Then using cmake and a build system, one can build a plugin for this new filter. Once this plugin is loaded the filter will appear under the "Alphabetical" list in the Filters menu.<br />
<br />
<br />
===== Filters with Multiple Input Ports =====<br />
If your filter requires multiple input ports, you have two options - 1) You can create helper functions in the VTK filter such as SetYourInputName which deal with addressing the VTK pipeline in the c++ code. 2) Address/access the input connection by number in the XML. The port_index property specifies which input connection the particular input will be connected to. The SetInputConnection function is the command that will actually be called with this port_index to setup the pipeline.<br />
<br />
An example XML file for a filter with multiple inputs is below. The filter takes three vtkPolyData's as input.<br />
<div class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"><br />
<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="filters"><br />
<!-- ================================================================== --><br />
<SourceProxy name="LandmarkTransformFilter" class="vtkLandmarkTransformFilter" label="LandmarkTransformFilter"><br />
<Documentation<br />
long_help="Align two point sets using vtkLandmarkTransform to compute the best transformation between the two point sets."<br />
short_help="vtkLandmarkTransformFilter."><br />
</Documentation><br />
<br />
<InputProperty<br />
name="SourceLandmarks"<br />
port_index="0"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set. This data set that will move towards the target data set.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="TargetLandmarks"<br />
port_index="1"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the target data set. This data set will stay stationary.<br />
</Documentation><br />
</InputProperty><br />
<br />
<InputProperty<br />
name="SourceDataSet"<br />
port_index="2"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkPolyData"/><br />
</DataTypeDomain><br />
<Documentation><br />
Set the source data set landmark points.<br />
</Documentation><br />
</InputProperty><br />
<br />
<Hints><br />
<!-- see below for what options to put here --><br />
</Hints><br />
<br />
</SourceProxy><br />
<!-- End LandmarkTransformFilter --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
<br />
</div><br />
<br />
To set the inputs in Paraview, simply select one of the inputs in the Pipeline Browser and then select the filter from the Filters menu. This will open a dialog box which will allow you to specify which object to connect to each input port.<br />
<br />
==== Adding ''Categories'' to the Filters Menu ====<br />
<br />
Now suppose we want to add a new category to the Filters menu, called "Extensions" and then show this filter in that submenu. In that case we need to add a hint to the XML file that tells ParaView what category to display this filter in.<br />
<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<ShowInMenu category="Extensions" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, we need a GUI configuration xml to tell the ParaView GUI to create the category. However, as of ParaView 4.3 the GUI configuration xml does nothing and the above method must be followed. This GUI configuration xml will look as such:<br />
<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
If the name of the category is same as an already existsing category eg. ''Data Analysis'', then the filter gets added to the existing category.<br />
<br />
The CMakeLists.txt must change to include this new xml (let's call it MyElevationGUI.xml) as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCE_FILES</font> MyElevationGUI.xml)<br />
<br />
Again, the GUI configuration xml is removed and will do nothing as of ParaView 4.3. If the option is specified in the CMakeLists.txt file, CMake will warn about its use.<br />
<br />
==== Adding Icons ====<br />
You can see that some filters in the Filters menu (eg. Clip) have icons associated with them. It's possible for the plugin to add icons for filters it adds as well. For that you need to write a Qt resource file (say MyElevation.qrc) as follows:<br />
<br />
<source lang="xml"><br />
<RCC><br />
<qresource prefix="/MyIcons" ><br />
<file>MyElevationIcon.png</file><br />
</qresource><br />
</RCC><br />
</source><br />
<br />
To use the icon for a filter in the pipeline add the following hint to the server manager xml.<br />
<source lang="xml"><br />
<!-- skip start of file --><br />
<Hints> <!-- examine the above server manger xml to determine where in the file this goes --><br />
<!-- possibly other hints --><br />
<PipelineIcon name=":/MyIcons/MyElevationIcon.png" /><br />
</Hints><br />
<!-- skip end of file --><br />
</source><br />
<br />
Prior to ParaView 4.0, the GUI configuration xml now refers to the icon provided by this resource as follows:<br />
<source lang="xml"><br />
<ParaViewFilters><br />
<Category name="Extensions" menu_label="&amp;Extensions"><br />
<!-- adds a new category and then adds our filter to it --><br />
<Filter name="MyElevationFilter" icon=":/MyIcons/MyElevationIcon.png" /><br />
</Category><br />
</ParaViewFilters><br />
</source><br />
<br />
Finally, the CMakeLists.txt file much change to include our MyElevation.qrc file as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyElevation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> MyElevationFilter.xml <br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyElevationFilter.cxx<br />
<font color="purple">GUI_RESOURCES</font> MyElevation.qrc)<br />
<br />
==== Adding GUI Parameters ====<br />
Simply add these in the server manager xml to expose parameters of the filter to the paraview user.<br />
===== Integer property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
</IntVectorProperty><br />
</source><br />
<br />
===== Boolean property =====<br />
This property appears as a check box control. A boolean property uses the IntVectorProperty with an extra line (BooleanDomain...) indicating this should be a check box rather than a text field.<br />
<source lang="xml"><br />
<IntVectorProperty name="bStartByMatchingCentroids"<br />
command="SetbStartByMatchingCentroids"<br />
number_of_elements="1"<br />
default_values="1"><br />
<BooleanDomain name="bool"/><br />
</IntVectorProperty><br />
</source><br />
<br />
===== String property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<StringVectorProperty name="YourStringVariable"<br />
command="SetYourStringVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</StringVectorProperty><br />
</source><br />
<br />
===== Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVariable"<br />
command="SetYourDoubleVariable"<br />
number_of_elements="1"<br />
default_values="1"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Multi-Value Double property =====<br />
This property appears as a text box.<br />
<source lang="xml"><br />
<DoubleVectorProperty name="YourDoubleVectorVariable"<br />
command="SetYourDoubleVectorVariable"<br />
number_of_elements="3"<br />
default_values="1.0 0.0 0.0"><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Double property slider =====<br />
This creates a slider that ranges from 0.0 to 1.0<br />
<source lang="xml"><br />
<DoubleVectorProperty name="PercentToRemove"<br />
command="SetPercentToRemove"<br />
number_of_elements="1"<br />
default_values="0.1"><br />
<DoubleRangeDomain name="range" min="0.0" max="1.0" /><br />
</DoubleVectorProperty><br />
</source><br />
<br />
===== Drop down list =====<br />
This creates a drop down list with 3 choices. The values associated with the choices are specified.<br />
<source lang="xml"><br />
<br />
<IntVectorProperty<br />
name="TransformMode"<br />
command="SetTransformMode"<br />
number_of_elements="1"<br />
default_values="1"><br />
<EnumerationDomain name="enum"><br />
<Entry value="6" text="RigidBody"/><br />
<Entry value="7" text="Similarity"/><br />
<Entry value="12" text="Affine"/><br />
</EnumerationDomain><br />
<Documentation><br />
This property indicates which transform mode will be used.<br />
</Documentation><br />
</IntVectorProperty><br />
</source><br />
<br />
=== Adding a Reader ===<br />
<br />
Adding a new reader through a plugin is similar to adding a filter. The only difference is that we do not need<br />
to specify what category the reader should be added to in the GUI. For the latest version of ParaView we do<br />
not need to specify anything special for the GUI as all of the details of the reader are available<br />
in the xml proxy definition of the reader. For ParaView version 4.0.1 and earlier we need the xml to define what file extensions this reader can handle. This xml (MyReaderGUI.xml) looks like this:<br />
<br />
<source lang="xml"><br />
<ParaViewReaders><br />
<Reader name="MyPNGReader" extensions="png"<br />
file_description="My PNG Files"><br />
</Reader><br />
</ParaViewReaders><br />
</source><br />
<br />
An example MyPNGReader.xml is shown below. In almost all cases you must have a SetFileName function property. You are free to have other properties as well, as with a standard (non-reader) filter. Also, the Hints section is needed in<br />
order to associate the file extension with the reader on the client. In ParaView 4.3 and later, the Hints section ReaderFactory hint is what the client uses to identify readers from sources.<br />
<br />
<source lang="cmake"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="sources"><br />
<!-- ================================================================== --><br />
<SourceProxy name="MyPNGReader" class="vtkMyPNGReader" label="PNGReader"><br />
<Documentation<br />
long_help="Read a PNG file."<br />
short_help="Read a PNG file."><br />
</Documentation><br />
<StringVectorProperty<br />
name="FileName"<br />
animateable="0"<br />
command="SetFileName"<br />
number_of_elements="1"><br />
<FileListDomain name="files"/><br />
<Documentation><br />
This property specifies the file name for the PNG reader.<br />
</Documentation><br />
</StringVectorProperty><br />
<br />
<Hints><br />
<ReaderFactory extensions="png"<br />
file_description="PNG File Format" /><br />
</Hints><br />
</SourceProxy><br />
<!-- End MyPNGReader --><br />
</ProxyGroup><br />
<!-- End Filters Group --><br />
</ServerManagerConfiguration><br />
<br />
</source><br />
<br />
And the CMakeLists.txt looks as follows where vtkMyPNGReader.cxx is the source for the reader and MyPNGReader.xml is the server manager configuration xml:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">REQUIRED_ON_SERVER</font>)<br />
<br />
Note that this is for the latest version of ParaView. For ParaView 4.0.1 and earlier the CMakeLists.txt file needs to include the GUI xml to associate the reader with the file name extension. This looks like:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyReader "1.0" <br />
<font color="purple">SERVER_MANAGER_XML</font> MyPNGReader.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMyPNGReader.cxx <br />
<font color="purple">GUI_RESOURCE_FILES</font> MyReaderGUI.xml)<br />
<br />
If you want your reader to work correctly with a file series, please refer to [[Animating legacy VTK file series#Making custom readers work with file series|file series animation]] for details.<br />
<br />
Once you generate the project using CMake and compile the project, in ParaView go to "Tools->Manage Plugins/Extensions". Under "Local Plugins", click "Load New" and browse for the shared library file you just created. You should now see your new file type in the "Files of type" list in the "Open file" dialog.<br />
<br />
=== Adding a Writer ===<br />
<br />
Similar to a reader plugin, for a writer plugin we need to tell ParaView what extensions this writer supports. For the current version<br />
of ParaView this is done in the Hints section of the server manager xml definition as follows:<br />
<br />
<source lang="xml"><br />
<Hints><br />
<WriterFactory extensions="tif"<br />
file_description="My Tiff Files" /><br />
</Hints><br />
</source><br />
<br />
For ParaView version 4.0.1 and earlier this is done in the GUI xml as follows:<br />
<br />
<source lang="xml"><br />
<ParaViewWriters><br />
<Writer name="MyTIFFWriter"<br />
extensions="tif"<br />
file_description="My Tiff Files"><br />
</Writer><br />
</ParaViewWriters><br />
</source><br />
<br />
=== Adding Customizations for Properties Panel ===<br />
<font color="green">* new in 4.0</font><br />
<br />
[[ParaView/Properties Panel|Properties Panel]] is the primary panel in ParaView used to change the parameters for visualization modules and displays. Plugins can provide new types of [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidget.html pqPropertyWidget] subclasses that can be used to control properties/property groups on this Properties panel.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property (vtkSMProperty), use the following:<br />
<br />
<font color="violet">add_paraview_property_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMProperty *smproperty, QWidget *parentObject=0)<br />
</source><br />
<br />
The TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute to request creation of this widget for a vtkSMProperty subclass.<br />
<br />
To register a new pqPropertyWidget subclass to be associated with a particular widget type for a property group (vtkSMPropertyGroup), use the following:<br />
<br />
<font color="violet">add_paraview_property_group_widget</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must refer to a pqPropertyWidget subclass with a constructor with the following prototype:<br />
<br />
<source lang="cpp"><br />
ClassName(vtkSMProxy *smproxy, vtkSMPropertyGroup *smgroup, QWidget *parentObject=0);<br />
</source><br />
<br />
As before, the TYPE specifies the string that will be used in the ServerManager XML as the value for the '''panel_widget''' attribute on a <PropertyGroup/> element to request creation of this widget for that group.<br />
<br />
Another mechanism for adding customizations for Properties panel is to provide [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyWidgetDecorator.html pqPropertyWidgetDecorator] subclasses to add custom control logic for widgets on the panel.<br />
<br />
Decorators can be registered as follows:<br />
<br />
<font color="violet">add_paraview_property_widget_decorator</font>(IFACES IFACE_SRCS<br />
<font color="purple">TYPE</font> "string-type-name"<br />
<font color="purple">CLASS_NAME</font> "class-name")<br />
<br />
The CLASS_NAME must point to a pqPropertyWidgetDecorator subclass and the TYPE is the string name used to request the creation of the decorator in the ServerManager XML as described [[ParaView/Properties Panel|here]].<br />
<br />
An example for customizing the Properties panel can be found in the ParaView source under '''Examples/Plugins/PropertyWidgets'''.<br />
<br />
=== Adding Documentation for Plugins ===<br />
<br />
Starting with ParaView 3.14, developers can provide documentation for plugins that is shown in the ParaView Help Window. There are two mechanisms for adding documentation from plugins.<br />
<br />
* And SERVER_MANAGER_XML files added to the ADD_PARAVIEW_PLUGIN macro are automatically parsed to process <Documentation /> elements. HTML pages summarizing the proxy and properties are automatically generated. This ensures that when the user click "?" for a filter/source added via the plugin, the help window shows appropriate help pages.<br />
<br />
* Using DOCUMENTATION_DIR command in the call to ADD_PARAVIEW_PLUGIN() to specify a directory containing html pages and/or images that gets added a the documentation for the plugin (in addition to the documentation generated using the SERVER_MANAGER_XML files e.g.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SurfaceLIC "1.0"<br />
<font color="purple">DOCUMENTATION_DIR</font> "${CMAKE_CURRENT_SOURCE_DIR}/doc"<br />
<font color="purple">SERVER_MANAGER_XML</font> ${SM_XMLS}<br />
...)<br />
<br />
This results in adding documentation to the "ParaView Online Help" when the plugin is loaded, as shown below.<br />
<br />
[[File:Paraview doc plugin.png | 600px]]<br />
<br />
=== Adding a Toolbar ===<br />
<br />
Filters, reader and writers are by far the most common ways for extending ParaView. However, ParaView plugin functionality goes far beyond that. The following sections cover some of these advanced plugins that can be written.<br />
<br />
Applications use toolbars to provide easy access to commonly used functionality. It is possible to have plugins that add new toolbars to ParaView. The plugin developer implements his own C++ code to handle the callback for each button on the toolbar. Hence one can do virtually any operation using the toolbar plugin with some understanding of the ParaView Server Manager framework and the ParaView GUI components. <br />
<br />
Please refer to '''Examples/Plugins/SourceToolbar''' for this section. There we are adding a toolbar with two buttons to create a sphere and a cylinder source. For adding a toolbar, one needs to implement a subclass for [http://doc.trolltech.com/4.3/qactiongroup.html QActionGroup] which adds the [http://doc.trolltech.com/4.3/qaction.html QAction]s for each of the toolbar button and then implements the handler for the callback when the user clicks any of the buttons. In the example '''SourceToobarActions.h|cxx''' is the QActionGroup subclass that adds the two tool buttons.<br />
<br />
To build the plugin, the CMakeLists.txt file is:<br />
<br />
<font color="green"># We need to wrap for Qt stuff such as signals/slots etc. to work correctly.</font><br />
QT4_WRAP_CPP(MOC_SRCS SourceToolbarActions.h)<br />
<br />
<font color="green"># This is a macro for adding QActionGroup subclasses automatically as toolbars.</font><br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "ToolBar/SourceToolbar")<br />
<br />
<font color="green"># Now create a plugin for the toolbar. Here we pass IFACES and IFACE_SRCS<br />
# which are filled up by the above macro with relevant entries</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SourceToolbar "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS} <br />
SourceToolbarActions.cxx)<br />
<br />
For the GROUP_NAME, we are using '''ToolBar/SourceToolbar'''; here '''ToolBar''' is a keyword which implies that the action group is a toolbar (and shows up under '''View | Toolbars''' menu) with the name '''SourceToolbar'''. When the plugin is loaded, this toolbar will show up with two buttons.<br />
<br />
<br />
=== Adding a Menu ===<br />
<br />
Adding a menu to the menu bar of the main window is almost identical to [[#Adding a Toolbar]]. The only difference is that you use the keyword '''MenuBar''' in lieu of '''ToolBar''' in the GROUP_NAME of the action group. So if you change the ADD_PARAVIEW_ACTION_GROUP command above to the following, the plugin will add a menu titled MyActions to the menu bar.<br />
<br />
<font color="violet">ADD_PARAVIEW_ACTION_GROUP</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> SourceToolbarActions<br />
<font color="purple">GROUP_NAME</font> "MenuBar/MyActions")<br />
<br />
If you give the name of an existing menu, then the commands will be added to that menu rather than create a new one. So, for example, if the GROUP_NAME is '''MenuBar/File''', the commands will be added to the bottom of the File menu.<br />
<br />
=== Adding Custom Property Widgets ===<br />
<br />
=== Autostart Plugins ===<br />
This refers to a plugin which needs to be notified when ParaView starts up or the plugin is loaded which ever happens later and then notified when ParaView quits. Example is in '''Examples/Plugins/Autostart''' in the ParaView source. For such a plugin, we need to provide a QObject subclass (pqMyApplicationStarter) with methods that need to be called on startup and shutdown.<br />
<br />
<source lang="cpp"><br />
...<br />
class pqMyApplicationStarter : public QObject<br />
{<br />
...<br />
public:<br />
// Callback for startup.<br />
// This cannot take any arguments<br />
void onStartup();<br />
<br />
// Callback for shutdown.<br />
// This cannot take any arguments<br />
void onShutdown();<br />
...<br />
};<br />
</source><br />
<br />
The CMakeLists.txt looks as follows:<br />
<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS pqMyApplicationStarter.h)<br />
<br />
<font color="green"># Macro for auto-start plugins. We specify the class name<br />
# and the methods to call on startup and shutdown on an instance of that class.<br />
# It fills IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_AUTO_START</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> pqMyApplicationStarter <font color="green"># the class name for our class</font><br />
<font color="purple">STARTUP</font> onStartup <font color="green"># specify the method to call on startup</font><br />
<font color="purple">SHUTDOWN</font> onShutdown <font color="green"># specify the method to call on shutdown</font><br />
)<br />
<br />
<font color="green"># Create a plugin for this starter </font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Autostart "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> pqMyApplicationStarter.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding a custom view <font color="red"> * obsolete *</font> ===<br />
<br />
<font color="red">Although the general procedure remains the same, the source code in this section is obsolete. See the Examples/Plugins/GUIView and Plugins/MantaView/ParaView directories of the ParaView source code for more up-to-date examples. Also, [http://www.paraview.org/pipermail/paraview/2012-January/023610.html this e-mail thread] discusses some issues of interest.</font><br />
<br />
ParaView contains a render view for rendering 3d images. It also contains chart views to visualize data in line charts and histogram charts. You may want to create another custom view that does your own view of the data.<br />
<br />
For this example, we'll just make a simple Qt widget with labels showing the displays that have been added to the view.<br />
<br />
To make a custom view, we need both client and server side plugins.<br />
<br />
For our server side, we simply have:<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="displays"><br />
<GenericViewDisplayProxy name="MyDisplay"<br />
base_proxygroup="displays" base_proxyname="GenericViewDisplay"><br />
</GenericViewDisplayProxy><br />
</ProxyGroup><br />
<ProxyGroup name="views"><br />
<ViewModuleProxy name="MyViewViewModule"<br />
base_proxygroup="rendermodules" base_proxyname="ViewModule"<br />
display_name="MyDisplay"><br />
</ViewModuleProxy><br />
</ProxyGroup><br />
<ProxyGroup name="filters"><br />
<SourceProxy name="MyExtractEdges" class="vtkExtractEdges"<br />
label="My Extract Edges"><br />
<InputProperty<br />
name="Input"<br />
command="SetInputConnection"><br />
<ProxyGroupDomain name="groups"><br />
<Group name="sources"/><br />
<Group name="filters"/><br />
</ProxyGroupDomain><br />
<DataTypeDomain name="input_type"><br />
<DataType value="vtkDataSet"/><br />
</DataTypeDomain><br />
</InputProperty><br />
<Hints><br />
<View type="MyView"/><br />
</Hints><br />
</SourceProxy><br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
We define "MyDisplay" as a simple display proxy, and "MyViewModule" as a simple view module.<br />
We have our own filter "MyExtractEdges" with a hint saying it prefers to be shown in a view of type "MyView." So if we create a MyExtractEdges in ParaView3, it'll automatically be shown in our custom view.<br />
<br />
We build the server plugin with a CMakeLists.txt file as:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView REQUIRED)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(SMMyView "1.0" <font color="purple">SERVER_MANAGER_XML</font> MyViewSM.xml)<br />
<br />
<br />
Our client side plugin will contain an extension of pqGenericViewModule.<br />
We can let ParaView give us a display panel for these displays, or we can make our own deriving from pqDisplayPanel. In this example, we'll make a simple display panel.<br />
<br />
We implement MyView in MyView.h:<br />
<source lang="cpp"><br />
#include "pqGenericViewModule.h"<br />
#include <QMap><br />
#include <QLabel><br />
#include <QVBoxLayout><br />
#include <vtkSMProxy.h><br />
#include <pqDisplay.h><br />
#include <pqServer.h><br />
#include <pqPipelineSource.h><br />
<br />
/// a simple view that shows a QLabel with the display's name in the view<br />
class MyView : public pqGenericViewModule<br />
{<br />
Q_OBJECT<br />
public:<br />
MyView(const QString& viewtypemodule, const QString& group, const QString& name,<br />
vtkSMAbstractViewModuleProxy* viewmodule, pqServer* server, QObject* p)<br />
: pqGenericViewModule(viewtypemodule, group, name, viewmodule, server, p)<br />
{<br />
this->MyWidget = new QWidget;<br />
new QVBoxLayout(this->MyWidget);<br />
<br />
// connect to display creation so we can show them in our view<br />
this->connect(this, SIGNAL(displayAdded(pqDisplay*)),<br />
SLOT(onDisplayAdded(pqDisplay*)));<br />
this->connect(this, SIGNAL(displayRemoved(pqDisplay*)),<br />
SLOT(onDisplayRemoved(pqDisplay*)));<br />
<br />
}<br />
~MyView()<br />
{<br />
delete this->MyWidget;<br />
}<br />
<br />
/// we don't support save images<br />
bool saveImage(int, int, const QString& ) { return false; }<br />
vtkImageData* captureImage(int) { return NULL; }<br />
<br />
/// return the QWidget to give to ParaView's view manager<br />
QWidget* getWidget()<br />
{<br />
return this->MyWidget;<br />
}<br />
/// returns whether this view can display the given source<br />
bool canDisplaySource(pqPipelineSource* source) const<br />
{<br />
if(!source ||<br />
this->getServer()->GetConnectionID() != source->getServer()->GetConnectionID() ||<br />
QString("MyExtractEdges") != source->getProxy()->GetXMLName())<br />
{<br />
return false;<br />
}<br />
return true;<br />
}<br />
<br />
protected slots:<br />
void onDisplayAdded(pqDisplay* d)<br />
{<br />
QString text = QString("Display (%1)").arg(d->getProxy()->GetSelfIDAsString());<br />
QLabel* label = new QLabel(text, this->MyWidget);<br />
this->MyWidget->layout()->addWidget(label);<br />
this->Labels.insert(d, label);<br />
}<br />
<br />
void onDisplayRemoved(pqDisplay* d)<br />
{<br />
QLabel* label = this->Labels.take(d);<br />
if(label)<br />
{<br />
this->MyWidget->layout()->removeWidget(label);<br />
delete label;<br />
}<br />
}<br />
<br />
protected:<br />
<br />
QWidget* MyWidget;<br />
QMap<pqDisplay*, QLabel*> Labels;<br />
<br />
};<br />
</source><br />
<br />
And MyDisplay.h is:<br />
<source lang="cpp"><br />
#include "pqDisplayPanel.h"<br />
#include <QVBoxLayout><br />
#include <QLabel><br />
<br />
class MyDisplay : public pqDisplayPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
MyDisplay(pqDisplay* display, QWidget* p)<br />
: pqDisplayPanel(display, p)<br />
{<br />
QVBoxLayout* l = new QVBoxLayout(this);<br />
l->addWidget(new QLabel("From Plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
The CMakeLists.txt file to build the client plugin would be:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MyView.h MyDisplay.h)<br />
<br />
<font color="violet">ADD_PARAVIEW_VIEW_MODULE</font>(IFACES IFACE_SRCS <br />
<font color="purple">VIEW_TYPE</font> MyView <font color="purple">VIEW_XML_GROUP</font> views<br />
<font color="purple">DISPLAY_XML</font> MyDisplay <font color="purple">DISPLAY_PANEL</font> MyDisplay)<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIMyView "1.0" <font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
We load the plugins in ParaView, and we create something like a Cone, then create a "My Extract Edges" filter. The multiview manager will create a new view and the label "Display (151)".<br />
<br />
In ParaView 3.4, there's also a macro, ADD_PARAVIEW_VIEW_OPTIONS() which allows adding options pages for the custom view, accessible from Edit -> View Settings. The example in ParaView3/Examples/Plugins/GUIView demonstrates this (until more information is put here).<br />
<br />
=== Adding new Representations for 3D View using Plugins <font color="green"> * new in version 3.7</font> ===<br />
<br />
ParaView’s 3D view the most commonly used view for showing polygonal or volumetric data. By default, ParaView provides representation-types for showing the dataset as surface, wireframe, points etc. It’s possible to add representations using plugins that extends this set of available representation-types.<br />
<br />
Before we start looking at how to write such a plugin, we need to gain some understanding of the 3D view and its representations. The 3D view uses 3 basic representation proxies for rendering all types of data:<br />
* (representations, UnstructuredGridRepresentation) – for vtkUnstructuredGrid or a composite dataset consisting of vtkUnstructuredGrid.<br />
* (representations, UniformGridRepresentation) – for vtkImageData or a composite dataset consisting of vtkImageData<br />
* (representations, GeometryRepresentation) – for all other data types.<br />
<br />
Each of these representation proxies are basically composite-representation proxies that use other representation proxies to do the actual rendering e.g. GeometryRepresentation uses SurfaceRepresentation for rendering the data as wireframe, points, surface and surface-with-edges and OutlineRepresentation for rendering an outline for the data. Subsequently, the 3 composite-representation proxies provide a property named '''Representation''' which allows the user to pick the representation type he wants to see the data as. The composite-representation proxy has logic to enable one of its internal representations based on the type chosen by the user.<br />
<br />
These 3-composite representation types are fixed and cannot be changed by plugins. What plugins can do is add more internal representations to any of these 3 composite representations to support new representations types, that the user can choose using the representation-type combo box on the display tab or in the toolbar.<br />
<br />
[[Image:Representationplugin.png|800px|Figure: Representation type combo-box allowing user to choose the sub-representation to use]]<br />
<br />
==== Using a new Mapper ====<br />
In this example, we see how to integrate a special poly-data mapper written in VTK into ParaView. Let’s say the mapper is called vtkMySpecialPolyDataMapper which is simply a subclass of vtkPainterPolyDataMapper. In practice, vtkMySpecialPolyDataMapper can internally use different painters to do perform special rendering tasks.<br />
<br />
To integrate this mapper into ParaView first we need to create a vtkSMRepresentationProxy subclass for that uses this mapper. In this example, since the mapper is a simple replacement for the standard vtkPainterPolyDataMapper, we can define our representation proxy as a specialization of the “SurfaceRepresentation” as follows:<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<RepresentationProxy name="MySpecialRepresentation"<br />
class="vtkMySpecialRepresentation"<br />
processes="client|renderserver|dataserver"<br />
base_proxygroup="representations"<br />
base_proxyname="SurfaceRepresentation"><br />
<Documentation><br />
This is the new representation type we are adding. This is identical to<br />
the SurfaceRepresentation except that we are overriding the mapper with<br />
our mapper.<br />
</Documentation><br />
<br />
<!-- End of MySpecialRepresentation --><br />
</RepresentationProxy><br />
</ProxyGroup><br />
<br />
</ServerManagerConfiguration><br />
</source><br />
<br />
vtkMySpecialRepresentation is a subclass of vtkGeometryRepresentationWithFaces where in the constructor we simply override the mappers as follows:<br />
<br />
<source lang="cpp"><br />
//----------------------------------------------------------------------------<br />
vtkMySpecialRepresentation::vtkMySpecialRepresentation()<br />
{<br />
// Replace the mappers created by the superclass.<br />
this->Mapper->Delete();<br />
this->LODMapper->Delete();<br />
<br />
this->Mapper = vtkMySpecialPolyDataMapper::New();<br />
this->LODMapper = vtkMySpecialPolyDataMapper::New();<br />
<br />
// Since we replaced the mappers, we need to call SetupDefaults() to ensure<br />
// the pipelines are setup correctly.<br />
this->SetupDefaults();<br />
}<br />
</source><br />
<br />
<br />
Next we need to register this new type with the any (or all) of the 3 standard composite representations so that it will become available to the user to choose in the representation type combo-box.<br />
To decide which of the 3 composite representations we want to add our representation to, think of the input data types our representation supports. If it can support any type of data set, then we can add our representation all the 3 representations (as is the case with this example). However if we are adding a representation for volume rendering of vtkUnstructuredGrid then we will add it only to the UnstructuredGridRepresentation. This is done by using the Extension xml tag. It simply means that we are extending the original XML for the proxy definition with the specified additions. Now to make this representation available as a type to the user, we use the <RepresentationType /> element , with “text” used as the text shown for the type in the combo-box, “subproxy” specifies the name of representation –subproxy to activate when the user chooses the specified type. Optionally one can also specify the “subtype” attribute, which if present is the value set on a property named “Representation” for the subproxy when the type is chosen. This allows for the subproxy to provide more than one representation type.<br />
<br />
<source lang="xml"><br />
<ServerManagerConfiguration><br />
<ProxyGroup name="representations"><br />
<br />
<Extension name="GeometryRepresentation"><br />
<Documentation><br />
Extends standard GeometryRepresentation by adding<br />
MySpecialRepresentation as a new type of representation.<br />
</Documentation><br />
<br />
<!-- this adds to what is already defined in PVRepresentationBase --><br />
<RepresentationType subproxy="MySpecialRepresentation"<br />
text="Special Mapper" subtype="1" /><br />
<br />
<SubProxy><br />
<Proxy name="MySpecialRepresentation"<br />
proxygroup="representations" proxyname="MySpecialRepresentation"><br />
</Proxy><br />
<ShareProperties subproxy="SurfaceRepresentation"><br />
<Exception name="Input" /><br />
<Exception name="Visibility" /><br />
<Exception name="Representation" /><br />
</ShareProperties><br />
</SubProxy><br />
</Extension><br />
<br />
</ProxyGroup><br />
</ServerManagerConfiguration><br />
</source><br />
<br />
The CMakeLists.txt file is not much different from what it would be like for adding a simple filter or a reader.<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(Representation "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font> Representation.xml<br />
<font color="purple">SERVER_MANAGER_SOURCES</font> vtkMySpecialPolyDataMapper.cxx vtkMySpecialRepresentation.cxx<br />
)<br />
<br />
<br />
Source code for this example is available under '''Examples/Plugins/Representation''' in the ParaView source directory.<br />
<br />
==== Using Hardware Shaders ====<br />
One common use-case for adding new representations is to employ specialized hardware shaders written using shading languages such as GLSL or Cg to perform specialized rendering. Such special rendering algorithms can be encapsulated in a special mapper or a vtkPainter subclass and then making a special mapper that uses the painter.<br />
<br />
In this example, we have a new vtkPainter subclasses vtkVisibleLinePainter that uses shaders to prune hidden lines from a wireframe rendering. Following is the CMakeLists.txt<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
<font color="green"><br />
# Compile-in all GLSL files are strings.<br />
# const char* with the names same as that of the file then become available for<br />
# use.</font><br />
<font color="violet">encode_files_as_strings</font>(ENCODED_STRING_FILES<br />
vtkPVLightingHelper_s.glsl<br />
vtkPVColorMaterialHelper_vs.glsl<br />
vtkVisibleLinesPainter_fs.glsl<br />
vtkVisibleLinesPainter_vs.glsl<br />
)<br />
<br />
<font color="violet">add_paraview_plugin</font>(<br />
HiddenLinesRemoval "1.0"<br />
<font color="purple">SERVER_MANAGER_XML</font><br />
HiddenLinesRemovalPlugin.xml<br />
<br />
<font color="purple">SERVER_MANAGER_SOURCES</font><br />
vtkVisibleLinesPolyDataMapper.cxx<br />
<br />
<font color="purple">SOURCES</font> vtkPVColorMaterialHelper.cxx<br />
vtkPVLightingHelper.cxx<br />
vtkVisibleLinesPainter.cxx<br />
${ENCODED_STRING_FILES}<br />
)<br />
<br />
vtkVisibleLinesPolyDataMapper is simply a vtkPainterPolyDataMapper subclass, like the previous example, which inserts the vtkVisibleLinesPainter at the appropriate location in the painter chain. The server manager configuration xml doesn’t look much different from the Using a new Mapper example except that we replace the mapper to be vtkVisibleLinesPolyDataMapper.<br />
<br />
Source code for this example is available under Examples/Plugins/HiddenLineRemoval in the ParaView source directory.<br />
<br />
=== Embedding Python Source as Modules ===<br />
<br />
Embedding Python source was first available in ParaView 3.6. Also be aware that you need Python 2.3 or greater to be able to load a plugin with embedded Python source.<br />
<br />
It is possible to take a Python module written in Python source code and embed it into a ParaView plugin. Once the plugin is loaded, the Python interpreter within the ParaView client (or pvpython or pvbatch) can access your module using the Python <tt>import</tt> command. Of course, Python has its own way of distributing modules; however, if your Python source relies on, say, a filter defined in a plugin or something else in a plugin, like a toolbar, relies on executing your Python module, then it can be more convenient to distribute and load everything if they are all wrapped into a single plugin.<br />
<br />
Let us say that you have a file named helloworld.py with the following contents.<br />
<br />
<source lang="python"><br />
def hello():<br />
print "Hello world"<br />
</source><br />
<br />
You can add this to a plugin by simply listing the file in the <tt>PYTHON_MODULES</tt> option of <tt>ADD_PARAVIEW_PLUGIN</tt>. Note that the file must be located in the same directory as the CMakeLists.txt file (more on that later).<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py<br />
)<br />
<br />
Once you load this plugin into ParaView (no matter how you do it), you can then access this source code by importing the helloworld module.<br />
<br />
<source lang="python"><br />
>>> paraview.servermanager.LoadPlugin('libPythonTest.dylib')<br />
>>> import helloworld<br />
>>> helloworld.hello()<br />
Hello world<br />
</source><br />
<br />
Note that if you are using the ParaView client GUI, you can load the plugin through the GUI's Plugin Manager or by autoloading the plugin (as described in [[#Using Plugins]]) instead of using the <tt>LoadPlugin</tt> Python command. You do, however, need the <tt>import</tt> command.<br />
<br />
It is also possible to have multiple modules and to embed packages with their own submodules (with an arbitrary depth of packages). You can set this up by simply arranging your Python source in directories representing the packages in the same way you set them up if you were loading them directly from Python (in fact, that might simplify debugging your Python code). If you have a file named __init__.py, that file is taken to be the implementation of the package represented by the directory it is contained in. This is the same behavior as Python itself.<br />
<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MyPythonModules "1.0"<br />
<font color="purple">PYTHON_MODULES</font> helloworld.py <font color="green"># Becomes module helloworld</font><br />
hello/__init__.py <font color="green"># Becomes package hello</font><br />
hello/world.py <font color="green"># Becomes module hello.world</font><br />
)<br />
<br />
Note that when Python imports a module, it first imports all packages in which it is contained. The upshot is that if you define a module in a package within your plugin, you must also make sure that the package is also defined somewhere. In the example above, if you removed the hello/__init__.py source file, you would not be able to load the hello/world.py file. Thus, it is best to include a __init__.py in every package directory you make, even if it is empty.<br />
<br />
== Examples ==<br />
<br />
The ParaView CVS repository contains many examples in the Plugins directory. Additional examples are available on this wiki at the [[Plugin Examples]] entry.<br />
<br />
== Adding plugins to ParaView source ==<br />
<br />
There are several plugins that are included in ParaView source itself and are built as part of ParaView's build process. To add such a plugin to the ParaView build there are two options:<br />
<br />
# Place the source for the plugin in a directory under ParaView/Plugins.<br />
# Add the source directory to the CMake variable '''EXTRA_EXTERNAL_PLUGIN_DIRS''' when building ParaView.<br />
<br />
Both approaches result in identical results. <br />
<br />
In general users should simply build their plugins separately, outside the ParaView source. However, when building ParaView statically, adding the plugin to be built as part of ParaView ensures that the static executables load the plugin, otherwise there is no mechanism for loading a plugin in statically built executables.<br />
<br />
In your plugin source directory, ParaView searches for a file name "plugin.cmake" which provides ParaView with information about the plugin. This file should contain the following code:<br />
<font color="green"># Contents of a typical plugin.cmake file</font><br />
<br />
<font color="violet">pv_plugin</font>(<PluginName><br />
<br />
<font color="green"># Provide brief description for the plugin used as documentation for<br />
# the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option provided to the user.</font><br />
<font color="purple">DESCRIPTION</font> "<text>"<br />
<br />
<font color="green"># If you want the plugin to be auto-loaded when ParaView starts, specify this option.<br />
# Users can manually mark any plugin to be auto-loaded using the Plugin Manager dialog.<br />
# This option is ignore for static-builds. All enabled plugins are auto-loaded in static<br />
# builds.</font><br />
<font color="purple">AUTOLOAD</font><br />
<br />
<font color="green"># Specify this option if PARAVIEW_BUILD_PLUGIN_<PluginName> option should default to TRUE.<br />
# If not specified, it defaults to FALSE and the user must turn it ON to build this plugin.<br />
# Note the user can always turn PARAVIEW_BUILD_PLUGIN_<PluginName> off using cmake.</font><br />
<font color="purple">DEFAULT_ENABLED</font><br />
<br />
<font color="green"># If providing more than 1 plugin or plugin is named differently (in add_paraview_plugin call)<br />
# than the <PluginName> specified,<br />
# you can use this option to notify ParaView of the plugin library names. ParaView uses these<br />
# names to locate the plugin at run time.</font><br />
<font color="purple">PLUGIN_NAMES</font> Name1 Name2<br />
)<br />
<br />
If now the plugin is enabled (by the user or by default) by turning ON the PARAVIEW_BUILD_PLUGIN_<PluginName> cmake option, then CMake will look for a CMakeLists.txt file next to the plugin.cmake. This file contains the calls to build the plugin including the '''add_paraview_plugin(...)''' call, and building of any other libraries that the plugin needs.<br />
<br />
A good place to start would be look at examples under ParaView/Plugins directory.<br />
<br />
== Plugins in Static Applications ==<br />
<br />
<font color="magenta">This functionality is new in ParaView 3.12</font><br />
<br />
It is possible to import plugins into a ParaView-based application at compile time. When building ParaView-based applications statically, this is the only option to bring in components from plugins. When built statically (i.e. with BUILD_SHARED_LIBS set to false), ParaView will automatically link and load plugins that were enabled via CMake by inserting the necessary PV_PLUGIN_IMPORT_INIT and PV_PLUGIN_IMPORT macros.<br />
<br />
The code below shows how the PV_PLUGIN macros would be used to statically load plugins in custom applications:<br />
<br />
<source lang="cpp"><br />
#include "vtkPVPlugin.h"<br />
<br />
// Adds required forward declarations.<br />
PV_PLUGIN_IMPORT_INIT(MyFilterPlugin)<br />
PV_PLUGIN_IMPORT_INIT(MyReaderPlugin)<br />
<br />
class MyMainWindow : public QMainWindow<br />
{<br />
// ....<br />
};<br />
<br />
MyMainWindow::MyMainWindow(...)<br />
{<br />
// ... after initialization ...<br />
<br />
// Calls relevant callbacks to load the plugins and update the <br />
// GUI/Server-Manager<br />
PV_PLUGIN_IMPORT(MyFilterPlugin);<br />
PV_PLUGIN_IMPORT(MyReaderPlugin);<br />
<br />
}<br />
</source><br />
<br />
== Pitfalls ==<br />
=== Tools->Manage Plugins is not visible! ===<br />
Plugins can only be loaded dynamically when ParaView is built with shared libraries. You must recompile Paraview with BUILD_SHARED_LIBS ON.<br />
<br />
=== SYNTAX ERROR found in parsing the header file ===<br />
When writing a VTK reader, filter, or writer for use with Paraview, any variable declaration in header files involving VTK classes or your own derived data type has to be wrapped in a "//BTX" "//ETX" pair of comments to tell the parser (Paraview's vtkWrapClientServer) to ignore these lines. The following is an example based on ParaView/Examples/Plugins/Filter/vtkMyElevationFilter.h:<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
private:<br />
vtkMyElevationFilter(const vtkMyElevationFilter&);<br />
void operator=(const vtkMyElevationFilter&);<br />
<br />
//BTX<br />
vtkSmartPointer<vtkPolyData> Source;<br />
vtkSmartPointer<vtkPolyData> Target;<br />
//ETX<br />
};<br />
</source><br />
<br />
If these tags are omitted, building the plugin will fail with an error message like the following:<br />
<source lang="text"><br />
*** SYNTAX ERROR found in parsing the header file <something>.h before line <line number> ***<br />
</source><br />
<br />
=== Compile error "invalid conversion from ‘vtkYourFiltersSuperClass*’ to ‘vtkYourFilter*’" ===<br />
Any VTK object that needs to be treated as a filter or source has to be a vtkAlgorithm subclass. The particular superclass a filter is derived from has to be given not only in the standard C++ way<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
</source><br />
<br />
but additionally declared with help of the "vtkTypeRevisionMacro". For the example given above<br />
<source lang="cpp"><br />
class VTK_EXPORT vtkMyElevationFilter : public vtkElevationFilter<br />
{<br />
public:<br />
vtkTypeRevisionMacro(vtkMyElevationFilter, vtkElevationFilter);<br />
}<br />
</source><br />
<br />
Otherwise, compiling the filter will fail with a variety of error messages (depending on superclass) like<br />
<source lang="cpp"><br />
vtkMyElevationFilter.cxx:19: error: no 'void vtkMyElevationFilter::CollectRevisions(std::ostream&)'<br />
member function declared in class 'vtkMyElevationFilter'<br />
</source><br />
or<br />
<source lang="cpp"><br />
vtkMyElevationFilterClientServer.cxx:97: error: invalid conversion from ‘vtkPolyDataAlgorithm*’ to<br />
‘vtkICPFilter*’<br />
</source><br />
<br />
=== Plugin loaded, but invalid ELF header ===<br />
What would cause this???<br />
<br />
=== Undefined symbol _ZTV12vtkYourFilter ===<br />
When you load your plugin, if you see a yellow ! warning triangle that says "undefined symbol....", you need to add<br />
<source lang="cpp"><br />
vtkCxxRevisionMacro(vtkYourFilter, "$Revision$");<br />
</source><br />
to your header file and recompile the plugin.<br />
<br />
=== Mysterious Segmentation Faults in plugins that use custom VTK classes ===<br />
<br />
This primarily concerns plugins that make calls to your own custom "vtkMy"(or whatever you called it) library of VTK extensions.<br />
<br />
Symptoms:<br />
* The plugin will load, but causes a segfault when you try to use it.<br />
* If you use a debugger you may notice that in some cases when your code calls vtkClassA.MethodB, what actually gets called is vtkClassC.MethodD, where MethodB is a virtual member function. This is occurs because of different vtable entries in the Paraview-internal versions of the VTK libraries.<br />
<br />
The solution is to make sure that your vtkMy library is compiled against Paraview's internal VTK libraries. Even if you compiled VTK and Paraview using the same VTK sources, you *must not* link against the external VTK libraries. (The linker won't complain, because it will find all the symbols it needs, but this leads to unexpected behaviour.)<br />
<br />
To be explicit, when compiling your vtkMy library, you must set the cmake variable VTK_DIR to point to the 'VTK' subdirectory in the directory in which you built Paraview. (On my system, cmake automatically finds vtk at /usr/lib/vtk-5.2, and I must change VTK_DIR to ~/source/ParaView3/build/VTK .)<br />
<br />
=== "Is not a valid Qt plugin" in Windows ===<br />
<br />
Make sure that all the DLLs that your plugin depends on are on the PATH. If in doubt, try placing your plugin and all its dependent DLLs in the bin dir of your build and load it from there.<br />
<br />
=== The system cannot find the path specified. error MSB6006: "cmd.exe" exited with code 3. ===<br />
<br />
You may get an error like this when trying to build your plugin with VisualStudio:<br />
<br />
<pre><br />
1> CS Wrapping - generating vtkMyElevationFilterClientServer.cxx<br />
1> The system cannot find the path specified.<br />
1>C:\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.CppCommon.targets(151,5): error MSB6006: "cmd.exe" exited with code 3.<br />
1>Done executing task "CustomBuild" -- FAILED.<br />
</pre><br />
<br />
This is caused for a mismatch between the configuration you used when building ParaView (e.g. Debug, Release, etc.) and the configuration currently chosen for building your plugin. So ensure those match.<br />
<br />
The problem is caused because inside the Linker properties there are references to the *.lib files, including the name of the directory that matches the configuration type, which may look something like this:<br />
<br />
<tt>C:\Users\MyUser\ParaView-v4.2.0-build\lib\'''Release'''\vtkPVAnimation-pv4.2.lib</tt><br />
<br />
== Legacy/Deprecated Components ==<br />
<br />
=== Adding an object panel ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Object Panels are the panels for editing object properties.<br />
<br />
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.<br />
<br />
To make your own, there is an explanation found on [[CustomObjectPanels]]<br />
<br />
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:<br />
<br />
<source lang="cpp"><br />
#include "pqAutoGeneratedObjectPanel.h"<br />
#include <QLabel><br />
#include <QLayout><br />
<br />
class ConePanel : public pqAutoGeneratedObjectPanel<br />
{<br />
Q_OBJECT<br />
public:<br />
ConePanel(pqProxy* pxy, QWidget* p)<br />
: pqAutoGeneratedObjectPanel(pxy, p)<br />
{<br />
this->layout()->addWidget(new QLabel("This is from a plugin", this));<br />
}<br />
};<br />
</source><br />
<br />
Then in our CMakeLists.txt file:<br />
<font color="violet">FIND_PACKAGE</font>(ParaView <font color="purple">REQUIRED</font>)<br />
<font color="violet">INCLUDE</font>(${PARAVIEW_USE_FILE})<br />
QT4_WRAP_CPP(MOC_SRCS ConePanel.h)<br />
<font color="violet">ADD_PARAVIEW_OBJECT_PANEL</font>(IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> ConePanel<br />
<font color="purple">XML_NAME</font> ConeSource <font color="purple">XML_GROUP</font> sources)<br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(GUIConePanel "1.0"<br />
<font color="purple">GUI_INTERFACES</font> ${IFACES}<br />
<font color="purple">SOURCES</font> ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
=== Adding components to Display Panel (decorating display panels) ===<br />
'''<font color="red">Deprecated since 3.98.''' Use [[Plugin_HowTo#Adding_Customizations_for_Properties_Panel|Properties Panel customizations]] instead. </font><br />
<br />
Display panel is the panel shown on the '''Display''' tab in the '''Object Inspector'''. It is possible to add GUI components to existing [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqDisplayPanel.html display panels].<br />
<br />
In this example we want to add a GUI element to the display panel shown for the spread sheet view to size of data that is fetched to the client at one time referred to as the ''Block Size''.<br />
<br />
For that we write the implementation in QObject subclass (say MySpreadsheetDecorator) with a constructor that takes in the pqDisplayPanel which is to be decorated.<br />
<br />
<source lang="cpp"><br />
...<br />
class MySpreadsheetDecorator : public QObject<br />
{<br />
...<br />
public:<br />
MySpreadsheetDecorator(pqDisplayPanel* panel);<br />
virtual ~MySpreadsheetDecorator();<br />
...<br />
};<br />
</source><br />
<br />
In the constructor, we have access to the panel, hence we can get the ''layout'' from it and add custom widgets to it. In this case, it would be a spin-box or a line edit to enter the block size. <br />
''pqDisplayPanel::getRepresentation()'' provides access to the representation being shown on the panel. We can use [http://www.paraview.org/ParaView3/Doc/Nightly/html/classpqPropertyLinks.html pqPropertyLinks] to link the "BlockSize" property on the representation with the spin-box for the block size so that when the widget is changed by the user, the property changes and vice-versa.<br />
<br />
Now the CMakeLists.txt to package this plugin looks like follows:<br />
<br />
QT4_WRAP_CPP(MOC_SRCS MySpreadsheetDecorator.h)<br />
<br />
<font color="green"># This is the macro to add a display panel decorator.<br />
# It needs the class name, and the panel types we are decorating. It fills up <br />
# IFACES and IFACE_SRCS with proper values as needed by ADD_PARAVIEW_PLUGIN macro.</font><br />
<font color="violet">ADD_PARAVIEW_DISPLAY_PANEL_DECORATOR</font>(<br />
IFACES IFACE_SRCS <br />
<font color="purple">CLASS_NAME</font> MySpreadsheetDecorator<br />
<font color="purple">PANEL_TYPES</font> pqSpreadSheetDisplayEditor <br />
<font color="green"># <-- This identifies the panel type(s) to decorate<br />
# Our decorator will only be instantiated for the panel types indicated here</font><br />
)<br />
<br />
<font color="green"># create a plugin</font><br />
<font color="violet">ADD_PARAVIEW_PLUGIN</font>(MySpreadsheetDecorator "1.0" <br />
<font color="purple">GUI_INTERFACES</font> ${IFACES} <br />
<font color="purple">SOURCES</font> MySpreadsheetDecorator.cxx ${MOC_SRCS} ${IFACE_SRCS})<br />
<br />
An example panel decorator is available under '''Examples/Plugins/DisplayPanelDecorator''' in the ParaView source.<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=Talk:ParaView/Plugin_HowTo&diff=57210Talk:ParaView/Plugin HowTo2014-12-29T18:02:17Z<p>DWilches: Save time for plugin developers</p>
<hr />
<div>About: "To create a plugin, one must have their own build of ParaView3."<br />
Building Paraview takes hours, more than 24 in my case. A packaged build of Paraview's resources needed for plugin development would be very welcomed by plugin developers. For example, there could be a git repository containing all headers, libs and everything else needed.</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57209ParaView:Build And Install2014-12-29T17:56:18Z<p>DWilches: I'm not sure of this one, but a clarification from part of Kitware would be welcome.</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external dependencies, typical for plugin developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are '''not''' supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57208ParaView:Build And Install2014-12-29T17:54:54Z<p>DWilches: /* Prerequisites */</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are '''not''' supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57207ParaView:Build And Install2014-12-29T17:53:57Z<p>DWilches: Make it clearer, I didn't see that the first time.</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are *not* supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57206ParaView:Build And Install2014-12-29T17:52:28Z<p>DWilches: Added a hint so people can go and take a nap meanwhile.</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are not supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target (this may take more than 12 hours depending on the speed of the build machine).<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57205ParaView:Build And Install2014-12-29T17:51:12Z<p>DWilches: Added information about other variables to be set to have Python scripting working.</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are not supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available. You will also need to setup the following variables:<br />
|-<br />
| || PYTHON_LIBRARY: Should point to your python*.lib file. For example on Windows: C:/Python27/libs/python27.lib<br />
|-<br />
| || PYTHON_INCLUDE_DIR: Should point to the include directory inside your Python installation. For example on Windows: C:/Python27/include<br />
|-<br />
| || PYTHON_EXECUTABLE: Should point to the python executable file. For example on Windows: C:/Python27/python.exe<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target.<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57204ParaView:Build And Install2014-12-29T17:43:51Z<p>DWilches: Broken link</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are not supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://download.qt.io/archive/qt/4.8/].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available.<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target.<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilcheshttps://public.kitware.com/Wiki/index.php?title=ParaView:Build_And_Install&diff=57203ParaView:Build And Install2014-12-29T17:42:20Z<p>DWilches: Fixed broken link. Added information about versions required for prerequisites.</p>
<hr />
<div>=Introduction=<br />
<br />
'''<font color="green">This page is applicable for ParaView 3.98 and above. For ParaView 3.14.1 and earlier versions, refer to the [http://paraview.org/Wiki/index.php?title=ParaView:Build_And_Install&oldid=46445 past version] of this document.</font>'''<br />
<br />
This page describes how to build and install ParaView. It covers both the released and the development versions, both Unix-type systems (Linux, HP-UX, Solaris, Mac), as well as Windows.<br />
<br />
ParaView depends on several open source tools and libraries such as Python, Qt, CGNS, HDF5, etc. Some of these are included in the ParaView source itself (e.g. HDF5), while others are expected to be present on the machine on which ParaView is being built (e.g. Python, Qt, CGNS). Based on whether you want to build ParaView along with all the external tools it needs or you want to build the external tools yourself (or use versions already available on your system), there are two ways to build ParaView from source.<br />
# To build ParaView complete with all the dependencies it needs, use the [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
# To build ParaView source itself by providing existing installations/builds of the external depencies, typical for developers, use the instructions on this page.<br />
<br />
=Prerequisites=<br />
<br />
*The ParaView build process requires [http://www.cmake.org CMake] version 2.8.8 or higher and a working compiler. On Unix-like operating systems, it also requires Make, while on Windows it requires Visual Studio (2008 or 2010).<br />
<br />
*Building ParaView's user interface requires [http://www.qt.io/download-open-source/ Qt], version 4.7.* ([http://download.qt.io/archive/qt/4.8/ 4.8.*] is recommended). To compile ParaView, either the LGPL or commercial versions of Qt may be used. Also note that on Windows you need to use VisualStudio 2008 or 2010+SP1 as Qt v4.8.* don't come with VS2012 or VS2013 builds.<br />
<br />
*In order to run ParaView in parallel, MPI [http://www-unix.mcs.anl.gov/mpi/], [http://www.lam-mpi.org/] is also required. <br />
<br />
*In order to use scripting, Python is required (version 2.7 is known to work, whereas version 3.4 is known to cause compilation problems) [http://www.python.org].<br />
<br />
* Also note, for Windows builds, unix-like environments such as Cygwin, MinGW are not supported.<br />
<br />
==Download And Install CMake==<br />
<br />
CMake is a tool that makes cross-platform building simple. On several systems it will probably be already installed. If it is not, please use the following instructions to install it. If CMake does not exist on the system, and there are no pre-compiled binaries, use the instructions below on how to build it. Use the most recent source or binary version of CMake from the CMake web site.<br />
<br />
===Using Binaries===<br />
<br />
There are several precompiled binaries available at the [http://www.cmake.org/cmake/resources/software.html CMake download page].<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Let's say on Linux, download the appropriate version and follow these instructions:<br />
<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8-Linux-i386.tar.gz<br />
mkdir software<br />
cd software<br />
tar xvfz ../cmake-2.8.8-Linux-i386.tar.gz<br />
</pre><br />
<br />
* Now you have the directory '''$HOME/software/cmake-2.8.8-Linux-i386/bin''', and inside there are executables '''cmake''' and '''ccmake'''.<br />
* You can also install CMake in the '''/usr/local''' or '''/opt''' by untaring and copying sub-directories. The rest of the instructions will assume the executables are in your '''$PATH'''.<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Windows====<br />
* Download the installer: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.exe<br />
* Follow the installation instructions<br />
<br />
====On Windows, if you are not administrator====<br />
* Download: http://www.cmake.org/files/v2.8/cmake-2.8.8-win32-x86.zip<br />
* Uncompress into some directory<br />
* Optional: create a shortcut on the desktop.<br />
</div><br />
|}<br />
<br />
===Build Your Own CMake===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
Download the source code: http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
<br />
<pre><br />
cd $HOME<br />
wget http://www.cmake.org/files/v2.8/cmake-2.8.8.tar.gz<br />
tar xvfz cmake-2.8.8.tar.gz<br />
cd cmake-2.8.8<br />
./configure --prefix=$HOME/software<br />
make<br />
make install<br />
</pre><br />
<br />
* Again, you can install it in '''/usr/local''' or '''/opt''' by changing the prefix.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====On Windows====<br />
To build CMake on windows, a previous version of CMake is required. This can be downloaded from the Cmake download page: [http://www.cmake.org/HTML/Download.html].<br />
<br />
</div><br />
|}<br />
<br />
==Download And Install Qt==<br />
<br />
ParaView uses Qt as its GUI library. Qt is required whenever the ParaView client is built. <br />
*As stated above, the LGPL of Qt can be found at [http://qt.nokia.com/downloads].<br />
**For source code, use the latest stable version of qt-everywhere-opensource-src-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work.<br />
**For binaries, use the latest stable version of qt-PLATFORM-opensource-VERSION.[tar.gz or zip or dmg]. If this gives you trouble, version 4.8.2 is known to work. When downloading binaries, ensure that your compiler version matches the Qt compiler indicated.<br />
<br />
==Download And Install ffmpeg (.avi) movie libraries==<br />
<br />
When the ability to write .avi files is desired, and writing these files is not supported by the OS, ParaView can attach to an ffmpeg library. This is generally true for Linux. Ffmpeg library source code is found here: [http://www.ffmpeg.org/]<br />
<br />
==Download And Install MESA 3D libraries==<br />
<br />
ParaView uses the OpenGL graphics drivers and card from a user's workstation. When you want to run ParaView's servers on a platform that does not include hardware OpenGL support, you must use MESA to emulate this hardware in software. Mesa is open source, and it can be downloaded from here: [http://www.mesa3d.org/]. <br />
<br />
There is a known problem with MESA version 7.8.2 and ParaView. This has been reported to the MESA team. Version 7.7.1 has been tested and seems to work correctly as well as 7.9.<br />
<br />
Build as follows:<br />
*make realclean<br />
*make TARGET (for instance, make linux-x86-64)<br />
<br />
Note - some platforms will complain during ParaView compiles about needing fPIC. In the configs directory, copy your platform file to another custom file, edit it, and add -fPIC to the compile lines. For instance, cp linux-x86-64 linux-x86-64-fPIC.<br />
<br />
For more elaborate discussion on building with Mesa/OSMesa support, refer to [[ParaView And Mesa_3D]].<br />
<br />
==Download ParaView Source Code==<br />
<br />
If you are trying to build a ParaView release, download it from the release page. For the development version, please follow the instructions below for checking it out from git.<br />
<br />
===Download The Release===<br />
<br />
Don't forget that you can always just download the binaries from the [http://paraview.org/paraview/resources/software.php ParaView download page]. This page contains binaries for several platforms and the source code for the releases.<br />
<br />
====Note: debian build====<br />
<br />
List of packages to build ParaView on Debian: <br />
<br />
libphonon-dev libphonon4 qt4-dev-tools libqt4-core libqt4-gui qt4-qmake libxt-dev g++ gcc cmake-curses-gui libqt4-opengl-dev mesa-common-dev<br />
<br />
With MPI (using openmpi, you can use any other flavour):<br />
<br />
openmpi-common openmpi-bin libopenmpi-dev<br />
<br />
With Python:<br />
<br />
python-dev<br />
<br />
===Checkout Development Version from git===<br />
Note that you may need to download and install a git client, here: [http://git-scm.com/]<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems====<br />
<pre><br />
Prepare directory for download<br />
# mkdir $HOME/projects<br />
# cd $HOME/projects<br />
<br />
To download the source code <br />
# git clone git://paraview.org/ParaView.git ParaView<br />
# cd ParaView<br />
# git checkout -b trunk origin/master<br />
# git submodule init<br />
# git submodule update<br />
<br />
To update the code<br />
# git fetch origin<br />
# git rebase origin/master<br />
#git submodule update<br />
<br />
</pre><br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
====On Windows====<br />
We recommend [http://msysgit.github.io/ msysgit]. msysgit provides an msys shell that has the appropriate environment set up for using git and it's tools.<br />
</div><br />
|}<br />
<br />
==Configure ParaView With CMake==<br />
* Always use a <font color="red">'''separate build directory'''</font>. Do not build in the source directory.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===On Unix-like systems===<br />
* Use ccmake (Curses CMake GUI) from the CMake installed location. CCMake is a Curses based GUI for CMake. To run it go to the build directory and specify as an argument the src directory.<br />
<br />
<pre><br />
mkdir $HOME/projects/ParaView-bin<br />
cd $HOME/projects/ParaView-bin<br />
<br />
ccmake $HOME/projects/ParaView3<br />
</pre><br />
[[Image:Brpv ccmake.png|400px]]<br />
<br />
===About CCMake (Curses CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, run configure (c key).<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the generate option is available (g key).<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode (t key).<br />
* To set a variable, move the cursor to the variable and press enter.<br />
** If it is a boolean (ON/OFF) it will flip the value.<br />
** If it is string or file, it will allow editing of the string.<br />
** For file and directories, the <nowiki><tab></nowiki> key can be used to complete.<br />
* To search for a variable press '/' key; to repeat the search, press the 'n' key.<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===On Windows===<br />
* Use CMakeSetup from the CMake install location.<br />
* Make sure to select the appropriate source and the build directory.<br />
* Also, make sure to pick the appropriate generator (on Visual Studio 6, pick the ''Visual Studio 6'' generator). Some CMake versions will ask you to select the generator the first time you press Configure instead of having a drop-down menu in the main dialog.<br />
[[Image:Brpv cmakesetup.png|400px]]<br />
<br />
===About CMakeSetup (Windows CMake GUI)===<br />
<br />
* Iterative process.<br />
** Select values, press the Configure button.<br />
** Set the settings, run configure, set the settings, run configure, etc.<br />
* Repeat until all values are set and the OK button becomes available.<br />
* Some variables (advanced variables) are not visible right away.<br />
* To see advanced varables, toggle to advanced mode ("Show Advanced Values" toggle).<br />
* To set the value of a variable, click on that value.<br />
** If it is boolean (ON/OFF), a drop-down menu will appear for changing the value.<br />
** If it is file or directory, an ellipsis button will appear ("...") on the far right of the entry. Clicking this button will bring up the file or directory selection dialog.<br />
** If it is a string, it will become an editable string.<br />
</div><br />
|}<br />
<br />
===ParaView Settings===<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| BUILD_SHARED_LIBS || If ON, use shared libraries. This way executables are smaller, but you have to make sure the shared libraries are on every system on the cluster. This option should be set to ON if you plan on using plugins for ParaView (there ways to use plugins in static builds of ParaView for advanced users).<br />
|-<br />
| PARAVIEW_USE_MPI || Turn this to ON to enable MPI. Other MPI options will not be available until you turn this on.<br />
|-<br />
| MPI_C_LIBRARIES || Paths to the MPI libraries (such as /usr/lib/libmpi.so). Should be found by default, but you may have to set it. Certain mpi implementations need more than one library. All the libraries can be specified by separating them with a ';'. (see the note below)<br />
|-<br />
| MPI_C_INCLUDE_PATH || Path to MPI includes (such as /usr/include/mpi). Again, this should be found by default.<br />
|-<br />
| PARAVIEW_ENABLE_PYTHON || Makes Python client scripting and the Python programmable filter available.<br />
|-<br />
| PARAVIEW_BUILD_QT_GUI || Flag to enable/disable the building of the ParaView Qt-based client. This option is useful when building ParaView on server nodes or when we are only interested in the Python client, as it avoids building of the Qt client thus does not require Qt. ON by default.<br />
|-<br />
| QT_QMAKE_EXECUTABLE || Path to Qt's qmake executable (such as /usr/local/bin/qmake). CMake uses this to locate the rest of the required Qt executables, headers and libraries.<br />
|-<br />
| PARAVIEW_ENABLE_FFMPEG || Enable FFMPEG support (UNIX only)<br />
|-<br />
| PARAVIEW_USE_VISITBRIDGE || Enable VisItBridge that adds support for additional file formats (requires Boost)<br />
|}<br />
<br />
'''Note for MPI settings:''' If your MPI variables aren't set automatically (usually the case if the compiler wrapper [mpicxx] is not in the path or in some standard directory), toggle advanced options and set MPI_COMPILER variable to the full path of your mpi compiler (usually mpicxx), and configure. This should set all the required MPI variables. If not, then you might need to enter them manually. <br> If you get an error such as "mpi.h: no such file or directory" then set the CMAKE_C_FLAGS= -lmpi and the CMAKE_CXX_FLAGS= -lmpi++ . This is in addition to the MPI variables.<br />
<br />
===Finish Configuring ParaView===<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====Using CCMake====<br />
<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki> (g key).<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
====Using CMakeSetup====<br />
* Once all configuration options are set, you should be able to just run <nowiki><generate></nowiki>, by clicking the "OK" button.<br />
</div><br />
|}<br />
<br />
==Build ParaView==<br />
<br />
You can now build ParaView using the appropriate build system.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="50%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
===Using Make===<br />
CMake will now generate Make files. These make files have all dependencies and all rules to build ParaView on this system. You should not however try to move the build directory to another location on this system or to another system.<br />
<br />
Once you have makefiles you should be able to just type:<br />
<br />
make<br />
<br />
* If you are on multi-processor system (let's say four processor), you can type:<br />
<br />
make -j 4<br />
<br />
[[Image:Brpv make.png|400px]]<br />
<br />
</div><br />
|width="50%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; float: right; padding: .4em .9em .9em"><br />
<br />
===Using Visual Studio===<br />
CMake will now create Visual Studio project files. Before you open Visual Studio, be sure that the Qt .dlls are in your path.<br />
You should now be able to open the '''ParaView''' project (or workspace) file. Make sure to select the appropriate build type (Debug, Release, ...).<br />
To build ParaView, simply build the '''ALL_BUILD''' target.<br />
<br />
[[Image:Brpv visualstudio71.png|400px]]<br />
|}<br />
<br />
=Install ParaView=<br />
<br />
ParaView can be run directly from the build directory. That said, for production environments, it should be installed in some system location.<br />
<br />
For that purpose simply follow these instructions to install to an appropriate location. (these need to be updated for Windows). Note that ParaView is designed to <font color="brown">'''install what it builds'''</font>. Thus only the libraries and executables that ParaView builds are installed. For example, these instructions will not install Qt or ffmpeg libraries to the specified location. If you are interested in creating a binary package that is complete and can be distributed to other users/systems, you may want to refer to [[ParaView:Superbuild|ParaView Super-Build]].<br />
<br />
===CMake Variables===<br />
<br />
Some of the CMake variables that affect installation rules are:<br />
<br />
{| border="0" cellpadding="4" cellspacing="4"<br />
|- <br />
| bgcolor="#abcdef" height="8" | '''Variable'''<br />
| bgcolor="#abcdef" height="8" | '''Value'''<br />
| bgcolor="#abcdef" height="8" | '''Description'''<br />
|-<br />
| CMAKE_INSTALL_PREFIX<br />
| <path><br />
| Set this to the root of the location where you want ParaView to be installed. For unix based systems, ParaView will be installed under bin/ lib/ directories under this install prefix. '''This option is not available on Mac OSX'''.<br />
|-<br />
| CMAKE_BUILD_TYPE<br />
| Release<br />
| Unless you want to end up with debug install, set this to Release.<br />
|-<br />
| PARAVIEW_INSTALL_DEVELOPMENT_FILES<br />
| OFF/ON<br />
| To install development files, including headers, so that developers can build plugins/custom-applications using the installed version of ParaView, set this to ON. '''Currently, this option is not available on Mac OSX or Windows'''.<br />
|-<br />
| MACOSX_APP_INSTALL_PREFIX<br />
| <path><br />
| Set this to the location where you want ParaView to install the app bundle on "make install". '''This option is only available on Mac OSX'''<br />
|}<br />
<br />
===Installing===<br />
Following the configuration, simply run 'make' to compile and build.<br />
<br />
{| cellspacing="3" <br />
|- valign="top" <br />
|width="30%" class="MainPageBG" style="border: 1px solid #ffc9c9; color: #000; background-color: #fff3f3"|<br />
<div style="padding: .4em .9em .9em"><br />
====On Unix-like operating systems:====<br />
make install<br />
<br />
This will install all the relevant files in directories under the CMAKE_INSTALL_PREFIX. The executables are installed in ${CMAKE_INSTALL_PREFIX}/bin and the libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib/paraview-${major}.${minor}.<br />
<br />
</div><br />
|width="30%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #f0f0ff"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
<br />
====On Windows:====<br />
<to be decided><br />
</div><br />
| width="40%" class="MainPageBG" style="border: 1px solid #c6c9ff; color: #000; background-color: #d1f0e5"|<br />
<div style="clear: right; text-align: left; padding: .4em .9em .9em"><br />
====On Mac:====<br />
make install<br />
<br />
This will create an app bundle in the directory specified by MACOSX_APP_INSTALL_PREFIX. This app bundle will have the main application executable under APP/Contents/MacOS, libraries under APP/Contents/Libraries, plugins under APP/Contents/Plugins, and additional executables such as the server executables and python executables under APP/Conents/bin.<br />
</div><br />
|}<br />
<br />
==Notes on Mac OSX==<br />
<br />
On Mac OSX, "'''make install'''" will install an app bundle to the location specified by MACOSX_APP_INSTALL_PREFIX. This app will contain all the ParaView libraries, plugins, python scripts, etc. that were built by ParaView. You can move this app around on the same machine like a regular app and it will work without any problems. Note, however, that this is not a redistributable app bundle. You cannot ship this off to your friend and expect it to work. This app does not include any *external dependencies*, such Qt libraries, or Python libraries, and has references to the versions that you used to build ParaView. This is not unique to Mac OSX, but to all other plaforms as well. "make install" is used to install runtimes to be used on the same machine. To generate redistributable packages, refer to [[ParaView:Superbuild|ParaView Super-Build]] instructions.<br />
<br />
==Miscellaneous Comments==<br />
* Build trees of ParaView on non-Windows systems, always have RPATH information embedded in the binaries. When a make install is performed or CPACK is used, all RPATH information is stripped from the binaries in the install tree (expect for paths to external libraries). By default ParaView builds forwarding executables (launchers) that are installed in the bin directory. These binaries properly set up the environment to launch the equivalent executable in the lib/paraview-x.y directory.<br />
* If you are compiling a MESA version of the ParaView server, start the server with the --use-offscreen-memory flag.<br />
<br />
== Notes ==<br />
=== Environment Variables ===<br />
<br />
If you build with shared libraries, you may have to add the Qt directory to you PATH environment variables to run ParaView. With Windows, one way to do so is to open up the environment variables dialog by clicking through '''Start'''|Control Panel|System|Advanced|Environment Variables. From that dialog, add a new user variable called PATH with a value of C:\Qt\4.8.2\bin. For other operating systems, add Qt/4.8.2/lib to your LD_LIBRARY_PATH environment variable.<br />
<br />
=Frequently Asked Questions=<br />
<br />
===="make install" does not install ffmpeg and other libraries as it did with 3.14.1 and earlier. Is this a bug?====<br />
<br />
This is a deliberate change. It was decided that ParaView should install only what it builds. Since ParaView doesn't build ffmpeg, it doesn't add install rules to install it. If you are interested in creating a package that includes all files ParaView depends on so that you can distribute to other, refer to<br />
[[ParaView:Superbuild|ParaView Super-Build]]. That is supposed to do exactly that.<br />
<br />
====How do I generate a distributable ParaView package?====<br />
<br />
Refer to [[ParaView:Superbuild | ParaView Super-Build]]. That is the process we use to generate the official binaries that are distributed on paraview.org. It streamlines the process of building all the depedencies for ParaView and then packaging them into installables or tarballs.<br />
<br />
====Do I need BUILD_SHARED_LIBS set to be ON if I want to enable Python scripting?====<br />
<br />
No. In ParaView 3.14.1 and earlier, this was indeed the case, ParaView required that BUILD_SHARED_LIBS was ON if Python support was to be enabled. That is no longer the case. BUILD_SHARED_LIBS and PARAVIEW_ENABLE_PYTHON can now be managed independently.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
{{ParaView/Template/Footer}}</div>DWilches