V-REP Introduction

V-REP Introduction

On V-REP's homepage the program is described as

  ...the Swiss army knife among robot simulators: you won't find a simulator with more functions, features, or more elaborate APIs.

V-REP's strength comes from several features:

1. V-REP provides a unified framework combining many powerful internal and external libraries that are often useful for robotics simulations. This includes dynamic simulation engines, forward/inverse kinematics tools, collision detection libraries, vision sensor simulations, path planning, GUI development tools, and built-in models of many common robots.
2. V-REP is highly extensible. V-REP developers provide an API that allows one to write custom plugins that add new features. You can embed Lua scripts directly into a simulation scene that, for example, process simulated sensor data, run control algorithms, implement user interfaces, or even send data to a physical robot. They also provide a remote API that allows one to develop standalone applications in many programming languages that are able to pass data in and out of a running V-REP simulation.
3. V-REP is cross-platform, mostly open-source, and provides a free educational license.

The purpose of this page is not to teach you how to use V-REP. Rather it is to describe demonstration scenes that have been developed to support learning from the book Modern Robotics. If you are interested to learn more about V-REP, check out the Useful Resources section below.

Demonstration V-REP Scenes

To run either of the scenes below, the first step will be to download V-REP for your operating system. You should download the latest non-limited EDUCATIONAL version. Next you will have to install V-REP. On Windows, you simply have an EXE that installs V-REP. On a Mac, you first need to unzip the download. The directory that is produced by unzipping the download contains a vrep.app directory that should allow you start V-REP through normal mechanisms, e.g., Finder/Spotlight/Launchpad. On Linux, you will need to extract the compressed tar archive (e.g., using a command like tar xvf V-REP_PRO_EDU_V3_3_2_64_Linux.tar.gz). Then you need to change directories into the V-REP source directory and run the vrep.sh shell script.

Once V-REP is open you will want to run one of the scenes below. To run any of them, you first run V-REP, then you click File->Open scene... and open one of the ttt files that are linked below. Then click either the Play button from the top toolbar or click Simulation->Start simulation and a GUI should pop up. Clicking the Stop button or Simulation->Stop simulation will close the GUI and stop the simulation.

Most of the scenes feature a simulation of a kinematically-controlled, non-respondable robot. Kinematically controlled means that all dynamics (inertias, torques, friction, etc.) of the system are neglected. We specify a configuration of the robot and it is instantaneously "teleported" to the new configuration. Non-respondable means that the links of the robot are not capable of interacting with the world or each other through collisions. In other words, we can put the robot in configurations that result in self-collisions.

The "interactive" scenes allow you to visualize the robot as you change its configuration using sliders. The "CSV" scenes allow animations of a robot based on a trajectory stored in a comma-separated values file, where each line corresponds to a timestep and consists of comma-separated numbers specifying the robot's configuration at that timestep. There are no joint limits in the "CSV" scenes.

Important note regarding csv file format: The example csv files included below for use with the csv scenes assume that periods, not commas, are used as decimal points. So pi is written as 3.14, not as 3,14. If you are using Linux and your region settings are set to a region that uses commas as the decimal separator, one solution, suggested by a Coursera student, is to invoke V-REP using US English settings:

LC_NUMERIC=en_US.UTF-8 ./vrep.sh

Another option, also suggested by a Coursera student, is to open the "System Settings" -> "Language support" -> "Regional Formats" tab. After changing the region to "English (United States)", log out and back in for the change to take effect.

The CSV mobile manipulation scene is a partly dynamically-controlled simulation of a respondable youBot from KUKA.

In each scene, there is a single Lua script called a non-threaded child script. When the scene is first run, there is a function that is called that sets up the GUI and creates variables that are going to be needed later on in the simulation. Then during every step of the simulation the main script, which is part of every V-REP scene, runs an "actuation" function from the child script. This actuation function is responsible for processing all of the changes to the GUI since the last time it was called (buttons clicked, label updates, etc.), and for sending joint commands to the simulated robot. Technically, there is also a "sensing" function in the child script that gets called by the main script, but in each of these scenes, the sensing function is empty. The GUIs are all built with V-REP's Qt-based custom UI framework.

