Menu
▾
▴
[Personalrobots-commit] SF.net SVN: personalrobots:[18086] pkg/trunk
|
From: <is...@us...> - 2009-07-01 05:56:07
|
Revision: 18086
http://personalrobots.svn.sourceforge.net/personalrobots/?rev=18086&view=rev
Author: isucan
Date: 2009-07-01 05:55:45 +0000 (Wed, 01 Jul 2009)
Log Message:
-----------
some documentation
Modified Paths:
--------------
pkg/trunk/motion_planning/ompl_planning/mainpage.dox
pkg/trunk/motion_planning/ompl_planning/manifest.xml
pkg/trunk/motion_planning/planning_environment/mainpage.dox
pkg/trunk/motion_planning/planning_models/mainpage.dox
pkg/trunk/util/geometric_shapes/mainpage.dox
pkg/trunk/world_models/collision_space/mainpage.dox
Modified: pkg/trunk/motion_planning/ompl_planning/mainpage.dox
===================================================================
--- pkg/trunk/motion_planning/ompl_planning/mainpage.dox 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/motion_planning/ompl_planning/mainpage.dox 2009-07-01 05:55:45 UTC (rev 18086)
@@ -2,43 +2,43 @@
\mainpage
\htmlinclude manifest.html
-@b ompl_planning is a node capable of planning kinematic paths for
-a set of robot models. Each robot model is a complete model specified
-in URDF or consists of an URDF group.
+@section summary Summary
+@b ompl_planning is a node capable of planning kinematic paths for a
+set of robot models. Each robot model is a group of links/joints from a
+URDF file, not necessarily the complete robot model. The available
+models (groups of links) are defined as described in the
+<a href="../../planning_environment/html">planning_environment</a> package.
+
Organization:
- - there are multiple models (a model is a group of links/joints we plan for)
- - there are multiple planners that can be used for each model
- - there are multiple types of planning requests
-The code is mostly implemented in the included RKP* files (ROS
-Kinematic Planning). There exists one basic class (RKPRequestHandler)
-that can handle different requests.
+ - there are multiple models (defined by @b group_list as in <a href="../../planning_environment/html">planning_environment</a>)
-A model is defined for each loaded URDF model, and for each of the
-URDF groups marked for planning. This model includes a kinematic
-model, a collision space (shared between models) and a set of
-planners. If a planner is used for different models, it is
-instantiated each time. Since planners may require different
-setup/configuration code, there exists a base class that defines the
-functionality and an inherited class for each type of planner that can
-be instantiated. The planners are associated to string names:
-kinematic::RRT, kinematic::LazyRRT, kinematic::EST, kinematic::SBL,
-kinematic::IKSBL. These string names can be used for the planner_id
-component of the planning request. If no planner_id is specified, an
-appropriate planner is automatically selected. This is in fact the
-prefered use.
+ - there are multiple planners that can be used for each model (defined by @b planner_configs as in <a href="../../planning_environment/html">planning_environment</a>)
+
+For each model, a kinematic structure (as in <a
+href="../../planning_models/html">planning_models</a>), a collision
+space (as in <a href="../../collision_space/html">collision_space</a>)
+and a set of planners (from <a href="../../ompl/html">ompl</a>) are
+maintained. The collision space is shared between models. If a
+planner is used for different models, it is instantiated each
+time.
+
+The planners are associated to string names: kinematic::RRT,
+kinematic::LazyRRT, kinematic::EST, kinematic::SBL, kinematic::IKSBL,
+kinematic::KPIECE, dynamic::RRT. These string names can be used for
+the @b planner_id component of the planning request. If no @b
+planner_id is specified, an appropriate planner is automatically
+selected. This is in fact the preferred use.
+
When checking states for validity, a resolution at which paths are
check needs to be defined. To make things easier for the user, this
-parameter is computed by default by the SpaceInformationRKPModel
-class. The current settings work fine for the PR2, but if another
-robot is to be used, different settings man need to be used.
+parameter is computed by default by the
+ompl_planning::SpaceInformationKinematicModel class. The current
+settings work fine for the PR2, but if another robot is to be used,
+different settings may need to be employed.
-\todo
-- Find a better way to specify resolution for state validity
-checking.
-
<!--
\section codeapi Code API
-->
@@ -71,10 +71,10 @@
\subsubsection topics ROS topics
Subscribes to:
-- only topics PlanningMonitor from planning_environment package subscribes to
+- only topics planning_environment::PlanningMonitor from <a href="../../planning_environment/html">planning_environment</a> package subscribes to
\subsubsection parameters ROS parameters
-- "~planning_frame_id"/string : if the default frame is not to be used when planning, this parameter allows changing that frame.
+- @b "~planning_frame_id"/string : if the default frame is not to be used when planning, this parameter allows changing that frame.
\subsubsection services ROS services
@@ -94,4 +94,4 @@
<!-- END: copy for each node -->
-*/
\ No newline at end of file
+*/
Modified: pkg/trunk/motion_planning/ompl_planning/manifest.xml
===================================================================
--- pkg/trunk/motion_planning/ompl_planning/manifest.xml 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/motion_planning/ompl_planning/manifest.xml 2009-07-01 05:55:45 UTC (rev 18086)
@@ -1,5 +1,5 @@
<package>
- <description>Kinematic motion planning using OMPL</description>
+ <description>Sampling-based motion planning using OMPL</description>
<author>Ioan A. Sucan</author>
<license>BSD</license>
<review status="unreviewed" notes=""/>
Modified: pkg/trunk/motion_planning/planning_environment/mainpage.dox
===================================================================
--- pkg/trunk/motion_planning/planning_environment/mainpage.dox 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/motion_planning/planning_environment/mainpage.dox 2009-07-01 05:55:45 UTC (rev 18086)
@@ -2,142 +2,204 @@
\mainpage
\htmlinclude manifest.html
+@section summary Summary
+
\b planning_environment is a library that allows users to instantiate
robot models and collision models based on data from the parameter
server with minimal user input. Additionally, state information for
both robot models and collision environments can be monitored.
-<!--
-In addition to providing an overview of your package,
-this is the section where the specification and design/architecture
-should be detailed. While the original specification may be done on the
-wiki, it should be transferred here once your package starts to take shape.
-You can then link to this documentation page from the Wiki.
--->
+@section conventions Conventions
+A URDF robot description is assumed to be loaded on the parameter
+server. The name of the parameter under which this description exists
+is taken as an argument to class constructors. Additionally, .yaml
+files describing the collision and planning information should be
+loaded on the parameter server under the same prefix as the robot
+description.
-\section codeapi Code API
+The collision.yaml file should define the follwing:
-The intended use for this package is to instantiante one of the two
-model classes and potentially one of the monitor classes.
+ - the robot links (same names as in the URDF description) that should be considered for collision checking under @b collision_links
-The model classes are:
-- \b RobotModels : allows the instantiation of various robot models (for example, a kinematic one) based on data from the parameter server. The URDF robot description and the .yaml files describing collision and planning information are assumed to be loaded.
+ - the self collision groups under @b self_collision_groups
-- \b CollisionModels : allows the instantiation of various robot models (for example, a kinematic one) and various collision spaces, based on data from the parameter server. This class inherits from \b RobotModels. The URDF robot description and the .yaml files describing collision and planning information are assumed to be loaded.
+ - the set of robot links that the robot can perceive with its sensors @b self_see ; (scaling and padding for these links is set with @b self_see_scale, @b self_see_padd)
-<hr>
-The monitor classes are:
-- \b KinematicModelStateMonitor : monitors the kinematic state of the robot. Optionally, monitors the base location. It uses the 'mechanism_state' topic.
-- \b CollisionSpaceMonitor : same as \b KinematicModelStateMonitor except it also monitors the state of the collision environment. It uses the 'collision_map' topic to receive new full maps and the 'collision_map_update' to receive updates. Attaching objects to robot links is possible using the 'attach_object' topic. The '~box_scale' parameter is used as the constant that gets multiplied to a box's maximum extent to obtain the radius of the sphere used in collision checking.
-- \b PlanningMonitor : same as \b CollisionSpaceMonitor except it also offers the ability to evaluate kinematic constraints and check paths and states for validity.
+An example collision.yaml file:
- <!-- Provide links to specific auto-generated API
-documentation within your package that is of particular interest to a
-reader. Doxygen will document pretty much every part of your code, so
-do your best here to point the reader to the actual API.
+@verbatim
-If your codebase is fairly large or has different sets of APIs, you
-should use the doxygen 'group' tag to keep these APIs together. For
-example, the roscpp documentation has 'libros' group.
--->
+## links for which collision checking with the environment should be performed
+collision_links:
+ base_link
+ torso_lift_link
+ head_pan_link
+ head_tilt_link
+ laser_tilt_mount_link
+ base_laser
+ ...
-\section rosapi ROS API
+## self collision is performed between groups of links; the names for the groups can be anything, but they must contain 'a' and 'b' as subgroups
+self_collision_groups: scg_r scg_l
-<!--
-Names are very important in ROS because they can be remapped on the
-command-line, so it is VERY IMPORTANT THAT YOU LIST NAMES AS THEY
-APPEAR IN THE CODE. You should list names of every topic, service and
-parameter used in your code. There is a template below that you can
-use to document each node separately.
+## -- for right arm; self-collision if any link in 'a' collides with some link in 'b'
+scg_r:
+ a: r_forearm_link r_gripper_palm_link r_gripper_l_finger_link r_gripper_r_finger_link r_gripper_l_finger_tip_link r_gripper_r_finger_tip_link
+ b: base_link base_laser torso_lift_link laser_tilt_mount_link head_tilt_link
-List of nodes:
-- \b node_name1
-- \b node_name2
--->
+## -- for left arm; self-collision if any link in 'a' collides with some link in 'b'
+scg_l:
+ a: l_forearm_link l_gripper_palm_link l_gripper_l_finger_link l_gripper_r_finger_link l_gripper_l_finger_tip_link l_gripper_r_finger_tip_link
+ b: base_link base_laser torso_lift_link laser_tilt_mount_link head_tilt_link
-<!-- START: copy from here to 'END' for each node
+## list of links that the robot can see with its sensors (used to remove
+## parts of the robot from scanned data)
+self_see:
+ r_upper_arm_link
+ r_upper_arm_roll_link
+ r_elbow_flex_link
+ r_forearm_link
+ r_forearm_roll_link
+ ...
-<hr>
+## The padding to be added for the body parts the robot can see
+self_see_padd: 0.1
-\subsection node_name node_name
+## The scaling to be considered for the body parts the robot can see
+self_see_scale: 1.0
-node_name does (provide a basic description of your node)
+@endverbatim
-\subsubsection Usage
-\verbatim
-$ node_type1 [standard ROS args]
-\endverbatim
-\par Example
+The planning.yaml file defines the groups of links/joints motion planning can be performed for and contains the following:
-\verbatim
-$ node_type1
-\endverbatim
--->
+ - the names of the groups (the model ID's) planning is done for, under @b group_list. This is important as motion planners will use these names as input.
-\subsubsection topics ROS topics
+ - the definition of each of the groups is under @b groups. Each definition contains
+ - @b links : the names of the robot links to plan for; the actuated joints are the ones that connect the links with their parents, as described in the URDF
+ - @b planner_configs : these are names of configurations for planners; each planner configuration contains a planner-specific set of parameters. The only parameter that must exist is 'type', which specified the planner to be used.
-Subscribes to:
-- @b "mechanism_state"/MechanismState : the parameters describing the robot's current state
-- @b "collision_map"/CollisionMap : data describing the 3D environment
-- @b "collision_map_update"/CollisionMap : updates to data describing the 3D environment
-- @b "attach_object"/AttachedObject : data describing an object to be attached to a link
+ - the content of each planning configuration under @ b planner_configs
-\subsubsection parameters ROS parameters
-Reads the following parameters from the parameter server
+An example planning.yaml file:
-Reads the following parameters from the parameter server
-- @b "~refresh_interval_collision_map"/double : if more than this interval passes, the maintained map is considered invalid
+@verbatim
-- @b "~refresh_interval_kinematic_state"/double : if more than this interval passes, the maintained kinematic state is considered invalid
+## the list of groups for which motion planning can be performed
+group_list:
+ base
+ left_arm
+ ...
-- @b "~bounding_planes"/string : a sequence of plane equations specified as "a1 b1 c1 d1 a2 b2 c2 d2 ..." where each plane is defined by the equation ax+by+cz+d=0
+## the definition of each group
+groups:
-- @b "~box_scale"/double : boxes from the collision map are approximated with spheres using the extents of the boxes. The maximum extent of the box is multiplied by the constant specified by this parameter to obtain the radius of the sphere approximating the box
+ base:
+ links:
+ base_link
+ planner_configs:
+ RRTkConfig1 RRTdConfig1 SBLkConfig1 KPIECEkConfig1
-A robot description and its corresponding planning and collision descriptions are assumed to be loaded on the parameter server as well.
+ left_arm:
+ links:
+ l_shoulder_pan_link
+ l_shoulder_lift_link
+ l_upper_arm_roll_link
+ l_upper_arm_link
+ l_elbow_flex_link
+ l_forearm_roll_link
+ l_forearm_link
+ l_wrist_flex_link
+ l_wrist_roll_link
+ planner_configs:
+ SBLkConfig2 LBKPIECEkConfig2l
-Sets the following parameters on the parameter server
+ ...
-- Sets the parameters it reads to default values
+## the planner configurations; each config must have a type, which specifies
+## the planner to be used; other parameters can be specified as well, depending
+## on the planner
-<!--
-\subsubsection services ROS services
-- \b "foo_service": [std_srvs/FooType] description of foo_service
+planner_configs:
+
+ RRTkConfig1:
+ type: kinematic::RRT
+ range: 0.75
+ RRTdConfig1:
+ type: dynamic::RRT
+ range: 0.75
-END: copy for each node -->
+ SBLkConfig1:
+ type: kinematic::SBL
+ projection: 0 1
+ celldim: 1 1
+ range: 0.5
+ KPIECEkConfig1:
+ type: kinematic::KPIECE
+ projection: 0 1
+ celldim: 1 1
+ range: 0.5
-<!-- START: Uncomment if you have any command-line tools
+ SBLkConfig2:
+ type: kinematic::SBL
+ projection: 5 6
+ celldim: 0.1 0.1
-\section commandline Command-line tools
+ LBKPIECEkConfig2l:
+ type: kinematic::LBKPIECE
+ projection: link l_wrist_roll_link
+ celldim: 0.1 0.1 0.1
-This section is a catch-all for any additional tools that your package
-provides or uses that may be of use to the reader. For example:
+@endverbatim
-- tools/scripts (e.g. rospack, roscd)
-- roslaunch .launch files
-- xmlparam files
+\section codeapi Code API
-\subsection script_name script_name
+The intended use for this package is to instantiante one of the two
+model classes and potentially one of the monitor classes.
-Description of what this script/file does.
+The model classes are:
+- \b planning_environment::RobotModels : allows the instantiation of various robot models (for example, a kinematic one) based on data from the parameter server. The URDF robot description and the .yaml files describing collision and planning information are assumed to be loaded.
-\subsubsection Usage
-\verbatim
-$ ./script_name [args]
-\endverbatim
+- \b planning_environment::CollisionModels : allows the instantiation of various robot models (for example, a kinematic one) and various collision spaces, based on data from the parameter server. This class inherits from \b planning_environment::RobotModels. The URDF robot description and the .yaml files describing collision and planning information are assumed to be loaded.
-\par Example
+<hr>
-\verbatim
-$ ./script_name foo bar
-\endverbatim
+The monitor classes are:
+- \b planning_environment::KinematicModelStateMonitor : monitors the kinematic state of the robot. Optionally, monitors the base location. It uses the 'mechanism_state' topic.
+- \b planning_environment::CollisionSpaceMonitor : same as \b planning_environment::KinematicModelStateMonitor except it also monitors the state of the collision environment. It uses the 'collision_map' topic to receive new full maps and the 'collision_map_update' to receive updates. Attaching objects to robot links is possible using the 'attach_object' topic. The '~box_scale' parameter is used as the constant that gets multiplied to a box's maximum extent to obtain the radius of the sphere used in collision checking.
+- \b planning_environment::PlanningMonitor : same as \b planning_environment::CollisionSpaceMonitor except it also offers the ability to evaluate kinematic constraints and check paths and states for validity.
-END: Command-Line Tools Section -->
+\section rosapi ROS API
-*/
\ No newline at end of file
+\subsection topics ROS topics
+
+Subscribes to:
+ - @b "mechanism_state"/MechanismState : the parameters describing the robot's current state
+ - @b "collision_map"/CollisionMap : data describing the 3D environment
+ - @b "collision_map_update"/CollisionMap : updates (additive) to data describing the 3D environment
+ - @b "attach_object"/AttachedObject : data describing an object to be attached to a link
+
+\subsection parameters ROS parameters
+
+Reads the following parameters from the parameter server
+ - @b "~refresh_interval_collision_map"/double : if more than this interval passes, the maintained map is considered invalid
+
+ - @b "~refresh_interval_kinematic_state"/double : if more than this interval passes, the maintained kinematic state is considered invalid
+
+ - @b "~bounding_planes"/string : a sequence of plane equations specified as "a1 b1 c1 d1 a2 b2 c2 d2 ..." where each plane is defined by the equation ax+by+cz+d=0
+
+ - @b "~box_scale"/double : boxes from the collision map are approximated with spheres using the extents of the boxes. The maximum extent of the box is multiplied by the constant specified by this parameter to obtain the radius of the sphere approximating the box
+
+A robot description and its corresponding planning and collision descriptions are assumed to be loaded on the parameter server as well.
+
+Sets the following parameters on the parameter server
+
+ - Sets the parameters it reads to default values
+
+
+*/
Modified: pkg/trunk/motion_planning/planning_models/mainpage.dox
===================================================================
--- pkg/trunk/motion_planning/planning_models/mainpage.dox 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/motion_planning/planning_models/mainpage.dox 2009-07-01 05:55:45 UTC (rev 18086)
@@ -2,31 +2,15 @@
\mainpage
\htmlinclude manifest.html
-\b planning_models is used for describing a kinematic robot model loaded from URDF. Visual geometry is ignored (only collision geometry is considered). This package allows performing forward kinematics for various groups of joints, for potentially multiple robots. The states for different groups of joints can be easily extractes using the KinematicModel class. The StateParams class allows easy updating of various state values by using the joint names specified in URDF.
+@section summary Summary
-<!--
-In addition to providing an overview of your package,
-this is the section where the specification and design/architecture
-should be detailed. While the original specification may be done on the
-wiki, it should be transferred here once your package starts to take shape.
-You can then link to this documentation page from the Wiki.
--->
+\b planning_models is used for describing a kinematic robot model loaded from URDF. Visual geometry is ignored (only collision geometry is considered). This package allows performing forward kinematics for various groups of joints, for potentially multiple robots. The states for different groups of joints can be easily extractes using the planning_models::KinematicModel class. The planning_models::StateParams class allows easy updating of various state values by using the joint names specified in URDF.
+
\section codeapi Code API
-- see the KinematicModel class
-- see the StateParams class
+- see the planning_models::KinematicModel class
+- see the planning_models::StateParams class
-<!--
-Provide links to specific auto-generated API documentation within your
-package that is of particular interest to a reader. Doxygen will
-document pretty much every part of your code, so do your best here to
-point the reader to the actual API.
-If your codebase is fairly large or has different sets of APIs, you
-should use the doxygen 'group' tag to keep these APIs together. For
-example, the roscpp documentation has 'libros' group.
--->
-
-
*/
\ No newline at end of file
Modified: pkg/trunk/util/geometric_shapes/mainpage.dox
===================================================================
--- pkg/trunk/util/geometric_shapes/mainpage.dox 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/util/geometric_shapes/mainpage.dox 2009-07-01 05:55:45 UTC (rev 18086)
@@ -2,6 +2,8 @@
\mainpage
\htmlinclude manifest.html
+@section summary Summary
+
\b geometric_shapes is a package containing the definition of simple shapes such as spheres, boxes, cylinders and meshes. These shapes can be converted into bodies and routines like tests for point inclusion or volume computation are also available.
<!--
Modified: pkg/trunk/world_models/collision_space/mainpage.dox
===================================================================
--- pkg/trunk/world_models/collision_space/mainpage.dox 2009-07-01 05:44:40 UTC (rev 18085)
+++ pkg/trunk/world_models/collision_space/mainpage.dox 2009-07-01 05:55:45 UTC (rev 18086)
@@ -2,27 +2,16 @@
\mainpage
\htmlinclude manifest.html
-\b collision_space is used to represent collisions between a given robot model and the environment. Self collision checking is performed and contact positions and normals can be computed.
+@section summary Summary
-<!--
-In addition to providing an overview of your package,
-this is the section where the specification and design/architecture
-should be detailed. While the original specification may be done on the
-wiki, it should be transferred here once your package starts to take shape.
-You can then link to this documentation page from the Wiki.
--->
+\b collision_space is used to represent collisions between a given
+robot model (as in <a href="../../planning_models/html">planning_models</a>) and the
+environment. Self collision checking is performed and contact
+positions and normals can be computed.
-<!--
-Provide links to specific auto-generated API documentation within your
-package that is of particular interest to a reader. Doxygen will
-document pretty much every part of your code, so do your best here to
-point the reader to the actual API.
+An abstract interface (collision_space::EnvironmentModel) is provided
+to a set of collision checking libraries.
-If your codebase is fairly large or has different sets of APIs, you
-should use the doxygen 'group' tag to keep these APIs together. For
-example, the roscpp documentation has 'libros' group.
--->
-
*/
\ No newline at end of file
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
