ステップ7: ライトの制御
=======================

Crawlerモデルはライト（光源）を搭載しています。ステップ7ではこのライトをコントローラから操作できるようにし、デバイスを制御する方法について学びます。

.. contents:: 目次
   :local:
   :depth: 2

.. _step7-ref1:

環境設定
--------

ライトを使用するにあたって、その効果をより分かりやすくするための環境設定を行うことにしましょう。

グラフィックス環境の確認
~~~~~~~~~~~~~~~~~~~~~~~~

ライトの効果が正しく描画されるようにするためには、 `グラフィックス環境のセットアップ <https://choreonoid.org/ja/documents/latest/install/setup-gpu.html>`_ が適切に行われている必要があります。Ubuntu Linux使用時は `Ubuntu LinuxにおけるGPUドライバのインストール <https://choreonoid.org/ja/documents/latest/install/setup-gpu.html#setup-gpu-ubuntu-gpu-driver>`_ についても確認してください。

環境モデルの変更
~~~~~~~~~~~~~~~~

これまで使ってきた床のモデルだけだと、ライトが照射されてもあまり代り映えがしません。そこで環境モデルも変更することにしましょう。今回はChoreonoidのサンプルとして用意されている "Labo1" というモデルを使うことにします。これは以下に示すような、研究用プラントを想定したモデルとなっています。

.. image:: images/step7-1.png

このモデルはChoreonoidのshareディレクトリの "model/Labo1" に "Labo1.body" というファイル名で格納されています。これまで作成してきたプロジェクトに追加して、このモデルを読み込んでください。

読み込んだアイテムのアイテムツリービュー上での配置は、他のモデルと同様にWorldアイテムの子アイテムとします。アイテムのチェックが入っていなければ、チェックを入れてモデルを表示しましょう。シーン内でのモデルの位置はデフォルトのままでOKです。そして、これまで読み込んでいた床のモデルである "Floor" アイテムは削除しておきましょう。アイテムを右クリックするとコンテキストメニューが表示されますので、そこから「カット」を選択することで削除できます。以上の作業を行うと、アイテムツリーは以下のようになっているかと思います。

.. image:: images/step7-2.png

なお、アイテム間の親子関係が同じであれば、アイテムの並び順はどうなっていてもOKです。なので例えばLabo1がAISTSimulatorの次に配置されたりしていてもかまいません。もし並び順が気になる場合は、アイテムをドラッグすることで並び順だけ変えることもできますので、そこは好きなように設定してください。

シーン設定の変更
~~~~~~~~~~~~~~~~

次にシーンの描画に関わる設定を変更しましょう。これを行うにあたっては、まず以下のシーンバーの「設定ボタン」を押します。

.. image:: images/step7-3.png

設定ボタンは、以下のギヤのアイコンです。

.. image:: images/step7-4.png

すると以下のような設定ダイアログが表示され、シーン描画に関する各種設定を行うことができます。

.. image:: images/step7-5.png

まず「XY（床）グリッド」のチェックを外して、グリッド線を表示しないようにしましょう。

次にライティングの設定をしましょう。まず「追加のライト」はオンになっていますでしょうか？ここがオンになっていれば、Crawlerモデルに搭載されたライトも有効となります。

そして、「ヘッドライト」と「ワールドライト」をオフにしてみましょう。すると下図のように、暗闇の中でCrawlerモデルのライトのみが辺りを照らしているようなシーンになるかと思います。

.. image:: images/step7-6.png

これでライトの効果がはっきりと分かりますね。（デフォルトのレンダラを使う場合は、ライトの照射がもう少しぼやっとした感じになります。）

.. ただしここまで暗くしてしまうと、シーンの一部しか見えなくなってしまうため、操作がしづらいかもしれません。そこで先ほどオフにした「ヘッドライト」や「ワールドライト」によるライティングも少し取り入れてみましょう。

.. まず、設定ダイアログで各ライトをひとつずつオンにしてみてください。するとそれぞれシーンが明るくなるかと思いますが、シーンの照らされ方は少し異なるのが分かるかと思います。「ヘッドライト」は視線の方向に向けて照射されるライトとなっており、「ワールドライト」はシーンの上部から下方に照射されるライトとなっています。次に両方のライトをオンにして、各ライトの強さを設定ダイアログの「照度」で調整しましょう。デフォルトの照度だとシーンが明るくなりすぎて雰囲気が出ないので、この値を適当に下げつつ、操作もしやすい明るさに調整してください。

GLSLレンダラを有効にしている場合は、影も表示することができます。これは設定ダイアログの「影」のチェックで設定します。それぞれ「ライト」に対象となるライトの番号を入力します。番号は1がCrawlerモデルに搭載されたライト、2がLabo1モデルの天井の照明に対応しますので、それぞれ有効にしてみて、表示がどのように変わるかを確認してください。

.. ヘッドライトとワールドライトの照度を調整し、ワールドライトと

Crawlerモデル、Labo1モデルのライトによる影を有効にしたシーンの例を、下図に示します。

.. image:: images/step7-7.png

これでシーンの雰囲気がそれらしくなってきました。ここまでの設定を "step7.cnoid" といった名前のプロジェクトファイルとして保存しておきましょう。

.. note:: 影については使用するGPUやGPUドライバによっては描画されないこともあります。詳しくは `グラフィックス環境のセットアップ <https://choreonoid.org/ja/documents/latest/install/setup-gpu.html>`_ を参照してください。


