Bodyファイル リファレンスマニュアル¶
概要¶
Choreonoid標準のBody形式モデルファイル(Bodyファイル)のリファレンスマニュアルです。
モデルファイルの規約¶
モデルファイルひとつにつき、ロボットや環境のモデル1体を記述するようにします。 また、ファイルの拡張子は通常のYAML形式ファイル(".yaml")と区別するため".body" をつけるようにします。
YAML文法¶
YAMLの文法については プログラマーのための YAML 入門 (初級編) などを参照してください。
ノード一覧¶
ノードとしては以下のようなものが定義されており、これらのインスタンスを組み上げていくことにより、モデルを作成します。 実モデル定義部においてこれらのノードのインスタンスを組み合わせて階層構造を作ることで、モデルを作成していきます。
リンク構造、動力学/機構パラメータを定義するノードとして、以下のノードが定義されています。
リンクの形状、表示を定義するノードとして、以下のノードが定義されています。
各種センサ・デバイスを定義するノードとして以下のノードが定義されています。
閉リンク機構を定義するノードとして以下のノードが定義されています。
ノードをグループ化するためのノードとして以下のノードが定義されています。
以下では各ノードの詳細を説明します。
ヘッダ¶
ファイルの先頭に置き、モデルファイルのフォーマットを指定します。
キー | 内容 |
---|---|
format | "ChoreonoidBody"を指定。 |
formatVersion | モデルファイルのフォーマットのバージョンを指定。現在のバージョンは1.0。 |
angleUnit | モデルファイルにおける関節角度の単位を指定する項目。"degree"または"radian"を指定。 |
name | モデルの名前を指定。 |
rootLink | ルートリンク名を指定。 |
リンク構造、動力学/機構パラメータを定義するノード¶
Linkノード¶
キー | 内容 |
---|---|
type | Link |
name | リンクの名称。モデル内で重複しない任意の文字列を指定可能 |
parent | 親リンク。親リンクの名前(nameに記述した文字列)で指定する。ルートリンクの場合は使用しない |
translation | 本リンクローカルフレームの親リンクからの相対位置。ルートリンクの場合はモデル読み込み時のデフォルト位置として使われる |
rotation | 本リンクローカルフレームの親リンクからの相対姿勢。姿勢は回転軸と回転角度に対応する4つの数値で表現 (Axis-Angle形式)。ルートリンクの場合はモデル読み込み時のデフォルト位置として使われる |
jointId | 関節ID値。0以上の整数値を指定する。モデル内で重複しない任意の値を指定可能。リンクが関節でない場合 (ルートリンクやjointTypeがfixedの場合)や、ID値によるアクセスを必要としない場合は、指定しなくてもよい |
jointType | 関節タイプ。 fixed (固定)、 free (非固定。ルートリンクにのみ指定可)、 revolute (回転関節)、 prismatic (直動関節)、 pseudoContinousTrack (簡易無限軌道)、 のどれかを指定 |
jointAxis | 関節軸。3次元ベクトルの3要素のリストとして関節軸の向きを指定する。値は単位ベクトルとする。関節軸がリンクのローカル座標におけるX, Y, Z、及びそれらの逆方向のいずれかに一致する場合は、対応する軸の文字(X, Y, Z,-X,-Y,-Z)によって指定することも可能。 |
jointAngle | 関節の初期角度。degreeで指定。 |
jointDisplacement | 関節の初期角度。radianで指定。 |
jointRange | 関節可動範囲。最小値、最大値の2つの値をリストとして列挙する。値をunlimitedと記述することで、可動範囲の制限を無くすことも可能。最小値と最大値の絶対値が同じでそれぞれ符号がマイナス、プラスとなる場合は 、その絶対値をひとつだけ(スカラ値として)記述してもよい |
maxJointVelocity | 関節の回転・移動速度の範囲をスカラ値(>=0)で指定。この値のマイナス、プラスの範囲に設定される。jointTypeがrevoluteのときは最大角速度(degree/sec)、それ以外のときは最大速度(m/sec) |
jointVelocityRange | 関節の回転・移動速度の範囲。最小値、最大値の2つの値をリストとして列挙する。maxJointVelocityより優先される。 |
rotorInertia | ロータ慣性モーメント。default値=0.0。 |
gearRatio | ギア比。default値=1.0。 等価ロータ慣性モーメントはgearRatio*gearRatio*rotorInertiaで設定される。 |
centerOfMass | 重心位置。リンクローカル座標で指定 |
mass | 質量[kg] |
inertia | 慣性モーメント。慣性テンソルの9要素をリストとして列挙。慣性テンソルの対称性より、上三角部分の6要素のみを列挙してもよい。 |
import | エイリアスをつけたノードをこの場所に読み込む。 import: *defined_alias |
elements | リンクの構成要素となる子ノードを記述 |
注釈
最初に記述するLinkノードはモデルのルートノードとみなされます。
注釈
剛体パラメータ(centerOfMass, mass, inertia)は次に述べるRigidBodyノードで記述することも可能です。その場合elementsを用いてRigidBodyノードをLinkノードの子ノードとして配置します。
RigidBodyノード¶
RigidBodyノードはリンクの剛体パラメータを定義します。
キー | 内容 |
---|---|
type | RigidBody |
centerOfMass | 重心位置。リンクローカル座標で指定 |
mass | 質量[kg] |
inertia | 慣性モーメント。慣性テンソルの9要素をリストとして列挙。慣性テンソルの対称性より、上三角部分の6要素のみを列挙してもよい。 |
elements | 子ノードでリンクの形状やセンサーなどを記述。 |
Transformノード¶
配下のノードを平行移動・回転・拡大縮小します。
キー | 内容 |
---|---|
type | Transform |
translation | 位置のオフセット |
rotation | 姿勢のオフセット |
scale | サイズの拡大・縮小 |
elements | 変換を受ける子ノードを記述。 |
リンク形状・見た目を定義するノード¶
Shapeノード¶
キー | 内容 |
---|---|
type | Shape |
geometry | リンクの形状を 幾何形状ノード のいずれかで記述 |
appearance | リンクの色やテクスチャを Appearanceノード として記述 |
幾何形状ノード¶
幾何形状の記述には、以下のBox、Shpere、Cyinder、Capsule、Cone、Extrusion、ElevationGrid、IndexedFaceSetのいずれかのノードを使用することができます。
Cylinderノード¶
Cylinderノードは円柱を記述する幾何形状ノードです。
キー | 内容 |
---|---|
type | Cylinder |
radius | 半径 |
height | 高さ |
bottom | true:底面あり(default) false:底面なし |
top | true:上面あり(default) false:上面なし |
Coneノード¶
Coneノードは円錐を記述する幾何形状ノードです。
キー | 内容 |
---|---|
type | Cone |
radius | 底面の半径 |
height | 高さ |
bottom | true:底面あり(default) false:底面なし |
Extrusionノード¶
Extrusionノードは押し出し形状を記述する幾何形状ノードです。
キー | 内容 |
---|---|
type | Extrusion |
crossSection | 押し出す断面の形状を頂点の座標で指定(x-z平面)。
crossSection: [ x0, z0, x1, z1, x2, z2, ・・・, xn, zn ]
のようにx座標,z座標を並べる。改行・スペースを入れて良い。
crossSection: [ x0, z0,
x1, z1,
:
|
spine | crossSectionで指定した断面を沿わせて動かす区分的直線を端点の座標で指定。
spine: [ x0, y0, z0, x1, y1, z1, ・・・, xn, yn, zn ]
|
orientation | spineの各点におけるcrossSectionの回転をaxis-angle形式のパラメータ(x, y, z, θ)を並べて指定。 1組のみ指定した場合は全spineで同じ回転が使われる。spineの個数より少ない場合は不足分が回転無しになり、spineの個数より多い場合は無視される。 |
scale | crossSectionで指定した断面のspineの各点における拡大率。x軸方向の拡大率、z軸方向の拡大率をspineの個数分並べて指定。1組のみ指定した場合は全spineで同じ拡大率になる。spineの個数より指定が少ない場合、未指定分は0倍に拡大され1点になる。spineの個数より多く指定された分は無視される。 |
creaseAngle | 光源と法線ベクトルの角度によってシェーディングを変えるための閾値。creaseAngle未満のときはスムーズシェーディングされる。デフォルトは0。 |
beginCap | true:開始端側の断面あり(default) false:開始端側の断面なし |
endCap | true:終端側の断面あり(default) false:終端側の断面なし |
※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#Extrusion
ElevationGridノード¶
ElevationGridノードはグリッドの格子点ごとに高さを与えた地形状の形状を記述する幾何形状ノードです。
キー | 内容 |
---|---|
type | ElevationGrid |
xDimension | x軸方向のグリッドの数 |
zDimension | z軸方向のグリッドの数 |
xSpacing | x軸方向のグリッド間隔 |
zSpacing | z軸方向のグリッド間隔 |
ccw | true: 頂点の順序が反時計回り false: 頂点の順序が時計回り |
creaseAngle | 光源と法線ベクトルの角度によってシェーディングを変えるための閾値。creaseAngle未満のときはスムーズシェーディングされる。デフォルトは0。 |
height | 各格子点上の高さを配列で指定。格子点の個数(xDimension*zDimension)分の要素が必要。 |
※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#ElevationGrid
IndexedFaceSetノード¶
IndexedFaceSetノードは、リストされた頂点から面(ポリゴン)を作成することによって形状を記述する幾何形状ノードです。
キー | 内容 |
---|---|
type | IndexedFaceSet |
coordinate | 頂点の座標を指定。 coordinate: [ x0, y0, z0, x1, y1, z1, ・・・, xn, yn, zn ]
のようにx座標,y座標、z座標を並べる。
|
coordIndex | coordで指定した座標に0からNまでインデックスを付けてポリゴン面を指定。インデックス「-1」は、現在の面が終了したことを示す。
coordIndex: [ 0, 1, 2, 3, -1, 3, 2, 4, 5, -1、 ・・・ ] のようにインデックスを並べる。頂点の順序は反時計回り。
|
texCoord | textureを貼る場合に使用する。テクスチャを頂点にマッピングするための2次元座標を指定。
texCoord: [ s0, t0, s1, t1, ・・・, sm, tm ]
のように、テクスチャの左下を(0.0, 0.0), 右上を(1.0, 1.0)としたときの座標を並べる。
|
texCoordIndex | coordIndexと同様に、各頂点のテクスチャ座標を選択するために使用する。coordIndexフィールドと同じ数のインデックスを含み、同じ位置に面の終了記号である「-1」を含まなければならない。
指定しない場合は、CoordIndexが使用される。
|
creaseAngle | 光源と法線ベクトルの角度によってシェーディングを変えるための閾値。creaseAngle未満のときはスムーズシェーディングされる。デフォルトは0。 |
※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#IndexedFaceSet
Appearanceノード¶
キー | 内容 |
---|---|
material | 物体表面の材質を Materialノード として記述 |
texture | 物体表面のテクスチャを Textureノード として記述 |
textureTransform | テクスチャの平行移動・回転・拡大縮小を TextureTransformノード として記述 |
Materialノード¶
キー | 内容 |
---|---|
ambientIntensity | 環境光の反射率(0.0〜1.0) |
diffuseColor | RGBごとの拡散反射率(物体の色) (RGBそれぞれ0.0〜1.0のリスト) |
emissiveColor | 物体自体から発光する色 (RGBそれぞれ0.0〜1.0のリスト) |
shininess | 輝度 (0.0〜1.0) |
specularColor | 鏡面反射率(光のハイライトの色) (RGBそれぞれ0.0〜1.0のリスト) |
transparency | 透過度(0:透明 〜 1:不透明) |
Textureノード¶
キー | 内容 |
---|---|
url | テクスチャファイルのパス |
repeatS | テクスチャを水平方向に繰り返し表示することを指定 |
repeatT | テクスチャを垂直方向に繰り返し表示することを指定 |
TextureTransformノード¶
キー | 内容 |
---|---|
translation | 位置のオフセット |
rotation | 姿勢のオフセット |
scale | サイズの拡大・縮小 |
center | rotation,scaleの中心点 |
※参照: http://tecfa.unige.ch/guides/vrml/vrml97/spec/part1/nodesRef.html#TextureTransform
Resourceノード¶
リンクの形状にCADやモデリングツールで作成したメッシュを読み込みます。
キー | 内容 |
---|---|
type | Resource |
uri | リンク形状のメッシュファイルのパス |
node | メッシュファイル内の特定のノードのみを読み込む場合にノード名を指定 |
各種センサ・デバイスを定義するノード¶
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軸加速度センサを定義します。
フィールド | 内容 |
---|---|
type | AccelerationSensor |
maxAcceleration | 計測可能な最大加速度。3次元ベクトルの3要素のリストとして指定する。 |
RateGyroSensorノード¶
RateGyroSensorノードは、3軸角速度センサを定義します。
キー | 内容 |
---|---|
type | RateGyroSensor |
maxAngularVelocity | 計測可能な最大角速度。3次元ベクトルの3要素のリストとして指定する。 |
ForceSensorノード¶
ForceSensorノードは、力/トルクセンサを定義します。
キー | 内容 |
---|---|
type | ForceSensor |
maxForce | 計測可能な力の最大値。3次元ベクトルの3要素のリストとして指定する。 |
maxTorque | 計測可能なトルクの最大値。3次元ベクトルの3要素のリストとして指定する。 |
Cameraノード¶
Cameraノードは、視覚センサを定義します。
キー | 内容 |
---|---|
type | Camera |
format | センサから取得する情報の種類を指定する。
・"COLOR" 色情報を取得
・"DEPTH" 深さ情報を取得
・"COLOR_DEPTH" 色情報と深さ情報を取得
・"POINT_CLOUD" 3次元点群を取得
・"COLOR_POINT_CLOUD" 色情報と3次元点群を取得
|
lensType | レンズの種類を指定する。
・"NORMAL" 通常レンズ (デフォルト値)
・"FISHEYE" 魚眼レンズ
・"DUAL_FISHEYE" 全方位カメラ
|
on | true/falseでカメラのON/OFFを指定 |
width | 画像の幅 |
height | 画像の高さ (lensType="FISHEYE","DUAL_FISHEYE"の場合はwidthの値から自動で決定 ) |
fieldOfView | カメラの視野角度 (lensType="DUAL_FISHEYE"の場合は指定不可) |
nearClipDistance | 視点から前クリップ面までの距離 |
farClipDistance | 視点から後クリップ面までの距離 |
frameRate | カメラが毎秒何枚の画像を出力するか |
注釈
視点の姿勢は以下のように定義されます。視線前方向 ・・・ ローカル座標系でZ軸の負の向き 視線上方向 ・・・ ローカル座標系でY軸の正の向き。
注釈
内部的にはformatが"COLOR"のときCamera、"COLOR"以外のときRangeCameraとして扱われます。レンズのタイプ指定はCameraのときのみ有効です。
RangeSensorノード¶
RangeSensorノードは、距離センサを定義します。
キー | 内容 |
---|---|
type | RangeSensor |
on | |
yawRange | 距離をスキャンする水平面角度。0度を中心として、その両側にyawStepの倍数の角度でyawRangeの範囲内の角度が計測される。センサに水平方向のスキャン機能がない場合は0とする。0度から360度の範囲でyawStepの倍数で指定する。 |
yawStep | スキャン中に距離が計測される水平面角度の刻み幅 |
pitchRange | 距離をスキャンする垂直面角度。0度を中心として、その両側にpitchStepの倍数の角度でpitchRangeの範囲内の角度が計測される。センサに垂直方向のスキャン機能がない場合は0とする。0度から170度の範囲でpitchStepの倍数で指定する。 (大きな値を指定すると、処理時間が増え、計測精度が悪くなります。) |
pitchStep | スキャン中に距離が計測される垂直面角度の刻み幅 |
scanRate | 1秒間あたり行うスキャン回数[Hz] |
minDistance | 計測可能な最小距離[m] |
maxDistance | 計測可能な最大距離[m] |
注釈
このセンサが取り付けられているリンクに対するこのセンサの姿勢。センサ座標系において、Z軸マイナス方向が計測正面、スキャンする場合の水平計測面はXZ平面、垂直計測面はYZ平面となります。 これはVisionSensorと同じですので、従来VisionSensorで代用していたモデルを変更する場合は 位置、姿勢はそのまま使えます。 水平、垂直の両方向にスキャンする場合の回転順は、yaw,pitchの順になります。
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要素のリストとして方向を指定。 |
beamWidth | 最大輝度で光の広がる角度。デフォルトは90度。 |
cutOffAngle | 完全に光が遮断される角度。デフォルトは45度。 |
cutOffExponent | 非負の値を指定。デフォルトは1.0。 |
attenuation | 減衰率。非負の3要素のリストを指定。 |
閉リンク機構を定義するノード¶
ExtraJointノード¶
ExtraJointノードは閉リンク機構を定義します。閉リンクの1つの関節がボールジョイントで接続されていると考え、2つのリンクが離れないように拘束力を発生させます。
フィールド | 内容 |
---|---|
link1Name | ボールジョイントを受けているジョイント名 |
link2Name | ボールジョイントが付いているジョイント名 |
link1LocalPos | link1Nameジョイントの拘束位置をそのジョイントのローカル座標で指定 |
link2LocalPos | link2Nameジョイントの拘束位置をそのジョイントのローカル座標で指定 |
jointType | 拘束の種類 ball:1点で固定 piston:jointAxisで指定した軸の向きにのみ動く |
jointAxis | jointTypeがpistonのとき、可動方向をlink1Nameジョイントのローカル座標で指定。 |
閉リンク機構のサンプルとして "share/model/misc/ClosedLinkSample.body" があります。