HAPTIX Simulation World API

Overview

이 튜토리얼에서는 haptix-comm simulation-specific API의 전반적인 내용을 다룬다.

설치 단계는 완료했다고 가정한다.

Documentation

API 문서는 여기를 참고하라.

Conventions and terminology

3차원 좌표 및 회전에 대한 '변환'은 pose라고 한다. world API에서 회전은 쿼터니안으로 설명한다.

문서를 통해 "링크", "조인트"및 "모델"을 참조한다.

"링크"는 전체가 움직이는 강체이다.

"조인트"는 두 개의 링크를 결합시키고 모션을 제한한다. 조인트는 한계를 질 수 있다.

"모델"은 0개 이상의 링크와 조인트로 구성 될 수 있는 객체이다. 이 예제의 대부분의 객체에는 나무 큐브와 크리켓 볼과 같은 하나의 링크와 0개의 조인트로 되어있다. 그러나 로봇 인공 팔은 많은 링크와 관절이있는 모델의 한 예이다.

예를 들어, 일반적인 출입구에는 세 개의 링크가 있다: 고정된 프레임, 문 자체, 그리고 핸들. 프레임과 문을 연결하는 경첩은 문을 회전시킬 수 있는 조인트로 모델링된다. 마찬가지로 문과 손잡이는 손잡이를 돌릴 수있는 조인트로 연결된다. 출입구는 전체적으로 모델로 구성된다.

Example

이 예제에서는, ARAT world에서 물체를 조작하기 위해 world API를 사용하는 방법을 보여준다.

Run the code: MATLAB

HAPTIX MATLAB SDK에는 이 예제에서 사용 된 hxs_example.m 스크립트가 이미 포함되어 있다. 만약 이동시키거나 삭제한 경우 여기에서 다운로드 할 수 있다. 다시 다운로드해야하는 경우 스크립트를 HAPTIX MATLAB SDK가 포함 된 폴더 나 MATLAB 경로에 위치시켜야한다.

예제를 실행하려면 먼저 Gazebo가 실행 중인지 확인한다 (바탕 화면 아이콘을 두 번 클릭하거나 터미널을 사용하면 된다).

MATLAB을 열고 HAPTIX SDK 폴더로 이동한 다음 hxs_example을 명령 프롬프트에 입력한다.

각 예제 API 호출을 통해 스크립트가 실행될 때 Gazebo 창을 보아라.

Run the code: Octave on Linux

Linux에서 haptix-comm 패키지를 설치하면 /usr/lib/x86_64-linux-gnu/haptix-comm에 옥타브 폴더가 설치된다. 이 폴더에는 이 실습에서 사용 된 hxs_example 스크립트가 들어있다. 이동하거나 삭제 한 경우 여기에서 다운로드 할 수 있다.

예제를 실행하려면 먼저 Gazebo가 실행 중인지 확인한다 (바탕 화면 아이콘을 두번 클릭하거나 터미널을 사용하여라).

터미널에서 앞서 언급 한 haptix-comm/octave 폴더로 이동하여 octave hxs_example.m을 입력한다.

각 예제 API 호출을 통해 스크립트가 실행될 때 Gazebo 창을 보아라.

The code explained

hxs_sim_info

현재 카메라 변형과 시뮬레이션에서 모든 모델 목록을 포함하는 시뮬레이션 정보를 검색한다. 이 API 호출은 시뮬레이션의 모든 모델을 반복접근하기에 좋은 시작점이다.

info = hxs_sim_info();

이 예제에서는 결과 정보 구조체를 사용하여 world의 모든 모델을 반복접근하여 모든 모델, 링크 및 조인트의 이름을 표시한다. 이 루프에서는 위치, 속도 및 내/외부 힘/ 토크와 같은 현재 동적 상태에 대한 링크와 접합을 요청 할 수도 있다.

hxs_camera_transform and hxs_set_camera_transform

시뮬레이션 카메라 각도의 위치와 방향을 설정한다.

% Get the user camera pose
tx = hxs_camera_transform();
% Move and rotate the user camera pose
new_tx = tx;
new_tx.pos(3) = new_tx.pos(3) + 1;
% assign equvalent of Euler angles rpy(0, 0, M_PI)
new_tx.orient = [0 1 0 0]';
hxs_set_camera_transform(new_tx);

여기에서는 현재 카매라의 이동과 회전에 대한 변환식을 구조체 tx에 저장하고, 카메라가 이동하는 것을 볼 수 있다.

hxs_model_color and hxs_set_model_color

