REACH

Robotic Evaluation And Comparison Heuristic

Table of Contents

• Description
• Installation
• ROS Integration
• Tips

Description

The REACH repository is a tool that allows users to visualize and quantitatively evaluate the reach capability of a robot system for a given workpiece. See the ROSCon 2019 presentation and video for a more detailed explanation of the reach study concept and approach.

Supported OS Distros

| OS | Support | | :— | :—: | | Ubuntu Focal | ✓ | | Ubuntu Jammy | ✓ |

Structure

reach is a ROS-independent package that provides the framework for the reach study process, defined in the diagram below:

The reach package also provides the interface definition for the required reach study functions:

1. TargetPoseGenerator
   • Generates Cartesian target poses that the robot should attempt to reach during the reach study
   • These target poses are expected to be relative to the kinematic base frame of the robot
   • The z-axis of the target poses is expected to oppose the z-axis of the robot kinematic tip frame
2. IKSolver
   • Calculates the inverse kinematics solution for the robot at an input 6 degree-of-freedom Cartesian target
3. Evaluator
   • Calculates a numerical “fitness” score of an IK solution (i.e., robot joint pose) at a given Cartesian target pose
   • Higher values indicate better reachability
   • Example numerical measures of reachability include manipulability, distance from closest collision, etc.
4. Display
   • Visualizes the robot/reach study environment, target Cartesian poses, IK solutions, and reach study results
5. Logger
   • Logs messages about the status and progress of the reach study

Plugins

The interfaces described above are exposed as plugins using the boost_plugin_loader library to support custom implementations.

Several default and dummy plugins have been created in the reach package. Many other ROS-based plugins have been implemented in the reach_ros and reach_ros2 packages. All of the plugins built in this project are discovered automatically by the plugin loader without additional manual steps.

The plugin loader class finds plugin libraries using two environment variables:

• LD_LIBRARY_PATH
  • The plugin loader searches for libraries containing plugins within the directories defined in the LD_LIBRARY_PATH environment variable.
  • When using a ROS-based build tool such as catkin or colcon this variable is set automatically to include both system level and workspace level folders by sourcing <devel|install>/setup.bash
• REACH_PLUGINS:
  • The plugin loader then looks for libraries with names defined by the environment variable REACH_PLUGINS within the directories specified by the environment variable LD_LIBRARY_PATH.
  • The names of these libraries should not include a prefix (e.g., lib) or a suffix (e.g., .so) and should be separated by a colon (:).
  • This variable must be set manually to specify plugin libraries not built in this project

If custom libraries created outside this project (for example libmy_custom_reach_plugins.so and libcool_reach_plugins.so) contain REACH plugins, make those plugin libraries visible to the plugin loader by setting the REACH_PLUGINS environment variable as follows:

export REACH_PLUGINS=my_custom_reach_plugins:cool_reach_plugins

Installation

Nominally, the reach package is ROS-independent, but it is convenient to use the ROS dependency management and build tools to build the package.

First, clone the repository into a catkin workspace

cd ~/reach_ws/src
git clone https://github.com/ros-industrial/reach.git
cd ..

Install the dependencies

vcs import src < src/reach/dependencies.repos
rosdep install --from-paths src --ignore-src -r -y

Build the repository

<catkin/colcon> build

ROS Integration

See the reach_ros and reach_ros2 repositories for ROS-based plugins, capability demos, and general usage instructions.

Tips

1. Ensure the object mesh and reach target position scales match and are correct (visualize in rviz). It is common to be off by a factor of 1000.
2. If a set of robot links are allowed to collide with the mesh, add their names to the touch_links field of the MoveItIKSolver plugin in the reach study configuration file.
3. The selection of IK solver is key to the performance of the reach study. Gradient-based solvers (such as KDL and TRAC-IK) are typically good choices.
   • Additional constraints (or lack thereof, such as orientation freedom about the tool z-axis) can also be incorporated into the IK solver (via parameters or source code changes) to produce different reach study results
   • For MoveIt-based plugins, the selection of IK solver is defined in the kinematics.yaml file
4. Reach study results are serialized to file and can be loaded using the API in reach for programmatic analysis or modification
5. You can specify a starting seed for the IK solver by providing a list of joint positions in the config. This be used to help the IK solver to find solutions for complex scenarios. It might also help to guide the solver to solutions that are closer to a certain configuration that you prefere. If no initial seed is provided, a pose with all joints at 0 position is used.

