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 differ slightly.

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\Robotics Library\0.7.0\MSVC\14.1\x64. In this directory, you can find several subdirectories with robot and scenario models as well as 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

bin\rlViewDemo.exe share\rl-0.7.0\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

bin\rlCollisionDemo.exe share\rl-0.7.0\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 model (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

bin\rlPlanDemo.exe share\rl-0.7.0\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

bin\rlCoachKin.exe share\rl-0.7.0\examples\rlsg\unimation-puma560_boxes.xml share\rl-0.7.0\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 myMdlDemo for the example in your home directory. In this directory, create 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(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_definitions(-D_USE_MATH_DEFINES)
find_package(RL COMPONENTS MDL REQUIRED)
add_executable(myMdlDemo myMdlDemo.cpp)
target_link_libraries(myMdlDemo ${RL_LIBRARIES})

This file controls the build process and will be processed by CMake. RL requires the C++11 standard and enabled math constants. find_package looks for the CMake config files included in RL's installation. add_executable creates a new program with corresponding *.cpp source files. target_link_libraries defines which libraries a program is to be linked against.

Add the following contents to the file myMdlDemo.cpp (adjust the path to the model accordingly) 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;
	std::shared_ptr<rl::mdl::Model> model(factory.create("C:\\Program Files\\Robotics Library\\0.7.0\\MSVC\\14.1\\x64\\share\\rl-0.7.0\\examples\\rlmdl\\unimation-puma560.xml"));
	rl::mdl::Kinematic* kinematics = dynamic_cast<rl::mdl::Kinematic*>(model.get());
	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 Visual Studio 2017 and open your myMdlDemo directory via File/Open/Folder. Change the build configuration in the toolbar to x64-Release and build the project via CMake/Build All. Set the active program to myMdlDemo.exe via Select Startup Item in the toolbar and run it via Debug/Start (you may have to set a beakpoint to prevent the console window from closing).

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

First, the build files are created. Open a command prompt and navigate to the myMdlDemo folder. Create a folder build inside it and run

cmake -G "Visual Studio 15 2017 Win64" ..

This will process the CMakeLists.txt in the parent directory and generate the Visual Studio solution. You may then compile one of the available configurations (Debug, MinSizeRel, Release, RelWithDebInfo). Please note that the Windows installer only ships with 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. For this, you will need to install the Qt development files as explained in the installation tutorial for Window. Make sure to add Qt's bin directory to the PATH environment variable and to also set the CMAKE_PREFIX_PATH environment variable to the install prefix of Qt.

Create a directory myViewDemo for the example in your home directory. In this directory, create 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(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_definitions(-D_USE_MATH_DEFINES)
find_package(Qt5 COMPONENTS Core Gui OpenGL Widgets REQUIRED)
find_package(RL COMPONENTS SG REQUIRED)
find_package(SoQt REQUIRED)
add_executable(myViewDemo myViewDemo.cpp)
target_link_libraries(
	myViewDemo
	${Qt5Core_LIBRARIES}
	${Qt5Gui_LIBRARIES}
	${Qt5OpenGL_LIBRARIES}
	${Qt5Widgets_LIBRARIES}
	${RL_LIBRARIES}
	${SoQt_LIBRARIES}
)

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\\Robotics Library\\0.7.0\\MSVC\\14.1\\x64\\share\\rl-0.7.0\\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 myViewDemo folder. Create a folder build inside it and run

cmake -G "Visual Studio 15 2017 Win64" ..
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.