오브젝트의 색상을 4-tuple (빨강, 녹색, 파랑, 알파)로 가져오고 설정한. 여기서 알파는 오브젝트의 투명도를 나타낸다.알파 값이 0 인 객체는 완전히 투명(보이지 않음)인 반면, 알파 값이 1이면 객체가 완전히 불투명(솔리드)을 의미한다.

% Change the table color.
hxs_set_model_color('table', [1;0;0;1])
pause(1);
% Row vectors work, too
hxs_set_model_color('table', [0,1,0,1])
pause(1);
hxs_set_model_color('table', [0;0;1;1])
% Get the color
color = hxs_model_color('table');

여기에서는 테이블의 색을 빨간색에서 초록색으로, 그리고 파란색으로 설정하였다.

hxs_contacts

한 모델이 다른 모델과 접촉하는 지점을 가져온다.

% Get contact information for the cube after it collides with the table
% Applying a force here induces a collision
hxs_apply_force('wood_cube_5cm', 'link', [0, 0, -1], 0.1);
pause(0.05);
contacts = hxs_contacts('wood_cube_5cm');

이 예제에서는 접촉 구조체를 검색하고 그것을 가로지르는 나무 큐브에 대한 각 접점을 출력한다. 큐브의 "뚜껑"링크와 접촉하는 입방체의 각 모서리에 하나씩, 4의 접점을 볼 수 있다.

hxs_linear_velocity and hxs_set_linear_velocity

모델의 선속도를 가져오고 설정한다. 선속도는 초당 미터 단위로 모델 속도의 (x,y,z)성분을 나타내는 3-vector 이다.

vel = hxs_linear_velocity('wood_cube_5cm');

이런 방식으로 검색한 속도는 모델의 canonical link의 속도로 표현된다. 나무 큐브와 같은 단일 링크 개체의 경우 전체 모델의 속도이다. 그러나 로봇 팔의 경우에는 팔뚝 링크(forearm link)의 속도이며 SDF의 표준 링크로 설정된다.

% Move by setting linear velocity
hxs_set_linear_velocity('wood_cube_5cm', [-0.5; 0; 0]);

이 방법으로 모델의 속도를 설정하면 API가 모델의 각 링크 속도를 설정한다.

hxs_angular_velocity and hxs_set_angular_velocity

모델의 각속도를 가져오고 설정한다. 각속도는 (x,y,z)축에 대한 초당 라디안 단위로 나타내는 3-vector이다.

vel = hxs_angular_velocity('wood_cube_5cm');

이 함수는 모델의 canonical link의 각속도를 반환한다.

% Move by setting angular velocity
hxs_set_angular_velocity('wood_cube_5cm', [0; 0; 100]);

단일 링크 모델의 경우, hxs_set_angular_velocity는 링크의 질량 중심을 기준으로 모델의 각속도를 설정한다.

hxs_apply_force, hxs_apply_torque, and hxs_apply_wrench

hxs_apply_X 함수는 모델, 링크, 벡터 또는 적용되는 힘, 토크, 렌치 등을 나타내는 구조체, 그리고 힘이 적용되는 지속 시간을 사용합니다. 지속 시간이 "0"이면 힘, 토크 또는 렌치의 지속 시간이 길어진다.

hxs_apply_force('wood_cube_5cm', 'link', [-1.0; 0; 0], 0.2);

이 함수는 목재 큐브 모델에서 X의 음의 방향으로 1 Newton의 힘을 0.2 초 동안 적용하는 것이다.

hxs_apply_torque('wood_cube_5cm', 'link', [0; 0; 0.1], 0.1)

이 함수는 목재 큐브 모델에서 0.1 초 동안 Z 축에 대해 0.1 Newton-meter의 토크를 적용하는 것이다.

% Apply force and torque at the same time.
wrench = struct('force', [0; 0; 1], 'torque', [0; 0; 0.1]);
hxs_apply_wrench('wood_cube_5cm', 'link', wrench, 0.1);

이 함수는 힘과 토크가 동시에 있는 렌치를 적용하는 것이다. 렌치는 Z 축 방향으로 1 Newton의 힘 성분과 Z 축에 대해 0.1 Newton-meter의 토크 성분을 가진다.

hxs_model_gravity_mode and hxs_set_model_gravity_mode

모델의 중력 모드를 가져오고 설정한다. 중력 모드가 1이면 모델에 중력이 발생한다(기본적으로, Z의 음의 방향에서 9.81 meters/second^2). 만약 중력 모드가 0이면 모델에 중력이 발생하지 않으며, 외력에 의해 방해받지 않는 한 공기중에 떠있게된다.

