Documentation

This section is mainly adressed for windows users.

Installer requires recent versions of Python, Qt and PyQt.

To run the examples, you will have to install PyOpenGL. This last package uses easy_install tool to be installed.

# installing easy_install
python ez_setup.py
# installing PyOpenGL
easy_install PyOpenGL

On windows, you may have to specify full path of easy_install

# installing PyOpenGL
C:\Python25\easy_install.exe PyOpenGL

On windows, you may simply install the last exe installer that you can find here. However, distribution are not frequent.

To test it, you may launch examples [Start Menu]/Programs/PyQGLViewer/examples.

You can look at the OpenAlea distribution of PyQGLViewer. See the OpenAlea website.

In particular for Linux (Ubuntu mainly) you can install it this way:

sudo add-apt-repository ppa:christophe-pradal/openalea
sudo add-apt-repository ppa:christophe-pradal/vplants
sudo apt-get install pyqglviewer

It will install a libQGLViewer package and PyQGLViewer.

For windows,after download and installing easy_install. You can type

easy_install -f http:://openalea.geforge.inria.fr/pi openalea.deploy
alea_install pyqglviewer

Or use the normal installation of openalea et vplants.

This may changed in the future. So look at the OpenAlea documentation to have an update procedure.

As a first step, you need of course to download and unzip the sources of PyQGLViewer.

Unzip the archive on your disk. For instance

unzip PyQGLViewer-x.x.zip 

A directory PyQGLViewer/ should be created.

This project requires a recent version of SIP, Qt4 and PyQt4.

To build PyQGlViewer, you need to have libQGLViewer. It is part of most Linux distribution. On Mac, it comes with macports. On Windows, with Cygwin.

If it is not the case or if you want to use a more recent version of the lib. You will need to build it from sources.

You should first download a version of the sources:

http://artis.imag.fr/~Gilles.Debunne/QGLViewer/download.html

Unzip the archive on your disk. For instance

tar xvzf libQGLViewer-x.x.x.tar.gz 

Source are now ready to compile. Go into libQGLViewer-x.x.x/QGLViewer dir

cd libQGLViewer-x.x.x/QGLViewer
qmake-qt4 QGLViewer.pro
make         # or nmake
make install # you should be root on linux

On windows to install the lib you should copy the QGLViewer2.dll in library repository such as %QTDIR%\bin

copy release\QGLViewer2.dll %QTDIR%\bin
copy release\QGLViewer2.lib %QTDIR%\lib

To have designer plugin (required if you will used pyuic), you should go to libQGLViewer-x.x.x/designerPlugin and invoke similar command

cd ../designerPlugin
qmake-qt4 designerPlugin.pro
make         # or nmake
make install # you should be root on linux

libQGLViewer is now compiled and usable.

Python wrappers can be built. For this, you should simply invoke the following command

python configure.py 

You should be root on linux to make it work. You can specify the source repository of libQGLViewer-x.x.x with -Q option. For instance

python configure.py -Q ../libQGLViewer-x.x.x 

python configure.py -Q ../libQGLViewer-x.x.x -I /extra/inc/dir -L /extra/lib/dir

Then you simply have to compile and install with

make         # or nmake
make install # or nmake install, you should be root

Once installed, you may want to see if your build work.

You can find classic examples of libQGLViewer translated for python and PyQGLViewer in the directory PyQGLViewer/examples/. To test them, go in that directory and invoke for instance

python simpleViewer.py

To test integration in designer:

python interface.py

To test texture 3D:

python texture3D.py

Enjoy.

The PyQGLViewer module follows the QGLViewer API.

However, wrappers generated by SIP translates some typical C++ function signatures to python compatible ones. For instance, if a parameter of a function is used to return a value (passed so as a reference), the python function will have this parameter directly has a return value:

 bool f(int x, float & res); 

will be translated into

def f(x) : 
    ...
    return True, res 

For instance, in the camera class, the member function

void Camera::convertClickToLine (const QPoint & pixel, Vec & orig, Vec & dir) const

is translated as

def Camera.convertClickToLine (pixel) -> return Vec orig, Vec dir

Additionnaly, C arrays are translated into python lists. For instance,

void Camera::getViewport (GLint viewport[4]) const

is translated as

def Camera.getViewport() -> return list

We plan to generate and present a complete python API documentation of the library that integrates all these details in the future.

The QGLViewer class has normally a selectBuffer() function that gives a buffer of ids and depth values from last selection. It is particularly useful when you implement multiple selection. Manipulating direct memory buffer and type recasting is not really possible in a high level language such as Python. We implement instead a QGLViewer.getMultipleSelection() function that gives an array of tuples containing min and max depth and id (or array of ids if you use nested ids) of selected objects. This function gives results only when called from inside QGLViewer.endSelection(point).

 def QGLViewer.getMultipleSelection():
    """ Gives list of id and associated depths of selected objects """
    return [(zmin1,zmax1,id1),...,(zminN,zmaxN,[nestedidN1,nestedidN2,...])]

You can check the version of the QGLViewer with the global hexadecimal value QGLViewerVersion. Moreover, the following convenience function gives the version as a string:

def QGLViewerVersionString():
    """ Return version of QGLViewer in a string format """

You can also check the version of the wrappers with the global hexadecimal value _ _version_ _ or the function PyQGLViewerVersionString for the string version.

Creating 3D textures requires to manipulate memory buffer. This is not very compatible with Python high level phylosophy. So we implement the binding of a list of QImage as a 3D texture.

def QGLViewer.bindTexture3D([QImage] images, target = GL_TEXTURE_3D, format = GL_RGBA):
    """ Generates and binds a 3D GL texture construct from a list of QImage """
    Return texture id 

The generated texture id is returned and can be used in later glBindTexture() calls.

The target parameter specifies the texture target. The default target is GL_TEXTURE_3D.

The format parameter sets the internal format for the texture. The default format is GL_RGBA8.

No mipmap generation is supported. And, in opposite to QGLWidget.bindTexture function, the 3D texture which is generated here is not cached. It have to be deleted at the end with glDeleteTexture([id]).