Changelog for package reach_core

1.7.2 (2024-12-05)

• Remove unnecessary signal handlers (#86)
• Contributors: Roman

1.7.1 (2024-11-21)

• Replace deprecated functions (#84)
  • Fixed deprecation of boost::progress_display
  • Fixed deprecation of std::random_shuffle
  • Comment dependency on Open3D until version for 24.04 is released to prevent CI job failures
• Contributors: Michael Ripperger

1.7.0 (2024-09-10)

• Fix CMake error about missing target MPI::MPI_C (#82)
• Registered state map type for Python binding (#80)
• CI Update (#81)
  • Updated CI workflow
  • Moved Python deps to package.xml
• Removed duplicate entry from clang format file (#78)
• Make NoOpEvaluator return 1.0 (#71)
  • Make NoOpEvaluator return 1.0
  • Fix pytest
• Keep plugin factories in scope (#74)
  • Keep plugin factories in scope
  • Run clang-format
• Fix typo (#73) Co-authored-by: Timon Engelke <<timon.engelke@dlr.de>>
• Fixed heat map generation Python bindings to have default values for hue low and high score (#68)
• Contributors: Michael Ripperger, Timon Engelke

1.6.0 (2023-10-04)

• Add seed state checks (#66)
  • Added utility from reach_ros for getting subset of joint state
  • Added check to ensure seed state parameter is set correctly
  • Updated function name
  • Run format jobs on 20.04
  • Clang format
• Contributors: Michael Ripperger

1.5.3 (2023-09-29)

• Updated links in README (#65)
• Update docs (#64)
  • Updated flow chart
  • Push docker image if ref_type is a tag
  • Update AFTER_SCRIPT
• Contributors: Michael Ripperger

1.5.2 (2023-09-07)

• Updated install of python module (#63)
• Contributors: Michael Ripperger

1.5.1 (2023-08-16)

• fix bools in yaml in Python (#59)
• Contributors: Marc Bestmann

1.5.0 (2023-07-28)

• Added ability to specify heat map color range (#58)
• Contributors: Marc Bestmann

1.4.0 (2023-07-13)

• Exposed relevant compile definitions for plugins to the Python interface (#57)
• Contributors: Michael Ripperger

1.3.2 (2023-07-13)

• Updated badges in README; added table of supported distros (#56)
• Removed -dev libraries before running unit tests in CI (#55)
• Updated CI configuration to be ROS-independent (#54)
• Update to later version of RICB that adds hook for PYTHONPATH (#51)
• Added colcon hook for setting the PYTHONPATH environment variable (#50)
• Minor Updates (#48)
  • Added virtual destructors
  • Compile Python bindings with c++14
  • Change comparison operator for clang-tidy
• Contributors: Michael Ripperger

1.3.1 (2023-06-14)

• fix parallelization error of omp parallel (#47)
• Contributors: Marc Bestmann

1.3.0 (2023-06-13)

• Initial IK seed (#46)
  • add option to specify initial IK seed
  • refactor based on PR comments
  • improve reading of seed parameter from yaml
• Contributors: Marc Bestmann

1.2.0 (2023-05-11)

• Exposed plugin implementations for linking by downstream projects (#45)
• Contributors: Michael Ripperger

1.1.0 (2023-05-10)

• Move ROS1 components (#44)
  • Removed reach_ros directory
  • Flattened reach package
  • Updated CI config file
  • Added demo GIF and README
  • Fixed table of contents; added references to ROS repos; removed section on ROS-specific usage and demos
  • Changes to support ROS2
  • Updated dependencies
  • Remove reach_ros from plugins target compile definitions
  • Added colcon package file
• Contributors: Michael Ripperger

1.0.0 (2022-12-06)

• Added Python interface (#38)
• Updated to later version of plugin loader (#39)
• Refactored repository into ROS-independent core package and ROS-based plugin implementation package (#37)
• Contributors: Michael Ripperger, Collin Thornton

0.2.2 (2022-08-24)

• Create nested results directories if they do not exist (#34)
• Contributors: Michael Ripperger

0.2.1 (2022-07-22)

0.2.0 (2022-07-22)

• Various Updates (#29)
  • Change FLANN search tree to PCL kd-tree; update nearest neighbors search; parallelize with hardware concurrency
  • Update to use non-deprecated IK solve function
  • Use Eigen vectorized array product rather than for loop
  • Support manipulability calculation for subset of dimensions
  • Added plugin for evaluating manipulability ratio
  • Simplified and vectorized joint penalty evaluator
  • Updated README
  • Updated unit test
• Incorporated heat map coloring to rviz markers (#30)
  • Incorporated heat map coloring to rviz markers
  • Fixed formatting on heat map rviz marker code

  * Minor updates Co-authored-by: David Spielman <<david.spielman@swri.org>> Co-authored-by: Michael Ripperger <<michael.ripperger@swri.org>>

• Contributors: David Spielman, Michael Ripperger

0.1.1 (2022-07-07)

0.1.0 (2022-07-05)

• Reverted reach_core version before releasing packages
• Fixed bug in reach_core/launch/setup.launch when starting the robot_state_publisher node (#26)
• Add CI, formatting (#25)
  • Added formatting files
  • Run clang formatting
  • Run CMake format
  • Updated to c++14
  • Added CI jobs
• Remove moveit_core dependency (#20)
  • Add moveit_core dependency
  • Remove moveit_core dep and header ref
• Plugin Unit Test (#16)
  • Added unit test to check loading of plugins
  • Updated to rostest
• Update plugin description with new library name (#15)
• Change the fixed frame in rviz (#14)
• Revise Point Cloud Loading Service (#12)
  • Updated service for loading point clouds
  • Revised and renamed server for loading point clouds
  • Updated handling of point cloud loading service
  • Updated launch file
  • Consolidated libraries
• Added install rule for config directory (#11)
• Demo Update (#8)
  • Added robot model to demo
  • Added unit test for demo
  • Updated install rules to install launch files in a 'launch' directory
  • Added joint limits file and reorganized configuration files
  • Added test dependencies to package.xml
• Merge pull request #3 from marip8/feature/demo Reach Study Demo
• Updated start launch file to load YAML files with substitution
• Merge pull request #2 from marip8/fix/launch_file Launch File Update
• Update to startup launch file argument loading
• Merge pull request #1 from marip8/feature/ci Continuous Integration
• Reorganized reach_core headers to allow easier install
• Updated packages CMakeLists
• Merge pull request #10 from mripperger/feature/license License
• Added licenses to files
• Merge pull request #9 from mripperger/update/clean-up Minor clean-up
• Updated Affine to Isometry
• Added missing headers
• Merge pull request #8 from mripperger/feature/plugins Plugin Implementation
• Updated README documentation
• Updated reach_core launch and config files
• Removed loading of kinematic group parameter in reach study node
• Moved multiplicative factory plugin to new directory
• Updated name of display base class in reach study instantiation of plugins
• Updated reach study components to accommodate updates to reach record definition
• Moved reach record generation utility and fixed for updated reach record message definition
• Added new pure virtual method to IK solver base class to return joint names
• Updated reach_core components to use base class defined within the package
• Moved multiplicative evaluation factory plugin into reach_core package
• Build file clean up for reach_core package
• Moved base class headers into reach_core package
• Updated calls to display update robot pose in reach visualizer
• Updated interactive marker callbacks to use bind
• Updated .rviz file
• Removed results directory
• Updated example reach study object configuration file
• Updated build files
• Updated reach study node to load new parameters
• Implemented plugins and changes to other core components in main reach study library
• Updated study parameters structure
• Revised reach visualizer class and removed functionality relocated to plugin class
• Added method to database class for writing to database message
• Added method to general utilties for creating from from point and normal
• Removed kinematic utilities
• Moved code out of IK helper class to be put into IK plugin; changed neighbor IK search to free functions
• Merge pull request #5 from mripperger/feature/seed_states Added support for specifying seed states from which to solve IK
• Added support for specifying seed states from which to solve IK
• Merge pull request #7 from mripperger/update/cleanup Removed deprecated code
• Removed deprecated code
• Merge pull request #6 from mripperger/reorganization Repository reorganization
• Reorganized into metapackage with reach_core and reach_msgs packages; fixes to code to accommodate changes
• Contributors: AndyZe, Collin Thornton, Michael Ripperger, Nathan Brooks, Ripperger, Michael A, mripperger