From: abn Date: Tue, 17 Mar 2015 12:54:54 +0000 (+0100) Subject: Added developper's documentation in the Sphinx format. X-Git-Tag: V7_6_0a1~7^2~3 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=5a23b824aadf7cd5ae3da123388d3d02bd64f550;p=modules%2Fparavis.git Added developper's documentation in the Sphinx format. --- diff --git a/doc/GeneralArchitecture.html b/doc/GeneralArchitecture.html deleted file mode 100644 index 4f568cef..00000000 --- a/doc/GeneralArchitecture.html +++ /dev/null @@ -1,935 +0,0 @@ - - - - - - - - - - - -

PARAVIS development

-

General architecture of PARAVIEW -extractor

-

-1.Introduction

-

2.General -architecture

-

3.Automatic -generation of container classes

-

-3.1. -Source files related to PARAVIS server definition

-

3.2. -Process of generation

-

3.3. -Definition of IDL interfaces

-

3.4. -Base interface and its implementation

-

3.5. -GUI events queue

-

3.6. -Overloaded methods definition

-

3.7. -Creation of objects in Python

-

3.8. -servermanager.py and simple.py

-

4.Trace -functionality

-



-

-



-

-

Introduction

-

This document describes development of ParaView server manager API -for PARAVIS module. The new API must provide following features:

-
    -

  1. Define interaction between two different processes: Python - console and PARAVIS GUI defined in SALOME desktop.

    -

  2. Make possible to manage PARAVIS GUI and ParaView server data - from Python scripts in synchronized mode.

    -

  3. The new API must be similar as much as possible to the API - provided by servermanager.py module from ParaView in order to make - possible launching the same scripts as in ParaView as in PARAVIS - without modifications.

    -
-

General architecture and development features of this task are -described below.

-

General architecture

-

Main components of PARAVIS architecture and their relations can be -represented as on the following picture:

-




-

-

The usual way to implement SALOME module is to develop a -Data/Algorithms engine unit as a CORBA server and module GUI as a -CORBA client. But in case if we need to use GUI and Algorithms from -Python console (what usually is an external process) in synchronized -mode then we have to implement them together as a CORBA server within -a one process.

-

On the diagram above following component are shown: -

- -

-Automatic generation of container classes

-

Source files related to PARAVIS server definition

-

In PARAVIS_SRC/idl/ directory:

-
    -

  1. PARAVIS_Gen.idl – defines main interfaces to PARAVIS - module.

    -

  2. PARAVIS_Gen_Types.idl – defines data collection - types.

    -

  3. hints_paravis – defines sizes of arrays missed in - standard VTK hints file. If some functions of VTK classes which - return array data are not extracted then it is necessary to edit - this file in order to describe missed functions.

    -

  4. pythonIDL.py – command file which is used for - extraction of IDL interfaces to Python files. This is modification - of similar file from omniidl product what takes into account - overloading of methods in class.

    -

  5. vtkWrapIDL.c – source file for building extraction - executables: vtkWrapIDL, - vtkWrapIDL_CC, vtkWrapIDL_HH.

    -
-

In PARAVIS_SRC/src/PVGUI directory:

-
    -

  1. PARAVIS_Gen_i.cc and - PARAVIS_Gen_i.hh – implementation - of PARAVIS_Gen interface.

    -

  2. PV_Events.h – defines - events for synchronization of CORBA client calls with main GUI - events queue.

    -

  3. Other files are related to GUI - definition and auxiliary tools.

    -
-

In PARAVIS_SRC/src/PV_SWIG -directory:

-
    -

  1. paravis.py – general - Python module for PARAVIS. It installs connection to PARAVIS CORBA - server, defines a variable myParavis in - order to provide acces to PARAVIS_Gen functions, - creates a set of empty constructors for all extracted ParaView - classes.

    -

  2. paravisSM.py – modified - copy of servermanager.py module from ParaView. Modification done - according to conventions defined by paravis.py module and features - of working with CORBA server.

    -

  3. pvsimple.py – modified - copy of simple.py module from ParaView. Modifications done because - of the same reasons.

    -
-

Process of generation

-

CORBA servant classes for wrapping of server manager API classes -is generated automatically. The process of building PARAVIS module -with generation of wrappers is performed in the following way:

