Difference between revisions of "Python GUI Tools"

From KitwarePublic
Jump to navigationJump to search
 
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== New tools in python shell ==
== New Tools with Python ==


A new set of tabs has been added to the python shell.  The python shell is accessed from the main paraview menu: Tools --> Python Shell.  The new tabs are:
If ParaView has been compiled with the Python wrapping, some advanced features become available to the user such as:


* Directory view
* Accessing a Python Shell
* Trace recording
* Macros
* Macros
* Trace
* Save ParaView state as a Python script


=== Directory View ===
Those features can be reached from the Tools menu for the Shell and Trace access.


This tab has a text entry box to enter a script directory.  By default, it is set to a 'demos' subfolder inside the paraview python module directory.  Only files in the script directory ending with .py are displayed.  The following buttons are available:
The management of macros is done inside the Macros menu.


* Refresh - refreshes the directory view, for convenience if you change something on disk that paraview doesn't know about
To save the state as a Python script, go to the File menu and choose Save State without forgetting to switch the file type to be Python *.py.
* New script - launches the built in editor and displays a new document
* Run selected - runs the python script currently selected in the directory view
* Add to macros - adds the currently selected python script to the macro set
Python files in the directory view can be double clicked to open them in the editor.


=== Macros ===
=== Macros ===


Python files in the directory view can be added to the macros set.  The current macros set is displayed in the listbox in the macros tab.  You can double click a macro to edit its assigned name.  The file on disk corresponding to a macro is displayed in the tooltip if you mouseover a macro in the listbox.
Macros allow the user to define a Python script as built-in actions that become accessible from the Macros menu or directly inside the Toolbar.


Macros are displayed in the macros menu and the macros toolbar. The macro menu is shown/hidden by a checkbox in the macros tab.  The macros toolbar can be shown/hidden from the paraview main menu:  View --> Toolbars --> Macro Toolbar. Both toolbar and menu are hidden by default, but if you show them it will be remembered between sessions.
Once a local file is defined as a macro (by clicking-on Create New Macro) the given file is copied inside the user specific ParaView directory. No reference is kept to the original file.  
Therefore, if you keep editing the original file, the changes won't affect the macro itself.  


Macros are saved between sessions using the [[ParaView Settings Files]].  Macros are referenced by absolute filename, so if the python file moves on disk the macro will no longer function.
The macros list is built dynamically at the ParaView start-up by listing the content of the ParaView/Macros directory, the user specific ParaView/Macros directory, and the additional directories defined by the user in the environment variable PV_MACRO_PATH.
Note: if you want to rename a macro, rename the file in one of the given directory.


Note: python is not initialized until you open the python shell for the first time. If you run a macro from the macro toolbar or menu before the python shell has been opened for the first time, you will notice a slight delay as python initializes itself. You should see a wait cursor while python is initializing.
Deleted macros DO NOT delete the files, but just rename them with a "." before the original file name and the file stays in the same directory.
 
Macros are displayed in the macros menu and the macros toolbar. The macros toolbar can be shown/hidden from the ParaView main menu: '''View'''|Toolbars|Macro Toolbar. The toolbar may be hidden by default.
 
Note: Python is not initialized until you open the Python shell for the first time. If you run a macro from the macro toolbar or menu before the Python shell has been opened for the first time, you will notice a slight delay as Python initializes itself. You should see a wait cursor while Python is initializing.
 
'''CAUTION''': If this section is not relevant for your ParaView version, please read the previous version of that page in history. This is for ParaView 3.10.


=== Trace ===
=== Trace ===


Trace is a new module. It can be imported with 'from paraview import smtrace', but normally the user never needs to directly use the trace module.  The trace tab provides buttons for controlling trace:
Trace as been introduced in ParaView 3.6.2 as a new module. It can be imported with "from paraview import smtrace," but normally the user never needs to directly use the trace module.  The trace menu items provides everything for controlling trace:


