Swig-python

From Manta Wiki
Jump to: navigation, search

It is possible to invoke Manta from a Python interpreter. Swig is used to generate python wrappers and there is a wxPython based GUI for Manta which does not depend on X11.

How do I build Manta with Swig/Python?

The rest of this page contains lengthly build instructions with complicated dependency version information etc., however on most common platforms (OSX/Darwin Ports and SUSE 10.x) everything should build out of the box provided that the necessary packages are installed.

Quick start

  • Check to see if you have the dependent packages installed: swig, python, wxWidgets/wxPython. Usually either the linux distribution default package will work or the current version available in MacPorts. Enable the BUILD_SWIG_INTERFACE cmake option, if the build doesn't work, review the instructions below in more detail.

CMake Version

Version 2.0 or greater of CMake is required to support swig.

CMake with Python 2.4.x

If you use Python version 2.4.X, you will have to edit the FindPythonLibs.cmake file. This may be alleviated by later versions of CMake, but I've only tested version 2.0.5-6. You can usually find this file wherever you installed CMake. Look for CMAKE_ROOT in your CMakeCache.txt file where you tried to configure your build. For example mine is:

//Path to CMake installation.
CMAKE_ROOT:INTERNAL=/usr/local/share/CMake

From here you can look for ${CMAKE_ROOT}/Modules/FindPythonLibs.cmake. All you have to do is add the 2.4 version of all the checks. Just look for where you see 2.3 or 23, make a copy, and change 2.3 and 23 to 2.4 and 24. Here is copy of one I've already modified FindPythonLibs.cmake.


SWIG Version

  • Manta requires at least SWIG version 1.3.23.

The following versions of swig have been tested:

Working versions:

  • 1.3.33 (OSX)
  • 1.3.29 (Suse 10.2)
  • 1.3.27 (Ubuntu 5.10 from source, Suse 10.x)

Problem versions:

  • 1.3.24-1ubuntu4 (Ubuntu 5.10 binary) - Segfaults on manta.i.

SWIG from Darwin Ports

  • On OSX swig is available through MacPorts:

[http://www.macports.org/]

  • After installing MacPorts use the port command to install swig:
sudo port install swig
at a terminal after setting up MacPorts.

Building Swig from source

Download sources or obtain cvs access instructions from: http://www.swig.org/download.html .

The same configure and build process may be used:

cd swig-1.3.27
./configure --prefix=your prefix
make -s
make install

Specifying the location of swig in CMake

CMake may have trouble finding your copy of swig if it is installed in a non standard location and is not in the system path. If this is so you will see something like this from ccmake:

 SWIG_DIR                        *SWIG_DIR-NOTFOUND

All you need to do is edit the listing to point to the directory where the swig binary is located, and run configure ('c') again. If swig's location is ~/build-linux/bin/swig specify ~/build-linux, and CMake will find it.

Dependency: Python

Both a python interpreter and development headers and libraries are necessary.

Python Packages

The following packaged versions have been tested:

  • 2.5.1 (OSX Leopard)
  • 2.3.3 (Mandrake 10.0) - Works fine
  • 2.4.2 (Ubuntu 5.10 binary) - Works fine with a little bit of hackery of CMake.
  • 2.5 (Open SUSE 10.2)
  • Be sure to install both the interpreter and development package (for example in Suse yast install both "python" and "python-devel").

Building Python from Source

Building from source is a reasonable solution if your Linux distribution choice doesn't have an up-to-date python package.

First check out the source from Python's svn repository:

svn co http://svn.python.org/projects/python/trunk python-svn

Next configure and build python. Usually it's a good idea to build packages like python with GCC even if you are planning to compile Manta with another compiler. Replace your prefix with the installation prefix you plan to place Python in.

cd python-svn
./configure --prefix=your prefix
make -s
make install

Python should build without any trouble on most linux distributions. I tested it on Suse 9.3.

Dependency: wxWidgets/wxPython

This dependency is part of the Apple developer tools that ships with OSX and is available in the package manager of most linux distributions. For example of the wxPython dependencies are available in Suse 10.2 through yast, just not on the sci install server.

  • If a binary version is not available: Download sources or obtain cvs access instructions from:

[http://www.wxpython.org/download.php#cvsaccess]

Note that the Python bindings are located in the wxPython/ sub-directory.

  • Next configure and build:

cd wxWidgets
./configure --prefix=your prefix --with-opengl
make -s
make install

Using the Manta swig/python interface

After building, update you PYTHONPATH environment variable to contain the Manta build lib/ and SwigInterface/ directories. There is a csh helper script that sets the path properly for your build in bin/

source bin/pythonpath.csh
python runmanta.py --np=2
python runwxmanta.py --np=2

wxWidgets: runwxmanta.py

runwxmanta.py contains an example script that creates a wxManta wxApp including default menus and a rendering frame. It does not require an X11 server to render.

See the Manta project page for an example of how to use a copy of this script in an external Manta-project.

X11: runmanta.py

Take a look at runmanta.py for examples of how to create a scene and set up the rendering pipeline. If you run it piped into python, you will want to make sure you call engine.beginRendering(True). If you run it from within the python interpreter, you will want to call that function with False. This will allow you to access back to the python interpreter prompt.

To run manta stuff from within the interpreter you need to import the manta or runmanta code in.

>>> from manta import *
>>> # You now have access to all things manta

Or

>>> from runmanta import *
>>> # manta starts up
>>> # You get your prompt back to do other stuff

Notes

Python 2.3 along with swig from Darwin Ports works out-of-the-box on my MacBook Pro. (abe)

For reference, my variables are set to:

PYTHON_DEBUG_LIBRARY             -framework Python                                                                   
PYTHON_EXECUTABLE                /Library/Frameworks/Python.framework/Versions/Current/bin/python2.4                 
PYTHON_INCLUDE_PATH              /Library/Frameworks/Python.framework/Versions/Current/include/python2.4             
PYTHON_LIBRARY                   -framework Python
SWIG_DIR                         /opt/local/bin                                                                      
SWIG_EXECUTABLE                  /opt/local/bin/swig                                                                       

For the latest version of wxPython the wxPython.GLCanvas package is no longer available. This is used by Manta in the wxManta.py file and needs to be changed to work with this latest version. wxManta.py is located in your build-dir/lib and the line that includes wxGLCanvas needs to become:

from wx.glcanvas import GLCanvas as wxGLCanvas

This will import the newer version without having to change the references in the code to point to the new name.


[On OSX presumably] you don't need to run manta from X11 as you did for previous builds. You can run it directly inside of the standard terminal. If you want to run inside of X11 for some reason, I ran into the issue of the Python installer only modifying my .bash_profile instead of .bashrc (and the X11 terminal is not a login shell, so this doesn't work). Simply move the code that the Installer added from .bash_profile to .bashrc.

To force a rebuild of all swig/python related code, delete both the build/lib directory and the build/SwigInterface directory.

Python References

Manta's python frontend uses several other packages including SWIG and wxWindows. Here are some useful references for these tools:

  • Dive Into Python Debian package: (apt-get install diveintopython)
  • SWIG 1.3 Reference
  • wxPython in Action. Noel Rappin and Robin Dunn. Manning. March, 2006. ISBN: 1-932394-62-1

In addition to viewing it on the web you can install it locally on Debian based distributions using the diveintopython package (apt-get install diveintopython).

FAQ

How do I start Manta from python?

Look at the runmanta.py example in the repository.

Or if wxPython is available, use:

python -m runwxmanta --np=<threads>

This script may be copied and easily modified to create different python frontends. The wxManta modual provides a common user interface.

Bad Pointers? Use manta_new(...)

Python objects of SWIG generated types are proxies to C++ pointers and can be treated as such. Sometimes when these pointers are deleted after they are passed to Manta and cause hard to track down segfaults.

Python performs garbage collection on objects once they pass out of scope so if you create a manta proxy object in a script, then pass it to Manta, Python may delete the proxy (and call the object's destructor) before Manta is finished with the object. The manta_new( proxy ) function provided by the Manta python module sets the obj.thisown flag to False and prevents the object from being garbage collected. Similarly manta_delete( proxy ) enables Python to garbage collect the object.

For example:

flat = Flat(NormalTexture()) # Wrong!
kdtree = KDTreeDyn( flat )   # flat, kdtree, and the texture
scene.setObject( kdtree )    # will be deleted!

# Verbose but correct.
flat = manta_new(Flat(manta_new(NormalTexture())))
kdtree = manta_new(KDTreeDyn( flat ))
scene.setObject( kdtree )

SWIG proxies are pointers.

SWIG proxies are never const protected and should be treated as non-const references at all times. For example:

>>> v0 = Vector(1,2,3)
>>> v1 = v0
>>> v2 = v0
>>> v1[0] = 5
>>> v2[0]
5.0
>>> v0.x()
5.0

If you take a closer look, you'll see that each x element is a proxy to the same memory address:

>>> v0[0]
<Swig Object of type 'Manta::Real *' at 0x307920>
>>> v1[0]
<Swig Object of type 'Manta::Real *' at 0x307920>
>>> v2[0]
<Swig Object of type 'Manta::Real *' at 0x307920>

Creating a new Vector fixes the problem:

>>> v3 = Vector(v0)
>>> v3[0]
<Swig Object of type 'Manta::Real *' at 0x30b9a0>

How do I add transactions to Manta from python code?

The python interface supports Manta's transaction and callback semantics. The difference is that the a callback to a Python function will be invoked at a synchronization point between the python interpreter and the rendering threads.


from manta import *
from pycallback import * # Location of createMantaTransaction

# Add the transaction.
engine.addTransaction( "auto view",
                       manta_new( createMantaTransaction( camera.autoview,
                                                          (bounds, ) )))

engine is an instance of MantaInterface, camera of Camera, and bounds is a BBox.

Note the trailing comma in the second argument tuple of createMantaTransaction.

Developing New Components with Manta/Python

Check out the example Manta project for instructions on how to create your own components in C++ and then attach them to Manta through the python interface.