-
    -

  1. Execute cmake command from a build directory. - During performing of this command it performs some standard steps - of SALOME module building and calls a Python command file - getwrapclasses.py is called. This procedure creates a list - of ParaView and VTK class names what has to be extracted. - This list includes all vtkSM* classes and vtk* classes - what are referred by previous group of classes. Results - of build_configure step are:

    -
      -

    1. idl/wrap.cmake – defines variables what lists all interfaces - (*.idl and *.cc files) what will be generated.

      -

    2. idl/vtkWrapIDL.c – defines a list of extracted classes in - form of char* array.

      -

    3. src/PVGUI/PARAVIS_CreateClass.cxx is a C++ file what - contains a one function CreateInstance. This function creates a - servant class which corresponds to a given name of original - ParaView/VTK class.

      -
    -

  2. Call make command in build directory. This command - does following steps related to automatic generation:

    -
      -

    1. Builds vtkWrapIDL executable in idl directory - what is responsible for generation of IDL files using names of - classes to wrap. This executable analyzes related header files for - classes from vtkWrapIDL.h and defines corresponded IDL file.

      -

    2. Defines all IDL files with help of this executable and - launches standard SALOME compilation for idl directory.

      -

    3. Compiles vtkWrapIDL_CC and - vtkWrapIDL_HH executables - in src/PVGUI directory what are responsible for generation of - header files (*.hh) and implementation files (*.cc) for servants - classes.

      -

    4. Generation of servant classes - with help of these executables and building the library.

      -
    -

  3. Call make install - command in build directory. This - will finalize building of libraries and generate Python files for - IDL interfaces.

    -
-

Note:

-

make -command can not be used with -j key because extraction of parent -classes should be done before extraction of child classes.

-

Definition of IDL interfaces

-

Process of IDL interfaces generation has to respect following -restrictions of IDL format:

-
    -

  1. IDL does not support several functions with the same name - within a one interface definition. Even they have different - parameters (overloading of methods as in C++). Also this is not - supported between parent and its ancestors.

    -

  2. In context of PARAVIS it is difficult to extract methods what - accept or return “void*” data type. In IDL it can be described - as “ANY” data type, but in context of ParaView it is not clear - to what type it has to be casted.

    -
-

IDL interfaces extracted following to the next principals:

-
    -

  1. All interfaces are inherited from a common parent interface - Base. -

    -

  2. Each interface includes all extracted methods of its - prototype class including all its parents.

    -

  3. If the prototype class contains overloaded methods (methods - with the same name) then each appearance of this method name is - supplied with index.

    -

  4. If prototype class contains methods which return or accept - void* then these methods are ignored.

    -

  5. If prototype class contains methods which return array (int*, - double*, ...) which size is not defined in “hints” or - “hints_paravis” files then these methods are ignored.

    -

  6. If prototype class - contains methods which get a pointer to function then these methods - are ignored.

    -

  7. If a method of prototype class returns/accepts a pointer on - ParaView/VTK class instance then interface will return/accept Base - interface.

    -
-

Base interface and its implementation

-

Base interface is defined in order to satisfy following points:

-
    -

  1. Sometimes we need to have a possibility to use a servant as a - pointer on a common interface.

    -

  2. We need to have possibility to define a common auxiliary - methods for all generated interfaces which out of ParaView/VTK - definitions.

    -

  3. We need to have a base implementation for all servant - classes.

    -
-

Currently Base class implements smart pointer on a vtkObjectBase -instance and several methods to Get/Set this pointer. By default each -ancestor class initializes this pointer with help of New() method. -This useful for classes what contain static methods. But after this -pointer can be reinitialized from outside what is used when we need -to have access to certain instance.

-

Also Base interface introduces a method IsSame(Base theOther). We -need this method when it is necessary to compare two ParaView objects -in Python process. In fact if we will apply standard operation “==” -then we will compare two wrapper instances instead of ParaView -objects instances. So, method IsSame(Base theOther) checks if two -wrappers refer to the same ParaView instance or not.

-

GUI events queue

-

Some calls of server manager API functions cause a modification of -GUI state: creation of new widgets, update of widgets state, -visualization of presentable objects in viewers. In our case we have -two different processes: Python console and PARAVIS GUI. At the same -moment the Python console “manages” PARAVIS GUI with help of -server manager API functions calls. So, for correct performance of -Python scripts the calls of Python commands have to be synchronized -with PARAVIS GUI events queue.

-

For this purposes all calls to server manager API from servant are -additionally wrapped by event classes. Therefore implementation of -servants methods accords to following general template:

-
    -

  1. Get an encapsulated pointer on VTK object instance.

    -

  2. Create a special event instance for target function call.

    -

  3. Launch event and wait while it returns.

    -

  4. Get result from event (if result is supposed).

    -

  5. Return this result as result of servant method.

    -
-

For example:

-

Class vtkSMProxyManager has a method GetProxy. This method -implemented in corresponded servant class as following:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

#

- 		-

Code

- 		-

Remarks

-
-

