Bodyファイルチュートリアル¶

本ページではChoreonoidの標準モデルファイル形式である「Bodyファイル」の記述方法について、チュートリアル形式で解説を行います。

SimpleTankモデル
モデルの基本構造
モデルファイルの用意
YAMLについて
ヘッダの記述
リンクの記述
Linkノード
車体リンクの記述
編集中のモデルの確認
ルートリンク特有の記述
剛体パラメータの記述
車体形状の記述
アンカーの設定
elementsの記述
砲塔ヨー軸部リンクの記述
エイリアスの利用
リンク相対位置の記述
関節の記述
関節動作の確認
砲塔ピッチ軸部の記述
RigidBodyノード
砲塔ピッチ軸土台部形状の記述
砲身部分の記述
Transformノード
- Transformパラメータ
砲塔ピッチ軸関節の記述
デバイスの記述
- スポットライトの記述
- ライト形状の記述
- カメラの記述
- カメラ位置姿勢の記述
- カメラの形状
クローラの記述
- 左クローラの記述
- 右クローラの記述

SimpleTankモデル ¶

対象とするモデルは以下に示す "SimpleTank" モデルとなります。

これは砲塔・砲身を動かす２軸の回転関節と、移動用の２つのクローラで構成されるモデルで、カメラとライトをデバイスとして搭載しています。

SimpleTankは、クローラ型モバイルロボットの標準サンプルである "Tank" モデルを簡略化したもので、基本的な構造はTankモデルと同じです。Tankモデルについては、

TankJoystick.cnoid
TankVisionSensors.cnoid

といったサンプルプロジェクトがChoreonoid本体に含まれています。

本マニュアルでは、このモデルを題材にシミュレーションを行う方法をまとめた Tankチュートリアルも用意しています。

モデルの基本構造 ¶

SimpleTankモデルは下図に示す5つの部位で構成されています。

ベースとなる部分が車体です。車体の上部には砲塔・砲身が備わります。この部分は砲塔の土台となってヨー軸回転を行う部分と、その上部に砲身とともに取り付けられるピッチ軸回転を行う２つの部分からなります。車体の左右の側面にはそれぞれ移動用のクローラ機構が取り付けられます。

これら5つの部分が「リンク」としてモデリングされます。車体の部分はモデルの中心となる部分であり、これを「ルートリンク」としてモデリングします。ルートリンクは各モデルに対して必ずひとつだけ定義する必要があります。砲塔の2リンクについてはそれぞれ回転関節としてモデリングします。また、クローラ部分は無限軌道の簡易シミュレーションに対応するリンクとしてモデリングします。

これらのリンクの間の階層構造（親子関係）は以下のようになります。

- 車体（ルート）
    + 砲塔ヨー軸部（回転関節）
           + 砲塔ピッチ軸部（回転関節）
    + 左クローラ
    + 右クローラ

なお、本チュートリアルでは各リンクの形状をモデルファイル本体にテキストで記述します。これにより、CADやモデリングツール等で作成した形状データを用いずに、テキストファイルだけでモデリングを完結しています。これに対して、CADやモデリングツール等で作成した形状データを用いることも可能です。これについては外部メッシュファイルの利用方法をご参照ください。

モデルファイルの用意 ¶

Body形式のモデルファイルはテキストファイルとして作成します。ファイルの拡張子は通常 ".body" とします。

モデルファイルの作成を開始するにあたって、まずはテキストエディタを用いて空のテキストを作成し、拡張子 ".body" をつけた適当なファイル名で保存しておきましょう今回は "simpletank.body" というファイル名で保存することにします。このファイルはChoreonoidのshareディレクトリの"model/tank"ディレクトリに完成品が格納されています。今回はそのファイルの内容を解説しながら、完成に至るまでの作成手順の例を示すということになります。

なお、以下の記述をまとめたものは SimpleTankモデルファイル全記述内容で参照することができます。

注釈

Ubuntuの標準テキストエディタ "gedit" を使ってモデルファイルを作成する場合、メインメニューの「表示」-「ハイライト」で表示される設定ダイアログで "YAML" を選択すると、YAMLのフォーマットに適した色付けがされ、編集しやすくなるかと思います。

YAMLについて ¶

Bodyファイルは記述方式のベースとしてYAMLを採用しています。YAMLの実際の記述方法は以下の解説を読めば概ね理解できると思いますが、より詳細な情報については YAMLの仕様書や各種解説記事を参照してください。

解説記事については、以下が分かりやすくて良いかと思います。

プログラマーのためのYAML入門（初級編）

ヘッダの記述 ¶

まずモデルファイルのヘッダとして、YAMLのマッピングを用いて以下のように記述します。

format: ChoreonoidBody
formatVersion: 1.0
angleUnit: degree
name: SimpleTank

最初の行の記述により、このファイルがChoreonoidのモデルファイルとして認識されるようになります。formatVersionは現在のところ1.0となります。今後仕様に変更があった場合に、新しい仕様と区別するためにバージョン番号を明示しておきます。

モデルファイルにおける関節角度の単位を指定する項目として、"angleUnit" があります。今回は "degree" を指定しているので、角度を度数法で記述します。ラジアンで記述したい場合は、ここに "radian" を指定します。通常は degree の方が記述がしやすいのではないかと思います。

モデルの名前は "name" に記述します。ここでは "SimpleTank" という名前にしています。

リンクの記述 ¶

モデルが有するリンクの情報は、"links:" に以下のように記述します。

links:
  -
    リンク1（ルートリンク）の記述
  -
    リンク2の記述
  -
    リンク3の記述
  ...

このようにYAMLのリストとして任意個のリンクを記述することができます。各リンクの記述部分を「Linkノード」と呼びます。最初に記述するLinkノードは、モデルのルートリンクとみなされます。

Linkノード ¶

LinkノードはYAMLのマッピング形式で記述します。マッピングの要素として、以下のようなパラメータが利用可能です。

