This is an old revision of the document!


Documentation

How to install the project from binaries

This section is mainly adressed for windows users.

Requirements

Installer requires recent versions of Python (v2.5), Qt (v4.3.1) and PyQt (v4.3).

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

Install

You can then simply install the 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

Requirements

This project requires a recent version of SIP (tested with 4.5.2, 4.6 and 4.7), 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

First, you need to build a customized version of libQGLViewer. Actually, it has been build from version 2.2.6-3. You should download a version of the sources:

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

for linux, archive is: http://artis.imag.fr/Members/Gilles.Debunne/QGLViewer/src/libQGLViewer-2.2.6-3.tar.gz

and for windows http://artis.imag.fr/Members/Gilles.Debunne/QGLViewer/src/libQGLViewer-2.2.6-3.zip

Unzip the archive on your disk. For instance

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

A directory libQGLViewer-2.2.x-x should be created

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

For info, it has been build with the following command

diff -abur libQGLViewer-2.2.x-x libQGLViewer-2.2.x-x-py > libQGLViewer-2.2.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-2.2.x-x and invoke the command

patch -p 0 -i PyQGLViewer/src/libQGLViewer-2.2.x-x-py.patch 

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

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

To have designer plugin (required if you will used pyuic), you should go to libQGLViewer-2.2.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.

Building PyQGLViewer

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-2.2.x-x with -Q option. For instance

python configure.py -Q ../libQGLViewer-2.2.x-x 
You may specify extra include and lib directories with -I and -L flags

python configure.py -Q ../libQGLViewer-2.2.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

You can then test the new module with all examples that you'll find in the directory PyQGLViewer/examples.

Good luck.

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

Version

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

Texture3D

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.1191928042.txt.gz ยท Last modified: 2007/10/09 13:07 by admin
Valid CSS Driven by DokuWiki Valid XHTML 1.0