% Check gravity mode on wooden cube
gravity_mode = hxs_model_gravity_mode('wood_cube_5cm');
disp(gravity_mode);
% Turn off gravity for cube, then nudge it upward
hxs_set_model_gravity_mode('wood_cube_5cm', 0);
% Row vectors work, too.
hxs_apply_force('wood_cube_5cm', 'link', [0, 0, 0.1], 0.1);
% Let it fly
pause(1);
% Bring it back down
hxs_set_model_gravity_mode('wood_cube_5cm', gravity_mode);

이 예제에서는 현재 중력 모드를 검색한다.이 모드는 기본적으로 1입니다. 그런 다음 중력을 끄고 위로 밀어보낸다. 중력이 큐브에서 작용하면 테이블쪽으로 뒤로 떨어지지만 중력이 꺼졌기때문에 테이블이 떠있게된다.

hxs_model_transform and hxs_set_model_transform

모델의 변형을 가져오고 설정한다. 이것은 canonical link의 현재 변환(일반적으로 단일 링크 모델의 질량 중심)으로 정의된다.

% Get the pose of the cube
tx = hxs_model_transform('wood_cube_5cm');
disp('Cube position:');
disp(tx.pos);
disp('Cube orientation:');
disp(tx.orient);
% Modify and set the pose
tx.pos(2) = tx.pos(2) + 0.25;
% define a 45 deg rotation about yaw (z) axis
tx.orient = [cos(pi/8) 0 0 sin(pi/8)]';
hxs_set_model_transform('wood_cube_5cm', tx);

이 예제에서는 큐브의 변형을 가져온 다음 다른 위치와 방향으로 수정한다.

팔 변환 설정 로봇 팔의 위치와 방향을 설정할 수도 있다.

% Set the position of the arm. Note that if the motion tracking device is
% active and unpaused, this change will be transient.
arm_tx = struct('pos', [1.0, 0, 1.5], 'orient', [1, 0, 0, 0]);
hxs_set_model_transform(hand, arm_tx)

이 명령들은 Optitrack과 같은 모션 추적 기술에 의해 무시될 것이다. 효과를을 적용하려면 모션 추적이 일시 중지되었는지 또는 사용 중지되었는지 확인하여라.

hxs_model_collide_mode and hxs_set_model_collide_mode

모델의 충돌 모드를 가져오고 설정한다. 세 가지 가능한 충돌 모드가 있습니다.

• hxsCOLLIDE: 기본 충돌 모드. 모델이 충돌 모드로 설정된 다른 모델과 충돌한다.
• hxsNOCOLLIDE: 모델이 아무 것도 충돌하지 않는다. 다른 모델이 hxsCOLLIDE로 설정되어 있어도 다른 모델을 통과합니다. 이 모델이 다른 모델을 통과 할 때 hxs_contacts는 접촉를 탐지하지 않는다.
• hxsDETECTIONONLY: hxsNOCOLLIDE와 같이 모델이 다른 모델을 통과하고 접촉력이 무시된다. 그러나 충돌은 여전히 hxs_contacts에 의해 감지된다. 즉, hxsDETECTIONONLY 모델이 다른 모델을 통과하면 hxs_contacts는 해당 타임 스텝의 모델에 대한 접촉 정보를 갖는다 (모델에 hxsNOCOLLIDE가 설정된 경우 제외).

대부분의 응용 프로그램에서는 hxsCOLLIDE 또는 hxsDETECTIONONLY를 권장한다.