* Start trace - starts trace.  If an active trace was previously started, it will be stopped, cleared, and restarted.
* '''Start trace''' - Starts trace.  If an active trace was previously started, it will be stopped, cleared, and restarted.
* Stop trace- stops trace.  The trace output generated so far will not be cleared until trace is started again or the python shell is reset. Some internal trace data structures hold references to c++ objects, so if you want to make sure everything is cleaned up try resetting the shell.
* '''Stop trace'''- Stops trace.  The trace output generated so far will not be cleared until trace is started again or the Python shell is reset. Some internal trace data structures hold references to C++ objects, so if you want to make sure everything is cleaned up try resetting the shell.
* Show trace- prints the current trace output in the python shell for display
* '''Edit trace'''- Opens the built in editor, creates a new document, and fills it with the current trace output.
* Edit trace- opens the built in editor, creates a new document and fills it with the current trace output
* '''Save trace'''- Opens a prompt for the user to specify a file name and saves trace to disk.
* Save trace- opens a prompt for the user to specify a filename and saves trace to disk.  The trace script is now available in the directory view.


<font color="red">TIP</font>: It's a good idea to stop trace before executing a trace script you just recorded. You can click the Disconnect Server button in the ParaView toolbar. This will clear the current pipeline objects, stop trace, and reset the Python interpreter.


TIP: It's a good idea to stop trace before executing a trace script you just recorded.  What I do is click the Disconnect server button in the paraview toolbarThis will clear the current pipeline objects, stop trace, and reset the python interpreter.
<font color="red">TIP</font>: Trace only records property values as they are modified.  If you have initialized a render view or a color lookup table prior to starting trace then the generated trace script may not perfectly reflect the state of the view or lookup tableFor best results, start trace before performing any other actions.  Also, see the CaptureAllProperties flag in the Trace Verbosity section below.


=== Trace verbosity ===
=== Trace Verbosity ===


Because of the way the GUI initializes certain proxies, some parts of the trace will be more verbose than others.   For example, every time a data representation is created, seven or eight properties related to selection are modified. It might be a nice feature to provide the user with a way to specify property suppressions.
Because of the way the GUI initializes certain proxies, some parts of the trace will be more verbose than others. For example, every time a data representation is created, seven or eight properties related to selection are modified. It might be a nice feature to provide the user with a way to specify property suppressions.


 
Trace can run with different verbose levels. In full property verbose mode, trace records all properties of a proxy when the proxy is registered. Normally, trace only records properties when they are modified from their default values. Control over the verbosity level is not currently available in the GUI, but you can start trace manually in verbose mode using the Python shell:
Trace can run with different verbose levels. In full property verbose mode, trace records all properties of a proxy when the proxy is registered. Normally, trace only records properties when they are modified from their default values. Control over the verbosity level is not currently available in the gui, but you can start trace manually in verbose mode using the python shell:


<pre>
<pre>
Line 57: Line 60:
</pre>
</pre>


=== Known issues with trace ===
=== Known Issues with Trace ===
 
It is possible to perform actions in the GUI that do not translate properly to trace.  Here is a list of things that do not currently work:
 
* renaming an object in the pipeline browser
* filters that use glyphs
* views other than 3D render view (also have not tested mpi render view)
* time
* scalar bar does work, but only if it's the last thing you add to the view
 


=== New built in editor ===
It is possible to perform actions in the GUI that do not translate properly to Trace.  Here is a list of things that do not currently work:


For convenience there is a new built in script editor.  When the editor is opened on OSX, the editor's menubar temporarily replaces paraview's menubar.  If this becomes too obtrusive the menu could be replaced by toolbar buttons.  It might be a nice feature to allow the user to specify a command to launch an external editor.
* Views other than 3D render view (also have not tested MPI render view)
* Time
* The start/stop trace buttons are not synced if trace is started manually from Python


