Installing (and Building) PyOpenGL

This document describes the process of installing PyOpenGL 3.x. Most users should be able to download setuptools .egg files using the easy_install script (the "Standard Install" below).

Dependencies

PyOpenGL has a number of dependencies which need to be installed before installing PyOpenGL. This list should point you to everything you need to get ready for running PyOpenGL:

Python 2.4+
ctypes (standard with Python 2.5 and above)
SetupTools (ez_setup)

Used to register and lookup data-format plugins (core to PyOpenGL)

OpenGL 1.1 and GLU (available pre-installed on most modern machines)

If your machine is a very old Win95 machine that has never had an OpenGL game, package, or graphics-card installed it is possible that you don't have OpenGL installed. You can get it from Microsoft in this (rare) case. Because of MSDN's rather capricious content-management system, that link may fail at some point. Search for OpenGL95.exe on Microsoft's site to find it if this happens.

Optional PyOpenGL Dependencies:

Numpy or Numeric

You will likely want a numeric library for any real-world code

We recommend using numpy if you are not supporting legacy code written to use Numeric

GLUT or FreeGLUT

Available as an rpm/deb/ebuild for most modern Linux machines
Available as a Win32 binary package

Python Imaging Library (PIL) any recent version

Not technically required for PyOpenGL, but you'll almost certainly need it for most PyOpenGL projects
Required for OpenGLContext (for all but the most simplistic of scenes)

The GL Extrusion library, available on most Linux distributions
Precompiled Win32 version is downloadable from the project file area (gle32.zip)

Togl v1.5+

You will need the Tcl/Tk version for your Python installation (often not installed)
Only required if you want to use PyOpenGL with Tk-based GUI programs

Note that Togl support is pretty much deprecated, it's there for legacy code (once you compile Togl), but you should likely choose a GUI library that has OpenGL support built-in for any new development.

OpenGLContext dependencies beyond PyOpenGL:

PyDispatcher

Provides the event-routing and field-watching infrastructure for the scenegraph

Optional, but generally useful OpenGLContext dependencies:

SimpleParse 2.1

Provides the VRML97 parser, strongly recommended

TTFQuery and
FontTools (for Numpy)

Provide access to TrueType fonts stored in the file system, used by the "toolsfont" and "pygamefont" modules in the scenegraph/text package. Without these modules, you will not have access to extruded fonts (toolsfont) or antialiased bitmap fonts (pygamefont)
This FontTools is patched to support using Numpy, unlike the core project

wxPython and/or
PyGame

Additional contexts/windowing environments, only GLUT contexts are available otherwise.
PyGame also provides antialiased bitmap fonts, while wxPython can provide aliased bitmap fonts if necessary

win32all

win32ui and win32con provide support for WGL-based polygonal text, only available for Win32 systems of course. The WGL polygonal text is not used by the scenegraph engine, so it is not required for anything save playing with the WGL polygonal text demonstration module.

Standard Install (setuptools/egg based)

The PyOpenGL package uses the "SetupTools" package, which is a common mechanism for distributing and installing Python packages. It is quite likely that Python developers will already have setuptools installed on their system. If you do not have it installed, download and run ez_setup.py. If you want to install your Python egg files in a non-standard location be sure to setup your .pydistutils.cfg to support this before installing the packages.

Note that you may want to uninstall any PyOpenGL 2.x or OpenGL-3.0.0a4 installation before attempting to install. The 3.0.0a4 release used the undecorated name in a misguided attempt to make things "simpler". The 3.0.0a5 and beyond packages use the same name as all previous PyOpenGL packages, "PyOpenGL".

Once you have setuptools installed (many Python developers already will have it), simply issue the command:

easy_install PyOpenGL

To have setuptools lookup the current version of the PyOpenGL package, download and install it. If setuptools fails to install the package, you may need to update your setuptools. Or you can try a direct download of the package with this command in the directory where you downloaded the package:

easy_install -f . PyOpenGL

If you do not have administrative permissions on your machine, you can create a .pydistutils.cfg file in your home directory to tell setuptools where to install new .egg files.

To update your install to the latest release of PyOpenGL:

easy_install -U PyOpenGL

Which will search for the latest registered version of the package and install that on your system.

If you use setuptools to package your application, you should declare a dependency on "PyOpenGL" to pull in the latest PyOpenGL 3.x release.