1

- 		-

//C++: - vtkSMProxy *GetProxy (const char *groupname, const char *name);

- 		-


-

-
-

2

- 		-

struct - CreateEventName(GetProxy_0): public SALOME_Event

- 		-

Generation - of unique event class name with help of a special macros

-
-

3

- 		-

{

- 		-


-

-
-

4

- 		-

typedef - ::vtkSMProxy* TResult;

- 		-


-

-
-

5

- 		-

TResult - myResult;

- 		-

Definition - of the return type

-
-

6

- 		-

typedef - ::vtkSMProxyManager* TObj;

- 		-


-

-
-

7

- 		-

TObj - myObj;

- 		-

Definition - of parameters

-
-

8

- 		-

typedef - char* TParam0;

- 		-


-

-
-

9

- 		-

TParam0 - myParam0;

- 		-


-

-
-

10

- 		-

typedef - char* TParam1;

- 		-


-

-
-

11

- 		-

TParam1 - myParam1;

- 		-


-

-
-

12

- 		-


-

- 		-


-

-
-

13

- 		-

CreateEventName(GetProxy_0)(TObj - theObj, TParam0 theParam0, TParam1 theParam1):

- 		-

Constructor - of event. Defines object instance and necessary parameters

-
-

14

- 		-

myObj(theObj), - myParam0(theParam0), myParam1(theParam1)

- 		-


-

-
-

15

- 		-

{ - }

- 		-


-

-
-

16

- 		-


-

- 		-


-

-
-

17

- 		-

virtual - void Execute()

- 		-

Execution - method.

-
-

18

- 		-

{

- 		-


-

-
-

19

- 		-

myResult - = myObj->GetProxy(myParam0, myParam1);

- 		-

Call - of target method

-
-

20

- 		-

}

- 		-


-

-
-

21

- 		-

};

- 		-


-

-
-

22

- 		-

//

- 		-


-

-
-

23

- 		-

PARAVIS_Base_ptr - vtkSMProxyManager_i::GetProxy_0 (const char *temp0, const char - *temp1) {

- 		-

Implementation - of servant method

-
-

24

- 		-

try - {

- 		-


-

-
-

25

- 		-

char - *c_temp0 = CORBA::string_dup(temp0);

- 		-

Getting - parameters

-
-

26

- 		-

char - *c_temp1 = CORBA::string_dup(temp1);

- 		-


-

-
-

27

- 		-

::vtkSMProxy* - avtkSMProxy = (getVTKObject() != NULL) ? ProcessEvent(new - CreateEventName(GetProxy_0)((::vtkSMProxyManager*)getVTKObject(), - c_temp0 , c_temp1)):NULL;

- 		-

If - wrapped object is defined then create event and launch it. Finally - it will return result.

-
-

28

- 		-


-

- 		-


-

-
-

29

- 		-

if(avtkSMProxy - == NULL) {

- 		-


-

-
-

30

- 		-

return - PARAVIS::vtkSMProxy::_nil();

- 		-


-

-
-

31

- 		-

}

- 		-


-

-
-

32

- 		-

PARAVIS_Base_i* - aPtr = ::CreateInstance(avtkSMProxy, - avtkSMProxy->GetClassName());

- 		-

Create - a wrapper (servant) class according to class name of result object

-
-

33

- 		-

aPtr->Init(avtkSMProxy);

- 		-

Initialize - the internal pointer of wrapper class by result

-
-

34

- 		-

return - aPtr->_this();

- 		-

Return - wrapper instance as result

-
-

35

- 		-

} - catch(...) {

- 		-


-

-
-

36

- 		-

MESSAGE("GetProxy - - Unknown exception was occurred!!!");

- 		-


-

-
-

37

- 		-

return - PARAVIS::vtkSMProxy::_nil();

- 		-


-

-
-

38

- 		-

}

- 		-


-

-
-

39

- 		-

}

- 		-


-

-
-


-

-

Overloaded methods definition

-

Classes of ParaView server manager API have overloaded methods. As -it is mentioned above description of IDL interface prohibits using of -the same name for various methods even they have different -parameters. To avoid this limitation we have to add index to name in -each appearance of overloaded method. But at Python script level it -is necessary to avoid using of function names with indexes. It is -necessary to provide possibility to use methods as they was defined -in API of corresponded class.

-

For tis purposes we redefined standard IDL to Python wrapping in -order to add a function which has a name of overloaded method and -accepts any parameters. This function analyzes input parameters and -selects what function (with which index) it has to be called.

-

For example:

-

vtkObject class contains definition of overloaded functions:

-

void RemoveObservers -(unsigned long event);

-

