Main Page Class Hierarchy Compound List File List Compound Members File Members
Motion Strategy Library Main Page
Motion Strategy Library
The Motion Strategy Library (MSL) allows easy development and testing
of motion planning algorithms for a wide variety of applications. The
software architecture is object-oriented and the general design is
highly modular. It was developed on a Linux system using GNU C++,
STL, and the FOX GUI
Toolkit.
The MSL is available as Open Source, free for both academic and
commerical use. Here is a copy of the licensing
agreement, which offers substantial freedom, to help spread
interest and applications of motion planning algorithms.
Presently MSL includes planners based on Rapidly-exploring Random Trees
(RRTs), Probabilistic Roadmaps (PRMs), and forward dynamic programming
(FDP). If you have any questions or comments regarding the software,
please do not hesitate to send e-mail.
MSL consists of seven C++ class hierarchies, each of which serving an
independent purpose. The relationship between these classes is shown
below.
This is not an inheritance diagram; it merely shows what information
is passed from one hierarchy to another. Inheritance diagrams are
included in the Class Hierarchy documentation.
Each of the seven class hierarchies is briefly explained below:
- Model:
These contain incremental simulators that model the
kinematics and dynamics of a variety of mechanical systems. The
methods allow planning algorithms to compute the future system state,
given the current state, an interval of time, and a control input
applied over that interval.
- Geom: These define the geometric
representations of all obstacles in the world, and of each part of the
robot. The methods allow planning algorithms to determine whether any
of the robot parts are in collision with each other or with obstacles
in the world.
- Problem: This is an interface
class to a planner, which abstracts the designer of a planning
algorithm away from particular details such as collision detection,
and dynamical simulations. Each instance of a problem includes both
an instance of Model and of Geometry. An initial state and final
state are also included, which leads to a problem to be solved by a
solver (typically a planning algorithm).
- Solver: There is currently
only one kind of solver, which is a hierarchy of planners.
A Solver is initialized with an
instance of Problem, and a method searches for a motion strategy that
solves a problem.
- Scene: This is an interface
class that computes configurations of all bodies to be displayed by a
rendering method. Scene receives most of its information directly
from Problem, but includes additional information relevant to
rendering, such as camera viewpoint.
- Render: This hierarchy of
classes contains different implementations of graphical rendering
requests. For example, when a graphical user interface (GUI) requests
that the a solution path is animated, a method in a Render class
displays the bodies in motion using configurations obtained from the
Scene class. Each derived class in Render corresponds to a different
graphics system. Presently, there are renderers for SGI IRIS
Performer, Open Inventor, Open GL. The flexibility provided
by these classes enables easy extensions to be made for other graphics
libraries and platforms.
- Gui: The graphical user interface
(GUI) is designed as a hierarchy of classes to enable specific user
interfaces to be designed for a variety of different motion strategy
problems and planning algorithms. Currently, there is one derived
class which serves as the GUI for all of the RRT-based planners. Each
instance of Gui includes an instance of an RRT Planner class and an
instance of a Render class. Using this design, the same basic GUI
design can be used, regardless of the particular rendering methods.
Here is the download information:
MSL Release 2.0 (07/22/03)
Source distribution:
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 7.2):
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 8.0):
[gzipped tar file]
For information about the new version, see the
Revision History
OLD RELEASES
MSL was developed on a PC running Red Hat Linux. Therefore
installation will probably be easiest on this platform. Versions of the software
has also successfully been installed on an SGI, SunOS, Windows 2000,
and many other flavors of Linux.
The following libraries are used by MSL:
- FOX C++ GUI Toolkit
This library is free for use under an LGPL license with a relinking
exemption addendum.
- Proximity Query Package
(PQP)
This package was developed at the University of North Carolina, and is
free for noncommerical use. It performs efficient collision detection and
distance computations for a collection of triangles in a 3D world.
PQP is generally easy to install. We have been playing around with
our own implementations of collision detection algorithms, and there is
a chance that future MSL version will not require PQP.
- Open GL, GLUT
OpenGL (or an equivalent API, such as MesaGL) is required for 3D
rendering using the GL-based renderer. The needed libraries can be
obtained for free on most platforms (for example, they are included in
RedHat Linux distributions). The library files are libglut, libGLU,
and libGL. The file libglut comes from the glut package, which
provides some GL utilities. If you are using Linux and want great
graphics performance, then you have to pay special attention to the
integration of a good graphics card, good Linux driver, GLX, and GL.
We have had the best luck using NVIDIA cards because great Linux
drivers are available from the NVIDIA web pages.
The most helpful web pages are: OpenGL, GLUT
and Mesa3D (Mesa3D is an alternative to
OpenGL).
- Open Inventor
This library is required ONLY if you want to use the Inventor-based
renderer. It currently has all of the features of the GL-based renderer,
plus a few more. We recommend using this one if you can. Open Inventor
is available as Open Source under the LGPL license.
- OpenGL
Performer
This library is required ONLY if you want to use the Performer-based
renderer. This library is only desirable if you want to develop
high-performance graphics with the MSL. It is also necessary, of
course, if you want to use Performer models. The MSL example of a car
driving through a nicely-rendered town is an example of such a model.
At the present time, Performer is available for SGIs and is free for
Linux. The Linux information is given on the Performer
for Linux page.
Several README files are contained within the distribution.
These contain useful information regarding installation,
running examples, and developing your own code that uses the
library.
Runnning the examples
In the default configuration, two executables are generated, plangl
and planleda. When running either of these, a path must be specified
that contains the problem. There are many example problems in the
data directory. To run one, type "plangl data/cage1".
The GuiPlanner window
The Construct button generates a planning graph, but does not attempt
to solve the problem. Plan attempts to find a path that connects the
InitialState to the GoalState (the PRM planner requires first using
Construct; RRT-based planners do not). If Plan fails, it can be
pressed again and the planner will continue to search using the
previous planning graphs as a starting point. The Planner menu allows
different planners to be attempted. The Display menu has functions
that show a solution path or show a 2D projection of the planning
graph. By default, the projection is shown using the first two state
varibles. In the planner control window the variables DrawIndexX
and DrawIndexY can be used to select other state variables to show in
the projection. The File menu contains many straightforward options
to read and write files. The Settings menu allows some planning
parameters to be adjusted, including DeltaT (the time step), NumNodes
(number of nodes to try to make each time Plan is pressed), and
GapDist (the distance threshold to use to declaring a connection has
been made in a dual tree search algorithm).
The GL renderer
The GL rendering window is primarily controlled using the render
control window. Some of the render control options can be performed
by pressing keys. Press 'h' to see a listing of these. Holding each
mouse button while moving allows a different type of change in the
viewpoint.
The Inventor Renderer
You can grab onto the environment and spin it.
The Performer renderer
When the Performer rendering window is open, there are several ways to
interact with the display. Pressing "c" will show or hide a control
bar that changes the animation speed. Pressing "b" will show or hide
a bounding box that is based on LowerWorld and UpperWorld. Pressing
"v" changes the viewpoint from either being global or being attached
to a body. Holding each mouse button while moving allows a different
type of change in the viewpoint.
Making a new problem
Each problem is described by a directory full of files. Most of them
are ASCII files that are easily read and written. To make a
new example, some files are necessary, while others are optional.
Default values of parameters will be assumed when optional files are
not present. Some particular models might require files that are not
used in other models. For example, ModelLinear requires files "A" and
"B" which specify the matrices in the equation xdot = Ax + Bu. Other
than reading the code, an easy way to find out which files might be
needed for a particular model is to modify an example that has been
included in this distribution and uses the same model.
The following files are required for all examples:
- GeomDim: The dimension of the environment (2 or 3)
- ModelXXX: A file named exactly after the motion model to be used.
Examples are Model2DRigid and Model3DRigidMulti.
- GeomXXX: A file named exactly after the geometry model, such as
GeomPQP3DRigid for a rigid body made of triangles in a 3D world (with
PQP being used for collision detection).
- IntialState: The initial state for the problem.
- GoalState: The desired goal state.
- Robot: A model of the robot, specified either as a list of
polygons if GeomDim = 2, or a list of 3D triangles if GeomDim = 3.
For problems that involve multiple bodies, the robots are named
Robot0, Robot1, ..., Robotk, for k robots.
The following files are optional:
- ModelDeltaT: The time increment to be used for numerical integration
of the state transition equation (equations of motion).
- PlannerDeltaT: The time increment to be used for an incremental
planning step.
- Obst: A list of stationary obstacles, specified either as a list
of polygons if GeomDim = 2, or a list of 3D triangles if GeomDim
= 3.
- EnvList: A list of file names that correspond to stationary
geometric models that can be loaded and rendered (they are not used
for collision detection). If EnvList does not exist, then Obst is
loaded and rendered.
- BodyList: A list of file names that correspond to movable bodies.
If BodyList does not exist, then Robot, or Robot0, Robot1, ..., Robotk
are loaded.
- LowerState: The lowest possible state vector. Each element is
the smallest value for that state variable.
- UpperState: The highest possible state vector. Each element is
the largest value for that state variable.
- RRTXXX: A default planner selection, such as RRTExtExt or
RRTConCon.
- Inputs: A list of input vectors to be applied to the state
transition equation. By making this file, one can override the
defaults from the class constructor. For example, an car that can go
forward or reverse can be converted into a forward-only car by simply
changing this file.
- ViewingPosition: The (x,y,z) position of the camera to be used in
rendering.
- ViewingDirection: The direction that the camera should point (a 3D
vector)
- ViewingOrientation: A possible rotation about the viewing
direction for the camera.
- LowerWorld: The smallest (x,y,z) value of the environment.
- UpperWorld: The largest (x,y,z) value of the environment.
- Holonomic: Let a planner know that the problem is holonomic with a
state transition equation of the form xdot = u. In this case,
performance can be greatly improved by ignoring the Inputs and
performing linear interpolation to generate local motions.
Extending existing models
Suppose that you would like to make your model derived class from
Model, or you would like to make your own variation of an RRT, PRM, or
FDP planner. This can be accomplished by writing very little code.
An example of how to make and use your own model is given in the
"tests" directory of the MSL distribution. Included in that
directory is a README that explains the examples. These are the
recommended way to use the MSL in a clean, object-oriented way.
If you write code this way and make some interesting contributions,
it will be easy for us to include it in future releases of the
library. If you simply hack away at the MSL source code, then it
will be nearly impossible to do this, and you will have difficulty
using upgraded versions of MSL.
Version 2.0
- For solutions generated by any RRT planner with "Con" in the name, the
animated path might appear incorrect for nonholonomic planning problems.
This is because linear interpolation is used between far away states
that are given for rendering. The algorithms still correctly compute the
trajectory using numerical integration (only the display is wrong).
- ANYTHING ELSE WE WANT TO ADD HERE????
I get many messages from researchers attempting to get the MSL to work
on Windows platforms. My student, Libo Yang took an MSL version from
a couple of years ago and fixed the code up to work under Windows
2000. Beyond that, we do not have the resources to maintain the code
for various Windows distributions, such as NT or XP. Once we release
the new open source version this summer, we would welcome any
contributions that help make the MSL work under these platforms. We
generally do our development in Linux, and do not have the expertise
or desire to provide extensive support for Windows. However, since
many users care about this, we are willing to incoprorate the
contributions of others, which may enable the library to be compiled
under various Windows platforms.
- Version 2.0 (7/22/03)
After two years of being at the
University of Illinois, we have finally released a new version, which
is substantially updated.
- Under some Linux platforms, the GL-based animation got stuck due to some
strange event handling problems (might be caused by problems in FOX).
You'll no longer have to jiggle the mouse to get the animations moving.
- The Performer renderer and GUI are working again, for the first time
under non-LEDA versions of MSL. This enables very sophisticated models
to be used.
- The Inventor-based GUI is much enhanced now. It has all of the
features of the GL-based GUI.
- The PRM implementations were very primitive. There are now improved
version that use the union-find algorithm to do fast connected-component
analysis. This greatly improves PRM performance.
- The timings were messed up after saving and loading a computed trajectory.
This is fixed.
- The triangle orientations generated by the code in the util directory,
and in many example problems, were messed up. This made the shading wrong
in the renderers. This is fixed.
- Some newer RRT-based planning algorithms have been added.
- More planning examples, including straightforward examples of
the 3D articulated body class, to make it easier to construct new
examples.
- The Euler angles for 3D rotation were given a range for the example
problems that resulted in a double cover of the configuration space. The
3D rotation code has been simplified to make debugging easier, and the
examples have been fixed.
- Version 1.2nl [non-LEDA] (9/1/01)
- This is the first version that was written without LEDA. Most
of the original functionality of MSL Version 1.2 was preserved.
- A render based on OpenInventor was added. Multiple cameras
and attached cameras are not supported.
- Version 1.2 (1/9/01)
- A new default renderer has been made based on GL and GLUT. This
greatly increases the portability of MSL. Features are described
above.
- All of the animation frame handling is done in the Render base class.
This facilitates the design of a new renderer.
- A render control window is available (describe above).
- A bidirectional version of FDP has been added.
- Version 1.1 (12/15/00)
- Animations in a rendering window are now displayed at a
rate given by the times associated with each state (generated
by a planner). On a slower graphics card, frames are simply
skipped to maintain the proper speed. The control bar allows
the time to be scaled, allowing the animation to be anywhere
from 1000 times slower to 1000 times faster.
- New models were added to support a collection of attached
3D bodies: Model3DRigidChain and Model3DRigidTree. New examples
were added to demonstrate these new models: 3dchain1, 3dtree1.
- Pressing "v" in the Performer rendering window will change the
viewpoint to be attached to a body. New variables were added
to Scene to specify the camera parameters. These variables can be
read in from files.
- A Probabilistic Roadmap Planner (PRM) was added, based on the
approach of Kavraki, Svestka, Latombe, Overmars, 1994.
- A Forward Dynamic Programming (FDP) planner was added, based
on the approach of Barraquand, Latombe, Algorithmica, 1993.
There are two derived classes, FDPStar (an A* search variant),
and FDPBestFirst (a best-first search variant). These methods
are grid-based, and are therefore limited to a few dimensions
(four or less in most circumstances). Under data, the directories
fdp1 and fdp2 contain examples.
- RRTCon is now derived from RRTGoalBias. By default, there is
no bias. A file named GoalProb can be used to override the
default.
- The bidirectional RRT planners use a new variable called
ConnectTimeLimit. If this time limit is reached (starting
at time zero when the connection begins), then the connection
is stopped, even if the sample is not reached. Note that this
is not real time, but time according to the integrations of
the model. A file named ConnectTimeLimit can be defined to
override the default (infinity).
- GapDist has been replaced by a vector called GapError. RRT-based
planners will consider connection to be made if the absolute value
of the difference between each state component is less than or equal
to the corresponding component of GapError.
- A number of minor bugs were fixed.
- Version 1.0.1 (11/15/00)
- A Solver base class has been defined, with Planner as a
child. RRT is a child of Planner. The GUI for the RRT planner has
been generalized to accomodate other planners more easily. Hence,
GuiRRT is replaced with GuiPlanner. "rrtpf" and "rrtleda" are
replaced with "planpf" and "planleda". The files "rrtpf.C",
"rrtleda.C", "guirrt.C", "guirrt.h" have been replaced with
"planpf.C", "planleda.C", "guiplanner.C", "guiplanner.h". The new
base classes are in "solver.h" and "planner.h".
- The step sizes for numerical integration and for planning can
now be controlled independently. For a problem, make a file called
ModelDeltaT to set the numerical integration step time, and PlannerDeltaT
for the planner. Default values have been set for the examples. Note that
if PlannerDeltaT is too large, then the collision checker might miss
collisions that occur from intermediate configurations.
- Minor bugs were fixed in the examples and in the code.
- Version 1.0 (11/11/00) The original distribution.
- Peng Cheng
GL-based renderer. Some RRT classes.
- James Kuffner
Original Inventor renderer. Help with design of basic classes.
- Steve LaValle
Supervision of project. Most of the design and implementation of
basic classes. Implementation of most RRT, Model, and Geom classes.
- Steve Lindemann
Many bug fixes. Improved PRM implementations.
- Aswath Manohar
Many bug fixes. Enhanced Inventor renderer and FOX GUI.
- Benjamin Tovar
Improved installation scripts.
- Libo Yang
Performer renderer. Help with design of basic classes.
- Anna Yershova
3DChain, 3DTree classes.
Web page maintained by Steve
LaValle and his students at the University of Illinois.