ParaView/Python Scripting: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
 
(5 intermediate revisions by the same user not shown)
Line 20: Line 20:
==Proxies==
==Proxies==


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.
{{ParaView/Template/DeprecatedUsersGuide}}


<source lang="python">
>>> sphereSource = vtk.vtkSphereSource() # VTK-Python script
>>> sphereSourceP = Sphere() # ParaView script
</source>
A proxy also provides an interface to modify the properties of the objects it maintains. For example, instead of:
<source lang="python">
>>> sphereSource.SetCenter(1.0, 1.0, 0.0)
</source>
you can write the following:
<source lang="python">
>>> sphere.Center = [1.0, 1.0, 0.0]
</source>
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.
<source lang="python">
>>> c = Cone()
<paraview.servermanager.Cone object at 0xaf73090>
>>> GetActiveSource()
<paraview.servermanager.Cone object at 0xaf73090>
>>> Shrink()
<paraview.servermanager.Shrink object at 0xb4f8610>
# Make the cone active
>>> SetActiveSource(c)
</source>
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.
<source lang="python">
>>> Cone()
<paraview.servermanager.Cone object at 0xaf73090>
>>> GetActiveSource()
<paraview.servermanager.Cone object at 0xaf73090>
>>> Shrink()
<paraview.servermanager.Shrink object at 0xb4f8610>
>>> SetActiveSource(c)
</source>
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:
<source lang="python">
# Delete the cone source
>>> Delete(c)
# To fully remove the cone from memory, get rid of the
# variable too
>>> del c
</source>
If you do not use a Python variable to hold the value returned by the pipeline object proxy constructor, the following is needed to delete the object:
<source lang="python">
Cone() # not: c = Cone()
# to delete this object:
# First, delete its entry in the ParaView's pipeline GUI or call Delete(FindSource("Cone1"))
# Then, this is needed:
import gc
gc.collect()
</source>
Please note that for destructors to be called, calls such as ''c = FindSource("name")'', respecively ''FindSource("name")'' will also require the call to ''del(c)'', respectively ''gc.collect()'' afterward.
==Properties==
==Properties==


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:
{{ParaView/Template/DeprecatedUsersGuide}}
 
<source lang="python">
>>> rp = sphere.GetProperty("Radius")
>>> rp.SetElement(0, 2)
1
>>> sphere.UpdateProperty("Radius")
</source>
 
The servermanager module makes property access much easier by defining Python property accessors for property objects:
 
<source lang="python">
>>> sphere.Radius = 3
</source>
 
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:
 
<source lang="python">
>>> cone = Cone(Radius=0.5, Center=[1, 0.5, 0])
<paraview.servermanager.Cone object at 0xaf73090>
</source>
 
You can also use the SetProperties() function to set property values.
 
<source lang="python">
>>> SetProperties(cone, Radius=0.2, Center=[2, 0.5, 0])
</source>
 
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.
 
All Property classes define the following methods:
 
* __len__()
* __getitem__()
* __setitem__()
* __getslice__()
* __setslice__()
* GetData()
* SetData().
 
Therefore, all of the following are supported:
 
<source lang="python">
>>> sphere.Center
[0.0, 0.0, 0.0]
>>> sphere.Center[0] = 1
>>> sphere.Center[0:3] = [1,2,3]
>>> sphere.Center[0:3]
[1.0, 2.0, 3.0]
>>> len(sphere.Center)
3
</source>
 
ProxyProperty and InputProperty also define
 
* append()
* __delitem__()
* __delslice__()
 
to support del() and append(), similar to Python list objects.
 
VectorProperty is used for scalars, vectors and lists of integer and floating point numbers as well as
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''.
 
<source lang="python">
>>> reader = ExodusIIReader(FileName='.../can.ex2')
# These variables are currently selected
>>> reader.PointVariables
['DISPL', 'VEL', 'ACCL']
# These are available in the file
>>> reader.PointVariables.Available
['DISPL', 'VEL', 'ACCL']
# Enable the DISPL array only
>>> reader.PointVariables = ['DISPL']
# Force read
>>> reader.UpdatePipeline()
# Now check the output. Note: GlobalNodeId is generated automatically by the reader.
>>> reader.PointData[:]
[Array: GlobalNodeId, Array: PedigreeNodeId, Array: DISPL]
</source>
 
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).
 
Glyph.Scalars is a bit more complicated. This property allows the developer to select the scalar array with which to scale the glyphs.
 
<source lang="python">
>>> sph = Sphere()
>>> elev=Elevation(sph)
# Glyph the points of the sphere with spheres
>>> glyph=Glyph(elev, GlyphType='Sphere')
# Scale the glyph with the Elevation array
>>> glyph.Scalars = 'Elevation'
>>> glyph.Scalars
['POINTS', 'Elevation']
# The above shows the association of the array as well as its name.
# In this case, the array is associated with POINTS as it has to be
# since Glyph cannot scale by cell arrays. We could have done:
>>> glyph.Scalars = ['POINTS', 'Elevation']
# Enable scaling by scalars
>>> glyph.ScaleMode = 'scalar'
</source>
 
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'').
 
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).
 