void RemoveObservers -(const char *event);

-


-

-

In IDL interface these function will be -defined as:

-

void _RemoveObservers_0 -(in long temp0);

-

void _RemoveObservers_1 -(in string temp0);

-


-

-

These functions -will be wrapped by standard IDL to Python wrapper as it is (with -indexes). But we need to call this function in Python as they were -defined in vtkObject definition – by name “RemoveObservers”. -For this purposes we modify IDL to Python wrapper in order to add the -following function:

-

def -RemoveObservers(self, *args):

-

if len(args) == 1 and -(type(args[0]) in [IntType, LongType]):

-

return -self.RemoveObservers_0(*args)

-

if len(args) == 1 and -(type(args[0]) in [StringType]):

-

return -self.RemoveObservers_1(*args)

-

print 'Warning: The -corresponding method of RemoveObservers group is not found for ' + -str(args)

-


-

-

After this we can use function -RemoveObserves in Python as it was defined without indexes.

-

Creation of objects in Python

-

Creation of CORBA object on client side is not so trivial as -usually. When client requests a creation of object then it has to be -created: -

- -

More simplest way is to request an -object from PARAVIS server interface PARAVIS_Gen. For this -purposes a method CreateClass function in PARAVIS_Gen -interface is defined. Also there is a function GetClassesList -which returns list of names of extracted classes. Both these methods -let to define a set of functions which looks like an object -constructor for all extracted classes. -

-

These definitions done in paravis.py -module with help of createConstructors function. Result of this -function is a set of functions which looks like vtkClassName(). These -functions return an object instance which wraps a pointer on -requested class vtkClassName instance with corresponded API.

-

For example call in Python console

-

> a = -vtkSMProxyManager()

-

returns an instance of -PARAVIS_Gen_vtkSMProxyManager object on client side which implements -all methods of vtkSMProxyManager class readdressing them to -incapsulated vtkSMProxyManager instance on server side.

-

servermanager.py and simple.py

-

In ParaView Python API is defined -with help of two modules servermanager.py and simple.py. PARAVIS has -corresponded modules paravisSM.py and pvsimple.py. Because of actions -described above we got a set of Python interfaces which is very close -to original Python API of ParaView. So, PARAVIS Python modules have -fiew modifications in comparison to original ones. These -modifications mainly related to:

-
    -

  1. Already mentioned problem with - “==” operation to wrapper classes.

    -

  2. Impossibility to use observers.

    -

  3. Reimplementation of hidden code - existing in ParaView which is called in Python console on its - creation.

    -

  4. Providing access to Trace - functionality.

    -
-

Trace functionality

-

Trace functionality in PARAVIS module is defined in GUI of module -using already existing Python functions in ParaView.

-

Because this trace functionality is used for “Dump Study” -functionality defined in SALOME then tracing is started automatically -on loading of PARAVIS module and registers all actions during whole -session. In case if there are no necessity tracing can be switched -off in preferences dialog box. But it is necessary to take into -account that dumping of study can't be done for PARAVIS module in -this case.

-

To check the trace content there are two functions defined in -pvsimple.py module and accessible in SALOME Python console:

- -

Connection with other SALOME modules

-

According to SALOME general architecture each module independs -from other modules by default. In general case adding of module to -module dependency can be caused by necessity to transfer some data -from one module to another. In this case a module consumer has to -“know” about API of module supplier what is going to be used. If -this API is not defined on a general module level then we have to use -direct connection to module object instance what implements a -necessary API.

-

In general algorithm of connected to a module-supplier API on a -module-consumer side looks like following:

-
    -

  1. Find and load a module-supplier component CORBA object from - active study.

    -

  2. Get a module-supplier engine from the component.

    -

  3. Using of the engine to get necessary data.

    -
- - \ No newline at end of file diff --git a/doc/GeneralArchitecture_html_m4ed0a034.gif b/doc/GeneralArchitecture_html_m4ed0a034.gif deleted file mode 100644 index 7bc987da..00000000 Binary files a/doc/GeneralArchitecture_html_m4ed0a034.gif and /dev/null differ diff --git a/doc/UserDocumentation.html b/doc/UserDocumentation.html deleted file mode 100644 index 2960bc89..00000000 --- a/doc/UserDocumentation.html +++ /dev/null @@ -1,166 +0,0 @@ - - - - - - - - - - -

PARAVIS development

-

PARAVIS user documentation

-

1.Introduction

-

2.Building -environment

-

3.VTK -library

-

4.Building -of PARAVIS

-

5.Starting -SALOME with PARAVIS

-

6.Commands -accessible in Python console

-

7.Trace -management

-

8.PARAVIS -GUI specific

