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.

Getting Started
To start interacting with ParaView through Python, you have to load the paraview.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 as 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 noninteractive, 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.

In this document, I will be using the Python integrated development environment, IDLE. My PYTHONPATH is set to the following:

This is on my Mac and uses the build tree. In IDLE, let’s start by loading the servermanager module.

In this example, we will use ParaView in stand-alone mode. Connecting to a ParaView server running on a cluster is covered later.

Creating a Pipeline
The simple module contains many functions to instantiate readers, filters and other related objects. You can get a list of objects this module can create from www.paraview.org/ OnlineHelpCurrent/.

Let’s start by creating a reader object to read a VTK file.

You can get some documentation about the cone object using help().

Help on LegacyVTKReader in module paraview.servermanager object:

This gives you a full list of methods and properties (data descriptors). When using ParaView’s Python interface, we interact with objects by reading and setting their properties. Let’s start by setting the name of the file to be read.

Note that we used a file from the VTKData repository. VTKData is a separate download from the download page on VTK.org. This file contains a uniform grid that has the numerical solution of the air flow in an office. Also note that the property is called FileNames rather than FileName and expects a Python list. This is because the VTK reader in ParaView can read a series of files that represent a time series.

Alternatively, we could have specified the file name when creating the object.

The constructor functions in paraview.simple all accept an arbitrary number of key,value pairs that represent property names and values.

We can read the property value back.

Now that we set the file name, we can access the metainformation about the data it contains. For example, we can get a list of point (node) centered data arrays by accessing the PointData property:

Note that before the function returned a value, “vtkFile-SeriesReader : [ ........... ]” appeared on the output. This is because ParaView forced the reader to execute and read data from the file so that it can give us the metadata. The paraview.simple module forces readers and filters to execute when necessary to always produce up-to-date metadata. This file contains two arrays: scalars and vectors. We can get the range of the scalar array as follows.

Now that we know the range of the scalar’s array, let’s extract some isosurfaces.

Here, we used the ListProperties() method to find the Isosurfaces method. We also set ComputeScalars on so that the output contains the contour value as a scalar.

Rendering
Next, we will display the outline of the data as well as the isosurfaces. First, let’s display the output of vtkreader as an outline.

Note that we used SetDisplayProperties() to set the representation type of vtkreader. We could have done the following instead.

Let’s also turn on the visibility of the isosurfaces and render.

Note, we set the color of the isosurface to be mapped from the scalar’s array. We also created a lookup table that is used for this mapping (MakeBlueToRedLT). This lookup table interpolates color from blue to red in the given range. We also moved the camera by 105 degrees using the Elevation() method. Finally, Render() renders the scene.

We can capture this window as an image as follows.

The resulting image is shown below.

Finally, we can save the state of ParaView to load later.

Using the Python Shell in ParaView
Let’s continue our tutorial inside the ParaView user interface. Quit Python and start ParaView. First load the state file we just saved using File->Load State. Next, bring up the Python shell using Tools->Python Shell. You will notice that we no longer have access to variables we defined in our previous session (vtkreader, c and dp). So, how do we access the objects that were in the state? Paraview.simple has two convenience methods that makes this easy.

GetSources() returns a Python dictionary that has references to all pipeline objects as well as their names. FindSource() finds an object given its name. You can find the name of the object in the pipeline browser.

Next, let’s delete the contour filter.

You will notice that the contour object is also removed from the pipeline browser. This is because both the user interface and the Python interpreter modify the same underlying engine and all changes made in one are immediately reflected by the other.

Client/Server Scripting
Let’s now switch back to the Python shell and explore how to connect to a ParaView server. Feel free to skip this section if you are not running ParaView in client/server mode.

First, start a ParaView server (pvserver) either on the local machine or on a remote server. I ran pvserver on my desktop for this example.

You can use the Connect() function to connect to a server.

Here, the first argument is the hostname and the second argument is the port number. The easiest way to get started is to load the state we previously saved.

Note that I had to set the active view manually as ParaView does not currently save the active objects in the state. We will fix this in the next release. Loading a state saved by a stand-alone ParaView application using a client/server ParaView works without problems as ParaView creates the appropriate objects under the cover. Everything discussed in this article should work without any modifications.

Acknowledgements
This work has been partially funded by Sandia National Laboratories through contract number DE-AC04-94AL85000.

 Berk Geveci is Kitware’s Director of Scientific Computing where he leads the scientific visualization and informatics teams. He is one of the leading developers of the ParaView visualization application and the Visualization Toolkit (VTK). His research interests include large scale parallel computing, computational dynamics, finite elements and visualization algorithms.