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

Install

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.

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

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.

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

unzip PyQGLViewer-x.x.zip 

A directory PyQGLViewer/ should be created.

Requirements

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:

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 

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

cd libQGLViewer-x.x.x
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 

Previous patches with lower versions than 2.3.4 where built from above repository. Thus to apply them you had to call

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

However they were not reusable from one version to the other.

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

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

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

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

python simpleViewer.py

To test integration in designer:

python interface.py

To test texture 3D:

python texture3D.py

Enjoy.

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.1301566505.txt.gz ยท Last modified: 2011/03/31 12:15 by admin
Valid CSS Driven by DokuWiki Valid XHTML 1.0