Python bindings for PolyVox preview

As part of the next release of PolyVox, we’re going to have the first Python bindings available and supported as well as preliminary support for C♯ bindings. This will allow easy integration of voxels into the technologies you’re already using.


For a long time now (at least 4 years) we’ve had some form of Python bindings available for PolyVox, created via the SWIG tool. If you were paying attention in those days, you would have seen that the bindings were often broken or even disabled from building completely. This was largely due to the fact that PolyVox was a fast-developing piece of software without a stable API. We didn’t want to slow down the development of new features by having the impedance of also having to update the bindings.

However, since we starting making proper numbered releases (beginning with 0.2.0 last year) the API has settled down and we’re making promises about how much (or little) it will change. This makes it a much more suitable target for building bindings to other languages.

Current status of Python bindings

My main target for the next release of PolyVox (0.3 when it’s out) has been improving and polishing the bindings for Python. In addition to the Python bindings, I have also enabled the building of C♯ bindings for those who would like to try those out too. The Python bindings are better supported however (we have nightly tests run on them, documentation and a demonstration example) and are less liable to change.

If you’re interested in taking a look, then I’ve uploaded a first draft of a section documenting the Python bindings which introduces the bindings and goes through a short code example. That short example is expanded as a full example in the usual example location,, which renders a blocky sphere to the screen using Python, PyOpenGL and PyGame without a single line of C++ needing to be written.

Voxel sphere rendered by Python

A voxel sphere rendered though PyOpenGL

For example, creating a volume is as simple as

import PolyVoxCore as pv

r = pv.Region(pv.Vector3Dint32_t(0,0,0), pv.Vector3Dint32_t(63,63,63))
vol = pv.SimpleVolumeuint8(r)

You can set the value of any voxel with a single call like:

vol.setVoxelAt(x, y, z, 10)

and you can extract a polygon mesh to be passed to your 3D engine of choice with

mesh = pv.SurfaceMeshPositionMaterialNormal()
extractor = pv.CubicSurfaceExtractorWithNormalsSimpleVolumeuint8(vol, r, mesh)

The unusually long names for the classes is an artefact of SWIG being able to represent all the varieties of C++ template instances. You’ll also notice that the API is not very Pythonic at present. I’m trying to get all the functionality working before adding another layer of Pythonicness.

All of the above is already in the develop branch of Git already so feel free to try it out. If you have any question please do ask in the comments below or in the forums.

In a future post I’ll detail some of the technical challenges I’ve faced to get all of PolyVox’s functionality working in both Python and C♯ via SWIG.


7 thoughts on “Python bindings for PolyVox preview

  1. It’s not directly conncected to your post about Python bindings, but i’m considering to make a polyvox.js version via emscripten i think it should be doable and a lot of people would grab this sweet piece of cake.
    Thanks as always for your effort in the development of Polyvox!

    • I had a play with emscripten about 6 months back. I found it worked very well and able to wrap PolyVox quite easily. The main problem I found was that since it’s basically compiling the LLVM IR to EMCAScript you have to deal with all the C++ ABI name-mangling issues so none of the functions have pleasant names. My next step would have been to generate a simple C API over PolyVox and then wrap that with emscripten but I didn’t get around to it. A future version of SWIG is hopefully going to support generating a C API maybe that’s an option. Regardless, I’d love to see what you manage to get working so be sure to post about it on the forums.

      • thank’s Matt! you gave me a good input, i think that i will get it a try and sure i will post the result in the forum!

  2. @Matt Williams,
    Do you have an ETA for 0.3? I really want to play with your Python bindings. I downloaded 0.2.1 thinking there would be more examples. Then I reread this post and realized it was more of a 0.3 preview post.

    I am eventually putting this in T3D and hence C++, but I wanted to play around with the fast prototyping capability of Python. Also, I have added Python to T3D using SWIG, but all the interfaces I did by hand. I found SWIG really great for helping me handle data structures, but many things I had to build as native Python API interfaces such as my callback system. So I think it is great that SWIG can generate stuff for you, however it really pays to know how to create the Python C functions from scratch. I was able to completely control the interface that way. T3D is an engine so my experience may not really translate to a library though.

    • Hi,

      We’ve started direct planning towards 0.3 as discussed in our forum at I imagine that we’re a few months out but since I’m in the middle of writing my PhD thesis at the moment, time is a little short. In the mean-time, you could check out the develop branch in Git to see all the things mentioned in this blog post.

      I’m currently writing a blog post giving more details of the Python bindings (and soon after another post about trying to do callbacks). I’ve found that using SWIG’s ability to insert native code for certain situations to be very helpful though my knowledge of the Python C API is limited.

      If you have any specific questions or things you want to talk about, please do pop into our forums.

Leave a Reply

Your email address will not be published.