<source lang="python">
>>> reader = ExodusIIReader(FileName='.../can.ex2')
>>> reader.TimestepValues
[0.0, 0.00010007373930420727, 0.00019990510190837085, 0.00029996439116075635, 0.00040008654468692839,
0.00049991923151537776, 0.00059993512695655227, 0.00070004, ...]
</source>
 
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:
 
<source lang="python">
>>> for prop in glyph:
print type(prop), prop.GetXMLLabel()
 
<class 'paraview.servermanager.InputProperty'> Input
<class 'paraview.servermanager.VectorProperty'> Maximum Number of Points
<class 'paraview.servermanager.VectorProperty'> Random Mode
<class 'paraview.servermanager.ArraySelectionProperty'> Scalars
<class 'paraview.servermanager.ArraySelectionProperty'> Vectors
<class 'paraview.servermanager.VectorProperty'> Orient
<class 'paraview.servermanager.VectorProperty'> Set Scale Factor
<class 'paraview.servermanager.EnumerationProperty'> Scale Mode
<class 'paraview.servermanager.InputProperty'> Glyph Type
<class 'paraview.servermanager.VectorProperty'> Mask Points
</source>
 
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.
 
<source lang="python">
>>> it = iter(s)
>>> for i in it:
print it.GetKey(), it.GetProperty()
</source>


==Domains==
==Domains==


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:
{{ParaView/Template/DeprecatedUsersGuide}}
 
<source lang="python">
>>> s = Sphere()
>>> Show(s)
>>> dp = GetDisplayProperties(s)
>>> dp.Representation
'Surface'
# The current representation type is Surface. What other types
# are available?
>>> dp.GetProperty("Representation").Available
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']
# Choose outline
>>> dp.Representation = 'Outline'
</source>


==Source Proxies==
==Source Proxies==


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.
{{ParaView/Template/DeprecatedUsersGuide}}
 
<source lang="python">
# Either
>>> glyph = Glyph(elev)
# or
>>> glyph.Input = elev
</source>
 
