This is an old revision of the document!


How to install the project from binaries

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
# 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

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

How to build and install the project from sources

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

Unzip the archive on your disk. For instance


A directory PyQGLViewer/ should be created.


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

PyQt4 should be installed with its sip and development files. Binaries version provides by Riverbank unfortunatly do not include all these development files. You may have to recompile it.

Building a custom version of QGLViewer

To build PyQGlViewer, you need to build a customized version of libQGLViewer. You should first download a version of the sources:

Unzip the archive on your disk. For instance

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

A directory libQGLViewer-x.x.x should be created. You have to compile the sources it. To be compatible with SIP, you first need to patch these sources.

The patch file libQGLViewer-x.x.x-py.patch can been found in PyQGLViewer/src dir.

For info, it has been build with the following command

diff -abur libQGLViewer-x.x.x libQGLViewer-x.x.x-py > libQGLViewer-x.x.x-py.patch 

For windows, the patch and diff tools can in the gnuwin32 project

To apply this patch, you should go in the parent directory of libQGLViewer-x.x.x and invoke the command

patch -p 0 -i PyQGLViewer/src/libQGLViewer-x.x.x-py.patch 
The patch file has been built on windows sources. The end of line character is different on unix systems. On linux, you may thus have to convert first the patch file to unix convention with the following comand.

dos2unix libQGLViewer-x.x.x-py.patch 

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

cd libQGLViewer-x.x.x/QGLViewer
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 C:\WINDOWS\system32

copy release\QGLViewer2.dll C:\WINDOWS\system32

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
make         # or nmake
make install # you should be root on linux

libQGLViewer is now compiled and usable.

Building PyQGLViewer

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


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 -Q ../libQGLViewer-x.x.x 
You may specify extra include and lib directories with -I and -L flags

python -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

Testing PyQGLViewer

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


To test integration in designer:


To test texture 3D:



API documentation

Standart API

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.

Additional functions

Multiple Selection

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 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 """


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]).

Back to top
documentation.1216206329.txt.gz ยท Last modified: 2008/07/16 13:05 (external edit)
Valid CSS Driven by DokuWiki Valid XHTML 1.0