Introduction

This documentation briefly describes how to use the CHAI3D plugin for V-REP.

Overview

The CHAI3D plugin creates an invisible CHAI3D scene (using the chai3d::cWorld class) that runs alongside the main V-REP simulation. The CHAI3D scene can be controlled from V-REP through a set of LUA functions that allow the user to perform the following tasks:

  • connect to haptic devices
  • copy V-REP objects to the CHAI3D scene so that they can be "felt" with the haptic device
  • keep the position and orientation of the CHAI3D objects in sync with their V-REP counterparts while the simulation is running
  • constrain the behavior of the haptic device (e.g. to emulate a 2D force-feedback joystick by constraining the haptic device in a plane)
  • change the characteristics of the haptic device constraints to reflect changes in the simulation (e.g. when driving a mobile robot using the haptic device as a 2D joystick, distance to obstacles can be made to affect the tension in the joystick)

Starting haptic rendering

Haptic devices can be connected to the CHAI3D scene by calling the simExtCHAI3D_start() LUA function.

Haptic objects

All haptic behavior in the CHAI3D scene is generated by Objects. There are 2 different types of objects in the CHAI3D plugin:

  • shape objects, which can be used to render any existing V-REP object in the CHAI3D scene,
  • constraint objects, which can be used to control the haptic device behavior in order to assist the user in a given manipulation task.

Shapes

Any object contained in the V-REP scene can be added to the CHAI3D world by using the simExtCHAI3D_addShape() LUA function. Once an object is added to the CHAI3D scene, it can be "felt" and explored haptically using any haptic device connected to the scene. If the object is moving in the V-REP simulation, it can be kept in sync on the CHAI3D side by using the simExtCHAI3D_updateShape() LUA function.

Constraints

Constraints are Objects of type CONSTRAINT_POINT, CONSTRAINT_SEGMENT or CONSTRAINT_PLANE. The haptic device end-effector can be constrained to a single point (), a segment or a plane by using the simExtCHAI3D_addConstraintPoint(), simExtCHAI3D_addConstraintSegment() and simExtCHAI3D_addConstraintPlane() LUA functions respectively. All constraints are implemented using three properties:

  • a stiffness scaling factor Kp, applied to the maximum stiffness supported by the device (
    MaxStiffness
    ). The stiffness factor describes how the force used to maintain the constraint varies with the distance from the constraint target
    Fp = Kp*MaxStiffness*distance
  • a viscosity scaling factor Kv, applied to the maximum damping supported by the device (
    MaxDamping
    ). The damping factor limits how fast the haptic device will move to meet the constraint
    Fv = Kv*MaxDamping*velocity
  • a maximum force limit Fmax, which limits how much force the Kp component can generate
    F_total = minimum(Fmax, Fp) + Fv

Each constraint parameters can be adjusted by using the simExtCHAI3D_updateConstraint() LUA function.

Interpolation

Stable haptic feedback requires the haptic control loop to run at or above 1 kHz with minimal jitter. This control rate cannot be achieved by V-REP simulation loop. In order to solve this problem, the CHAI3D plugin runs its own, internal high-priority haptic loop. To avoid discontinuities in the force-feedback when updating objects and constraints parameters from V-REP at a lower refresh rate, the CHAI3D plugin linearly interpolates all controllable parameters (position, orientation, stiffness, etc.) internally. The interpolation is automated and uses the last V-REP simulation step as a time base to determine the interpolation rate. While this approach significantly improves the quality of the haptic feedback, please keep in mind that it does introduce a slight delay in haptic response that may become noticeable if the V-REP refresh rate drops significantly.

callbacks

The following LUA callbacks are available to use in V-REP LUA scripts:

Example LUA Script

This is a sample sequence of LUA calls to setup a haptic scene, add an object (copied from a V-REP object called 'myVREPObject'), and constrain the haptic device movement in a XY plane at origin with haptic guides along the main joystick XY axis:

-- connect to haptic device and start haptic simulation
local deviceIndex = 0
local toolRadius = 0.01
local workspaceRadius = 1.0
if simExtCHAI3D_start(deviceIndex, toolRadius, workspaceRadius) == 1 then
-- add elements of the V-REP world to the haptic scene
myObject = simGetObjectHandle('myVREPObject')
local vertices, indices = simGetShapeMesh(myObject)
local pos = simGetObjectPosition(myObject, -1)
local orient = simGetObjectOrientation(myObject, -1)
myHapticObject = simExtCHAI3D_addShape(vertices, indices, pos, orient, 1000)
-- constrain joystick in a plane
myJoystickPlane = simExtCHAI3D_addConstraintPlane (0, { 0, 0, 0.01 }, { 0, 0, 1 }, 2000, 10, 10)
-- add joystick attractors along X and Y axis to guide user
myJoystickSegmentX = simExtCHAI3D_addConstraintSegment(0, {-0.1, 0, 0.01 }, {0.1, 0, 0.01}, 1000, 2, 1)
myJoystickSegmentY = simExtCHAI3D_addConstraintSegment(0, {0, -0.1, 0.01 }, {0, 0.1, 0.01}, 1000, 2, 1)