-

9. -PARAVIEW options

-

Introduction

-

This document describes features of -ParaView Python extractor using in PARAVIS module of SALOME platform. -In general building of PARAVIEW module is not too much differ from -usual process of any other SALOME module building, and result Python -API extracted for using in SALOME Python console is similar to the -server manager API of ParaView. But there are some features what is -desirable to understand for effective using of extractor.

-

Building environment

-

It is -necessary to check that PARAVIS_SRC directory contains following -files and they are up-to-date:

-
    -

  1. src/Paraview/lex.yy.c

    -

  2. src/Paraview/vtkParse.tab.c

    -

  3. src/Paraview/vtkParse.h

    -
-

VTK library

-

SALOME already -uses VTK library for visualization and post-processing purposes. -PARAVIS also uses VTK library supplied with ParaView. In order to -avoid problem with using of different versions of VTK library in -different components of SALOME platform it is necessary to use the -same version supplied with ParaView for all components and modules of -SALOME. -

-

For this -purposes a new option “--with-paraview” has been defined -for configure script. This option configures building procedure to -use VTK from ParaView. It means that GUI package and all modules has -to be configured with this option.

-

Building of PARAVIS

-


-

-
    -

  1. - Call cmake in a build directory: -

    -

    - > - ccmake ../PARAVIS_SRC

    -

  2. Call make command in build directory. -

    -

    > make

    -

  3. - Call - make install command in build directory. -

    -

    - > make - install

    -
-

-Starting -SALOME with PARAVIS

-

> runSalome –modules="PARAVIS"

-

If it is necessary then other SALOME modules can be added to -“modules” list separated by comma.

-

Commands -accessible in Python console

-

Loading ParaView Python API for PARAVIS can be done with help of -command:

-

> from pvsimple import *

-

This command makes accessible the same Python API what provided by -simple.py module in ParaView (see ParaView documentation). -

-

Trace management

-

Last version of ParaView is supplied with trace functionality. -PARAVIS also supports this feature. But in contrary to ParaView, -which can start/stop trace in any moment, in PARAVIS trace is -activating or deactivating for whole session.

-

Trace functionality can be switched on/off in SALOME preferences -dialog box in PARAVIS tab (main menu | Preferences...). It contains -check box “Deactivate Trace”. By default the trace is -activated. Change of check box state makes effect only for next -session.

-

User can get the trace with help of two commands (after pvsimple -import):

-
    -

  1. PrintTrace() - prints the trace content directly into Python - console window.

    -

  2. SaveTrace(fileName) - saves the trace into a given disk file.

    -
-

Also trace is using for “Dump Study” functionality. -But if the tracing is switched off then “Dump Study” -doesn't saves PARAVIS module state.

-

SALOME study save

-

On SALOME study saving PARAVIS module data is also saved in the -study. This data is saved in form of ParaView state file. ParaView -state file could have references on external files imported during -PARAVIS working session. These referenced files can be saved with the -current study depending on preference “Paraview state saving -type” defined in PARAVIS preferences dialog box. This -preference can have three possible state:

-
    -

  1. “Save referenced files only for built-in server”. - In case if this option is active then referenced files will be saved - in study together with ParaView state only if in PARAVIS was used - built-in ParaView server. In case of remote ParaView server the - state will be saved as it is without referenced files.

    -

  2. “Always save referenced files if they are accessible”. - In this case referenced files will be saved with ParaView state for - any type of ParaView server but only in case if they are accessible - across local file system.

    -

  3. “Never save referenced files”. In this case - referenced files will be never saved with ParaView state.

    -
-

It is necessary to be aware that if referenced files are not saved -in study then there is no guarantee that the saved study will be -opened correctly on other station or if the referenced files will be -moved or deleted.

-

PARAVIS GUI specific

-

In fact -PARAVIS is a ParaView GUI integrated into SALOME environment. General -architecture of ParaView is very different from general architecture -of SALOME. If SALOME is an application which is able to open several -documents (studies) within one application session because it has -multi-document architecture, then ParaView has a single document -architecture what means that it can have only one document (data -structure) opened within one session.

-

This leads to -the fact that PARAVIS module can be opened only once within SALOME -application session. It can be opened only in a first desktop -appeared after SALOME launch. Other desktops, even they opened with -study containing PARAVIS data, can not load PARAVIS module.

-



-

-

PARAVIEW options

-

If it is necessary to define a spcific command line -parameters for ParaView application then it can be defined with help -of PARAVIS_OPTIONS environment variable. For example:

-

export PARAVIS_OPTIONS=--server=myServer

-

If it is necessary to define several command line -parameters then these parameters has to be separated by “:” -symbol.

