|
Syzygy Documentation: Python ProgrammingIntegrated Systems Lab01/02/2007 Documentation Table of Contents Thank you to Peter Brinkmann for creating the initial version of the Syzygy Python bindings.
Python Bindings BackgroundWe are using SWIG to generate Python bindings for some of the most commonly-used Syzygy classes and functions. Syzygy Python bindings are currently available for Linux, Windows, and Mac OS X, but not for Irix. Make sure you have Python (version 2.2 or greater) installed before proceeding (OS X and most Linux distributions come with Python installed) If you are using the cygwin command shell on windows, make sure that it does not include its own version of Python or SWIG. You must remove them if they exist, since cygwin's Python and Syzygy use incompatible object-file formats (gcc vs. Visual Studio). Install the native Windows version of Python from python.org. If you will be compiling the bindings, as opposed to using a precompiled SDK, you must set the SZGHOME, SZGBIN, SZGEXTERNAL, etc. environment variables as described in Getting the Software. This section will show you how to start writing Syzygy programs using Python. You should start by understanding how to get the Syzygy software and set up your Python environment. If you are using a precompiled Syzygy SDK, the Python bindings are included; you do not need to compile them. Otherwise, read the section on compiling the Python bindings. After completing these steps, test your installation. If you will be running Python programs in Cluster Mode (via dex, szgd, and virtual computers), you should understand the way Python interacts with the cluster. The szg repository contains several examples that demonstrate preferred Syzygy programming models, both in szg/python/demo and in szg/doc/python. Compiling the Syzygy Python BindingsThe precompiled Syzygy SDK includes the Python bindings. If you have the precompiled SDK, please skip this section.
Installing Supporting Syzygy Software for PythonThe Syzygy Python bindings consist of two SWIG-generated files: a Python module (PySZG.py) that makes calls to a shared library (_PySZG.dll on Windows, _PySZG.so on other platforms); the shared library makes calls to the Syzygy shared libraries. These files are normally kept with the rest of your executables and shared libraries, as they are platform-specific. In the precompiled SDK, these are in the "bin" subdirectory. If you compiled the libraries yourself, they should have been automatically copied to your SZGBIN directory. Python has an internal search path for loadable modules. If the environment variable PYTHONPATH exists, its contents are prepended to the module search path. You must add the directory containing the two PySZG files to your PYTHONPATH variable. Your PATH and dynamic linker environment variables must be set as explained in Getting the Software. The directory containing the Syzygy executables and libraries must be on your PATH and on the dynamic linker search path. If you simply want to be able to play around with Syzygy objects at the Python interpreter, or if you only plan to write programs using the distributed scene graph application framework, then you do not need to install anything else. Please proceed to the next section. However, programs based on the more flexible master/slave application framework require the Python OpenGL bindings package, PyOpenGL, which in turn requires the Python numarray module. The installation procedure varies by platform. Testing Your Syzygy Python InstallationThe first confidence test is simple. Try to load the Python bindings from within the interpreter. You should be able to execute the following commands:
python
from PySZG import *
g = arGraphicsDatabase()
g.printStructure()
If this works, try running the included demos in standalone mode. Make sure you are in standalone mode by typing the Syzygy command dlogout, then cd to the demo/blobby or demo/skeleton directory and type "python .py". If you've installed the optional pycube demo package, try some of those. Note that some of them depend on modules that are in the top pycube directory. In order for these to work in standalone mode, you will need to manually add this directory to your PYTHONPATH environment variable (when you run the demos on a Syzygy cluster (i.e. in Cluster Mode, see below), the pycube directory must added to you SZG_PYTHON/path Syzygy database variable, and is then automagically added to the PYTHONPATH). Running Syzygy Python Programs in Cluster ModeTo understand this section, you should read about the Syzygy Distributed OS. We assume that Python programs are organized, along with their data, like textures, sounds, and input files, in subdirectories of an overall Python programs directory. The top level of that Python programs directory might contain library modules used by various programs. When you type e.g. "dex the_computer blobby.py", the target szgd searches through the directories listed in the SZG_PYTHON/path Syzygy database variable for a directory containing a file named "blobby.py". It then executes Python, passing "blobby.py" as a parameter. In order for szgd to find Python, you must set the variable SZG_PYTHON/executable to the full path to the Python executable (note that on Windows you should omit the '.exe' suffix). Consider the following example:
In this case, the following lines should appear in your dbatch file:
the_computer SZG_EXEC path /home/the_user/bin
the_computer SZG_PYTHON executable /usr/bin/python
the_computer SZG_PYTHON path /home/the_user/py-szg/demo
Note that szgd only searches one level of subdirectories for each directory in the SZG_PYTHON path variable, so setting it to /home/the_user/py-szg wouldn't work (because the blobby directory would be two levels down). When you type
dex the_computer blobby.py
szgd searches the SZG_PYTHON path until it finds blobby.py. It executes python, with the path to blobby.py passed as a command-line argument. It modifies the execution environment by prepending the directory containing blobby.py and the directory above that to the PYTHONPATH, so that modules contained in those directories can be loaded. PLEASE NOTE. szgd processes dex commands differently depending upon whether the program is native or Python and determines which is which via the file extension (.py). Consequently, it is very important to have this extension on your Python program. Python programs can be executed on virtual computers, much like native Syzygy programs. For example, say you've installed a copy of the py-szg demo directory on each computer that is part of a virtual computer named the_cluster (or installed it on a networked drive that is mounted on each computer) and that you've set the Syzygy database parameters as described above for each computer, then
dex the_cluster blobby.py
and
dkill the_cluster blobby.py
should work. Pitfalls in Syzygy Python Programming You should be very careful to put the line
from PySZG import *
BEFORE any imports of PyOpenGL modules in your Python code. This is because the PyOpenGL modules go actually try to load the GLUT dynamic library themselves from their local installation and this may conflict with the Syzygy GLUT. The Python cPickle module (for persistent storage of Python objects, either files or in strings) seems to be less cross-platform than advertised. Actually, we're not sure if this is a platform or a version issue; a file generated with cPickle on a Windows machine running Python 2.2 can't be un-pickled on a Linux machine running Python 2.3. The Python master/slave framework uses cPickle in the setObject method, for packing an arbitrary Python object into a string for transfer from master to slaves, so this implies that Python master/slave applications may run into trouble running on mixed-platform or -version clusters. We've run into a few other cases in which cPickle behaves strangely, throwing exceptions for no apparent reason; some of these can be avoided by using the slower pickle module instead (pickle is written in Python, cPickle in C). Or if security is a concern, you could used twisted.spread.banana and twisted.spread.jelly from the Twisted package. Pickle is a security risk, because an attacker could insert arbitrary commands in a string that would be executed on un-pickling; only use pickle if you control both ends of a transaction. |
|
[Schedule] [Labs] [Beckman Meeting Rooms] [Equipment] [Projects] [CUBE Projects] [Syzygy] [VSS] [People] [Events] [Publications] |
