BALLPythonScripting

Scripting in Python

Introduction

Our ultimate - but unfortunately so far unreached - goal is to have all of BALL's data structures and algorithms wrapped for usage in python scripting. At the time of writing most classes have been wrapped though.

There are three ways how users can develop and run BALL python scripts:

• pure BALL python e.g. interactive python shell
• BALLView's integrated Scripting Mode
• BALLView's integrated Instant Mode

If BALLView 's integrated modes are used, a special script startup.py is run that offers helper methods for e.g. removeWater(), BALLView related methods e.g. showOnlyScene() and getDatasetControl(), and python hotkey-mapping.

In the integrated modes access to the maincontrol and representations is provided as well.

Please note that theses methods are not available in pure BALL python.

Installation

Install BALL on your system (see DevelopmentEnvironment).

1. If you used CMake to build BALL (highly recommended for versions >= 1.3.2), the python bindings will have been created automatically. But if you used autoconf for building BALL, the python bindings need to be compiled manually.

 cd source/EXTENSIONS/
 make sip && make && make install

2. Setting up the environment:

In order to use BALL python support you need to set the following variables: PYTHONPATH

 export PYTHONPATH=<PATH to BALL libs>:<PATH to sip libs>

LD_LIBRARY_PATH

 export LD_LIBRARY_PATH=<PATH to BALL libs>:<PATH to QT libs>:<PATH to sip libs>

3. After you have made these settings you are able to start your interactive python shell, e.g. type

 python

or run your script

 python myscript.py

Scripting with Python

You need to include the BALL library into your script

import BALL

or

from BALL import *

For scripting please note the following:

• Take care that you have to remain consistent in your use of either tabs or plain spaces for python indentation, since python relies on the relative indentation of nested blocks to determine the grouping of statements correctly.
• Take care, that you have two empty lines at the end of the given script, since python needs them to interpret them as the end of the script.

You can find some example python code snippets and scripts in the CodeLibrary#scripting-with-python.

Documentation

As a rule of thumb all BALL classes are equally named in C++ and python. Thus beeing aware of the special python syntax the BALL web documentation can be used for python as well. The current state of the Python bindings can be checked here.

Another important point to keep in mind is the very special python indentation. Take care that you remain consistent in your use of either tabs or plain spaces for python indentation. Python relies on the relative indentation of nested blocks to determine the grouping of statements correctly.

You also have to take care that your script ends with two empty lines. Python needs them to interprete the end of the script.

Example scripts can be found in

• source/EXAMPLES/PYTHON/
• source/EXAMPLES/PYTHON/BALLView/
• source/EXAMPLES/PYTHON/howtos/

If BALLView's Instant Mode is used, you can get help by

• instantiating a class object and using the dir() command to get all available methods for the current object
• using the autocompletion by pressing the 'right arrow key'

Advanced

If you plan to add some python bindings either of existing or new C++ BALL classes seek advice in Creating a Python binding.