CrowdWalk チュートリアル
- CrowdWalkとは
- 動作環境
- インストール・アップデート
- サンプルの実行
- シミュレーションの準備
- マップファイルの作成
- ジェネレーションファイルの作成
- シナリオファイルの作成
- プロパティファイルの作成
- 一次元空間モデルを採用し大規模群衆流動にも対応したマルチエージェント歩行者シミュレータです。
- Java アプリケーションなので様々な OS 上で使用する事ができます。
- CrowdWalk のソースコードは GitHub 上で管理されており、MIT ライセンスの下で誰でも無料で利用することができます。
- CrowdWalk が用いる数理モデル(空間モデル、移動モデル)については、山下倫央・副田俊介・大西正輝・依田育士・野田五十樹(2012)『一次元歩行者モデルを用いた高速避難シミュレータの開発とその応用』情報処理学会論文誌 Vol.53 や、山下倫央・岡田崇・野田五十樹『大規模群集流動の制御に向けたシミュレーション環境の構築』JAWS2012 に解説されています。
- ネットワークマップとは、シミュレーションの舞台となる空間や構造物を定義したモデルデータの事です。
- リンクとノードにより構成されたネットワーク構造を持ちます。災害エリアやポリゴンデータを含む場合もあります。
- リンク - 長さと幅を持つ直線状の領域で、道路や廊下、部屋などに相当します。内部に複数の仮想レーンを持ち、エージェントはこの仮想レーンの上を移動します。
- ノード - 座標と標高(あまり使われない)を持つ点です。リンクの終端、または接続点となります。
- 災害エリア - 津波や洪水による浸水、または有害ガスの発生を示す矩形領域です。エージェントの移動速度や生命状態に影響を与えます。
- ポリゴンデータ - 3D 用と 2D 用の2種類のタイプがあり、構造物や河川・海面の表示に使います。
- エージェントは人の歩行をシミュレーションします。
- ソーシャルフォースモデルにより移動速度を計算しています。
- エージェントの移動ルート:
- 基本的にエージェントは発生地点からゴール地点までの最短ルートを進みます。ただし途中の経由地点が設定されている場合は、最短ルートで経由地点を通過しながらゴールに向かいます。つまりエージェントの移動ルートはシミュレーション開始時に予め決まっています。
- 設定によりエージェントの移動ルールに特性を持たせる事も出来ます。その場合は上記の限りではありません。
ネットワークマップの作成・編集をおこないます。
コンソールへのメッセージ表示のみでシミュレーションを実行します。
真上から見下ろす形で進行状況を表示しながらシミュレーションを実行します。
三次元上の任意の視点で進行状況を表示しながらシミュレーションを実行します。
シミュレーションの過程や結果をログファイルに出力します。
- agent trail - ゴールまでたどり着いたエージェントのゴールした時点でのJSON形式のログ
- agent movement history - ゴールまでたどり着いたエージェントのゴールした時点でのログ
- individual pedestrians - ステップ毎の各エージェントの状態を個別に記録するログ
- evacuated agents - ステップ毎の脱出エージェント数をゴール別に記録するログ
例) agent_movement_history.csv
GenerationFileの情報,エージェントID,発生時刻1,発生時刻2,到着時刻1,到着時刻2,移動時間1,移動時間2
EACH TEST3 19:00:00 1 10 EXIT,ag09476,19:00:00,240,19:01:15,315,00:01:15,75
EACH TEST3 19:00:00 1 10 EXIT,ag09515,19:00:00,240,19:01:16,316,00:01:16,76
EACH TEST3 19:00:00 1 10 EXIT,ag09511,19:00:00,240,19:01:16,316,00:01:16,76
EACH TEST3 19:00:00 1 10 EXIT,ag09483,19:00:00,240,19:01:16,316,00:01:16,76
EACH TEST 19:00:00 1 10 EXIT,ag03801,19:00:00,240,19:01:16,316,00:01:16,76
EACH TEST3 19:00:00 1 10 EXIT,ag09617,19:00:00,240,19:01:17,317,00:01:17,77
EACH TEST 19:00:00 1 10 EXIT,ag00154,19:00:00,240,19:01:17,317,00:01:17,77
EACH TEST 19:00:00 1 10 EXIT,ag03829,19:00:00,240,19:01:17,317,00:01:17,77
・
・
・
以下のソフトウェアが動作する環境が必要です。
- コマンドラインシェル
- CrowdWalk をコマンドラインから起動するシェルスクリプトを実行します。
- Bourne Shell のシェルスクリプトが実行できるシェルであれば何でもよいですが、どれを使ったらよいか分からない場合は Bash を使ってください。以降の解説では Bash の使用を前提にしています。
- CrowdWalk を正常にコンパイル・実行するために以下の環境変数の設定が必要です。
export LANG=ja_JP.UTF-8
export JAVA_OPTS='-Dgroovy.source.encoding=UTF-8 -Dfile.encoding=UTF-8'
- Git
- CrowdWalk のダウンロードやアップデートをおこないます。
- JDK(Java Development Kit)
- CrowdWalk のソースコードのコンパイル及び実行をおこないます。
- JDK 8 以上が必要です。ただし機能を CUI モードのシミュレータに限定するならば JDK 1.6 以上であれば動作します。
- Oracle 版の JDK を使用する場合は、2020年12月まで無償アップデートが継続される JDK 8 をお勧めします。
- Gradle
- CrowdWalk のソースコードをビルドします。
- Ruby
- 特別なツールを実行する際に必要となります。通常の使用では不要です。
- テキストエディタ
- 各種設定ファイルの編集をおこないます。
使用している OS 上でこれらのソフトウェアが動作する様にセットアップをおこなってください。
Windows7 向けのセットアップ手順は CrowdWalk のセットアップ に記載されています。
以降の操作はすべて Bash のコマンドライン上でおこなうものとして解説します。またインストールはホームディレクトリ直下におこなうものとします。
まずは Bash を起動してコンソールウィンドウを開いてください。カレントディレクトリがホームディレクトリになっていなければホームディレクトリに移動してください。
次のコマンドを実行して GitHub から CrowdWalk のソースコードをダウンロードします。
git clone https://github.com/crest-cassia/CrowdWalk.git
ダウンロードが完了すると以下のディレクトリ構成でファイルが作成されます。
Crowdwalk/
crowdwalk/
floodtocrowdwalk/
GisToCrowdwalk/
img2movie/
- crowdwalk
Crowdwalk 本体及びサンプルデータがあるディレクトリ。
通常はここをカレントディレクトリにして作業をおこないます。 - floodtocrowdwalk
浸水データを元に、マップファイルに Area タグを埋め込むツール。 - GisToCrowdwalk
シェープファイル形式の地図データを CrowdWalk のマップファイルに変換するツール。 - img2movie
FFmpeg を利用してスクリーンショット画像を動画に変換するツール。
必要なライブラリをダウンロードして、ソースコードをコンパイルし、実行可能形式のアーカイブファイルにまとめるまでの一連の作業をビルドといいます。
CrowdWalk の作業ディレクトリに移動します。
cd ~/CrowdWalk/crowdwalk
ビルドコマンドを実行します。
gradle
初回実行時は大量のライブラリがダウンロードされるため、しばらく時間が掛かります。
問題なく終了したら BUILD SUCCESSFUL と表示されます。
ビルドが完了したら動作確認します。
次のコマンドを実行して CrowdWalk のヘルプが表示されれば OK です。
sh quickstart.sh -h
スクリーンショット保存用のディレクトリをあらかじめ作成しておきます。プロパティファイルの設定により別のディレクトリにする事も可能です。
mkdir screenshots
CrowdWalk の作業ディレクトリに移動します。
cd ~/CrowdWalk/crowdwalk
次のコマンドを実行してソースコードを最新の状態に更新します。
git pull
注意!
GitHub からダウンロードしたファイルの内容を変更するとgit pullコマンドが失敗してしまいます。
以下のコマンドで変更されたファイルをすべて元に戻すことができます。(変更したファイルが必要ならバックアップを取ってから実行してください)
git checkout .
ビルドコマンドを実行して再ビルドします。
gradle
sample ディレクトリにシミュレーションのサンプルファイルがいくつか用意されています。
※サンプルの中にはログファイルを出力するものもあるため注意してください。
以下に実行手順を二つ示します。操作方法についても簡単に説明します。いずれも実行は CrowdWalk の作業ディレクトリ(~/CrowdWalk/crowdwalk)からおこないます。
三つの部屋と廊下を一次元空間モデルで表現したものです。各部屋からエージェントが発生し、右端にある出口に向かいます。
実行してみましょう。3D グラフィックモードでシミュレータを起動します。
sh quickstart.sh sample/basic-sample/properties.json -g
シミュレータが起動してウィンドウが開きます。
ボタンをクリックしてください。シミュレーションがスタートしてエージェントが発生します。
緑色で丸く表示されているのがエージェントです。一直線上に並んでいないのはレーン数分並列に歩行しているためです。(もともと表示がちょっとズレる傾向もあります)
エージェントは移動速度によって緑から赤へと色が変化します。
ボタンを何度かクリックしてください。シミュレーションが1秒ずつ進行していきます。これをステップ実行といいます。
次に 
ボタンをクリックしてください。 ボタンが 
ボタンに切り替わり、シミュレーションが一瞬で最後まで進んで終了します。
ボタンをクリックして に戻してから 
ボタンをクリックしてください。シミュレータが一旦終了して再起動します。
wait と表示されたスクロールバーを右端まで移動して値を 300 にしてから ボタンをクリックしてください。今度はシミュレーションがゆっくり進行していきます。ステップ毎に 300 ミリ秒時間を置いているためです。
シミュレーションが終了する前に ボタンをクリックしてください。シミュレーションが一時停止します。 ボタンをクリックするとシミュレーションが再開します。
マップが表示されている画面上でマウスの左ボタンを押しながらドラッグしてください。画面の中心を基準にしてマップが回転します。右ボタンを押しながらドラッグした場合にはマップが水平移動します。
次にマウスホイールを前後に回してください。表示スケールが変わってマップに近づいたり遠ざかったりしている様に見えるはずです。
次に 
をクリックしてタブパネルを View に切り替えてください。
ボタンをクリックすると最初の表示状態に戻ります。
Help メニューの Quick reference でシミュレータの操作方法の一覧を確認する事が出来ます。
関門海峡花火大会を門司港側で見物していた観客の帰宅時の移動をシミュレーションしたものです。
観客は電車に乗って帰宅するため全員門司港駅に向かいます。門司港駅の入り口がゴールです。
道路上の複数の地点で交通整理(通行止/解除)がおこなわれます。また駅構内の混雑防止のため電車の発着に合わせて入構制限がおこなわれます。(残念ながら電車の発着の様子は表示されません)
今回はエージェント数が多いため、3D グラフィックモードよりも表示処理が軽い 2D グラフィックモードでシミュレータを起動します。また重要性の低い動作ログの表示を抑制するため -lError オプションを付加します。
sh quickstart.sh sample/stop-sample2/properties.json -g2 -lError
背景地図表示用の画像をダウンロードするため、シミュレータが起動するまでに2分半ほど時間が掛かります。一度ダウンロードした画像はキャッシュディレクトリに保存されるため以後ダウンロードされる事はありません。
シミュレータが起動してウィンドウが表示されると同時にシミュレーションがスタートします。
View タブの Show background map チェックボックスを ON にしてください。背景地図として写真(※)が表示されます。
※出典：国土地理院ウェブサイト
設定により背景地図を標準地図(※)にしたり、より解像度の高い写真にする事も出来ます。
現在、カメラワーク機能が有効になっています。この状態では設定データにより視点が決められ、マップの回転や拡大・縮小操作は無効となります。確認してみてください。
カメラワーク機能を解除するには Camera タブの Replay チェックボックスを OFF にします。
CrowdWalk でシミュレーションを開始するためには最低限次のファイルを用意する必要があります。
- マップファイル
- ジェネレーションファイル
- シナリオファイル
- プロパティファイル
マップファイルはネットワークマップを保存したファイルの事です。
- CrowdWalk のマップエディタを使って作成します。
- シェープファイルや OSM など別の形式の地図データを元に、変換ツールを使って作成する事も出来ます。
- XML 形式なのでテキストエディタを使って編集する事も可能です。
ジェネレーションファイルは、エージェントの特性や発生場所、発生時刻、移動ルートなどを定義したファイルです。
JSON 形式と CSV 形式(旧形式)があります。
シナリオファイルは、シミュレーション実行中に発生させるイベントのスケジュールを定義したファイルです。
JSON 形式と CSV 形式(旧形式)があります。CSV 形式は非推奨です。
プロパティファイルは、上記の3ファイルを含む各種設定ファイルのパス指定やシミュレータの各種パラメータを設定したファイルです。
JSON 形式と XML 形式(旧形式)があります。XML 形式は非推奨です。
その他、必要に応じて以下のファイルも使用します。
- 背景画像ファイル
- Fallback ファイル - デフォルトセッティング値
- カメラワーク設定ファイル - シミュレータ画面の視点設定
- Pollution ファイル - 浸水やガスなどの災害状況データ
- Link appearance ファイル - リンクの表示設定
- Node appearance ファイル - ノードの表示設定
- Agent appearance ファイル - エージェントの表示設定
- Polygon appearance ファイル - ポリゴンの表示設定
- Coastlineファイル - 海岸線データ
- Ruby スクリプトファイル - シミュレータの機能を拡張する外部プログラム
以降のセクションでは basic-sample で使用した必須ファイルを実際に作成しながら解説を進めていきます。
この画像を基にマップファイルを作成します。
次の手順で作業を進めます。
- 準備。
- グループの作成。
- 基となる画像を背景にセット。
- 画像の上にノードを作成。(仮置き)
- ノードをつないでリンクを作成。
- ノード・リンクの位置調整。
- リンク幅を設定。
- ノードとリンクにタグを付加。
始めにマップファイルを作成するための準備として保存先のディレクトリを作成します。
このディレクトリには設定ファイルやデータファイルも保存されます。まず、マップの元となる画像ファイルをコピーします。
コマンドラインで以下のコマンドを実行してください。
cd ~/CrowdWalk/crowdwalk
mkdir practice
cp sample/basic-sample/rooms.png practice
コマンドラインで次のコマンドを実行してマップエディタを起動します。CrowdWalk をオプションなしで起動するとマップエディタのウィンドウが開きます。
sh quickstart.sh
階層を持つ建物などの編集を容易にするため、ネットワークマップは内部をグループ化する構造を持っています。マップエディタは通常、グループ単位で編集をおこないます。
なおグループ構造はシミュレーションには一切影響を与えません。
現在の状態は root グループが存在するだけの、空のネットワークマップです。(空のネットワークマップでも root グループだけは存在します)
root グループに直接マップを作成すると後からグループを追加する事が出来なくなってしまうため、新たにグループを作ってそこにマップを作成します。
グループ名は "FLOOR" とします。
Groups タブの root を右クリックして Add group を選択してください。
Add group ダイアログが表示されたら Tag フィールドに "FLOOR" と入力して OK ボタンをクリックしてください。
FLOOR グループが追加され、カレントグループ(現在編集中のグループ)も FLOOR に変わりました。
マップエディタにはアンドゥー/リドゥー機能があり、操作の取り消し/再操作をする事が出来ます。Edit メニューの Undo または Redo を選択してもよいですが、Ctrl キーを押しながら Z でアンドゥー、Y でリドゥーと覚えておくと便利です。
アンドゥー回数に制限はありませんがマップファイルの保存をおこなうとリセットされます。また、ネットワークマップの変更を伴わない操作(表示スケールの変更など)にはアンドゥーは適用されません。
ここで一旦セーブしてマップファイルを作成します。マップファイルが存在していないと次の手順でおこなう背景画像のセット機能が使えないためです。
File メニューの Save map を選択してください。ファイル選択ダイアログが表示されたら、先程作成した "practice" ディレクトリに "test_model.xml" というファイル名で保存してください。
Save map メニューの選択でファイル選択ダイアログが表示されましたが、これはマップファイルがまだ存在していなかったためです。マップファイルが存在している場合にはファイル選択ダイアログは表示されず直ちに上書き保存となります。
Save map as メニューを選択すれば常にファイル選択ダイアログが表示されます。
次に背景画像のセットをおこないますが、その前に編集画面のスケールを、作成するマップに合わせておきます。
View メニューの Show grid を選択してください。編集画面にグリッドが表示されます。
左上に表示されている通り、グリッドのスケールは 10m × 10m です。
通路の長さは 20m なので表示スケールをこれに合わせて変更します。また、マップはなるべく座標原点付近に作る様にします。
画面上でマウスの右ボタンを押しながら右斜め下方向にドラッグしてください。座標原点を示す赤いクロスが現れます。
マウスカーソルを原点(クロスの交点)に合わせてマウスホイールを回転してください。
表示スケールが変わってグリッドの間隔が変化している事が分かります。ウィンドウ下側のステータスラインには現在のスケール値が表示されます。
適当な表示スケールになるまでマウスホイールを回します。
Mode ラインの 
ボタンをクリックして編集モードを Background Image に切り替えます。
マウスカーソルを原点に合わせてから右クリックして、Set background image を選択してください。
ファイル選択ダイアログが表示されたら "practice" ディレクトリの画像ファイル "rooms.png" を選択してください。先ほど右クリックした時の位置に背景画像としてセットされます。
Background Image モードではマウスホイールを回転すると背景画像が拡大・縮小されます。Ctrl キーを押しながらマウスホイールを回転すると微調整(1/10単位での拡大・縮小)になります。
また、Shift キーを押しながらマウスの左ボタンを押してドラッグすると背景画像を移動する事が出来ます。
これらの操作を組み合わせて通路の長さが 20m になる様に拡大し、部屋の左上の角が原点に当たる様に位置を調整します。
背景画像のセットはこれで完了です。
次にノードを作成します。
Mode ラインの 
ボタンをクリックして編集モードを Add Node に切り替えます。
Add Node モードではマウスを左クリックするとカーソル位置にノードが作成されます。
必要なノード(全部で12個)を作成します。作成する順番は特に気にする必要はありません。後で位置を調整するので正確に配置する必要もありません。
次にリンクを作成します。
Mode ラインの 
ボタンをクリックして編集モードを Add Link に切り替えます。
Add Link モードでは、まずリンクを設置したいノードを選択します。ノード上でマウスを左クリックするとそのノードが選択されます。
ノードが選択されるとマウスカーソルの移動に伴って設置可能なリンクが仮のリンク線として表示されます。
マウスを左クリックすると決定となり、リンクが作成されます。リンクの長さと幅はステータスラインの length 値と width フィールドの値になります。リンクの幅は後でまとめて設定するので width 値は入力しません。
リンクが作成されると選択状態が反対側のノードに移ります。ノードの選択を解除するにはマウスを右クリックするか ESC キーを押します。
必要なリンクをすべて作成します。
次にグリッドのスナップ機能を使ってノード・リンクの水平・垂直を整えます。
View メニューの Set grid を選択してください。グリッドの設定ダイアログが表示されます。
Grid width(m) と Grid height(m) の値を 0.2 に変更して OK ボタンをクリックしてください。
グリッドのスケールが変更されて細かくなります。
作業がし易くなる様に表示を少し拡大します。
View メニューの Centering with scaling を選択してください。丁度よいサイズにスケーリングされます。
なおスケーリングは自分で作業がし易くなる様に自由に変更して構いません。
Mode ラインの 
ボタンをクリックして編集モードを Edit Node に切り替えます。
Edit Node モードでは Shift キーを押しながらノード上でマウスの左ボタンを押してドラッグする事により、そのノードを移動する事が出来ます。グリッドのスナップ効果でノードは 20cm 単位で移動します。
ドア近くのノードから位置を整えていくと作業がし易いです。
すべてのノードの位置を整えて、リンクが水平または垂直になる様にします。
ノードを移動してもリンクの長さは変化しません。
リンク長がノード座標を元に計算した値と 10cm 以上差があると、リンクがオレンジ色で表示されます。
正しいリンク長にするため再計算して更新する必要があります。
Mode ラインの 
ボタンをクリックして編集モードを Edit Link に切り替えます。
次にマウスカーソルをマップ画面上に移動してから Ctrl キーを押しながら A を押してください。リンクが全て選択状態となり色が赤に変わります。
マウスを右クリックして Recalclate link length を選択してください。Recalclate link length ダイアログが表示されます。
そのまま OK をクリックしてください。これですべてのリンク長が再計算されて更新されました。
マウスカーソルをクリックしてリンクの選択を解除してください。オレンジ色だったリンクが黄色になっている事が確認できます。
次にリンクの幅を設定します。
下の図を参考にします。(長さの方は無視してください)
まず各部屋のリンクの幅を 6m に設定します。
Ctrl キーを押しながら Room 1, Room 2, Room 3 のリンクをマウスで左クリックしてください。3本のリンクが選択されたはずです。
リンクの選択状態を維持したまま、マウスを右クリックして Set link attributes を選択します。
リンク設定ダイアログが表示されたら width フィールドに 6.0 をセットして右側の Set ボタンをクリックしてください。
これで3つのリンクの幅が 6m に設定されました。
同じように通路上の4つのリンクの幅を 3m に設定します。
各部屋と通路の出入り口にあるドアのリンク幅は元々 1m なので設定する必要はありません。
次にノードとリンクにタグを付加します。
ここで付加するタグは、ジェネレーションファイルでエージェントの発生地点やゴール地点を設定するための識別子として使用します。
Room 1 のリンク上でマウスを右クリックして Set link attributes を選択します。 リンク設定ダイアログが表示されたら Add tag フィールドに "ROOM1" と入力して Add ボタンをクリックしてください。
タグが付加されたためマウスカーソルをリンクに重ねると ROOM1 と表示される様になります。
同じように Room 2, Room 3 のリンクにも "ROOM2", "ROOM3" とタグを付加してください。
また Room 1 と Room 2 の間の通路には "HALLWAY_1"、Room 2 と Room 3 の間の通路には "HALLWAY_2" とタグを付加してください。
次にノードにタグを付加します。
ボタンをクリックして Edit Node モードに切り替えます。
Exit の上に配置したノード上でマウスを右クリックして Set node attributes を選択します。
ノード設定ダイアログが表示されたら Add tag フィールドに "EXIT" と入力して Add ボタンをクリックしてください。
タグが付加されてノードに EXIT と表示されます。
タブをクリックしてください。
ノードタブに切り替わってノードの各パラメータが表示されます。EXIT タグが存在する事を確認してください。
次に 
タブをクリックしてください。
リンクタブに切り替わってリンクの各パラメータが表示されます。リンク幅やタグが正しくセットされている事を確認してください。
タブ画面のテーブルに表示されているノードやリンクをマウスで左クリックすると、マップ画面でクリックした時と同様に選択する事が出来ます。
右クリックした時も同様にコンテキストメニューを表示して操作する事が出来ます。
ネットワークマップはこれで完成です。
File メニューの Save map を選択してマップファイルに保存してください。(何も反応はありませんが保存されています)
マップエディタには沢山の機能があります。Help メニューの Quick reference で機能の一覧を確認する事が出来ます。
