Robotics Library

First Steps with RL on Windows

The following tutorial assumes the Windows build of the Robotics Library has been set up. Even though the Robotics Library API is identical for Linux, the command line and the build process behave differently, and therefore the steps in the tutorials will vary.

One of the demo programs included in the installation that can be used to solve path planning queries in an example scenario with a typical industrial robot manipulator.

Prerequisites

Follow the Windows Installation. If Windows is not installed, we recommend setting up a virtual machine for trying out RL and following these tutorials.

Pre-installed examples and robot model files

Open a terminal and navigate to C:\Program Files (x86)\rl-0.6.2. In this directory, you find several directories with robot and scenario models as well as the Doxygen documentation and a few example programs. You can find all the example models in the source tree in the folder examples.

rlViewDemo

Our first example program is rlViewDemo. You may for instance run

"%RL_DIR%\bin\rlViewDemo.exe" "%RL_DIR%\share\rl\examples\rlsg\unimation-puma560_boxes.xml"

rlViewDemo is a very simple program that opens a static graphical scene and shows it using the SoQt Examiner Viewer. The scene is defined by rlsg\unimation-puma560_boxes.xml, which follows the RL scene graph format. It only adds names (links 0 to 10) to the 11 rigid bodies of the robot and to the two models, the robot and the environment. The actual scene with its triangles and colors is defined by VRML files, which are linked by the XML file.

Optional: Edit rlsg\unimation-puma560_boxes.wrl and comment out the environment model with # signs at the start of the corresponding lines, then run rlViewDemo again. Undo the changes.

rlCollisionDemo

rlCollisionDemo is a very simple program that allows you to translate a model in the environment and check for collisions.

Run

"%RL_DIR%\bin\rlCollisionDemo.exe" "%RL_DIR%\share\rl\examples\rlsg\scene.xml"

This will a simple scene, but the second model--the environment--will be selected for collision checking. The "robot" is only treated as a graphical models (as given in rlsg\scene.wrl), for now, its kinematics are unknown. You can translate the first model. When it intersects the model of the environment, the window will turn red.

rlPlanDemo

Finally, we consider the kinematics of a robot and run rlPlanDemo. The rlkin directory contains the Denavit-Hartenberg parameters of several robots. For robot path planning, both the kinematics, as well as the scene graph with collision objects are needed.

Run

"%RL_DIR%\bin\rlPlanDemo.exe" "%RL_DIR%\share\rl\examples\rlplan\unimation-puma560_boxes_rrtConCon.xml"

Hit F4 to choose a random pose, and Ctrl+F2 to set it as an end position. Then, hit space to find a collision-free path, which will be visualized.

This example uses a RL planning XML file rlplan\unimation-puma560_boxes_rrtConCon.xml, which in turn includes the kinematics in rlkin\unimation-puma560.xml and the scene graph in rlsg\unimation-puma560.convex\unimation-puma560.convex.xml.

Optional: You may edit rlkin\unimation-puma560.xml and set much smaller min/max angle ranges for several joints. Then, path planning will become more difficult or even impossible for many poses. Undo all changes.

rlCoachKin & rlCoachMdl

RL installation also includes two very simple "virtual robot" visualization socket server programs. rlCoachKin is for Denavit-Hartenberg kinematic chains (as defined in rlkin\*.xml files), rlCoachMdl is the equivalent tool for arbitrary geometric chains (allowing branches).

Run the program by specifying a scene file and a corresponding kinematics description

"%RL_DIR%\bin\rlCoachKin.exe" "%RL_DIR%\share\rl\examples\rlsg\unimation-puma560_boxes.xml" "%RL_DIR%\share\rl\examples\rlkin\unimation-puma560.xml"

The socket server now displays the robot in the scene and listens for commands at port 11235. The usual way how to test a simple robot control program is to use this visualization server, connecting through the RL class rl::hal::Coach.

Now, in a second terminal, establish a socket connection to the visualization server

telnet localhost 11235

Usually, the coach visualization servers will only be used behind a transparent interface rl::hal::JointPositionActuator, and you do not need to write any socket commands yourself. Setting joint angles is rather straightforward however: enter 2 followed by the ID of the scene model (in this case 0) and 6 values for the joint angles in radians.

2 0 1.57 0.31 0 0 1.57 0

Writing your first applications

Forward kinematics calculation for a robot manipulator

In the following steps, we develop a very simple kinematics application using the Robotics Library.

Create a directory for the example in your home directory. In this directory, create a folder build and two files, a CMakeLists.txt and a myMdlDemo.cpp file.

Add the following content to your CMakeLists.txt file.

cmake_minimum_required(VERSION 2.8.11)
project(myMdlDemo)
set(RL_DIR "C:/Program Files (x86)/rl-0.6.2/lib/rl")
find_package(RL COMPONENTS MDL REQUIRED)
if(CMAKE_SIZEOF_VOID_P EQUAL 4)
	add_definitions(-DEIGEN_DONT_ALIGN)
endif(CMAKE_SIZEOF_VOID_P EQUAL 4)
add_executable(
	myMdlDemo
	myMdlDemo.cpp
)
target_link_libraries(
	myMdlDemo
	${RL_LIBRARIES}
)

This file controls the build process and will be processed by CMake. find_package calls a known script, this is especially useful for libraries at non-standard locations with additional binary tools. add_executable creates a new program, following the *.cpp files to be compiled for that program. target_link_libraries defines which libraries a program is to be linked against.

Add the following contents to the file myMdlDemo.cpp and save both files.