=== UI issues ===
=== New Built-in Editor ===


The new tab widget is embeded in the python shell dialog using a QSplitter. The tabs can be hidden completely by collapsing the splitterThe splitter state should be remembered between sessions.  So should the size/position of the python dialog, and the size/position of the script editor
For convenience, there is a new built-in script editor. When the editor is opened on OSX, the editor's menu-bar temporarily replaces ParaView's menu-bar. If this becomes too obtrusive, the menu could be replaced by toolbar buttonsIt might be a nice feature to allow the user to specify a command to launch an external editor.
Please report any ui issues with the new python gui, and include your platform and qt version.


== New C++ API ==
== New C++ API ==


New classes have been introduced under Qt/Python. They depend on classes in Qt/Core but not Qt/Components. A new class named pqPythonManager is available globally through the pqApplicationCore instance:
New classes have been introduced under Qt/Python. They depend on classes in Qt/Core but not Qt/Components. A new class named pqPythonManager is available globally through the pqApplicationCore instance:


<pre>
<pre>
Line 86: Line 81:
</pre>
</pre>


The python manager has a public method:
The Python manager has a public method:


<pre>
<pre>
Line 92: Line 87:
</pre>
</pre>


Calling this method will return the python shell. Python will be initialized on the first call to this method and the returned pqPythonDialog will be ready to use. pqPythonDialog offers public methods for executing python files and strings of python code.
Calling this method will return the Python shell. Python will be initialized on the first call to this method and the returned pqPythonDialog will be ready to use. pqPythonDialog offers public methods for executing Python files and strings of Python code.


If you plan to call methods in the python c api, you must make the python interpreter active:
If you plan to call methods in the Python C API, you must make the Python interpreter active:


<pre>
<pre>
Line 105: Line 100:
</pre>
</pre>


When the python interpreter is reset, pqPythonDialog emits a signal 'interpreterInitialized()'. The pqPythonManager listens for this signals and imports the paraview modules. So when this signal is triggered, it is not guaranteed that paraview python modules have been imported yet. After the paraview python modules are imported, the pqPythonManager emits a signal 'paraviewPythonModulesImported()'.
When the Python interpreter is reset, pqPythonDialog emits a signal interpreterInitialized(). The pqPythonManager listens for this signals and imports the ParaView modules. So when this signal is triggered, it is not guaranteed that ParaView Python modules have been imported yet. After the ParaView Python modules are imported, the pqPythonManager emits a signal paraviewPythonModulesImported().

Latest revision as of 07:20, 18 August 2015

New Tools with Python

If ParaView has been compiled with the Python wrapping, some advanced features become available to the user such as:

  • Accessing a Python Shell
  • Trace recording
  • Macros
  • Save ParaView state as a Python script

Those features can be reached from the Tools menu for the Shell and Trace access.

The management of macros is done inside the Macros menu.

To save the state as a Python script, go to the File menu and choose Save State without forgetting to switch the file type to be Python *.py.

Macros

Macros allow the user to define a Python script as built-in actions that become accessible from the Macros menu or directly inside the Toolbar.

Once a local file is defined as a macro (by clicking-on Create New Macro) the given file is copied inside the user specific ParaView directory. No reference is kept to the original file. Therefore, if you keep editing the original file, the changes won't affect the macro itself.

The macros list is built dynamically at the ParaView start-up by listing the content of the ParaView/Macros directory, the user specific ParaView/Macros directory, and the additional directories defined by the user in the environment variable PV_MACRO_PATH. Note: if you want to rename a macro, rename the file in one of the given directory.

Deleted macros DO NOT delete the files, but just rename them with a "." before the original file name and the file stays in the same directory.

Macros are displayed in the macros menu and the macros toolbar. The macros toolbar can be shown/hidden from the ParaView main menu: View|Toolbars|Macro Toolbar. The toolbar may be hidden by default.