As of 3.0.0a3 PyOpenGL is dependant on the setuptools package. You cannot run without the setuptools support, as it is used to provide the plugin mechanism used by array data-type plugin mechanism. You will probably want to install numpy as well. ctypes is a dependency for Python 2.4 and Python 2.3 but included with Python 2.5.

Source Install

If (for whatever reason) you would like to install from the source distribution you can do so. To accomplish the install you will need setuptools installed (see standard installation above). When that is in place, download and unpack the .tar.gz or .zip file and run the following command:

python setup.py install

CVS Install

If you are working in an area that's currently under active development you may prefer to use the CVS version of the PyOpenGL package. OpenGL-ctypes (the code-name for the 3.0.0 version of PyOpenGL) is developed and maintained within the PyOpenGL CVS repository. To check out the current version of OpenGL-ctypes:

cvs -z3 -d:pserver:anonymous@pyopengl.cvs.sourceforge.net:/cvsroot/pyopengl co -P OpenGL-ctypes

You can install the checkout to your path for further development as follows (from the OpenGL-ctypes checkout directory):

./setupegg.py develop --install-dir=~/YOUR-WORKING-DIRECTORY-ON-PYTHONPATH-HERE

When you make a change, run cvs diff on the OpenGL-ctypes directory to produce a patch file and upload it to the SourceForge patch tracker. I prefer "context" diffs (cvs diff -c) for contributed code, as it makes it easier to see where the code fits in. That said, I'm happy to get code in any readily integrated format.

Building Documentation

Building the documentation-set from source uses Java-based DocBook processing scripts, so it can take quite a bit of work to set up properly. Most developers will never need to do this, but future administrators (such as myself) will likely want some instructions. Here's the steps.

Install Java
Install the Saxon Java XSLT processor

Add Saxon install root directory (where saxon.jar is) to the system environment as SAXON_HOME

Install the DocBook-XSL package

Unpack as PyOpenGL2\doc\docbook-xsl within the source-tree (this will require renaming the directory from something like 'docbook-xsl-1.59.1' to 'docbook-xsl')
Add PyOpenGL2\doc\docbook-xsl to the shell environment as DOCBOOK_XSL_HOME (note that you still must use the doc\docbook-xsl directory even with the variable set)

Install Sun's Resolver package

Add the resolver root directory (where the file resolver.jar is) to the system environment as RESOLVER_HOME

Download the Oasis XML Docbook catalog and DTD (optional, but speeds up processing considerably)

Expand into the PyOpenGL2\doc\docbook directory
Create a file named CatalogManager.properties in PyOpenGL2\doc\docbook with these contents (where catalog.xml is the filename of the Oasis XML catalog). Note that the PyOpenGL2\doc\docbook directory is added to the classpath to make this file available to the resolver. Note also that the relative-catalogs value seems to be somewhat fickle, you may want to try "false" if saxon is complaining about missing entity files:

catalogs=catalog.xml
relative-catalogs=true
static-catalog=yes
verbosity=1

Install the MathML DTD in PyOpenGL2\doc\docbook\mathml\
Add these declarations to the PyOpenGL2\doc\docbook\catalog.xml file (the last lets the 4.1.2 documents use the 4.2 DTD), the others make the various parts of the mathml dtd available:

<public publicId="-//W3C//DTD MathML 2.0//EN"
		uri="mathml/mathml2.dtd"/>
<public publicId="-//W3C//ENTITIES MathML 2.0 Qualified Names 1.0//EN"
		uri="mathml/mathml2-qname-1.mod"/>
<public publicId="-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
		uri="mathml/xhtml-math11-f.dtd"/>
<public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
        uri="docbookx.dtd"/>

Install David Carlisle's MathML XSL stylesheets into PyOpenGL2\doc\xsl\mathml\

ctop.xsl,mathml.xsl,pmathml.xsl,pmathmlcss.xsl

(For HTML Help) Add the directory with the hhc.exe file from the html help workshop to your path.

Note that the HTML-help feature is not likely to work with the new javascript+CSS formatting provided by the MathML stylesheets above. Expect the results to be either unreadable or simply fail to be generated.

Run setup.py build_doc --formats=html,htmlhelp (warning, this will take a very long time to complete (figure an hour or so at least))

Building Older Releases

If you would like to build the 2.x release of PyOpenGL, you can view the original installation documentation.