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 library. MSL is available for free academic use, and is mainly
intended for research and educational purposes. 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 1.2 (1/9/01)
Given that we
mostly developed the code for research purposes, there will most
likely be bugs and installation difficulties. We appreciate any
feedback so that we can improve the software.
Source distribution:
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 6.2):
[gzipped tar file]
- MSL Release 1.1 (12/15/00)
Source distribution:
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 6.2):
[gzipped tar file]
- MSL Release 1.0.1 (11/15/00)
Source distribution:
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 6.2):
[gzipped tar file]
- MSL Release 1.0 (11/11/00)
Source distribution:
[gzipped tar file]
Linux binary distribution (Compiled using Red Hat 6.2):
[gzipped tar file]
MSL was developed on a PC running Red Hat Linux 6.2. Therefore
installation will probably be easiest on this platform. The software
has also successfully been installed on an SGI.
The following libraries are used by MSL:
- FOX C++ GUI Library
This library is free for academic use by a GNU liscense.
- Proximity Query Package
(PQP)
This package was developed at the University of North Carlina, and is
free for academic use. It performs efficient collision detection and
distance computations for a collection of triangles in a 3D world.
PQP is generally easy to install.
- 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 is usually easier install the GL-based renderer, but
eventually this one will have more features). It is available
as open source.
- IRIS
Performer
This library is required ONLY if you want to use the Performer-based
renderer (it is much easier to install the GL-based renderer). At the
present time, Performer is available for SGIs and is free for Linux.
The Linux system requirements are described on the
Performer installation page for Linux. The basic dependencies are
XFree86 3.3.3.1 or above, OpenGL 1.2, and Motif/Lesstif. Versions of
all of these can be obtained free for noncommercial use.
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
"example" directory of the MSL distribution. Included in that
directory is a README that explains the example.
Version 1.2
- 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).
- 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.
- Add more features to RenderInventor.
- Improve the GUI code and menu options.
Web page maintained by Steve LaValle
Partial support provided by NSF CAREER Award IRI-970228 (LaValle),
Honda Research.
Contributors: Anna Atramentov, Peng Cheng, James Kuffner, Steve LaValle,
and Libo Yang.