ParaQ:Scripting

Overview

In initial discussions with customers, we have identified Scripting as an important requirement for ParaQ, and have collected Scripting Requirements. In general terms, we have studied the capabilites of similar, familiar tools, and have folded appropriate capabilites from ParaView, Cubit, VisIt, and Ensight into our requirements.

Goals

The goals of ParaQ scripting are:

• To simplify developer testing through scripting.
• To enable users to automate repetative offline tasks.
• To enable developer debugging in the short term to speed development of ParaQ and ParaView Server.

Design

ParaQ scripting will be build on top of the ParaView server manager (PVSM) API. Main reasons behind this decision are:

• We need a scripting interface independent of the GUI (accessible through the python client)
• PVSM is designed to provide such an interface
• PVSM is already wrapped into Tcl, Python and client/server streams

Diagram of the ParaView Server Manager API, showing how multiple clients are built against the PVSM layer. Initially, this would include the ParaQ client, and a Scripting client.

ParaQ scripts will directly manipulate the PVSM through it's published API using one or more of the supported scripting languages (Python, Tcl and Java). A python client will be implemented (more on this later). In order to provide a easy-to-use, full featured and backwards compatible scripting language, the following guidelines will be followed:

• Clean separation of GUI/engine functionality. All the functionality to be accessed through the scripting interfaceshould be implemented in PVSM and accesses through the publish PVSM API by the GUI.
• Stable PVSM API. Since the scripting interface will depend on the PVSM interface, PVSM API should be stable and backwards compatible as much as possible. If possible, backwards compatibility should be automatically tested routinely.
• Clear and easy-to-use API. The SM API should be clear. Although the PVSM API is verbose due to it's design, simplifications can be made in the scripting language.
• Well documented. Wherever possible, documentation should be automatically generated from the code (a la doxygen and more). Where automatically generating the documentation is not possible, it should be hand generated.

This design generates several other requirements (see below for discussion):

• Multiple clients can connect to a single PVSM simultaneously.
• Changes made by one client are communicated to all other currently clients.
• Clients are responsible for updating themselves when informed about PVSM changes.

Implementation details

Saving state/script

ParaQ will be able to save the PVSM state in two formats:

• XML
• Python scripts

Both will be generated from the in-memory representation of the state (stored as XML nodes) by either directly saving or parsing/converting. This will ensure that the code to save state is centralized and both are always in sync. Users will be able to edit and load both back into ParaQ (XML into both GUI and script clients, python into script client alone).

Script client

As mentioned above, there will be two ParaQ clients:

• Qt client
• Python client

Both will access the VTK layer through the server manager. Note that these are two separate applications. We do not plan to include a python interpreter in the Qt client. However, the python client should be able to connect to the server through sockets at the same time as the Qt client. This means both will be able to drive the same session simultaneously.

Note: When either client is running in standalone mode, the same process will be client and server at the same time. In theory, the other client should be able to connect to this process and issue SM command. Most probably, this will not be possible if the main process is the python client (i.e. python client is started first and is driving the server). Since python does not provide an event loop, it cannot listen to a socket and provide a user prompt.

Short Term Delivery: Debugging Script Window

In the short run, a python interpreter should be embedded in the Qt client to help debugging. This will allow read-only access to the PVSM state, and will allow interactive runtime debugging of the system. This short-term deliverable will be built because the capability to connect multiple clients to one server (sync'ed server managers) will not be available initially. Important restrictions on this debugging script window.

• It must not be used from any C++ code.
• It must not access the GUI (no Qt classes will be wrapped).
• It should not be used to execute arbitrary PVSM scripts, as the results of those scripts will not be communicated back to the ParaQ client (this is the read-only aspect of the debugging script window)

Multiple sync'ed clients

Multiple (currently, two) clients will be able to connect to the same server. Here, server might be a separate process or part of a stand-alone client/server process. When a client connects to a server, it will populate it's PVSM state from the server and update it's GUI (no-op for python client). It will then be possible for both client to manipulate the PVSM. When PVSM state changes, it will invoke appropriate events to notify all clients. This will allow us to:

• load a python script to modify the state of both the python client and the Qt client
• load XML state in the same way (from either client)
• to programatically drive the visualization through the python client and have the GUI update itself in the process

Simplified PVSM API

The PVSM API is verbose. For example, to create a sphere proxy, modify the origin property and update the server, the following is required

proxy = proxyManager.NewProxy("sources", "SphereSource")
origProp = proxy.GetProperty("Origin")
origProp.SetElement(0, 0)
origProp.SetElement(1, 1)
origProp.SetElement(2, 0)
proxy.UpdateVTKObjects()

In python, we should be able to create appropriate proxy class to simplify this to:

proxy = proxyManager.NewPythonProxy("sources", "SphereSource")
proxy.SetOrigin(0,1,0)
proxy.UpdateVTKObjects()

We should also make sure that the help and function listing reflects this.