Bodyファイル リファレンスマニュアル

概要

Choreonoid標準のBody形式モデルファイル（Bodyファイル）のリファレンスマニュアルです。

モデルファイルの規約

モデルファイルひとつにつき、ロボットや環境のモデル１体を記述するようにします。 また、ファイルの拡張子は通常のYAML形式ファイル(".yaml")と区別するため".body" をつけるようにします。

キーの記述形式について

Choreonoidで使用するYAMLファイルにおけるキーの記述形式について、従来「ロワーキャメルケース」を用いていましたが、これを「スネークケース」に順次切り替えています。ただし切り替えは完全ではなく、一部のキーはまだキャメルケースとなっています。このためChoreonoidで使用するYAMLファイルではキャメルケースとスネークケースが混在している場合があります。これはBodyファイルでも同様です。

本マニュアルではスネークケースに移行済みのキーについてはスネークケースで表記しています。従来キャメルケースで定義されていたキーについては、互換性維持のため最新版でも古い形式のキーを読み込めるようにしています。ただしこの措置は今後廃止される可能性もありますので、新たにファイルを作成する際は新しい形式を利用するようにしてください。

YAML文法

YAMLの文法については プログラマーのための YAML 入門 (初級編) などを参照してください。

ノード一覧

ノードとしては以下のようなものが定義されており、これらのインスタンスを組み上げていくことにより、モデルを作成します。 実モデル定義部においてこれらのノードのインスタンスを組み合わせて階層構造を作ることで、モデルを作成していきます。

リンク構造、動力学/機構パラメータを定義するノードとして、以下のノードが定義されています。

リンクの形状、表示を定義するノードとして、以下のノードが定義されています。

各種センサ・デバイスを定義するノードとして以下のノードが定義されています。

閉リンク機構を定義するノードとして以下のノードが定義されています。

ノードをグループ化するためのノードとして以下のノードが定義されています。

以下では各ノードの詳細を説明します。

ヘッダ

ファイルの先頭に置き、モデルファイルのフォーマットを指定します。

ヘッダのフィールド

キー

内容

format

"ChoreonoidBody"を指定。

format_version

モデルファイルのフォーマットのバージョンを指定。現在のバージョンは2.0。

angle_unit

モデルファイルにおける関節角度の単位を指定する項目。"degree"または"radian"を指定。

name

モデルの名前を指定。

root_link

ルートリンク名を指定。

リンク構造、動力学/機構パラメータを定義するノード

RigidBodyノード

RigidBodyノードはリンクの剛体パラメータを定義します。

RigidBodyノードの項目

キー

内容

type

RigidBody

center_of_mass

重心位置。リンクローカル座標で指定

mass

質量[kg]

inertia

慣性モーメント。慣性テンソルの9要素をリストとして列挙。慣性テンソルの対称性より、上三角部分の6要素のみを列挙してもよい。

elements

子ノードでリンクの形状やセンサーなどを記述。

Transformノード

配下のノードを平行移動・回転・拡大縮小します。

Transformノードのフィールド

キー

内容

type

Transform

translation

位置のオフセット

rotation

姿勢のオフセット

scale

サイズの拡大・縮小

elements

変換を受ける子ノードを記述。

リンク形状・見た目を定義するノード

Shapeノード

Shapeノードのフィールド

キー

内容

type

Shape

geometry

リンクの形状を 幾何形状ノード のいずれかで記述

appearance

リンクの色やテクスチャを Appearanceノード として記述

幾何形状ノード

幾何形状の記述には、以下のBox、Shpere、Cyinder、Capsule、Cone、Extrusion、ElevationGrid、IndexedFaceSetのいずれかのノードを使用することができます。

Boxノード

Boxノードは直方体を記述する幾何形状ノードです。

Boxノードのフィールド

キー

内容

type

Boxを指定

size

直方体の縦横奥行きの長さ

Sphereノード

Sphereノードは球を記述する幾何形状ノードです。

Sphereノードのフィールド

キー

内容

type

Sphere

radius

球の半径

Cylinderノード

Cylinderノードは円柱を記述する幾何形状ノードです。

Cylinderノードのフィールド

キー

内容

type

Cylinder

radius

半径

height

高さ

bottom

true:底面あり(default) false:底面なし

top

true:上面あり(default) false:上面なし

Capsuleノード

Capsuleノードはカプセル（円柱＋球２つ）を記述する幾何形状ノードです。

Capsuleノードのフィールド

キー

内容

type

Capsule

radius

半径

height