The SourceProxy class provides several additional properties and methods that are specific to pipelines (See vtkSMSourceProxy documentation for a full list).
* '''UpdatePipelineInformation()''': This method calls UpdateInformation() on the VTK algorithm. It also calls UpdatePropertyInformation() to update any information properties.
* '''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.
* '''GetDataInformation()''': This method is used to obtain meta-data about one output. It is discussed further below.
* PointData and CellData properties discussed below.
 
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:
 
<source lang="python">
>>> di = glyph.GetDataInformation(0)
>>> di
<paraview.servermanager.DataInformation object at 0x2d0920d0>
>>> glyph.UpdatePipeline()
# Get the data type.
>>> di.GetDataClassName()
'vtkPolyData'
# Get information about point data.
>>> pdi = glyph.PointData
# We are now directly accessing the wrapper for a VTK class
>>> len(pdi)
2
# Get information for a point array
>>> ai = pdi[0]
>>> ai.GetRange(0)
(0.0, 0.5)
</source>
 
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:
 
*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.
 
*Bring data from a given process to the client.
 
*Use a reduction algorithm and bring its output to the client. For example, find the minimum value of an attribute.
 
Here is a demonstration:
 
<source lang="python">
>>> from paraview.simple import *
>>> Connect("kamino")
Connection (kamino:11111)
>>> s = Sphere()
# Get the whole sphere. DO NOT DO THIS IF THE DATA IS LARGE otherwise
# the client will run out of memory.
>>> allsphere = servermanager.Fetch(s)
getting appended
use append poly data filter
>>> allsphere.GetNumberOfPolys()
96
# Get the piece of the sphere on process 0.
>>> onesphere = servermanager.Fetch(s, 0)
getting node 0
>>> onesphere.GetNumberOfPolys()
48
# Apply the elevation filter so that we have a useful scalar array.
>>> elev = Elevation(s)
# We will use the MinMax algorithm to compute the minimum value of
# elevation. MinMax will be first applied on each processor. The results
# will then be gathered to the first node. MinMax will be then applied
# to the gathered results.
# We first create MinMax without an input.
>>> mm = MinMax(None)
# Set it to compute min
>>> mm.Operation = "MIN"
# Get the minimum
>>> mindata = servermanager.Fetch(elev, mm, mm)
applying operation
# The result is a vtkPolyData with one point
>>> mindata.GetPointData().GetNumberOfArrays()
2
>>> a0 = mindata.GetPointData().GetArray(1)
>>> a0.GetName()
'Elevation'
>>> a0.GetTuple1(0)
0.0
</source>


==Representations and Views==
==Representations and Views==


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().
{{ParaView/Template/DeprecatedUsersGuide}}
It is easy to create new views.
 
<source lang="python">
>>> view = CreateRenderView()
</source>
 
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:
 
<source lang="python">
>>> GetRenderViews()
[<paraview.servermanager.RenderView object at 0xaf64ef0>, <paraview.servermanager.RenderView object at 0xaf64b70>]
>>> GetActiveView()
<paraview.servermanager.RenderView object at 0xaf64b70>
</source>
 
You can also change the active view using SetActiveView().
 
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.
 
<source lang="python">
>>> Show(elev, GetRenderViews()[1])
<paraview.servermanager.GeometryRepresentation object at 0xaf64e30>
>>> Render(GetRenderViews()[1])
</source>
 
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().
 
<source lang="python">
>>> dp = GetDisplayProperties(elev)
>>> dp
<paraview.servermanager.GeometryRepresentation object at 0xaf649d0>
</source>
 
Display properties and views have a large number of properties some of which are poorly documented. We will cover some them here.
 
<source lang="python">
>>> from paraview.simple import *
# Create a simple pipeline
>>> sph = Sphere()
>>> elev = Elevation(sph)
>>> Show(elev)
>>> Render()
# Set the representation type of elev
>>> dp = GetDisplayProperties(elev)
>>> dp.Representation = 'Points'
# Here is how you get the list of representation types
>>> dp.GetProperty("Representation").Available
['Outline', 'Points', 'Wireframe', 'Surface', 'Surface With Edges']
>>> Render()
# Change the representation to wireframe
>>> dp.Representation = 'Wireframe'
>>> Render()
# Let’s get some information about the output of the elevation
# filter. We want to color the representation by one of it’s
# arrays.
# Second array = Elevation. Interesting. Let’s use this one.
>>> ai = elev.PointData[1]
>>> ai.GetName()
'Elevation'
# What is its range?
>>> ai.GetRange()
(0.0, 0.5)
# To color the representation by an array, we need to first create
# a lookup table.  We use the range of the Elevation array
>>> dp.LookupTable = MakeBlueToRedLT(0, 0.5)
>>> dp.ColorAttributeType = 'POINT_DATA'
>>> dp.ColorArrayName = 'Elevation' # color by Elevation
>>> Render()
</source>
 
Here is the result:
[[Image:SMView.png|thumb|center|800px|'''Figure 14.2''' Object displayed in a view]]
 
 
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.
 
<source lang="python">
>>> camera = GetActiveCamera()
>>> camera
<libvtkCommonPython.vtkCamera vtkobject at 0xe290>
>>> camera.Elevation(45)
>>> Render()
</source>
 
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:
 
<source lang="python">
>> WriteImage("/Users/berk/image.png")
</source>
 
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.
 
[[Image:Image.jpg|thumb|center|800px|'''Figure 14.3''' Saving a view as an image]]


=Advanced Concepts=
=Advanced Concepts=


==Dealing with lookup tables==
==Dealing with lookup tables==
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.
{{ParaView/Template/DeprecatedUsersGuide}}
 
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().
 
<source lang="python">
def GetLookupTableForArray(arrayname, num_components, **params):
    """Used to get an existing lookuptable for a array or to create one if none
    exists. Keyword arguments can be passed in to initialize the LUT if a new
    one is created. Returns the lookup table."""
    ....
</source>
 
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.
 
 
<source lang="python">
# To color the representation by an array, we need to first create
# a lookup table.  We use the range of the Elevation array
>>> dp.LookupTable = GetLookupTableForArray("Elevation", 1,
                      RGBPoints = [min, 0, 0, 1, max, 1, 0, 0],
                      ColorSpace = "HSV")
>>> dp.ColorAttributeType = 'POINT_DATA'
>>> dp.ColorArrayName = 'Elevation' # color by Elevation
>>> Render()
</source>


==Loading State and Manipulating It==
==Loading State and Manipulating It==

Latest revision as of 18:38, 24 June 2024

Katie O adding to ParaView Guide LaTex

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.

ParaView and Python

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.

Note: Server Manager is a library that is designed to make it easy to build distributed client-server applications.

This document is a short introduction to ParaView's Python interface. You may also visit the Python recipes page for some examples.

Quick Start - a Tutorial

PAGE DELETED
The ParaView's Python documentation has been moved from the Wiki to The ParaView Python Documentation. Please use the history if you want to access the old version of this document.

paraview.simple Module

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Proxies and Properties

Proxies

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Properties

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Domains

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Source Proxies

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Representations and Views

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Advanced Concepts

Dealing with lookup tables

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Loading State and Manipulating It

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Dealing with Time

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Animating

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Loading Data Files

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Writing Data Files (ParaView 3.9 or later)

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Exporting CSV Data

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Updating View Layout

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.

Multiple Renders

PAGE DELETED
The Paraview's User Guide and Reference Manual have been moved from the Wiki to The ParaView Guide. Please use the history if you want to access the old version of this document.



ParaView: [Welcome | Site Map]
Retrieved from "https://public.kitware.com/Wiki/index.php?title=ParaView/Python_Scripting&oldid=65263"