Scene 1: Interactive UR5

This scene helps you visualize a UR5 robot from Universal Robots. The model of the UR5 was created by importing a URDF from the ROS-Industrial ur5_description package. The GUI in this scene features two tabs. One tab lets you drag sliders to modify the joint angles of each joint, and the other tab allows you to specify comma-separated angles for all 6 joints in an editable text box and ask for the SE(3) transformation from the base frame to the end-effector frame. The frames attached to the base and end-effector are persistently displayed (x-axis in red, y-axis in green, z-axis in blue). Note that all angles are specified in radians.

• Download the ttt scene file here.

Scene 2: CSV Animation UR5

This scene animates the motion of the UR5 robot based on a csv file representing the trajectory of the robot. Each row of the csv file represents a timestep and each column of the csv file is the joint angle through time for one of the joints (first column is joint 1, last column is joint 6).

• Download the ttt scene file here.
• Download an example csv file here.

Scene 3: Interactive youBot

This scene helps you visualize a youBot mobile manipulator from KUKA. The KUKA youBot consists of a mecanum-wheel omnidirectional base and a 5R robot arm. Move the mobile base of the robot and the joints of the robot using sliders. All angles are represented in radians.

• Download the ttt scene file here.

Scene 4: CSV Animation youBot

This scene animates the motion of the youBot based on a csv file representing the trajectory of the robot. Each row of the csv file represents a timestep and each column of the csv file is a configuration variable through time. The csv file has either 12 or 13 columns. Columns 1-3 represent the mobile base configuration variables, ordered as (phi, x, y), where phi is the angle of the base and (x, y) is the location of its center. Columns 4-8 represent the five arm joint angles, joint 1 through joint 5. Columns 9-12 represent the wheel angles, where wheel 1 is column 9 and wheel 4 is column 12, and the numbering of the wheels is shown in the figure on the right. Column 13 is optional. If it is present, then 0 means the gripper is open and 1 means the gripper is closed. If there is no column 13, then the gripper is open by default. All angles are specified in radians.

• Download the ttt scene file.
• Download an example csv file.
• Download a .zip file of basic motions of the youBot mobile base. This folder has five basic motions of the youBot mobile base, showing the correct wheel motions associated with some basic motions of mobile base. You can check that your wheeled mobile base kinematics (or odometry) are correct by comparing your wheel motions to the wheel motions in these .csv files.
  • yb1.csv: Constant speed spin in place (wheels on the left side and right side of the robot move at opposite speeds).
  • yb2.csv: Constant speed forward motion (all wheels move at the same speed).
  • yb3.csv: Constant speed sideways motion (wheels on opposite corners move at the same speed).
  • yb4.csv: Constant speed diagonal motion (wheels 2 and 4 move at the same speed while wheels 1 and 3 are stationary).
  • yb5.csv: Constant speed diagonal motion (wheels 1 and 3 move at the same speed while wheels 2 and 4 are stationary).

Scene 5: CSV Motion Planning Kilobot

This scene allows you to visualize motion planning on an undirected graph using graph-search techniques such as A*. To visualize the planned motion, we are using the kilobot robot moving in a planar square environment of dimensions -0.5 <= x <= 0.5 and -0.5 <= y <= 0.5. Obstacles are represented as cylinders, and the graph itself is illustrated as blue nodes with yellow edges. The path that the kilobot actually follows is indicated by green edges, and the goal node is in red. See the image to the right.

This scene does not do motion planning. Instead, it displays the output of your motion planner. It expects you to provide the path to a folder with four files, named nodes.csv, edges.csv, path.csv, and obstacles.csv:

• nodes.csv: If the graph has N nodes, then this file has N rows. Each row is of the form ID,x,y,heuristic-cost-to-go. ID is the unique integer ID number of the node, and these ID numbers should take values 1 through N. x, y are the (x,y) coordinates of the node in the plane. heuristic-cost-to-go is an optimistic approximation of the shortest path from this node to the goal node (e.g., the Euclidean distance to the goal node). This information is useful for A-star search but is not represented in the visualization of the path.