キー	内容
name	リンク名
parent	親リンク。親リンクの名前（nameに記述した文字列）で指定する。ルートリンクの場合は使用しない
translation	本リンクローカルフレームの親リンクからの相対位置。ルートリンクの場合はモデル読み込み時のデフォルト位置として使われる
rotation	本リンクローカルフレームの親リンクからの相対姿勢。姿勢は回転軸と回転角度に対応する4つの数値で表現(Axis-Angle形式）。ルートリンクの場合はモデル読み込み時のデフォルト位置として使われる
jointType	関節タイプ。 fixed (固定）、 free (非固定ルートリンク）、 revolute (回転関節）、 prismatic (直動関節）、 pseudoContinousTrack (簡易無限軌道）のどれかを指定
jointAxis	関節軸。3次元ベクトルの3要素のリストとして関節軸の向きを指定する。値は単位ベクトルとする。関節軸がリンクのローカル座標におけるX, Y, Zのいずれかに一致する場合は、対応する軸の文字(X, Y, Zのいずれか）によって指定することも可能。
jointRange	関節可動範囲。最小値、最大値の2つの値をリストとして列挙する。値をunlimitedと記述することで、可動範囲の制限を無くすことも可能。最小値と最大値の絶対値が同じでそれぞれ符号がマイナス、プラスとなる場合は、その絶対値をひとつだけ（スカラ値として）記述してもよい
jointId	関節ID値。0以上の整数値を指定する。モデル内で重複しない任意の値を指定可能。リンクが関節でない場合（ルートリンクやjointTypeがfixedの場合）や、ID値によるアクセスを必要としない場合は、指定しなくてもよい
centerOfMass	重心位置。リンクローカル座標で指定
mass	質量[kg]
inertia	慣性モーメント。慣性テンソルの9要素をリストとして列挙。慣性テンソルの対称性より、上三角部分の6要素のみを列挙してもよい。
elements	リンクの構成要素となる子ノードを記述

車体リンクの記述 ¶

ではまず本モデルの車体部分に対応するルートリンクを記述しましょう。対応するLinkノードをlinks以下に次のように記述してください。

links:
  -
    name: CHASSIS
    translation: [ 0, 0, 0.1 ]
    jointType: free
    centerOfMass: [ 0, 0, 0 ]
    mass: 8.0
    inertia: [
      0.1, 0,   0,
      0,   0.1, 0,
      0,   0,   0.5 ]
    elements:
      Shape:
        geometry:
          type: Box
          size: [ 0.45, 0.3, 0.1 ]
        appearance: &BodyAppearance
          material:
            diffuseColor: [ 0, 0.6, 0 ]
            specularColor: [ 0.2, 0.8, 0.2 ]
            shininess: 0.6

YAMLでは各行のインデントがデータの構造も規定することになりますので、上記の記述でインデントが揃っているところはそのまま揃えて記述するように注意してください。

リンクの定義では、そのリンクを特定するための名前をまず設定します。ここでは、

name: CHASSIS

という記述により、"CHASSIS" という名前に設定しています。

編集中のモデルの確認 ¶

まだルートリンクしか記述していませんが、この時点でもモデルとしては成立しています。そこで、編集中のファイルをChoreonoid上で読み込んで表示させ、正しく記述ができているか確認してみましょう。メインメニューの「ファイル」-「読み込み」-「ボディ」を選択し、表示されるダイアログで対象のファイルを選択します。その際、ダイアログ上で「アイテムツリービューのチェックを入れる」を有効にしておくか、読み込み後にアイテムのチェックボックスをクリックすると、シーンビュー上に以下のように表示されるかと思います。

アイテム読み込み時にエラーが出たり、読み込めてもうまく表示できなかったりした場合は、これまでの記述内容を確認してください。

モデルファイルの修正後にそれを再度読み込む場合、修正前のファイルが既にボディアイテムとして読み込まれているのであれば、アイテムの「再読み込み機能」を用いて簡単に読み込み直すことができます。これは以下のいずれかの操作で行います。

アイテムツリービュー上で対象のアイテムを選択し、"Ctrl + R" キーを押す。
アイテムツリービュー上で対象のアイテムを右クリックすると出てくるメニューで「再読み込み」を選択する。

再読み込みを行うと、更新されたファイルがその場で読み込み直されて、（読み込みエラーがなければ）現在のアイテムがそれに置き換わります。更新したファイルに形状等の変化があれば、シーンビュー上の表示も即座にこれを反映します。この機能を使えば、テキストファイルで直接モデルファイルを編集しながら、比較的効率的にモデルファイルの編集を進めていくことが可能です。この「再読み込み」操作は本チュートリアルを進める上で何度も行うことになりますので、覚えておいてください。

ルートリンク特有の記述 ¶

CHASSISリンクでは、

translation: [ 0, 0, 0.1 ]

という記述により、モデル読み込み時の初期位置を設定しています。（正確に言うとワールド座標系におけるルートリンク原点の位置となります。）

translationは通常親リンクからの相対位置を表すパラメータなのですが、ルートリンクに関しては親リンクがありません。その代わりに、モデル読み込み時におけるワールド座標原点からの相対位置とみなすわけです。なお、初期姿勢についても、rotation を用いることで設定可能です。また、初期位置を気にしないのであれば、これらのパラメータを設定する必要はありません。

ここではZ座標値を 0.1 とすることで、ルートリンクの初期位置をZ軸方向に0.1[m]上げた位置としています。これにより、ルートリンクの原点を車体の中心部にとりつつも、それを読み込んだ場合にクローラの下面がちょうどZ=0の面に一致するようにしています。環境モデルではここを床面にとることが多いため、それに合わせやすいよう上記の設定をしています。

次に、

jointType: free

という記述により、このモデルが空間中を自由に動けるモデルであることを設定しています。

jointTypeは通常親子リンク間を接続する関節のタイプを指定するパラメータですが、ルートリンクの場合は意味が少し異なり、リンクが環境に固定されるか否かを指定します。ここに"fixed"を指定するとリンクが固定されますので、ベース部分が床に固定されているマニピュレータ等に対してはそのように設定してください。一方、今回のモデルのように特定の箇所に固定さない場合は、ここに"free"を指定します。

剛体パラメータの記述 ¶

各リンクは通常剛体としてモデリングされます。この情報を記述する Linkノードとして、centerOfMass, mass, inertia があります。CHASSISリンクではこれらに関して以下のように記述しています。

centerOfMass: [ 0, 0, 0 ]    mass: 8.0    inertia: [      0.1, 0,   0,      0,   0.1, 0,      0,   0,   0.5 ]

centerOfMass には、リンクのローカル座標における重心位置を記述します。CHASSISリンクのローカル座標原点は車体中央部に設定しており、重心もそこにに一致させています。

mass には質量を、inertiaには慣性テンソルの行列要素を指定します。

ここでは慣性テンソルに適当な値を設定していますが、適切な計算やCADツールなどを用いて、妥当な値を設定するようにしてください。

慣性テンソルは対称行列なので、上三角部分の6要素のみを記述してもOKです。この場合、上記の値は

inertia: [      0.1, 0,   0,           0.1, 0,                0.5 ]

と書けます。

なお、剛体のパラメータは"RigidBody"ノードを用いて独立して記述することも可能です。これについては後ほど説明します。

車体形状の記述 ¶

リンクの形状は、Linkノードの "elements" 以下に記述します。CHASSISリンクに関しては以下のように記述されています。

Shape:        geometry:          type: Box          size: [ 0.45, 0.3, 0.1 ]        appearance: &BodyAppearance          material:            diffuseColor: [ 0, 0.6, 0 ]            specularColor: [ 0.2, 0.8, 0.2 ]            shininess: 0.6

この部分は「Shapeノード」となります。先ほどモデルファイルを読み込んだ際にシーンビューに表示された形状は、ここで記述されています。

Shapeノードでは、geometryで幾何形状を記述し、appearanceで表面の見た目を記述します。

今回はgeometryのtypeに"Box"を指定し、箱型（直方体）の幾何形状を表現するBoxノードを記述しています。Boxノードでは size パラメータとして x, y, z軸方向の長さをリストとして記述します。この他にも球(Sphere)、シリンダ(Cylinder)、円柱(Cone)といった形状ノードを利用することが可能です。

appearancについては物体表面の材質を記述するmaterialを記述しています。materialでは以下のパラメータを設定可能です。

キー	内容
ambientIntensity	環境光に対する反射係数のスカラ値を指定します。値の範囲は0.0から1.0となります。デフォルトでは0.2となっています。
diffuseColor	拡散反射係数のRGB値を記述します。RGB値は赤、緑、青のの3成分をリストとして記述したもので、各成分の値の範囲は0.0から1.0となります。
emissiveColor	放射色のRGB値を指定します。デフォルトでは無効（全成分が0）となっています。
specularColor	鏡面反射係数のRGB値を記述します。デフォルトでは無効（全成分が0）となっています。
shininess	光沢度を0.0から1.0のスカラ値で指定します。この値が大きいと鏡面反射によるハイライトがシャープになります。デフォルトでは0.2となっています。
transparency	透明度を指定します。値は0.0から1.0のスカラ値で、0.0で完全に不透明となり、1.0で完全に透明となります。デフォルトでは0.0となっています。

ここではdiffuseColor、specularColor、shininessの3つのパラメータを設定することで、少し金属的な光沢のある緑色の材質を表現しています。

注釈

このような形状の記述については、文法的には多少異なるものの、その構造や形状タイプ、パラメータ等について VRML97 で定義されているもの（ Shape 、 Box 、Sphere 、 Cylinder 、 Cone 、 Appearance 、 Material 等）を踏襲するようにしています。VRML97はOpenHRP形式のモデルファイルでベースとしていた形式なので、それの利用経験がある方でしたら勝手をつかみやすいのではないかと思います。

注釈

冒頭でも述べたように、本チュートリアルでは各リンクの形状について上記のような記述方式を利用してモデルファイル中にテキストとして記述します。これに関して、モデリングツールやCADツール等を用いて別途作成した形状データのファイルを用いることも可能です。そちらについては別のドキュメントで解説します。

アンカーの設定 ¶

上記のコードでは、

appearance: &BodyAppearance

というように、appearanceの直後に "&BodyAppearance" という記述を付与しています。

これはYAMLの「アンカー」という機能に対応するもので、YAMLの特定の箇所に名前をつけ、後ほどその名前で参照するというものです。これにより、同じ記述が繰り返し現れる場合でも、最初の記述にアンカーをつけておけば、それを参照することで残りの記述を省略することが可能となります。なお、アンカーを参照する部分はYAMLでは「エイリアス」と呼ばれます。

ここでappearanceに設定した材質のパラメータについては、同じ内容を砲塔ピッチ軸土台部形状の記述でも適用しますので、そこで再利用できるようにアンカーをつけています。実際の利用方法はエイリアスの利用で述べます。

elementsの記述 ¶

モデルファイルにおいては、ある構成要素の情報をまとめたものを「ノード」と呼びます。その例としてこれまでLinkノードやShapeノードを紹介してきました。

ノードの中には、その子ノードとして下位のノードを含むことが可能なものもあります。これにより、ノードは階層的に記述されます。これを行う一般的な方法として、 elements というキーがあります。

elementsでは、基本的にはYAMLのリスト表現を用いて以下のように子ノードを記述します。

elements:
  -
    type: ノードタイプ名
    key1: value1
    key2: value2
    ...
  -
    type: ノードタイプ名
    key1: value1
    key2: value2
  ...

下位のノードがさらにelementsを含むことが可能な場合、以下のように階層を深くしていくことも可能です。

elements:
  -
    type: ノードタイプ名
    key1: value1
    elements:
      -
        type: ノードタイプ名
        key1: value1
        elements:
          ...

このように、elementsを用いることで、多様なタイプのノードを複数組み合わせた構造を記述することも可能となります。

なお、あるタイプのノードがelements以下にひとつしか含まれない場合は、以下のような簡略化記法も使用可能です。

elements:
  ノードタイプ名:
     key1: value1
     key2: value2
     ...

先のものと大きな違いはありませんが、こちらの方がリスト表現を使わない分少しだけシンプルな記述になっています。

Linkノードではこのelementsを用いることで、形状やセンサといった様々な要素を含むことが可能です。他にelementsが使用可能なノードとしては、TransformやRigidBodyといったノードもあります。

注釈

モデルが複数のリンクを有する場合、リンク間の関係も一般的に階層的なものとなります。これをLinkノードのelementsを用いて記述することも考えられますが、本形式のモデルファイルではそのような記述は行いません。これは、そのような記述を行うと、リンクの階層構造が深くなるに従ってモデルファイル内のテキストの階層も深くなってしまい、テキストとしての確認や編集がしづらくなってしまうからです。リンクの階層構造は、Linkノードの"parent"キーを用いて記述します。

砲塔ヨー軸部リンクの記述 ¶

次は砲塔の土台となるヨー軸部のリンクを記述しましょう。これまでの記述に以下を加えて下さい。

-    name: TURRET_Y    parent: CHASSIS    translation: [ -0.04, 0, 0.1 ]    jointType: revolute    jointAxis: -Z    jointRange: unlimited    maxJointVelocity: 90    jointId: 0    centerOfMass: [ 0, 0, 0.025 ]    mass: 4.0    inertia: [      0.1, 0,   0,      0,   0.1, 0,      0,   0,   0.1 ]    elements:      Shape:        geometry:          type: Box          size: [ 0.2, 0.2, 0.1 ]        appearance: *BodyAppearance

ここまで記述してファイルを保存し、前述の再読み込みを行って下さい。するとシーンビュー上のモデルの表示が以下のようになるかと思います。

車体の上部に新たに追加された部分が、砲塔の土台部分となります。この部分はヨー軸回転をするようになっており、そのための関節も含んでいます。

nameに指定したように、本リンクの名前は "TURRET_Y" としています。これは砲塔(Turret)のYaw軸であることを表しています。また、CHASSISリンクと同様に、centerOfMass, mass, inertia の剛体パラメータも記述しています。

形状についても、CHASSISリンクと同様にBoxタイプのgeometoryを用いています。これの size パラメータを調整することで、砲塔の土台部分として適切なサイズの形状にしています。

エイリアスの利用 ¶

上記の形状記述において、appearanceについてはCHASSISリンクと同じでよいので、車体形状の記述で設定した内容を再利用することにします。CHASSISリンクのappearanceには"BodyAppearance"という名前でアンカーの設定を行いました。ここでその内容を

appearance: *BodyAppearance

という記述によってYAMLのエイリアスとして呼び出しています。このようにアンカーでつけた名前に "*" をつけることで、エイリアスとして参照することが可能です。

リンク相対位置の記述 ¶

TURRET_Yリンクは、CHASSISリンクの小リンクとしてモデリングします。

これを行うために、まず

parent: CHASSIS

によってこのリンクの親リンクがCHASSISであることを明示します。

つぎに、このリンクの親リンクからの相対位置（オフセット）を指定します。これを行うのがtranslationパラメータで、本リンクでは

translation: [ -0.04, 0, 0.08 ]

としています。これによって、CHASSISリンクの原点から後方へ5[cm]、上方へ8[cm]移動した位置に本リンクの原点を設定しています。この位置は親リンクの座標系に基づいています。

ここで相対位置の効果を確認するため、translationの記述をなしとしてみましょう。上記のtranslationの行を削除するか、行の先頭に#をつけてコメントアウトし、モデルの再読み込みを行なってください。

すると先ほど表示されていた砲塔の部分が見えなくなったかと思います。これは、砲塔の部分も車体の中心部に配置されてしまい、その中に埋まってしまったからです。そこで、シーンビューのワイヤフレーム表示をONにしてみてください。すると以下のように表示されるかと思います。

このようにワイヤフレームにすると、車体の中に砲塔部が埋まっているのが確認できます。

これで分かるように、リンクの位置を適切に配置するためには、先程のようにtranslationの記述が必要となるわけです。この値もいろいろと変えてどうなるか試してみてください。

なお、相対姿勢（座標系の向き）についても、rotationパラメータを用いて指定することが可能です。 rotation は

rotation: [ x, y, z, θ ]

の形式で記述します。これは姿勢（回転）を回転軸とその軸まわりの回転角度で指定するというもので、 x, y, z に回転軸の単位ベクトルを指定し、θに回転角度を指定します。

このパラメータの実際の使用例は後ほど紹介します。

関節の記述 ¶

親子関係のある２つのリンクは通常関節によって接続されます。TURRET_Yリンクについても、親リンクCHASSISに対してヨー軸の関節で接続され、CHASSISに対するヨー軸向きを変えられるようになっています。これに関する情報は、TURRET_Yリンクの以下のパラメータによって記述されています。

jointType: revolute
jointAxis: -Z
jointRange: unlimited
jointId: 0

ここではまずjointTypeにrevoluteを指定しています。これにより、親リンクとの間に回転関節が設定されることになります。（これは1自由度の回転関節であり、ヒンジとも呼ばれます。）

jointAxisには関節軸を指定します。ヒンジ関節の場合はその回転軸をここに指定します。指定の仕方は、X、Y、Zの文字で行う場合と、３次元ベクトルとして指定する方法があります。いずれの場合も、軸方向はリンクのローカル座標系で記述します。ここでは "-Z" を指定することで、Z軸のマイナス方向を回転軸としています。関節軸を3次元ベクトルで指定する場合は、

jointAxis: [ 0, 0, -1 ]

となります。この書き方だと、X、Y、Z軸以外にも任意の向きを軸に設定可能です。

Z軸は本モデルも含めて通常鉛直上向きに設定されるため、本関節はヨー軸回転を行う関節となります。向きはZ軸マイナス方向としているため、関節角度のプラス側が右方向への回転、マイナス側が左方向への回転となります。関節の位置はこのリンクの原点に設定されます。親リンクからみたこの位置は、先ほどtranslationで設定した位置になります。

jointTypeとしては他に直動関節に対応する"prismatic"も指定可能です。この場合jointAxisには直動方向を指定します。

関節可動範囲は jointRange を用いて設定します。ここではunlimitedを指定し、可動範囲の制限をなしとしています。可動範囲を設定したい場合は、

jointRange: [ -180, 180 ]

といったように、下限と上限の値を並べて記述します。この例のように下限と上限の絶対値が同じ場合は、その絶対値で

jointRange: 180

と書くこともできます。

jointIdには、この関節に割り振るID値（0以上の整数）を設定します。ID値はChoreonoidのインタフェース上で参照したり、この値によって操作する関節を指定したりすることができます。また、ロボットを制御するプログラムからもこの値を用いて関節を特定することができます。この値は自動的には割り振られず、このようにモデル作成時に適当な値を明示的に割り振るようになっています。この際、必ずしも全ての関節にID値を割り振る必要はありません。ただし、関節角度等を配列に格納する際にそのインデックスとしてこの値が使われることもあるので、なるべく0から隙間なく連続する値を割り振るのが望ましいです。

このモデルは砲塔のヨー軸、ピッチ軸の２つの関節を持ちますので、関節IDとしてそれぞれ0と1を割り振ることにします。

関節動作の確認 ¶

関節が正しくモデリングできているかを確認する場合、ChoreonoidのGUI上で実際にモデルの関節を動かしてみることが有効です。ロボット／環境モデルの基本 - 位置・姿勢の変更で紹介した機能を用いてこれを試してみましょう。

まず、関節スライダビューを用いて関節を動かしてみましょう。作成中のモデルをアイテムツリービュー上で選択すると、関節スライダビューの表示はに以下のようになっているかと思います。

この表示により、関節IDが0のTURRET_Yという関節が定義できていることが分かります。そして、ここのスライダを操作してみてください。するとシーンビュー上でTURRET_Yに対応する直方体がヨー軸まわりに回転することが確認できるかと思います。例えば、関節角度が-30°、0°、+30°のときのモデルの姿勢はそれぞれ以下のようになります。

../../_images/tank_turret_y_rotation.png

TURRET_Yについては関節可動範囲を無制限にしているのですが、この場合関節スライダでは-360°から+360°の範囲で動かすことが可能です。可動範囲に制限を加えている場合は、その範囲内でスライダを操作することが可能となります。

シーンビュー上での関節角の変更も可能です。シーンビューを編集モードに切り替えて、TURRET_Yの部分をマウスでドラッグしてください。するとマウスの動きを追従するように関節を回転できるかと思います。うまく行かない場合は、上記リンクページをみて設定等を確認してください。

砲塔ピッチ軸部の記述 ¶

次に砲塔ピッチ軸部を記述していきましょう。まず以下をlinks以下に追加してください。

-    name: TURRET_P    parent: TURRET_Y    translation: [ 0, 0, 0.05 ]    jointType: revolute    jointAxis: -Y    jointRange: [ -10, 45 ]    maxJointVelocity: 90    jointId: 1    elements:      -        # Turret        type: RigidBody        centerOfMass: [ 0, 0, 0 ]        mass: 3.0        inertia: [          0.1, 0,   0,          0,   0.1, 0,          0,   0,   0.1 ]        elements:          Shape:            geometry:              type: Cylinder              height: 0.1              radius: 0.1            appearance: *BodyAppearance

nameに指定したように、このリンクの名前は "TURRET_P" としています。

# Turret

という記述はコメントです。#のあとの行末までのテキストはコメントとなります。

ここまで記述してモデルの再読み込みを行うと、モデルは以下のように表示されるかと思います。

砲塔ピッチ軸の土台となる部分が追加されました。

RigidBodyノード ¶

上記の記述において、剛体パラメータの記述はLinkノードで行わずに、別途 RigidBody というノードを用いて行っています。

RigidBodyノードは剛体パラメータの記述に特化されたノードであり、centerOfMass, mass, inertia の3つのパラメータを記述することが出来ます。これらはLinkノードで用いていたものと同じ意味を持ちます。このノードをLinkノードのelements以下に記述することでも、剛体パラメータを設定できます。逆に、RigidBodyに代わる簡略的な記法として、Linkノードにも直接剛体パラメータを記述できるようになっていると考えることもできます。

剛体パラメータの記述にあえてRigidBodyノードを用いる利点としては、以下が挙げられます。

剛体パラメータの共有が可能とする
任意の座標系で記述できる
複数の剛体を組み合わせるかたちで記述できる

まず、剛体パラメータを独立したノードとして記述できるので、これにアンカーの設定やエイリアスの利用を適用することで、同じ剛体パラメータの共有が可能となります。これは同じパーツが多数使われている機構をモデリングする際に便利です。

また、ノードが独立していると、 Transformノードも個別に適用することが可能となり、これを用いて任意の座標系で各剛体のパラメータを記述することが可能となります。

さらに、各リンクの記述に使用するRigidBodyノードの個数に制限はないため、リンク全体の剛体パラメータを複数の剛体を組み合わせるかたちで記述することも可能となります。この場合、リンクが含む全てのRigidBodyを反映した剛体パラメータがリンクの剛体パラメータとして設定されます。これを利点1,2と組み合わせれば、複数のパーツで構成される複雑な形状についても、効率的で保守性の高いなモデリングが可能となります。

TURRET_PリンクではRigidBodyノードの使用例として、2つのRigidBodyノードを組み合わせてリンクを構成しています。ひとつ目は先ほど読み込んだ砲塔ピッチ軸の土台部分で、ふたつ目はその先につながる砲身の部分です。

なお、RigidBodyも elementsの記述に対応したノードであり、これを用いることで他のノードを含むことも可能です。ここでは以下で説明する形状部分をelementsの中に記述しています。このようにすることで、剛体の物理パラメータと形状をRigidBodyノードのもとにまとめることができ、モデルの構造がより分かりやすくなるかと思います。

砲塔ピッチ軸土台部形状の記述 ¶

砲塔ピッチ軸土台部の形状は、以下のように記述しています。

Shape:
  geometry:
    type: Cylinder
    height: 0.1
    radius: 0.11
  appearance: *BodyAppearance

ここではgeometryにCylinderノードを用いることで、シリンダ形状を表現しています。Cylinderノードではパラメータとしてシリンダの高さ(height)と半径(radius)を指定します。シリンダの位置と姿勢は、原点を中心とするXZ平面上の設定半径の円をY軸正負の両方向に高さ分押し出した形状に対応しています。ここではこの姿勢を変更せずにそのまま使っています。

appearanceについては、先ほどと同様にBodyAppearanceをエイリアスとして参照し、これまでと同じ設定としています。

砲身部分の記述 ¶

次に砲身部分の記述も追加しましょう。以下のコードをTURRET_Pリンクのelementsに追加してください（インデントを合わせるよう注意して下さい）。

-        # Gun        type: Transform        translation: [ 0.2, 0, 0 ]        rotation: [ 0, 0, 1, 90 ]        elements:          RigidBody:            centerOfMass: [ 0, 0, 0 ]            mass: 1.0            inertia: [              0.01, 0,   0,              0,    0.1, 0,              0,    0,   0.1 ]            elements:              Shape:                geometry:                  type: Cylinder                  height: 0.2                  radius: 0.02                appearance: *BodyAppearance

モデルの再読み込みを行うと、以下のように砲身部分も表示されるかと思います。

この部分も先ほどと同様に、RigidBodyノードを用いて記述し、形状もこのノードの中に含めています。形状としてはやはりシリンダを用いており、長さと半径を調整することで砲身を表現しています。

Transformノード ¶

砲身部分の記述では、RigidBodyノードの上位に

type: Transform
translation: [ 0.2, 0, 0 ]
rotation: [ 0, 0, 1, 90 ]
elements:

という記述を挟んでいます。この部分をTransformノードと言います。

Transformノードは、そのelements以下に記述する内容の座標系を変換するためのノードです。これはリンク相対位置の記述で述べた、Linkノードのtranslation、rotationパラメータと同様の効果を持ちます。ただし、対象がLinkノードのelements以下に記述するノードである点と、複数のTransformノードを組み合わせて使うことができるという点が異なります。

この効果をみるため、Transformノードを無効化してみましょう。Transformノード全体を取り除いてもよいのですが、

type: Transform
#translation: [ 0.2, 0, 0 ]
#rotation: [ 0, 0, 1, 90 ]
elements:

として、translationとrotationの部分をコメントアウトすることでも、同じ結果を再現できます。この状態でモデルの再読み込みを行うと、結果は以下の図のようになるかと思います。

../../_images/tank_turret_barrel_no_transform.png

砲塔部分に埋まっているのが砲身として記述した部分です。これでは位置があっていませんし、向きも横向きになってしまっています。

これはCylinderノードによって生成されるシリンダ形状の座標系がもともとこのようにとられているからで、当然と言えば当然の結果です。先ほどの砲塔ピッチ軸土台部分についてはこの座標系で問題ありませんでしたが、砲身として使う場合は、この位置と姿勢を修正する必要があります。

それを行うために上記のTransformノードを挿入していたというわけです。ここでは

rotation: [ 0, 0, 1, 90 ]

によって、まずZ軸まわりに90度回転させ、砲身の向きがモデルの前後方向(X軸）と一致するようにしています。そして

translation: [ 0.2, 0, 0 ]

によってシリンダを前方に20cm移動させ、砲塔の前面に配置されるようにしています。

なお、TransformのelementsにはRigidBodyノードも含まれていることに注意してください。これにより、形状だけでなくRigidBodyノードに記述されている剛体のパラメータについても上記の座標変換が適用されます。逆に言えば、シリンダのローカル座標で剛体パラメータを記述できるわけで、その方が重心位置や慣性テンソル等の算出にかかる手間も減るかと思います。

Transformパラメータ ¶

Transformノードを用いる代わりに、対象となるノードに直接 translation や rotation のパラメータを記述する方法もあります。これらのパラメータを「Transformパラメータ」と呼びます。

例えばRigidBodyノードもTransformパラメータに対応していますので、砲身部分は以下のように記述することも可能です。

-        # Gun        type: RigidBody:        translation: [ 0.2, 0, 0 ]        rotation: [ 0, 0, 1, 90 ]        centerOfMass: [ 0, 0, 0 ]        mass: 1.0        inertia: [          0.01, 0,   0,          0,    0.1, 0,          0,    0,   0.1 ]        elements:         Shape:            geometry:              type: Cylinder              height: 0.2              radius: 0.02            appearance: *BodyAppearance

Transformのtranslationとrotationを、そのままRigidBodyに持ってきただけです。こちらの方が記述がシンプルになります。内部的にはTransformノードを挿入するのと同じ処理が行われていますが、それを簡略化した記述方法だと考えてください。

Transformパラメータは、他にShapeノードや後ほど解説するデバイス関連のノードでも利用可能となっています。

砲塔ピッチ軸関節の記述 ¶

砲塔ピッチ軸関節の記述についても確認しましょう。TURRET_Pリンクでは、以下の部分で関節を記述しています。

parent: TURRET_Y
translation: [ 0, 0, 0.04 ]
jointType: revolute
jointAxis: -Y
jointRange: [ -45, 10 ]
jointId: 1

親リンクはTURRET_Yです。関節はこのリンクとの間に設置されます。また、translation によって、親リンクからのオフセットをZ軸方向に4cmとしています。

関節のタイプはTURRET_Yと同様にrevoluteを指定し、回転（ヒンジ）関節としています。ここでは回転軸をピッチ軸に対応するY軸としています。ただし軸の向きはマイナス方向としていて、関節角度マイナス方向を砲身の下方向への回転、プラス方向を上方向への回転としています。また、jointRangeにより可動範囲を上側に45°、下側に10°としています。jointIdには1を設定し、TURRET_Yで設定した0とは異なる値としています。

この関節の挙動も確認をしてみましょう。関節スライダビューで以下のようにTURRET_YとTURRET_Pに対応する関節２つ分のインタフェースが表示されているかと思います。

ここのスライダを使うか、シーンビュー上のドラッグを用いて、まずピッチ軸（TURRET_P）を動かしてみて下さい。これにより、で砲身の上下方向の向きを以下のように変えられるかと思います。

../../_images/tank_turret_p_rotation.png

また、ヨー軸についてはこれまでと同じですが、砲身のヨー軸向きも連動して変化することが確認できます。これはTURRET_PリンクがTURRET_Yリンクの子リンクとなっているためです。

デバイスの記述 ¶

Choreonoidで定義されるロボットモデルにおいて、ロボットに搭載されるセンサ等の機器は「デバイス」と呼ばれます。本Tankモデルではスポットライトとカメラの２つのデバイスを搭載することとします。以下ではこれらのデバイスの記述方法について解説します。

スポットライトの記述 ¶

まず、暗闇の中で活動するロボットのシミュレーションをできるように、ライト（光源）のデバイスを搭載することにしましょう。ライトについてはいくつかの種類がありますが、ここではロボットに搭載するライトとして一般的な、スポットライトを用いることとします。

デバイスはいずれかのリンクに搭載されることになりますので、リンクのelements以下にその定義を記述します。ライトの方向を変えられるように、ライトは砲塔ピッチ軸部に搭載することにしましょう。これにより、砲塔ヨー軸、ピッチ軸の動きと連動してライトの向きも変わることになります。

これを実現するため、TURRET_Pリンクのelementsに以下の記述を追加してください。

-        type: SpotLight        name: Light        translation: [ 0.08, 0, 0.1 ]        direction: [ 1, 0, 0 ]        beamWidth: 36        cutOffAngle: 40        cutOffExponent: 6        attenuation: [ 1, 0, 0.01 ]

ここでは type: SpotLight により、スポットライトのデバイスに対応するSpotLightノードの記述としています。記述内容のポイントを以下にまとめます。

このデバイスの名前として"Light"を設定しています。デバイスを扱うプログラムからは名前を使ってデバイスにアクセスすることが多いため、デバイスにはこのように名前を設定するようにしてください。
デバイスノードでも Transformパラメータが利用可能です。ここではtranslationによってライトの設置位置を指定しています。これはTURRET_Pリンク原点からの相対位置になります。
SpotLightのdirectionパラメータで、光軸方向を指定しています。モデルの正面を向けたいので、X軸方向としています。
beamWidth, cutOffAngle, cutOffExponent のパラメータでスポットライトとの照射範囲を設定しています。また、attenuationで光源からの距離に対する光の減衰具合を設定しています。

ライト形状の記述 ¶

ライトに対応する形状を記述しましょう。SpotLightノードの最後にelementsとして以下を追記してください。

elements:          Shape:            rotation: [ 0, 0, 1, 90 ]            translation: [ -0.02, 0, 0 ]            geometry:              type: Cone              height: 0.04              radius: 0.025            appearance:              material:                diffuseColor: [ 1.0, 1.0, 0.4 ]                ambientIntensity: 0.3                emissiveColor: [ 0.8, 0.8, 0.3 ]

ここではライトの形状としては円錐形状（Coneノード）を使用しています。これもデフォルトの座標系だと向きが合わないので、 Transformパラメータを利用して向きを変えています。また、光源がこの形状によって隠れてしまうことのないよう、少し後方にずらした位置としています。レンダリングにおいて影も発生させる場合にはこの点注意する必要があります。

materialではemissiveColorも設定し、暗闇の中でもライトの部分が光って見えるようにしています。

ここまで記述してモデルの再読み込みを行うと、ライトの形状が以下のように表示されるかと思います。

これにより、ライトが正しい位置と向きで設置されているかをモデルの見た目で確認することができます。

ただし、デバイスを搭載するにあたって、対応する形状は必ずしもなくても構いません。また、対応する形状があるとしても、必ずしもデバイスノードのelements以下に記述しなければいけないわけではありません。今回の例ではモデリングを分かりやすくするためにそうしましたが、デバイスは基本的に形状とは関係なく機能します。

カメラの記述 ¶

カメラのデバイスも追加しましょう。SpotLightノードと同様に、以下をTURRET_Pリンクのelements以下に追加します。

-        type: Camera        name: Camera        translation: [ 0.1, 0, 0.05 ]        rotation: [ [ 1, 0, 0, 90 ], [ 0, 1, 0, -90 ] ]        format: COLOR_DEPTH        fieldOfView: 65        nearClipDistance: 0.02        width: 320        height: 240        frameRate: 30        elements:          Shape:            rotation: [ 1, 0, 0, 90 ]            geometry:              type: Cylinder              radius: 0.02              height: 0.02            appearance:              material:                diffuseColor: [ 0.2, 0.2, 0.8 ]                specularColor: [ 0.6, 0.6, 1.0 ]                shininess: 0.6

カメラはCameraノードを用いて記述します。

このノードでは、取得する画像の形式をformatで指定します。ここは以下の３つのいずれかを指定することができます。

COLOR
DEPTH
COLOR_DEPTH

COLORを指定した場合は通常のカラー画像となります。DEPTHの場合は、距離画像が得られます。COLOR_DEPTHの場合、これら両方の画像を同時に取得することができます。これはKinect等のRGBDカメラのシミュレーションを想定しています。

また、画像のサイズ（解像度）をwidthとheightで指定します。ここでは横320 x 縦240の解像度としています。さらに、画像取得のフレームレートをframeRateに設定します。

カメラ位置姿勢の記述 ¶

カメラの位置については

translation: [ 0.1, 0, 0.05 ]

の記述により、ライトのやや下側に設定しています。

カメラの姿勢は、デフォルトではY軸正方向がカメラの上方向に対応し、Z軸負方向がカメラの正面（視線）方向となります。これとは異なる向きにカメラを向けたい場合は、 Transformノードもしくは Transformパラメータのrotationを用いて、カメラの姿勢を変更する必要があります。

今回のモデルでは、Z軸が鉛直上向きにとられていますので、デフォルトの向きだとカメラが下を向いてしまいます。そこで上位のTransformノードで

rotation: [ [ 1, 0, 0, 90 ], [ 0, 1, 0, -90 ] ]

と記述することにより、カメラの向きを望みのものに設定しています。

rotationによる姿勢の指定方法はリンク相対位置の記述で説明したように、回転軸と回転角度の組で指定します。ここではさらにその組が２つ与えられています。実はrotationはこのように複数の姿勢表現を列挙して記述することも可能となっています。この場合、姿勢値（回転指令）を右側から順番に適用していくことになります。（各要素を回転行列と考えて、行列の掛け算をこの順番で適用するのと同じとなります。）

ここではまず [ 0, 1, 0, -90 ] によってY軸まわりに-90度回転します。これでカメラは正面を向くことになります。ただしこの状態だとまだカメラの上向きがモデルの左方向となっており、カメラが横に倒れたような画像になってしまいます。そこでさらに [ 1, 0, 0, 90 ] によってX軸まわりに90度回転することにより、カメラを起こして、望みの画像が得られるようにしています。

この２つの回転をひとつの回転表現にまとめることも可能ですが、そのようにまとめた値は直観的に把握したり算出したりすることが困難です。これに対して上記のような複数の回転を組み合わせることで、このようなテキストによる記述も容易となります。

カメラの形状 ¶

ここではカメラのレンズを想定したものとして、シリンダ形状を付与しています。これにより、モデルの表示は以下のようになります。

なお、カメラの定義にて

nearClipDistance: 0.02

という記述をしています。これはカメラ画像内に収める外界の範囲をカメラ中心点より少し前方にずらすための記述です。今回カメラの形状を付与していることにより、そのままではその形状によって前方の視界が遮られることになってしまいます。この記述を入れることで、カメラ形状の外側をカメラ画像に映すことが可能となります。

クローラの記述 ¶

最後にクローラの部分を記述します。

左クローラの記述 ¶

まずは左側のクローラから記述しましょう。リンクの記述で述べたlinksの階層（インデント）に戻って、以下の記述を追加してください。

-    name: TRACK_L    parent: CHASSIS    translation: [ 0, 0.2, 0 ]    jointType: fixed    jointAxis: Y    actuationMode: jointSurfaceVelocity    centerOfMass: [ 0, 0, 0 ]    mass: 1.0    inertia: [      0.02, 0,    0,      0,    0.02, 0,      0,    0,    0.02 ]    elements:      Shape: &TRACK        geometry:          type: Extrusion          crossSection: [            -0.22, -0.1,             0.22, -0.1,             0.34,  0.06,            -0.34,  0.06,            -0.22, -0.1            ]          spine: [ 0, -0.05, 0, 0, 0.05, 0 ]        appearance:          material:            diffuseColor: [ 0.2, 0.2, 0.2 ]

この状態でモデルの再読み込みを行うと、以下のように左側のクローラがモデルに加わるかと思います。

クローラは車体に接続されるものなので、本リンクでは親リンクを再度CHASSISと指定しています。

また、親リンクからの相対位置として、

translation: [ 0, 0.2, 0]

を記述することで、本リンクの位置を車体の左側に設定しています。

クローラは本来、金属やゴムでできた履帯を繋ぎあわせたベルト状のものを内部のホイールで駆動して回すという機構ですが、そのような複雑な機構をシミュレートするのは一般的には難しい課題です。そこで今回モデリングするクローラは、リンクひとつで表される擬似的なクローラとします。リンクひとつなのでベルト状の履帯はなく、クローラ全体がひとつの剛体で表現されています。踏破能力は正確なクローラには全く及びませんが、クローラと環境との接触部分に推進力を与えることで、ある程度クローラに近い動きを実現することが可能です。この詳細は無限軌道の簡易シミュレーションを参照してください。

このような擬似クローラ（簡易クローラ）の場合、関節が動くわけではありませんので、リンクのjointTypeには "fixed" を指定します。

jointAxis には想定されるクローラのホイールの回転軸方向を指定します。この軸に対して右ねじ正方向の回転が前進方向となります。ここではY軸を回転軸としています。

そして actuationMode に "jointSurfaceVelocity" 設定します。このようにしておくと、このリンクが擬似クローラとして駆動されることになります。（このパラメータはモデル使用時に制御プログラム側でも設定できるので、必ずしもモデルファイルに記述しておく必要はありませんが、擬似クローラの場合はモデルファイルにも書いておいたほうが分かりやすくてよいかと思います。）

クローラの形状は "Extrusion"タイプの幾何形状ノードによって記述しています。これは押し出し形状とも呼ばれるもので、まず断面の形状をcrossSectionで指定し、それをspineの記述に従って押し出すようなかたちで立体形状を記述するものです。ここではクローラの断面を台形とし、それをY軸方向に押し出して幅を持たせた形状としています。この記述方式は本々VRML97で定義されているものであり、その詳細は VRML97のExtrusionノードの仕様を参照いただければと思います。

ここで記述した形状にもアンカーの設定を行います。ここでは "TRACK" というアンカーをつけて、右側のクローラの形状としても使い回すことにします。

右クローラの記述 ¶

右側のクローラも記述しましょう。先ほど同様にlinksの階層に以下を追加してください。

-    name: TRACK_R    parent: CHASSIS    translation: [ 0, -0.2, 0 ]    jointType: fixed    jointAxis: Y    actuationMode: jointSurfaceVelocity    centerOfMass: [ 0, 0, 0 ]    mass: 1.0    inertia: [      0.02, 0,    0,      0,    0.02, 0,      0,    0,    0.02 ]    elements:      Shape: *TRACK

このリンクの内容は、一部左右対称となっている以外は左クローラとほぼ同じ内容となっています。形状に関しては先ほど"CRAWLER"という名前で設定したアンカーをエイリアスとして参照しています。

モデルの再読み込みを行って以下のようなモデルが表示されれば、これで完成です！