- - \ No newline at end of file diff --git a/doc/dev/CMakeLists.txt b/doc/dev/CMakeLists.txt index 6ab4f644..95121a0a 100644 --- a/doc/dev/CMakeLists.txt +++ b/doc/dev/CMakeLists.txt @@ -26,6 +26,7 @@ ADD_CUSTOM_TARGET(html_docs COMMAND ${_cmd}) INSTALL(CODE "EXECUTE_PROCESS(COMMAND \"${CMAKE_COMMAND}\" --build ${PROJECT_BINARY_DIR} --target html_docs)") INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION ${SALOME_INSTALL_DOC}/dev/PARAVIS) +INSTALL(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/images DESTINATION ${SALOME_INSTALL_DOC}/dev/PARAVIS/images) SET(make_clean_files html doctrees) SET_DIRECTORY_PROPERTIES(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${make_clean_files}") diff --git a/doc/dev/images/archi.jpg b/doc/dev/images/archi.jpg new file mode 100644 index 00000000..803bc795 Binary files /dev/null and b/doc/dev/images/archi.jpg differ diff --git a/doc/dev/index.rst b/doc/dev/index.rst index bd5a9200..e34405bb 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -2,10 +2,9 @@ PARAVIS Module - Architecture and conception ############################################ -This documentation is intended for SALOME's developpers or anyone wishing to modify the module itself. +*This documentation is intended for SALOME's developpers or anyone wishing to modify the module itself. If you are looking for user documentation, please launch SALOME, activate the PARAVIS module, and refer -to the Help menu there. - +to the Help menu there.* PARAVIS is the visualization module of SALOME. The module is a tight integration of the functionalities offered by ParaView in the SALOME architecture. @@ -13,23 +12,246 @@ The architecture of the PARAVIS module has been revised end of 2014 to offer a s If you are looking for the Doxygen of the C++ code, it can be found here: `Doxygen documentation `_ -.. toctree:: - :maxdepth: 1 +Overview - Executive summary +%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The PARAVIS module represents the integration of ParaView inside SALOME. + +SALOME uses by default the *detached* server mode of ParaView: the ``pvserver`` is launched outside the main Salome process +and the ParaVis module, or the PVViewer view (Window -> ParaView view) connects to it. + +Following this logic, the PVSERVER CORBA service has a very restrained role. Its only purpose is to: + +* control the start and stop of the pvserver process +* provide the URL of the pvserver, so that a client can connect to it. + +Hence, we emphazise the fact that the CORBA engine does *not* provide any access to the objects or the visualisation +results themselves. It only serves to establish the link with the ``pvserver``. The latter can then be queried (with +the standard ParaView mechanisms) to retrieve those objects. + +A typical session looks like this: + +* start SALOME's GUI +* request activation of PARAVIS (or request activation of a *Paraview's View*) + * activation of the PVSERVER CORBA service + * invokation of the method ``FindOrStartPVServer()``: launches the pvserver process and returns its URL + (in the standard ParaView's format, e.g. ``cs://localhost:11111``) + * invokation of the standard ParaView's API to connect to the pvserver (e.g. ``Connect()`` method in the + Python module ``paraview.simple``) +* use the standard ParaView's API to interact with the server (either from the C++ side, within SALOME's GUI + or from a Python script, using for example the methods provided in the Python module ``pvsimple``). + +The picture below summarizes the architecture: + +.. image:: images/archi.jpg + :scale: 70 + +In terms of code structure, the main, all the initialization logic of ParaView is attached to the ``PVViewer`` +(ParaView's viewer) located in the GUI module in the **src/PVViewer** folder. +The CORBA engine and the graphical interface of the ParaVis module are located in the ParaVis module of SALOME. + +Functionalities +%%%%%%%%%%%%%%% + +The following functionalities are offered by the PVSERVER and the ParaVis module: + +* full embedding of ParaView's functionalities inside SALOME environment +* manage ParaVis GUI and ParaView server data from Python scripts in synchronized mode. +* compatibility of the Python scripting interface with the ``paraview.simple`` and the ``paraview.servermanager`` + modules. + +Folder structure +%%%%%%%%%%%%%%%% + +ParaVis module +============== + +In the ParaVis module, here is the list of code folders: + +* **idl**: contains the IDL for the PVSERVER CORBA service +* **src/ENGINE**: implementation of the IDL's functionalities in Python. Mainly deal with the start/stop of the pvserver +* **src/Plugins**: SALOME's specific plugins for ParaView: MEDReader, etc ... +* **src/PVGUI**: graphical elements constituing the ParaVis client in the SALOME GUI. Management of the menus, the toolbars, + etc ... seen in PARAVIS interface. +* **src/PV_SWIG**: Python modules to be able to invoke visualization functionalities from a script + +At the time of writing the PVSERVER CORBA service is sitll hosted by the ParaVis module, but it should move to GUI +to be able to compile GUI without any dependency to PARAVIS. At present, this is only a weak dependency in the sense +that nothing is needed at link time, but only at run-time. + +GUI module +========== + +One can request a ParaView view without activating the ParaVis module itself. For example the MED module now integrates +a control visualization which is in fact a ParaView view. + +To make this work, a specific type of viewer (*PVViewer*, short for ParaView viewer) has been created in the GUI module itself. +The code is located in **src/PVViewer**. + +This folder contains the following classes: + +* ``PVViewer_Behaviors``: re-instanciates the desired ParaView behaviors (a behavior defines for example the fact that ParaView + should automatically reconnect to the server if a disconnection occurs) +* ``PVViewer_EngineWrapper``: encapsulates the calls to the PVSERVER CORBA service in a dynamic fashion, so that GUI can be + compiled without having a link dependency to the ParaVis module +* ``PVViewer_GUIElements``: see :ref:`view_part` +* ``PVViewer_LogWindowAdapter``: an adapter to redirect VTK and ParaView's output messages to the SALOME's message + window (not working?) + +The folder also contain the adaptor classes needed to make the ParaView +native 3D view (a ``pqTabbedMultiViewWidget``) fit into the *SUIT* +model (i.e. the model imposed by SALOME's GUI architecture to define a new type of view): + +* ``PVViewer_ViewManager``: this class centralizes all the initialization logic (see method ``ParaviewInitApp``) of the + ParaView application (``pqCoreApplication``). +* ``PVViewer_ViewModel`` +* ``PVViewer_ViewWindow`` + + +Reminder about ParaView's architecture +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +ParaView works in a client/server mode. In two words, a server part (the ``pvserver``) takes care of the 'intensive' +computations (filter, etc ...) and a client part serves to control this server, and obviously visualize the final rendering. + +The ``pvserver`` represents the main visualisation server, and can be either: + +* *built-in*, in which case, launching ParaView suffices to activate it automatically; +* *detached*, in which case, one has to launch the server first (possibly on another host) and then connect + to it from a client. -Overview -%%%%%%%% +The various types of clients are: -Blabal +* either the standard ParaView GUI (where the name and type of the current server can be + seen by looking at the top element in the pipeline widget) +* or a Python script, using for example the module ``paraview.simple`` and the ``Connect()`` method. -Another sub-section for test -============================ +Historically the pvserver was not able to receive the connections from multiple clients, but this has been changed from +ParaView 4.0 (or was it 3.98?). Salome now exploits this feature. +.. _view_part: +Viewer part (in GUI module) +%%%%%%%%%%%%%%%%%%%%%%%%%%% +In the GUI module of SALOME, the folder **src/PVViewer** contains all the code needed to activate a minimal ParaView +3D view, without activating the ParaVis module itself. +This folder hence deals with: +* the initialization of the ParaView application (``pqApplicationCore``) +* the initialization of ParaView's desired behaviors (class ``PVViewer_GUIElements``) +* the initialization of all the GUI elements needed for a later activation of the ParaVis interface: at the time of + writing the pipeline, some menus, and other elements are very hard to connect *after* having set up a 3D view. They are + however not wanted when the user just requested a 3D view, outside the ParaVis interface. We hence create those elements + any way, but hide them, so that we can later show them again, once the ParaVis module is activated. -Specificities in the code -%%%%%%%%%%%%%%%%%%%%%%%%% +The class ``PVViewer_GUIElements`` is in charge of this. + +ParaVis graphical interface +%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The initialization of the viewer takes part of instantiating the most important widgets, notably: + +* the pipeline +* the dynamic menus (filters and sources) +* the macros +* the Properties panel +* and finally the toolbars + +In the ParaVis module, the class ``PVGUI_Module`` represents the GUI client compliant with the usual architecture of +a SALOME GUI module. The implementation is split in three ``cxx`` files: + +* ``PVGUI_Module.cxx``: core stuff: module initialization and activation, management of the Python trace, etc ... +* ``PVGUI_Module_actions.cxx``: creation of the Qt actions and menus +* ``PVGUI_Module_widgets.cxx``: hide/show various widgets and save/restore their positions in the main window. + +Embedded Python interpreter - Multi-threading +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +ParaView is a mono-threaded application. It also provides an embedded Python interpreter to make the Python shell work. +SALOME on the other hand is multi-threaded, and also provides an embedded Python's interpreter. + +Making the two work together has often been (and still is) a painful job! +If you run into this sort of problems, take a look at what the GIL is: +`Global Interpreter Lock `_ + +In Salome, the current setup is to: + +* patch ParaView itself so that all calls to the Python C API are GIL safe (using ``PyGILState_Ensure``, ``PyGILState_Release``) +* have Salome's embedded Python console work in mono-threaded mode (although it is fully capable of being asynchronous). + This is achieved in ``src/PyConsole/PyConsole_Editor.cxx`` and the initialization of the ``myIsSync`` boolean member to ``True``. + +**The last point is of crucial importance**: it basically means that all the GUI events are in a single thread. +Even without considering + +All the calls to the Python API in the rest of SALOME are (should be!) GIL safe. + +The ParaView Python's trace mechanism has long been a problem, but has fortunately been rationalized thanks to the API of +ParaView providing clear methods to control the start/stop (and other options of the trace). +This is grouped in the ``ParaViewCore/ServerManager/Core/vtkSMTrace`` class and used in the +method ``PVGUI_Module::startTrace()``. + +Python modules +%%%%%%%%%%%%%% +The modules found in **src/PV_SWIG** are mostly simple namespace forwards from the original ParaView's modules (i.e. they +redirect to the original modules): + +* ``pvsimple`` is a forward of ``paraview.simple`` with little extra functionalities to make sure: + * the connection to the correct PVSERVER is automatically established + * that a ParaView's view is available when importing the module from the embedded Python console. +* ``paravisSM`` is a forward of ``paraview.servermanager``. It is left mostly for backward compatibility (it used to be + full of nasty overrides). + +Those forward/similarities are naturally intended so that a script written for pure ParaView can easily be ported +to ParaVis. The conversion boils down to replacing ``import paraview.simple`` by ``impory pvsimple`` (with a few other +extra details of lesser importance). + +Updating to a newer ParaView version +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +The following items should be revised each time an upgrade to a newer ParaView version is done. +They are often a copy/paste of ParaView's source code with a slight amendment to fit SALOME's requirements. + +* *initialization sequence*: currently located in GUI module, ``PVViewer_ViewManager::ParaViewInitApp()``: the following + classes should be inspected, and compared with their equivalent in ParaView source code to see if an update is necessary: + * ``PVViewer_ViewManager`` (GUI module): method ``ParaviewInitApp()``, ``ParaviewInitBehaviors()``, ``ParaviewLoadConfigurations()`` + and finally ``ConnectToExternalPVServer()`` should be re-read. Their precise ordering is used in ``PVGUI_Module::initialize()`` + and the whole sequence should be compared with what can be found in: + * ``Applications/ParaView/ParaViewMainWindow.cxx`` + * ``CMake/branded_paraview_initializer.cxx.in``, and the method ``Initialize()`` + * ``PVViewer_Behaviors`` (GUI module): compare with ``Qt/ApplicationComponents/pqParaViewBehaviors.cxx`` +* *menus and actions*: ``PVGUI_Module_widgets.cxx`` (ParaVis module) should be compared with ``Applications/ParaView/ParaViewMainWindow.cxx`` +* *settings dialog box*: ``PVGUI_ParaViewSettingsPane`` (ParaVis module) should be compared with ``Qt/Components/pqSettingsDialog.h`` +* *trace mechanism*: method ``PVGUI_Module::startTrace()`` should be compared with ``pqTraceReaction::start()`` in file + ``Qt/ApplicationComponents/pqTraceReaction.h`` + +Miscellaneous +%%%%%%%%%%%%% + +**Trace management** + +Contrary to ParaView, which can start/stop its trace at any moment, in PARAVIS the trace is activated +or deactivated for the whole session. + +The trace functionality can be switched on/off in SALOME preferences dialog box, in the PARAVIS tab (main menu | Preferences...). +It contains a check box “Deactivate Trace”. By default the trace is activated. +Change of check box state makes effect only for next session. + +Also, the trace is used for the "Dump Study" functionality. But if the tracing is switched off then the "Dump Study" +doesn't save PARAVIS module trace. + +**Application options** + +If it is necessary to define a spcific command line parameter for ParaView application, +then it can be defined with the help of the PARAVIS_OPTIONS environment variable. For example: :: + + export PARAVIS_OPTIONS=--server=myServer + +If it is necessary to define several command line parameters, these parameters have to be separated by the “:” character. Various TODO %%%%%%%%%%%% + +* make the PVSERVER a true CORBA service not linked to the PARAVIS module +* the PARAVIS module should be a *light* module (TODO check again why this is blocking). +