rosaria/Legacy/Aria/pythonExamples/README.txt

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.