• edges.csv: If the graph has E edges, then this file has E rows. Each row is of the form ID1,ID2,cost. ID1 and ID2 are the node IDs of the nodes connected by the edge. cost is the cost of traversing that edge. This file can be empty if you do not wish to display edges.

• path.csv: This file specifies the solution path in the graph, and it is a single line, of the form ID1,ID2,... The first number is the ID of the first node in the solution path, and the last number is the ID of the last node in the solution path. If there is no solution to the motion planning problem, the path can consist of a single ID number, the ID of the node where the robot starts (and stays).

• obstacles.csv: This file specifies the locations and diameters of the cylindrical obstacles. Each row is x, y, diameter, where (x,y) is the center of the obstacle and diameter is the diameter of the obstacle. This file can be empty if there are no obstacles.

Nothing prevents you from providing files with nodes or edges inside obstacles. The path.csv file is certainly the output of a graph search planner. Inputs to the planner could be the obstacles.csv file and a specification of the positions of the start and goal nodes, or it could be the nodes.csv and edges.csv files and a specification of the start and goal nodes, or it could be other information, depending on your planner. But in any case, this scene requires the four files above for the visualization.

• Download the ttt scene file here.
• Download a zip file of a directory of example csv files here. You will need to extract the folder from this zip file.
• A description of a sampling-based planning assignment using this scene.

Scene 6: CSV Mobile Manipulation youBot

This scene has a youBot mobile manipulator and a cube. The youBot is expected to pick up the cube and put it down at a goal location ("pick and place"). This scene animates a user-specified csv file, of the same form described above, where each row of the csv file has 13 variables: 3 for the chassis configuration, 5 for the arm joint angles, 4 for the wheel angles, and 1 for the gripper state (0 = open, 1 = closed). Unlike the other youBot csv animation scene, however, the whole robot is now respondable, meaning that the links and chassis of the robot are now capable of interacting with the world or each other through collisions. The gripper of the youBot and the cube are dynamically modeled to simulate practical pick-and-place. In other words, if the gripper does not close on the block properly, it may slide away, and if you open the gripper when it is holding a block, the block will fall to the floor.

• Download the ttt scene file here.
• Download an example csv file here.

Scene 7: CSV Animation MTB

This scene simulates a RRPR robot. It animates a csv file containing a trajectory of joint angles. Each column of the csv file is the joint angle/length through time for one of the joints (in the order of RRPR). A single row of the csv file represents a complete configuration of the robot at a particular time. The prismatic joint (P) has the joint limit range [0, 0.2]. The assumed time step between rows is equal to the time step that V-REP uses for simulation; the default is 0.05 seconds.

• Download the ttt scene file here.
• Download an example csv file here.

Switching Between Scenes

Press the Stop button to stop the simulation of the current scene, then choose File>Open scene.... You can also use File>Open recent scene to switch to a scene you previously loaded. Then you press the Play button to run the scene. Alternatively, stop the simulation and then press the Scenes button in the top toolbar to see which scenes are currently open and select one to be in the foreground. The scene selector toolbar button may also be used to switch between opened scenes. Read more here.

Recording a Movie

V-REP comes with a video recorder. Go to Tools>Video recorder. You may need to stop the current scene to be able to configure the video recorder. You can find more information on recording V-REP movies here: http://www.coppeliarobotics.com/helpFiles/en/aviRecorder.htm.

A simpler option may be to just use your computer's screen recording software. On the Mac, you can use Quicktime. On Linux, you can use SimpleScreenRecorder or recordMyDesktop. On Windows, you can use Screen Recorder. Or you may have your own solution.

Exploring Other Scenes

You are encouraged to explore some of the (quite impressive) scenes that come pre-loaded with V-REP. You can find these scenes in the scenes directory under the V-REP directory. Running and studying these can be a great way to learn more about the V-REP capabilities and to understand how to put together more complex scenes.

Useful Resources

• V-REP Overview Presentation
• V-REP Videos Page
• V-REP Tutorial Series
• Overview of V-REP Features
• V-REP API Documentation These are all functions that can either be called directly from a custom C/C++ plugin or through a Lua embedded script.
• Remote API Documentation The Remote API is how V-REP enables scripts and programs written in other languages (MATLAB, Java, Python, etc.) to interact with a V-REP simulation