#include <iostream>
#include <rl/math/Transform.h>
#include <rl/math/Unit.h>
#include <rl/mdl/Kinematic.h>
#include <rl/mdl/Model.h>
#include <rl/mdl/XmlFactory.h>

int
main(int argc, char** argv)
{	
	rl::mdl::XmlFactory factory;
	rl::mdl::Kinematic* kinematics = dynamic_cast< rl::mdl::Kinematic* >(factory.create("C:\\Program Files (x86)\\rl-0.6.2\\share\\rl\\examples\\rlmdl\\unimation-puma560.xml"));
	rl::math::Vector q(6);
	q << 10, 10, -20, 30, 50, -10;
	q *= rl::math::DEG2RAD;
	kinematics->setPosition(q);
	kinematics->forwardPosition();
	rl::math::Transform t = kinematics->getOperationalPosition(0);
	rl::math::Vector3 position = t.translation();
	rl::math::Vector3 orientation = t.rotation().eulerAngles(2, 1, 0).reverse();
	std::cout << "Joint configuration in degrees: " << q.transpose() * rl::math::RAD2DEG << std::endl;
	std::cout << "End-effector position: [m] " << position.transpose() << " orientation [deg] " << orientation.transpose() * rl::math::RAD2DEG << std::endl;
	return 0;
}

Run "CMake (cmake-gui)" from the start menu. Choose your source directory and a previously created build directory (different from the source directory). Press "Configure" (with "Visual Studio 10" as a generator) and "Generate". Run "Microsoft Visual Studio 2010" and open the generated project file myMdlDemo.sln in your build directory.

In the solution explorer, set "myMdlDemo" as a startup project (right-click on the myMdlDemo project). Select build type "RelWithDebInfo" and start the build process by pressing "F5". The console should output a position and orientation. This verifies that the Robotics Library is properly installed.

Optional: You can configure the project and build the application from the command line with the following steps instead.

For multi core compilation support (e.g., quad core) set these variables before running the other commands

set VCBUILD_DEFAULT_OPTIONS=/M%NUMBER_OF_PROCESSORS%
set CL=/MP

Now, the first makefiles are created. Open a command prompt and navigate to the build folder. Run

cmake -G "Visual Studio 10" ..

This will process the CMakeLists.txt in the parent directory and generate the Visual Studio solution. You then may compile within Visual Studio or compile one of the available configurations (Debug, MinSizeRel, Release, RelWithDebInfo). Please note that the Windows installer only ships with the release binaries, thus we recommend to select RelWithDebInfo.

cmake --build . --config RelWithDebInfo

Run your program with the following command. The console should output a position and orientation. This verifies that the Robotics Library is properly installed.

RelWithDebInfo\myMdlDemo.exe

You have successfully set up your own project to use the kinematics component of the Robotics Library.

Visualization of a robot manipulator

In the following steps, we develop a very simple visualization example using the Robotics Library.

Create a directory for the example in your home directory. In this directory, create a folder build and two files, a CMakeLists.txt and a myViewDemo.cpp file.

Add the following content to your CMakeLists.txt file.

cmake_minimum_required(VERSION 2.8.11)

project(myViewDemo)

set(RL_DIR "C:/Program Files (x86)/rl-0.6.2/lib/rl")
find_package(RL COMPONENTS SG REQUIRED)
find_package(Qt4 REQUIRED)

if(CMAKE_SIZEOF_VOID_P EQUAL 4)
	add_definitions(-DEIGEN_DONT_ALIGN)
endif(CMAKE_SIZEOF_VOID_P EQUAL 4)

add_executable(
	myViewDemo
	myViewDemo.cpp
)
target_compile_definitions(
	myViewDemo
	PUBLIC
	"" ${QT_DEFINITIONS}
	-DSOQT_DLL
)
target_include_directories(
	myViewDemo
	PUBLIC
	${QT_INCLUDES}
	${RL_DIR}/../../include
)
target_link_libraries(
	myViewDemo
	${QT_QTCORE_LIBRARY}
	${QT_QTGUI_LIBRARY}
	${QT_QTOPENGL_LIBRARY}
	${RL_LIBRARIES}
	${RL_DIR}/../../lib/soqt1.lib
)

Add the following contents to the file myViewDemo.cpp and save both files.

#include <iostream>
#include <QWidget>
#include <Inventor/SoDB.h>
#include <Inventor/Qt/SoQt.h>
#include <Inventor/Qt/viewers/SoQtExaminerViewer.h>
#include <rl/sg/so/Scene.h>

int
main(int argc, char** argv)
{
	SoDB::init();

	QWidget* widget = SoQt::init(argc, argv, argv[0]);
	widget->resize(800, 600);

	rl::sg::so::Scene scene;
	scene.load("C:\\Program Files (x86)\\rl-0.6.2\\share\\rl\\examples\\rlsg\\unimation-puma560_boxes.xml");

	SoQtExaminerViewer viewer(widget, NULL, true, SoQtFullViewer::BUILD_POPUP);
	viewer.setSceneGraph(scene.root);
	viewer.setTransparencyType(SoGLRenderAction::SORTED_OBJECT_BLEND);
	viewer.show();

	SoQt::show(widget);
	SoQt::mainLoop();

	return 0;
}

Build the application as explained in the example above or open a command prompt and navigate to the build folder. Run

cmake -G "Visual Studio 10" ..
cmake --build . --config RelWithDebInfo
RelWithDebInfo\myViewDemo.exe

You have successfully set up your own project to use the scene graph component of the Robotics Library.