.. _step7-ref2:

ライトのコントローラ
--------------------

環境設定が長くなってしまいましたが、本題に入りましょう。今回作成するのは、Crawlerモデルのライトを操作するためのコントローラで、これを "LightController" とします。このコントローラのソースコードを以下に示します。

.. _controller-example4:

.. literalinclude:: ./src/crawler/LightController.cpp
   :language: C++
   :caption: LightController.cpp

これまでと同様に、上記ソースコードを "LightController.cpp" というファイル名でプロジェクトディレクトリに保存します。

CMakeLists.txt に

.. cmake-example3:

.. literalinclude:: ./src/crawler/CMakeLists.txt
   :language: YAML
   :caption: CMakeLists.txt
   :lines: 6

を追加して、コンパイルを行って下さい。


.. _step7-ref3:

コントローラの導入
------------------

ステップ5で導入したTrackControllerと同様に、LightControllerについても対応するシンプルコントローラアイテムを生成し、これをTurretControllerの子アイテムとして配置するようにしてください。これを行うと、アイテムツリービューは以下のようになります。

.. image:: images/step7-8.png

このように配置することで、TurretController、HingeController、TrackController、LightControllerのcontrol関数が順番に呼ばれ、これらが一体となって機能することになります。


.. _step7-ref4:

ライトの操作
------------

シミュレーションを実行して、ライトの操作ができるようになっていることを確認しましょう。

ライトの操作はゲームパッドもしくは仮想ジョイスティックビューのA、X、Yボタン（プレイステーションのゲームパッドの場合は×、□、△ボタン）に割り当てられています。

まずAボタンでライトのオン・オフを切り替えられます。

また、X、Yボタンで、ライトの照射範囲を変えられます。Xボタンを押すと照射範囲を狭くし、Yボタンを押すと広くします。

これまで実現してきたクローラやカメラ台座の操作も引き続き可能ですので、Crawlerモデルを移動させながら、Labo1の様々な箇所をライトで照射してみてください。

なお、シミュレータアイテムのプロパティである「デバイス状態の記録」がtrueになっていれば、ライトの操作についてもシミュレーション結果として記録され、 `シミュレーション結果の再生 <https://choreonoid.org/ja/documents/latest/simulation/execution-and-playback.html#simulation-result-playback>`_ の際に再現されます。このプロパティはデフォルトでtrueになっています。この機能の確認のため、ライトをいろいろと操作した後にシミュレーションを停止して、シミュレーションの再生を行ってみて下さい。


.. _step7-ref5:

実装内容の解説
--------------

Choreonoidではライトを「デバイス」のひとつとして定義しています。本ステップのポイントは、コントローラからデバイスへ出力を行う方法を知ることにあります。

まず、initialize関数の ::

 light = io->body()->findDevice<SpotLight>("Light");

によって、入出力用Bodyオブジェクトから、SpotLight型で"Light"という名前をもつデバイスオブジェクトを取得し、これをlight変数に格納しています。デバイスに関しても、このオブジェクトを入出力用に使います。Lightの定義については、 :doc:`Crawlerモデルの作成 <./step0>` におけるスポットライトの記述を参照してください。

control関数では、 ::

 static const int buttonID[] = { 0, 2, 3 };

により、ライトの操作に使うボタンのIDを設定しています。これらのIDが通常A、X、Yボタンに対応します。ボタンの対応がうまくいかない場合は、ここを調整するようにしてください。

Aボタンの状態について、 ::

 bool currentState = joystick.getButtonState(buttonID[0]);

で取得しています。このように、ボタンの状態はgetButtonState関数を用いて取得することができます。そして、 ::

 if(currentState && !prevButtonState){
     light->on(!light->on());
     changed = true;
 }

によって、ボタンが押されたときに、SpotLightデバイスのon関数を用いて、lightオブジェクトのオン・オフ状態を切り替えるようにしています。

なお、入出力用デバイスオブジェクトの状態を変更しただけでは、その内容を出力したことにはなりません。これを行うには、デバイスオブジェクトに対して "notifyStateChange" という関数を実行する必要があります。これによって状態の変化がシミュレータ本体にも検知され、実際にシミュレーションに反映されることになります。

ただしこの関数は、デバイスの複数のパラメータを変化させる場合でも、(一回のcontrol関数呼び出しにおいて）一回実行するだけでOKです。このため、本実装ではまずchangedというbool変数を状態変化があったかどうかのフラグとして利用し、最後の ::

 if(changed){
     light->notifyStateChange();
 }

でまとめて一回実行するようにしています。

ライトの照射範囲を変える操作についても同様です。照射範囲拡大の操作については、 ::

 if(joystick.getButtonState(buttonID[1])){
     light->setBeamWidth(std::max(0.1f, light->beamWidth() - 0.001f));
     changed = true;

によってXボタンの状態を判定し、ボタンが押されていればSpotLightのsetBeamWidth関数で、照射角度の値を減らしています。Yボタンの操作についてもこれと同様です。

デバイスの扱いに関しては、より詳細な解説が `コントローラの実装 <https://choreonoid.org/ja/documents/latest/simulation/howto-implement-controller.html>`_ の `デバイスに対する入出力 <https://choreonoid.org/ja/documents/latest/simulation/howto-implement-controller.html#simulation-device>`_ 以降の節にもありますので、そちらもご参照下さい。