Read Me

===============================================================================
Bot2D
===============================================================================

An open source simulator based off of the Box2D physics library. Here are the 
various parts of the simulation engine:

File / Dir      Comments
=============   ===============================================================
controllers/    Automatic controllers (e.g. seek, flee, follow)
models/         Dynamic / kinematic models (e.g. unicycle, hovercraft)
mods/           Sensors (e.g. laserArray, gps)
geom.py         Geometry structs (e.g. point, pose, circle, polygon)
gui.py          OpenGL visualization
simulation.py   Box2d physics engine
vehicle.py      A vehicle is a container for mods, a model, and a shape
xmlconfig.py    XML parser converts .xml files into python data structures

===============================================================================
Getting Started
===============================================================================

The best way to learn is by example. Start with the bowling example -- it will
show you how to create a very simple custom mod (a blinking LED). To start this 
scenario enter the following commands in a terminal:

$ cd examples/bowling
$ python main.py

===============================================================================
Maps
===============================================================================

Maps can be constructed using any Scalable Vector Graphics (SVG) editor. We 
currently support Inkscape although other ones (e.g. Skencil) should also work.
Maps can be built using any of the polygon or straight line drawing tools --
curved lines will not register.

===============================================================================
Config Files
===============================================================================

We have a very nice xml parser that converts xml files directly into a python
data structure. It has the following mapping:

1. XML tags are converted into python lists
2. XML attributes are converted into python members
3. XML attributes are converted into floats when possible

For example the xml file...

<bot2d>
    <vehicle id="bot1">
        <shape type="box" width="1.1" height="0.6"/>
        <model type="unicycle"/>
    </vehicle>
    <vehicle id="bot2">
        <shape type="circle" radius="0.5"/>
        <model type="omni"/>
    </vehicle>
</bot2d>
... would map to the following python data structure.

bot2d.vehicle[0].id = "bot1"
bot2d.vehicle[0].shape[0].type = "box"
bot2d.vehicle[0].shape[0].width = 1.1
bot2d.vehicle[0].shape[0].height = 0.6
bot2d.vehicle[0].model[0].type = "unicycle"
bot2d.vehicle[1].id = "bot2"
bot2d.vehicle[1].type = "omni"
bot2d.vehicle[1].shape[0].type = "circle"
bot2d.vehicle[1].shape[0].radius = 0.5
bot2d.vehicle[1].model[0].type = "omni"

===============================================================================
Vehicles
===============================================================================

A vehicle is comprised of four basic things: shapes, mods (e.g. sensors and 
actuators), a dynamic model, and zero or more controllers.

A vehicle can be made up of one or more shape. These are boxes, circles, and
polygons. Due to some box2d restrictions a polygon can only have eight points
and must be convex. However you can create a non-convex body by combining 
several shapes.

A vehicle can have multiple controllers to make the vehicle move autonomously.
The set of controllers are ranked by the order they were listed in the config
file. The first controller takes charge of the vehcile until it becomes 
inactive. Then the second controller will take over. For example let's say we
want to do some obstacle avoidance. The first controller will become active
whenever there is an obstacle in front of us.