REACH

Robotic Evaluation And Comparison Heuristic

![Robot Reach Study][1]

![Reach Study Demo][2]

![Reach Study Heat Map][3]

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:

![Reach Study Flow Diagram][4]

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

File truncated at 100 lines see the full file

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

File truncated at 100 lines see the full file