153 lines
6.3 KiB
Plaintext
153 lines
6.3 KiB
Plaintext
|
|
|
|
|
|
USING THE PYTHON WRAPPER FOR ARIA
|
|
---------------------------------
|
|
|
|
A "wrapper" library for Python has been provided in the "python" directory.
|
|
This wrapper layer provides a Python API which simply makes calls into the
|
|
regular Aria C++ library (libAria.so/AriaVC10.dll). In general, the Python API
|
|
mirrors the C++ API.
|
|
|
|
The Aria Python wrapper currently requires Python version 2.4.4 if on Debian 3 or Windows,
|
|
Python 2.5 if on Debian 5, or Python 2.7 if on Ubuntu 12. Multiple versions of
|
|
Python may be installed on Debian Linux; if so, commands are provided such as
|
|
'python2.4' or 'python2.5' or 'python2' to invoke the different versions of
|
|
Python.
|
|
|
|
NOTE: You should use the versions of Python mentioned above, since the wrapper
|
|
library code is generally only compatible with the runtime libraries provided
|
|
by these versions. To use a different version of Python, you must
|
|
rebuild the wrapper library (see below).
|
|
|
|
You can download Python 2.4.4 from:
|
|
http://www.python.org/download/releases/2.4.4
|
|
(Python 2.2 is also at python.org.)
|
|
|
|
On Debian, you can install Python 2.5 by entering the following command
|
|
when connected to the Internet:
|
|
|
|
sudo apt-get install python
|
|
|
|
Or, you can download Python 2.5.5 from:
|
|
http://www.python.org/download/releases/2.5.5
|
|
|
|
On Ubuntu, you can install Python 2.7 with the following command:
|
|
|
|
sudo apt-get install python2.7
|
|
|
|
|
|
(NOTE if using Python 2.6 or later: Python 2.6 requires native C++ DLLs to be
|
|
named with a ".pyd" file extension, rather than .dll/.so as was
|
|
allowed in previous versions. So if Python 2.6 is unable to import the
|
|
AriaPy DLL module, rename _AriaPy.dll or _AriaPy.so to _AriaPy.pyd
|
|
in the python/ subdirectory.)
|
|
|
|
Documentation about the Python language and libraries is at:
|
|
http://docs.python.org
|
|
|
|
To use the wrapper library you must create an environment variable called PYTHONPATH
|
|
that has the full path to Aria's 'python' directory in it.
|
|
|
|
On Linux, set it to:
|
|
/usr/local/Aria/python
|
|
|
|
On Windows, set it to:
|
|
C:\Program Files\MobileRobots\Aria\python
|
|
|
|
Environment variables are set in Windows in the Advanced tab of the System control panel.
|
|
|
|
|
|
For an example you can start the simulator, then enter
|
|
the pythonExamples directory and run:
|
|
|
|
python simple.py
|
|
|
|
On Windows, you can just double-click simple.py.
|
|
|
|
NOTE: The Python wrapper API is not as well tested as Aria itself. If
|
|
you encounter problems, please notify the aria-users mailing list. Furthermore,
|
|
some methods have been omitted or renamed, and you have to do a few things
|
|
differently (see next section).
|
|
|
|
|
|
|
|
|
|
USING ACTIONS IN PYTHON
|
|
-----------------------
|
|
|
|
Writing classes in Python that subclass classes from Aria is not as
|
|
straightforward as making subclasses of native Python classes. Subclasses
|
|
of classes in the wrapper are not direct subclasses of the C++ classes,
|
|
they are only subclasses of the Python wrapper classes, which implement the logic
|
|
to redirect calls between the C++ and wrapper classes. The practical
|
|
consequences of this include the following:
|
|
|
|
1. You cannot call a virtual method in the parent class which the subclass
|
|
overrides -- it will always be directed to the subclass's implementation.
|
|
For example, you can override ArAction::setRobot(), which is a virtual
|
|
method. But then, any call to setRobot() on the subclass will always
|
|
be directed to the subclass's implementation; calling
|
|
self.ArAction.setRobot() from you subclass's setRobot() override would
|
|
result in an infinite recursion, so Swig throws an exception instead.
|
|
There is no workaround for this other than extending each parent class
|
|
in wrapper.i ad-hoc to include an additional method with a new name to
|
|
invoke the method defined in the parent. We have done this for a few
|
|
cases (such as ArAction::setRobot()), but If this ever becomes neccesary
|
|
for any others, please let us know and we will add the extension.
|
|
|
|
2. Swig currently does not make protected methods available to
|
|
subclasses, though this may be fixed in the future.
|
|
|
|
|
|
OTHER DIFFERENCES
|
|
-----------------
|
|
|
|
See the C++ API docs for various classes for notes about how they might be
|
|
used differently in Python. For example, ArConfigArg and ArFunctor are used
|
|
slightly differently (since those classes use features unique to C++).
|
|
|
|
|
|
|
|
REBUILDING THE PYTHON WRAPPER
|
|
-----------------------------
|
|
|
|
You must rebuild the Python wrapper if you make any interface changes to
|
|
ARIA and want them to be available in Python. You may also need to rebuild
|
|
the wrapper if you want to use another version of Python (as distributed, the
|
|
wrapper libraries were built with and linked against the 2.4 Python runtime library
|
|
on Debian Linux and Windows, and 2.2 on RedHat 7).
|
|
|
|
If you want to rebuild the Python wrapper you need to install SWIG, you
|
|
can get it from http://www.swig.org/download.html (use version 1.3.29 or newer.)
|
|
You'll also need Python, which you can get from
|
|
http://www.python.org.
|
|
|
|
On Linux, you may also need to install a Python "Development" package in addition
|
|
to the main Python runtime package. e.g. on Debian, install python2.4-dev. On
|
|
Windows, if the python24_d.lib library is missing, you can download the
|
|
Python 2.4 source code and compile the "python" project in the PCbuild subdirectory.
|
|
|
|
Set the environment variable PYTHON_INCLUDE to the full path of Python's
|
|
include directory. On Linux, this is usually /usr/include/python2.4 for
|
|
Python 2.4 or /usr/include/python2.2 for Python 2.2 or /usr/include/python2.7
|
|
for Python 2.7. On Windows, it depends
|
|
on where you installed Python but a typical value is C:\Python24\include for
|
|
Ptyhon 2.4).
|
|
|
|
On Windows you'll also need to set the environment variables
|
|
PYTHON_LIB to the full path of the Python library and PYTHON_LIBDIR to the directory
|
|
containing all the Python libs. These depend on where
|
|
you installed Python, but a typical value would be "C:\Python24\libs\python24.lib" for
|
|
PYTHON_LIB and "C:\Python24\libs" for PYTHON_LIBDIR for Python 2.4.
|
|
Set environment variables in the Advanced section of the System control panel.
|
|
|
|
On Linux Run 'make python' in the Aria directory, and again run 'make python' in
|
|
the ArNetworking subdirectory if you also want the wrapper library for
|
|
ArNetworking. On Windows, open the AriaPy-vc2010.sln file in the 'python'
|
|
directory with Visual Studio 2010 and build AriaPy and, if desired,
|
|
ArNetworkingPy in Release configuration. The native ARIAlibrary may be
|
|
automatically rebuilt if neccesary.
|
|
|
|
|