Python paraview Module

This documents the paraview module available for python programmers.

Getting Started

One has to use either the pvpython executable or the python console provided by the ParaView3 application to use this module. One cannot simply import this module in the standard python interpretor. This is because the module does not include any server manager initialization which is essesential for the paraview client. For the purposes of this document, unless otherwise stated, when we say pvpython we imply the pvpython interpretor or the python console in ParaView3 application.

To use paraview, simply import the paraview module.

 import paraview

pvpython setups up the environment paths so that the paraview module is located automatically.

Connections

ParaView client cannot work without a server connection. The server connection can be a connection to an actual remove server or a builtin server. By default, there is no connection, hence the user must set up a connection first. paraview module provides connect function to create built-in, server, as well as data-server-render-server connections.

To create a built in connection, use connect with no arguments as follows:

 connection = paraview.connect()

To connect to a server, we can do:

 connection = paraview.connect("hostname", 11111)

To connect to a data-server and a render server, we do:

 connection = paraview.connect("data-server-hostname", 11111, "render-server-hostname, 22222)

11111 and 22222 are tcp/ip port ids and should be replaced by appropriate values. All the above methods return a pyConnection object which encapsulates the ConnectionID used by server manager as well as the meta data about the connection such as host name etc etc. The connection ID is accessible as:

 connection.ID

The paraview module provides function that take this connection object as an argument. For most of such functions, the connection argument is optional. When not present, the connection set as the ActiveConnection for the module, if any, is used. To change the active connection one can do:

 paraview.ActiveConnection = myconnection

To disconnect, we can do:

 paraview.disconnect(connection)

Builder Functions

The paraview module provides several convenience functions that can be used to create/register proxies, create render modules, displays etc. All the functions that return a proxy return a pyProxy wrapper vtkSMProxy object. pyProxy wrapper is explained later.

createProxy

This function creates a proxy. The arguments are:

Argument	Description
xml_group	group of the proxy type to create
xml_name	name of the proxy type to create
register_group (optional)	group under which to register the proxy. If None, the proxy is not registered with the proxy manager. Note that if sharing a session with the ParaView GUI, it is required to register sources and filters in the sources group. Otherwise, the GUI will not recognize the proxy.
register_name (optional)	name with which to register the proxy. If None, and register_group is not-None then a proxy is registered with a name created using the proxy's SelfID.
connection (optional)	connection on which to create the proxy. If None, then the ActiveConnection is used.

createRenderWindow

This function creates a new render window. It takes connection as the only optional argument. If not specified, ActiveConnection is used as the connection on which to create the render module. The type of the render module created depends on the type of the connection. This function also registers the render module with the proxy manager.

createDisplay

This function creates a new display for a proxy suitable for a particular render module and also adds the display to the render module.

Argument	Description
proxy	proxy to create the display for.
renModule	render module to which the display gets added.

This function also registers the display under "displays" group.

Examples

Simple Sphere

 import paraview
 # create a built in connection and make it the active connection.
 paraview.ActiveConnection = paraview.connect()
 # create a sphere and register it under sources.
 sphere = paraview.createProxy("sources","SphereSource","sources")
 # create a render module.
 renModule = paraview.createRenderWindow()
 # create a display
 display = paraview.createDisplay(sphere, renModule)
 # reset camera
 renModule.ResetCamera()
 # render.
 renModule.StillRender()

pyProxy: wrapper for vtkSMProxy

One can create a vtkSMProxy object in python as

 proxy = paraview.vtkSMProxy()

However, the API for accessing properties from a proxy is cumbersome. One has to get the property with the correct name using vtkSMProxy::GetProperty() then get/set elements on this property. To simplify the python API, we provide pyProxy class as a wrapper to a vtkSMProxy object. One can wrap an existing vtkSMProxy object as follows:

 pyproxy = pyProxy(proxy)
 # pyproxy.SMProxy == proxy

The original vtkSMProxy object is always accessible using the member SMProxy on the pyProxy object. Any method call not defined by pyProxy is passed on to the internal vtkSMProxy object, so one rarely needs to access the SMProxy attribute. eg.

 pyproxy.UpdateVTKObjects() <==> pyproxy.SMProxy.UpdateVTKObjects()

Set/Get API for properties

pyProxy simplifies property access. To set a property with name "Radius" on a pyproxy we can do:

 pyproxy.SetRadius(12.0) 
 pyproxy.SetCenter(0,0,0)

instead of

 proxy.GetProperty("Radius").SetElement(0, 12.0)
 proxy.GetProperty("Center").SetElement(0, 0)
 proxy.GetProperty("Center").SetElement(1, 0)
 proxy.GetProperty("Center").SetElement(2, 0)

Similarly to get current property values we can do:

 value_list1 = pyproxy.GetRadius()
 value_list2 = pyproxy.GetCenter()

Note that these methods returns python list of values of the property. In case of Radius, the value_list1 will just have a single element, while in case of Center, the list will have 3 values.

The Set API works even for proxy properties. Thus to set the input for a filter proxy, we can do

 pyproxy.SetInput(pyproxy2)

Keep in mind that the properties of a proxy are not pushed to the server until UpdateVTKObjects() is called. The only exception to this rule is the convenience function InvokeCommand(). A command is a property that has no values but is used to invoke a method such as Render(). InvokeCommand() will force the server to execute a command:

 pyproxy.InvokeCommand("StillRender")

AddTo/RemoveFrom for proxy properties

For a proxy property, the pyProxy class defines AddTo and RemoveFrom methods as well. eg. to add a proxy to the Displays property on a proxy, we can do

 pyproxy.AddToDisplays(pyproxy2)

Similarly to remove a proxy from the proxy property Displays, we do

 pyproxy.RemoveFromDisplays(pyproxy2)

In all the above methods where the argument can be a proxy, it can either be a vtkSMProxy or a wrapped pyProxy object.

ListMethods

pyProxy.ListMethods() can be used to obtain a list of property names provided by the proxy.

Property Iterators

pyProxy wrapper also provides iterators that iterate over all (exposed) properties of the proxy. eg:

 for smproperty in pyproxy:
    print smproperty

One can explicitly obtain an iterator from the pyproxy object as well. The advantage of doing so is that one can query the iterator for the key (or exposed property name) of the property during each iteration. eg:

 iter = pyproxy.__iter__()                       # or iter = paraview.pyPropertyIterator(proxy)
 for smproperty in iter:
   print "Proxy: %s" % iter.GetProxy()           # proxy (or subproxy) to which the property belongs. 
   print "Property Name: %s" % iter.GetKey()     # name of the property.
   pass                                          # iter.GetProperty() == smproperty

Documentation

To obtain documentation from a proxy, we can do:

 smdoc = pyproxy.GetDocumentation() # returns a vtkSMDocumentation object for the proxy.
 print smdoc.GetLongHelp()
 print smdoc.GetShortHelp()
 print smdoc.GetDescription()

To get property documentation, we can do:

 for smproperty in pyproxy:
   smdoc = smproperty.GetDocumentation()

Alternative, documentation can be obtained from the Proxy Manager without instantiating a proxy, as explained later.

pyProxyManager: wrapper for vtkSMProxyManager

Similar to pyProxy, this is a wrapper for the vtkSMProxyManager. It overrides vtkSMProxyManager methods that return proxies so that the returned values are pyProxy objects wrapped around the vtkSMProxy objects returned by vtkSMProxyManager. Additionally, this class provides iterators to iterate over registered proxies, proxy definitions, compound proxy definitions etc.

GetProxiesOnConnection(connection)

This method returns a list of proxies register with the proxy manager that are on a particular connection. The connection is passed as an argument.

GetProxiesInGroup(groupname, connection=None)

This method returns a list of proxies registered in a particular group, which is passed as an argument. If the optional argument connection is present, then only those proxies that belong to the group and are on the connection are returned.

ListProperties(groupname, proxyname)

Returns a list of exposed properties provided by a proxy of the given type. This allows the user to query the proxy manager for properties of proxy without creating an instance of it.

Registered Proxy Iterators

One can iterate over all registered proxies simply as:

 for proxy in pypxm:
   print proxy.GetXMLName()

The iterator is a pyProxyIterator object, which is a wrapper around vtkSMProxyIterator. The wrapper is essential to implement the python iterator protocol.

 pypxm.__iter() <===> pyProxyIterator()

group_iter(groupname, connection=None)

Returns an iterator object (pyProxyIterator) that iterates over all registered proxies in the given group. If connection is non-None, then the proxies not on the connection are skipped. eg.

 iter = pypxm.group_iter("sources",paraview.ActiveConnection)  # all proxies in "sources" group, on the ActiveConnection.
 for proxy in iter:
   print "%s.%s" % (iter.GetGroup(), iter.GetKey())
   print iter.GetProxy()                                       # iter.GetProxy() == proxy

The pyProxyIterator provides access to the groupname and name with which the current proxy is registered.

connection_iter(connection)

Returns an iterator object (pyProxyIterator) that iterates over all registered proxies on a particular connection.

Proxy Definition Iterators

To iterate over all proxy definitions known to the proxy manager, one can use the definition_iter() method. eg. to iterate over all know types of filters:

 for definition in paraview.pyProxyManager().definition_iter("filters"): 
   print "%s : %s" % (definition["group"], definition["key"])

The group name argument is optional, when not specified, it will iterate over all known groups as well. Note that the definition iterator returns a dict with two keys: group and key. The value of group is the definitions group name while that of key is the definitions proxy type name.

Documentation

Here's a small example for obtain documentation for all known proxy types and all of their exposed properties without explicitly instantiating the proxies.

 pypxm = paraview.pyProxyManager()
 for definition in pypxm.definition_iter("filters"):
   group = definition["group"]
   key = definition["key"]
   print "%s : %s" % (group, key)
   proxy_doc = pypxm.GetProxyDocumentation(group,key)
   print proxy_doc.GetDescription()
   property_list = pypxm.ListProperties(group, key)
   for property_name in property_list:
     property_doc = pypxm.GetPropertyDocumentation(group, key, property_name)
     if property_doc:
        print property_name
        print property_doc.GetDescription()

Examples

Exodus Reader

 import paraview
 # Create default builtin connection
 paraview.ActiveConnection = paraview.connect()

 # Create the reader proxy.
 reader = paraview.createProxy("sources", "ExodusReader", "sources")
 reader.SetFileName("/home/myself/Datasets/Exodus/can.ex2")
 reader.UpdateVTKObjects()

 # Create render window
 renWin = paraview.createRenderWindow()
 # create and add display
 display = paraview.createDisplay(reader, renWin)
 # render
 renWin.ResetCamera()
 renWin.StillRender()

 # Update all information properties. 
 reader.UpdatePropertyInformation()
 # Get the timestep available in the data set.
 time_step_range = reader.GetTimeStepRangeInfo()
 print "TimeStep Range: %s" % str(time_step_range)
 # Get the point arrays available.
 point_array_info = reader.GetPointArrayInfo()
 print "Point Arrays: %s" % str(point_array_info)

 # Set timestep to last.
 reader.SetTimeStep(time_step_range[1])
 # Enable the first point array.
 reader.SetPointArrayStatus(point_array_info[0], point_array_info[1]);
 reader.UpdateVTKObjects()

 renWin.ResetCamera()
 renWin.StillRender()