% Check collide mode on the cube
collide_mode = hxs_model_collide_mode('wood_cube_5cm');
disp(collide_mode);
% Let it drop through the table
hxs_set_model_collide_mode('wood_cube_5cm', 0);
% Hack: apply a small force to disturb the cube to make it actually fall.
hxs_apply_force('wood_cube_5cm', 'link', [0; 0; 0.1], 0.1);
pause(1);
% Turn collisions back on (won't bring the cube back, of course)
hxs_set_model_collide_mode('wood_cube_5cm', collide_mode);

이 예제에서는 큐브의 충돌 모드를 확인한다. 충돌 모드는 기본 hxsCOLLIDE로 설정된다. 그런 다음 테이블을 통과할 수 있게 hxsNOCOLLIDE`에 해당하는 항목을 0으로 설정한다. 그런 다음 원래 충돌 모드로 다시 설정한다.

hxs_add_model and hxs_remove_model

hxs_add_model은 완전한 SDF 설명을 기반으로 scene에 새 모델을 추가한다. 모델의 새 이름과 초기 위치 및 방향을 지정할 수도 있다.

SDF에서 모델을 작성하는 방법을 알아 보려면 Gazebo 모델 작성 자습서를 참조하거나 모델 편집기 사용 방법을 참고하라.

hxs_remove_model은 world에서 일치하는 이름을 가진 모델을 제거한다. hxs_remove_model`은 존재하지 않는 모델을 제거하려고 시도하면 오류를 반환한다.

% Define a new model.  Here, we're taking the cricket_ball model from:
%  https://bitbucket.org/osrf/gazebo_models/src/default/cricket_ball/model.sdf
% and tweaking it slightly (just changing the color from Red to Green).
sdf = '<sdf version="1.5"> <model name="cricket_ball"> <link name="link"> <pose>0 0 0.0375 0 0 0</pose> <inertial> <mass>0.1467</mass> <inertia> <ixx>8.251875e-05</ixx> <ixy>0</ixy> <ixz>0</ixz> <iyy>8.251875e-05</iyy> <iyz>0</iyz> <izz>8.251875e-05</izz> </inertia> </inertial> <collision name="collision"> <geometry> <sphere> <radius>0.0375</radius> </sphere> </geometry> </collision> <visual name="visual"> <geometry> <sphere> <radius>0.0375</radius> </sphere> </geometry> <material> <script> <uri>file://media/materials/scripts/gazebo.material</uri> <name>Gazebo/Green</name> </script> </material> </visual> </link> </model> </sdf>';
% Add the new model to the world, at the world origin, 5m off the ground, with
% gravity enabled.  Then it will drop onto the table.
hxs_add_model(sdf, 'green_cricket_ball', [0; 0; 5], [0; 0; 0], 1);
pause(2);
% Define and add a constraint
constraint_sdf = '<sdf version="1.5"><joint name="test_constraint" type="revolute"><parent>table::link</parent><child>wood_cube_5cm::link</child><axis><xyz>0 1 0</xyz></axis></joint></sdf>';
% Enable when there's an implementation of hxs_add_constraint in Gazebo.
hxs_add_constraint(constraint_sdf, 'wood_cube_5cm');
pause(2);
% Roll the ball to the right
hxs_apply_torque('green_cricket_ball', 'link', [0; 0.05; 0], 0.1)
pause(2);
% Remove constraint
% Enable when there's an implementation of hxs_remove_constraint in Gazebo.
hxs_remove_constraint('test_constraint', 'wood_cube_5cm'); 
pause(2);
% Remove the model
hxs_remove_model('green_cricket_ball');

이 예제에서는 하드 코드 된 SDF 문자열을 사용하고 새로운 green_cricket_ball 모델을 만든다. 모델은 위치 (0, 0, 5)에 있는 전역 좌표계 프레임에 나타나며, 이는 나무 케이스 위로 떨어지는 것을 의미한다. 우리는 모델이 외부 교란에 반응한다는 것을 보여주기 위해 토크를 적용한 다음 이를 world에서 제거한다.

hxs_set_model_joint_state

하나 이상의 관절이있는 모델의 경우, 이 함수는 모델, 관절 중 하나의 이름, 두 개의 스칼라 값을 사용한다. 그런 다음 스칼라 입력을 기반으로 모델에서 지정된 조인트의 위치와 속도를 설정한다.

% Set the state of a wrist joint.  Note that, because there's a controller
% acting on the wrist, this change will only be transient; the controller will
% restore the wrist back to the current target position.
hxs_set_model_joint_state(hand, hand_joint, 0.5, 0.0);
pause(1);

% Set the position of the arm. Note that if the motion tracking device is
% active and unpaused, this change will be transient.
arm_tx = struct('pos', [1.0, 0, 1.5], 'orient', [1, 0, 0, 0]);
hxs_set_model_transform(hand, arm_tx)

% Move the camera
hxs_set_camera_transform(new_tx);
pause(1);
% Reset the world, which will move the camera back
hxs_reset(1);
pause(1);

이 예제에서는 로봇 팔의 손목 관절 상태를 설정한다. 팔의 모터가 관절을 actively controlling하기 때문에 관절은 원래 위치로 되돌아간다. 손목 관절을 바르게 설정하려면, hx_update를 사용한다 (다른 튜토리얼에서 설명함).

hxs_reset

world를 다시 설정한다. 인수를 "0"으로 설정하여 재설정하면 로봇 팔과 viewpoint는 재설정되지 않는다. reset에 0이 아닌 인수가 전달되면 전 세계의 모든 항목이 원래 위치로 재설정된다.

% Move the camera
hxs_set_camera_transform(new_tx);
pause(1);
% Reset the world, which will move the camera back
hxs_reset(1);