高さ

Coneノード

Coneノードは円錐を記述する幾何形状ノードです。

Coneノードのフィールド

キー

内容

type

Cone

radius

底面の半径

height

高さ

bottom

true:底面あり(default) false:底面なし

Extrusionノード

Extrusionノードは押し出し形状を記述する幾何形状ノードです。

Extrusionノードのフィールド

キー

内容

type

Extrusion

cross_section
押し出す断面の形状を頂点の座標で指定(x-z平面)。
cross_section: [ x0, z0, x1, z1, x2, z2, ・・・, xn, zn ]
のようにx座標,z座標を並べる。改行・スペースを入れて良い。
cross_section: [ x0, z0,
x1, z1,
：

spine
cross_sectionで指定した断面を沿わせて動かす区分的直線を端点の座標で指定。
spine: [ x0, y0, z0, x1, y1, z1, ・・・, xn, yn, zn ]

orientation

spineの各点におけるcross_sectionの回転をaxis-angle形式のパラメータ(x, y, z, θ)を並べて指定。 1組のみ指定した場合は全spineで同じ回転が使われる。spineの個数より少ない場合は不足分が回転無しになり、spineの個数より多い場合は無視される。

scale

cross_sectionで指定した断面のspineの各点における拡大率。x軸方向の拡大率、z軸方向の拡大率をspineの個数分並べて指定。1組のみ指定した場合は全spineで同じ拡大率になる。spineの個数より指定が少ない場合、未指定分は0倍に拡大され1点になる。spineの個数より多く指定された分は無視される。

crease_angle

光源と法線ベクトルの角度によってシェーディングを変えるための閾値。crease_angle未満のときはスムーズシェーディングされる。デフォルトは0。

begin_cap

true:開始端側の断面あり(default) false:開始端側の断面なし

end_cap

true:終端側の断面あり(default) false:終端側の断面なし

※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#Extrusion

ElevationGridノード

ElevationGridノードはグリッドの格子点ごとに高さを与えた地形状の形状を記述する幾何形状ノードです。

ElevationGridノードのフィールド

キー

内容

type

ElevationGrid

x_dimension

x軸方向のグリッドの数

z_dimension

z軸方向のグリッドの数

x_spacing

x軸方向のグリッド間隔

z_spacing

z軸方向のグリッド間隔

ccw

true: 頂点の順序が反時計回り false: 頂点の順序が時計回り

crease_angle

光源と法線ベクトルの角度によってシェーディングを変えるための閾値。crease_angle未満のときはスムーズシェーディングされる。デフォルトは0。

height

各格子点上の高さを配列で指定。格子点の個数(x_dimension*z_dimension)分の要素が必要。

※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#ElevationGrid

IndexedFaceSetノード

IndexedFaceSetノードは、リストされた頂点から面（ポリゴン）を作成することによって形状を記述する幾何形状ノードです。

IndexedFaceSetノードのフィールド

キー

内容

type

IndexedFaceSet

vertices
頂点の座標を指定。 vertices: [ x0, y0, z0, x1, y1, z1, ・・・, xn, yn, zn ]
のようにx座標,y座標、z座標を並べる。

faces
verticesで指定した座標に0からNまでインデックスを付けてポリゴン面を指定。インデックス「-1」は、現在の面が終了したことを示す。
faces: [ 0, 1, 2, 3, -1, 3, 2, 4, 5, -1、 ・・・ ] のようにインデックスを並べる。頂点の順序は反時計回り。

tex_coords
textureを貼る場合に使用する。テクスチャを頂点にマッピングするための2次元座標を指定。
tex_coords: [ s0, t0, s1, t1, ・・・, sm, tm ]
のように、テクスチャの左下を(0.0, 0.0), 右上を(1.0, 1.0)としたときの座標を並べる。

tex_coord_indices
facesと同様に、各頂点のテクスチャ座標を選択するために使用する。facesフィールドと同じ数のインデックスを含み、同じ位置に面の終了記号である「-1」を含まなければならない。
指定しない場合は、facesが使用される。

crease_angle

光源と法線ベクトルの角度によってシェーディングを変えるための閾値。crease_angle未満のときはスムーズシェーディングされる。デフォルトは0。

※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#IndexedFaceSet

Appearanceノード

Appearanceノードのフィールド

キー

内容

material

物体表面の材質を Materialノード として記述

texture

物体表面のテクスチャを Textureノード として記述

texture_transform

テクスチャの平行移動・回転・拡大縮小を TextureTransformノード として記述

Materialノード

materialノードのフィールド

キー

内容

ambient

環境光の反射率(0.0〜1.0)

diffuse

RGBごとの拡散反射率(物体の色) (RGBそれぞれ0.0〜1.0のリスト)

emissive

物体自体から発光する色 (RGBそれぞれ0.0〜1.0のリスト)

shininess

輝度 (0.0〜1.0)

specular

鏡面反射率(光のハイライトの色) (RGBそれぞれ0.0〜1.0のリスト)

transparency

透過度(0:透明 〜 1:不透明)

Textureノード

textureノードのフィールド

キー

内容

url

テクスチャファイルのパス

repeat_s

テクスチャを水平方向に繰り返し表示することを指定

repeat_t

テクスチャを垂直方向に繰り返し表示することを指定

TextureTransformノード

textureTransformノードのフィールド

キー

内容

translation

位置のオフセット

rotation

姿勢のオフセット

scale

サイズの拡大・縮小

center

rotation,scaleの中心点

※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#TextureTransform

Resourceノード

リンクの形状にCADやモデリングツールで作成したメッシュを読み込みます。

Resourceノードのフィールド

キー

内容

type

Resource

uri

リンク形状のメッシュファイルのパス

node

メッシュファイル内の特定のノードのみを読み込む場合にノード名を指定

各種センサ・デバイスを定義するノード

Deviceノード

各種デバイスで共通の設定項目を示します。

Deviceノードの共通フィールド

キー

内容

name

デバイスの名前

id

デバイスのID

translation

ローカル座標系の位置を、親ノード座標系からのオフセット値で指定。

rotation

ローカル座標系の姿勢を、親ノード座標系からのオフセット値で指定([x, y, z, θ] ベクトル[x, y, z]の周りにθ回転)。

注釈

各種センサノードはそのセンサが取り付けられているLinkノードの下に取り付けます。 例えば、サンプルモデルの腰部(WAIST)に加速度センサを取り付けている場合は、次のように記述します。

links:
  -
    name: WAIST
    elements:
      -
        type: AccelerationSensor
        id: 0

AccelerationSensorノード

AccelerationSensorノードは、3軸加速度センサを定義します。

AccelerationSensorノードのフィールド

フィールド

内容

type

AccelerationSensor

max_acceleration

計測可能な最大加速度。3次元ベクトルの3要素のリストとして指定する。

RateGyroSensorノード

RateGyroSensorノードは、3軸角速度センサを定義します。

RateGyroSensorノードのフィールド

キー

内容

type

RateGyroSensor

max_angular_velocity

計測可能な最大角速度。3次元ベクトルの3要素のリストとして指定する。

Imuノード

Imuノードは、3軸加速度センサと3軸角速度センサを一体化したIMU（慣性計測ユニット）を定義します。

Imuノードのフィールド

キー

内容

type

Imu

max_acceleration

計測可能な最大加速度。3次元ベクトルの3要素のリストとして指定する。

max_angular_velocity

計測可能な最大角速度。3次元ベクトルの3要素のリストとして指定する。

ForceSensorノード

ForceSensorノードは、力／トルクセンサを定義します。

ForceSensorノードのフィールド

キー

内容

type

ForceSensor

max_force

計測可能な力の最大値。3次元ベクトルの3要素のリストとして指定する。

max_torque

計測可能なトルクの最大値。3次元ベクトルの3要素のリストとして指定する。

Cameraノード

Cameraノードは、視覚センサを定義します。

Cameraノードのフィールド

キー

内容

type

Camera

format
センサから取得する情報の種類を指定する。
・"COLOR" 色情報を取得
・"DEPTH" 深さ情報を取得
・"COLOR_DEPTH" 色情報と深さ情報を取得
・"POINT_CLOUD" 3次元点群を取得
・"COLOR_POINT_CLOUD" 色情報と3次元点群を取得

lens_type
レンズの種類を指定する。
・"NORMAL" 通常レンズ　(デフォルト値）
・"FISHEYE" 魚眼レンズ
・"DUAL_FISHEYE" 全方位カメラ

on

true/falseでカメラのON/OFFを指定

width

画像の幅

height

画像の高さ　(lens_type="FISHEYE","DUAL_FISHEYE"の場合はwidthの値から自動で決定 )

field_of_view

カメラの視野角度　(lensType="DUAL_FISHEYE"の場合は指定不可)

near_clip_distance

視点から前クリップ面までの距離

far_clip_distance

視点から後クリップ面までの距離

frame_rate

カメラが毎秒何枚の画像を出力するか

注釈

視点の姿勢は以下のように定義されます。視線前方向 ・・・ ローカル座標系でZ軸の負の向き 視線上方向 ・・・ ローカル座標系でY軸の正の向き。

注釈

内部的にはformatが"COLOR"のときCamera、"COLOR"以外のときRangeCameraとして扱われます。レンズのタイプ指定はCameraのときのみ有効です。

RangeSensorノード

RangeSensorノードは、距離センサを定義します。

RangeSensorノードのフィールド

キー

内容

type

RangeSensor

on

yaw_range

距離をスキャンする水平面角度。0度を中心として、その両側にyaw_stepの倍数の角度でyaw_rangeの範囲内の角度が計測される。センサに水平方向のスキャン機能がない場合は0とする。0度から360度の範囲でyaw_stepの倍数で指定する。

yaw_step

スキャン中に距離が計測される水平面角度の刻み幅

pitch_range

距離をスキャンする垂直面角度。0度を中心として、その両側にpitch_stepの倍数の角度でpitch_rangeの範囲内の角度が計測される。センサに垂直方向のスキャン機能がない場合は0とする。0度から170度の範囲でpitch_stepの倍数で指定する。 （大きな値を指定すると、処理時間が増え、計測精度が悪くなります。）

pitch_step

スキャン中に距離が計測される垂直面角度の刻み幅

scan_rate

１秒間あたり行うスキャン回数[Hz]

min_distance

計測可能な最小距離[m]

max_distance

計測可能な最大距離[m]

注釈

このセンサが取り付けられているリンクに対するこのセンサの姿勢。センサ座標系において、Z軸マイナス方向が計測正面、スキャンする場合の水平計測面はXZ平面、垂直計測面はYZ平面となります。 これはVisionSensorと同じですので、従来VisionSensorで代用していたモデルを変更する場合は 位置、姿勢はそのまま使えます。 水平、垂直の両方向にスキャンする場合の回転順は、yaw,pitchの順になります。

SpotLightノード

SpotLightノードは、ライトを定義します。

SpotLightノードのフィールド

キー

内容

type

SpotLight

on

true/falseでライトのON/OFFを指定します。

color

ライトの色(R,G,Bそれぞれの値を0.0〜1.0で指定)

intensity

明るさを0.0〜1.0で指定。

direction

光の向き。3次元ベクトルの3要素のリストとして方向を指定。

beam_width

最大輝度で光の広がる角度。デフォルトは90度。

cut_off_angle

完全に光が遮断される角度。デフォルトは45度。

cut_off_exponent

非負の値を指定。デフォルトは1.0。

attenuation

減衰率。非負の3要素のリストを指定。

閉リンク機構を定義するノード

ExtraJointノード

ExtraJointノードはボディに追加の拘束を加えるためのノードです。閉リンク機構を定義します。閉リンクの1つの関節がボールジョイントで接続されていると考え、2つのリンクが離れないように拘束力を発生させます。

注釈

本ノードが実現する拘束の種類は現状では非常に限定されたものとなっています。さらに、対応する拘束の種類はシミュレータアイテム（物理エンジン）のタイプにもよります。

ExtraJointノードのフィールド

フィールド

内容

link1_name

ボールジョイントを受けているジョイント名

link2_name

ボールジョイントが付いているジョイント名

link1_local_pos

link1_nameジョイントの拘束位置をそのジョイントのローカル座標で指定

link2_local_pos

link2_nameジョイントの拘束位置をそのジョイントのローカル座標で指定

joint_type

拘束の種類 ball：1点で固定 hinge：回転関節 piston：並進（軸回りの回転は拘束されない）

axis

joint_typeがhingeまたはpistonのとき、拘束の軸をlink1_nameリンクのローカル座標で指定。

このノードはBodyファイルのトップレベルに "extra_joints" というキーのリストとして記述します。 閉リンク機構のサンプルとして "share/model/misc/ClosedLinkSample.body" があります。

ノードをグループ化するノード

Groupノード

一部のノードをグループ化するために使用します。

Groupノードのフィールド

キー

内容

name

グループの名前

 
(使用例)
elements:
  - &SUBSYSTEM
    type: Group
    name: SUBSYSTEM
    elements:
      -
        (グループの１要素)
      -
        (グループの１要素)
       :

としてグループノードにエイリアスをつけておくと、別の場所にSUBSYSTEMと同じ構成があるとき、

elements: *SUBSYSTEM

で記述できます。