Note: Python is not initialized until you open the Python shell for the first time. If you run a macro from the macro toolbar or menu before the Python shell has been opened for the first time, you will notice a slight delay as Python initializes itself. You should see a wait cursor while Python is initializing.

CAUTION: If this section is not relevant for your ParaView version, please read the previous version of that page in history. This is for ParaView 3.10.

Trace

Trace as been introduced in ParaView 3.6.2 as a new module. It can be imported with "from paraview import smtrace," but normally the user never needs to directly use the trace module. The trace menu items provides everything for controlling trace:

  • Start trace - Starts trace. If an active trace was previously started, it will be stopped, cleared, and restarted.
  • Stop trace- Stops trace. The trace output generated so far will not be cleared until trace is started again or the Python shell is reset. Some internal trace data structures hold references to C++ objects, so if you want to make sure everything is cleaned up try resetting the shell.
  • Edit trace- Opens the built in editor, creates a new document, and fills it with the current trace output.
  • Save trace- Opens a prompt for the user to specify a file name and saves trace to disk.

TIP: It's a good idea to stop trace before executing a trace script you just recorded. You can click the Disconnect Server button in the ParaView toolbar. This will clear the current pipeline objects, stop trace, and reset the Python interpreter.

TIP: Trace only records property values as they are modified. If you have initialized a render view or a color lookup table prior to starting trace then the generated trace script may not perfectly reflect the state of the view or lookup table. For best results, start trace before performing any other actions. Also, see the CaptureAllProperties flag in the Trace Verbosity section below.

Trace Verbosity

Because of the way the GUI initializes certain proxies, some parts of the trace will be more verbose than others. For example, every time a data representation is created, seven or eight properties related to selection are modified. It might be a nice feature to provide the user with a way to specify property suppressions.

Trace can run with different verbose levels. In full property verbose mode, trace records all properties of a proxy when the proxy is registered. Normally, trace only records properties when they are modified from their default values. Control over the verbosity level is not currently available in the GUI, but you can start trace manually in verbose mode using the Python shell:

from paraview import smtrace
smtrace.start_trace(CaptureAllProperties=True)

# actions in the gui

smtrace.stop_trace()

Known Issues with Trace

It is possible to perform actions in the GUI that do not translate properly to Trace. Here is a list of things that do not currently work:

  • Views other than 3D render view (also have not tested MPI render view)
  • Time
  • The start/stop trace buttons are not synced if trace is started manually from Python

New Built-in Editor

For convenience, there is a new built-in script editor. When the editor is opened on OSX, the editor's menu-bar temporarily replaces ParaView's menu-bar. If this becomes too obtrusive, the menu could be replaced by toolbar buttons. It might be a nice feature to allow the user to specify a command to launch an external editor.

New C++ API

New classes have been introduced under Qt/Python. They depend on classes in Qt/Core but not Qt/Components. A new class named pqPythonManager is available globally through the pqApplicationCore instance:

  pqPythonManager* manager = qobject_cast<pqPythonManager*>(
    pqApplicationCore::instance()->manager("PYTHON_MANAGER"));

The Python manager has a public method:

  pqPythonDialog* pythonShellDialog();

Calling this method will return the Python shell. Python will be initialized on the first call to this method and the returned pqPythonDialog will be ready to use. pqPythonDialog offers public methods for executing Python files and strings of Python code.

If you plan to call methods in the Python C API, you must make the Python interpreter active:

  pqPythonDialog* dialog = manager->pythonShellDialog();
  dialog->shell()->makeCurrent();

  // Calls to python c api

  dialog->shell()->releaseControl();

When the Python interpreter is reset, pqPythonDialog emits a signal interpreterInitialized(). The pqPythonManager listens for this signals and imports the ParaView modules. So when this signal is triggered, it is not guaranteed that ParaView Python modules have been imported yet. After the ParaView Python modules are imported, the pqPythonManager emits a signal paraviewPythonModulesImported().