Kitware Source Feature Article: October 2009

Python Trace

ParaView is a scientific visualization application offering a variety of data processing and rendering algorithms. The client-server architecture enables data-parallel processing in a distributed memory environment. Users don’t need a cluster to run ParaView. Perhaps the most common use of ParaView is a built-in mode where the client and server co-exist in a single process running on a desktop. Whether operating on a supercomputer or on a MacBook, the ParaView power-user can always take advantage of the Python scripting language to streamline his or her work. The ParaView Python interface allows efficient control over most tasks that can be performed through the GUI including: opening data files, constructing visualization pipelines, adjusting the camera, and exporting post-processed data or animations.

An exciting new extension to the ParaView Python interface is Python trace. This feature will be available in the 3.6.2 release. The goal of trace is to generate human readable, and not overly verbose, Python scripts that mimic a user’s actions in the GUI. The scripts can be used for a variety of purposes, but there was one particular use case considered for driving development of Trace—rapid prototyping of scripts for batch or in-situ/co-processing and visualization.

The idea is that a user could open a small representative piece of their data in the ParaView GUI, interactively build a visualization pipeline, and then save a trace script to be used in batch mode on full-size data. Alternatively, the script could be called from a co-processing module enabling data to be post-processed and visualized as it is produced by simulation codes without the need for writing the data to a disk to be collected and processed elsewhere. The script should be more or less ready to go, although it may have to be modified slightly to account for different pathnames or to replace a reader with a bridge to a co-processing library.

Python Dialog Trace Tab
The Trace tab in the Python Dialog

Now we’ll take a brief look at how trace is implemented in order to understand what we can expect from trace, then we’ll get started with a tutorial. First a quick word about the ParaView architecture and its Python interface.

In ParaView, the data and C++ objects that filter, process, and render the data reside on the server. There is a proxy object on the client for each object on the server. Proxies have states which are represented by properties. Changing a proxy property on the client means the property value is streamed to the server where an appropriate C++ function is called to set the value on the proxy’s server-side object. So how does this work in the Python interface? Take the following Python code:

s = Sphere()
s.Center = [1,  0,  0]

The call to Sphere() creates a client-side proxy object which, in turn, creates a server-side object—vtkSphereSource. Setting the proxy property Center to the list [1, 0, 0] streams the values to the server where vtkSphereSource::SetCenter(1, 0, 0) is called. So what does this mean for trace? It means you can mimic most actions the user performs when clicking around in the GUI by creating proxies and setting their property values. Unfortunately, not all actions in the GUI can be represented with such proxy manipulations, so trace won’t work for all cases.

Let's Walk Through an Example
You can try this at home if you download the 3.6.2 release of Paraview. Fire up the ParaView client and then go to the Tools menu and select Python Shell. The Python dialog will open, showing an interactive interpreter on the left and some tools on the right in tabbed panels. Switch to the tab labeled Trace and click the button Start Trace. For this example we will use generated data, but you could also use a reader to load a dataset from disk. Go to the Sources menu, select Octree Fractal, and then click Apply in the Properties tab of the Object Inspector panel. Now click the Show Trace button in the Python dialog.

Already we have accumulated quite a bit of Python code with only two clicks of the mouse. Let’s look at what we have so far. You’ll see Python code that: creates the octree fractal source; creates a color lookup table for the source’s point data; creates a display representation for the fractal source; sets the ColorArrayName property of the display to ‘FractalIterations’; assigns the lookup table using the LookupTable property; and finally sets the camera position and orientation properties to render the current scene.

Now let’s see how trace reacts to a simple property change. Go to the Properties tab of the Object Inspector and change the Dimension property from 2 to 3, then click Apply. Click Show Trace again in the Python dialog.

Trace Tutorial Image Result
Result image of the trace tutorial

You’ll see the same output that was printed before and then some new code for our latest changes. The Dimension property has been modified and the lookup table has also been modified to account for the new scalar range of the FractalIterations array.

Now we will build a simple pipeline. Go to the Filters menu and choose Contour, click Apply. In the Pipeline Browser change the selected source back to the fractal source and then apply a Clip filter from the Filters menu. Adjust the clipping plane if you want, and then click Apply. Now go to the View menu and choose Show Color Legend. Adjust the camera angle to something a little more interesting and we’re done! Click Stop Trace.

Now there is just one final thing to do before we’re ready to send our script to a 1024 node cluster. Click Edit Trace and enter this line at the end of the script:

WriteImage(‘output.png’)

Happy tracing! For more information on Python trace, please visit the ParaView Wiki and search for “ParaView/ Python Scripting”, “IEEE Vis09 ParaView Tutorial”, “Python GUI Tools”, or “ParaView#Python Scripting”.

Acknowledgements
This work was funded in part by EDF (www.edf.fr).

Pat Marion  Pat Marion is an R&D Engineer in Kitware’s Chapel Hill, NC office where he works on a variety of scientific visualization and medical projects. Pat has hiked the Pacific Crest Trail from Mexico to Canada and spent five months working on organic farms in Spain and Italy.