CrowdWalk チュートリアル

このチュートリアルの内容

CrowdWalkとは
- 特徴
- 機能紹介
動作環境
インストールとアップデート
サンプルの実行
- basic-sample
- stop-sample2
シミュレーションの準備
- 必須ファイル
- その他のファイル
マップファイルの作成
ジェネレーションファイルの作成
シナリオファイルの作成
プロパティファイルの作成
シミュレーションの実行
- ログレベル
ログ出力
- ログの種類と出力フォーマット
- ログを出力する

ＣｒｏｗｄＷａｌｋとは

一次元空間モデルを採用し大規模群衆流動にも対応したマルチエージェント歩行者シミュレータです。
Java アプリケーションなので様々な OS 上で使用する事ができます。
CrowdWalk のソースコードは GitHub 上で管理されており、MIT ライセンスの下で誰でも無料で利用することができます。
CrowdWalk が用いる数理モデル(空間モデル、移動モデル)については、山下倫央・副田俊介・大西正輝・依田育士・野田五十樹(2012)『一次元歩行者モデルを用いた高速避難シミュレータの開発とその応用』情報処理学会論文誌 Vol.53 や、山下倫央・岡田崇・野田五十樹『大規模群集流動の制御に向けたシミュレーション環境の構築』JAWS2012 に解説されています。

特徴

network_model

ネットワークマップ

ネットワークマップとは、シミュレーションの舞台となる空間や構造物を定義したモデルデータの事です。
リンクとノードにより構成されたネットワーク構造を持ちます。災害エリアやポリゴンデータを含む場合もあります。
- リンク - 長さと幅を持つ直線状の領域で、道路や廊下、部屋などに相当します。内部に複数の仮想レーンを持ち、エージェントはこの仮想レーンの上を移動します。
- ノード - 座標と標高(あまり使われない)を持つ点です。リンクの終端、または接続点となります。
- 災害エリア - 津波や洪水による浸水、または有害ガスの発生を示す矩形領域です。エージェントの移動速度や生命状態に影響を与えます。
- ポリゴンデータ - 3D 用と 2D 用の2種類のタイプがあり、構造物や河川・海面の表示に使います。

エージェント

エージェントは人の歩行をシミュレーションします。
ソーシャルフォースモデルにより移動速度を計算しています。
エージェントの移動ルート:
- 基本的にエージェントは発生地点からゴール地点までの最短ルートを進みます。ただし途中の経由地点が設定されている場合は、最短ルートで経由地点を通過しながらゴールに向かいます。つまりエージェントの移動ルートはシミュレーション開始時に予め決まっています。
- 設定によりエージェントの移動ルールに特性を持たせる事も出来ます。その場合は上記の限りではありません。

機能紹介

マップエディタ

ネットワークマップの作成・編集をおこないます。

networkmap_editor

シミュレータ(CUI モード)

コンソールへのメッセージ表示のみでシミュレーションを実行します。 cui_simulator

シミュレータ(2D グラフィックモード)

真上から見下ろす形で進行状況を表示しながらシミュレーションを実行します。 2d_simulator

シミュレータ(3D グラフィックモード)

三次元上の任意の視点で進行状況を表示しながらシミュレーションを実行します。 3d_simulator

ログの出力

シミュレーションの過程や結果をログファイルに出力します。

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 以上であれば動作します。
- 動作確認済み
  - Linux: OpenJDK 19
  - Windows: Oracle JDK 17
  - macOS: Liberica JDK 17 x86 (M1の場合もx86エミュレーションを使用)
Ruby
- 特別なツールを実行する際に使うことがあります。通常の使用ではCrowdWalkのRubyスクリプト機能を使う場合も不要です。
テキストエディタ
- 各種設定ファイルの編集をおこないます。

使用している OS 上でこれらのソフトウェアが動作する様にセットアップをおこなってください。
Windows7 向けのセットアップ手順は CrowdWalk のセットアップに記載されています。

インストールとアップデート

以降の操作はすべて Bash のコマンドライン上でおこなうものとして解説します。またインストールはホームディレクトリ直下におこなうものとします。

まずは Bash を起動してコンソールウィンドウを開いてください。カレントディレクトリがホームディレクトリになっていなければホームディレクトリに移動してください。

注意!
GitHub からダウンロードしたファイルのファイル名・ディレクトリ名を変更すると git コマンドが正常に動作しなくなる場合があります。これらの変更はしない様に気を付けてください。

また、ダウンロードしたファイルの内容を変更するとgit pullコマンドが失敗してしまいます。
以下のコマンドで変更されたファイルをすべて元に戻すことができます。(変更したファイルが必要ならバックアップを取ってから実行してください)

git checkout .

ダウンロード

次のコマンドを実行して GitHub から CrowdWalk のソースコードをダウンロードします。

git clone https://github.com/crest-cassia/CrowdWalk.git

ダウンロードが完了すると以下のディレクトリ構成でファイルが作成されます。

Crowdwalk/
    crowdwalk/
    floodtocrowdwalk/
    img2movie/

crowdwalk
Crowdwalk 本体及びサンプルデータがあるディレクトリ。
通常はここをカレントディレクトリにして作業をおこないます。
floodtocrowdwalk
浸水データを元に、マップファイルに Area タグを埋め込むツール。
img2movie
FFmpeg を利用してスクリーンショット画像を動画に変換するツール。

※ GisToCrowdwalk は廃止されました。シェープファイルをマップファイルに変換するには、マップエディタの Edit / Read shapefile を使います。

ビルド

必要なライブラリをダウンロードして、ソースコードをコンパイルし、実行可能形式のアーカイブファイルにまとめるまでの一連の作業をビルドといいます。

CrowdWalk の作業ディレクトリに移動します。

cd ~/CrowdWalk/crowdwalk

ビルドコマンドを実行します。

./gradlew

初回実行時は大量のライブラリがダウンロードされるため、しばらく時間が掛かります。
問題なく終了したら BUILD SUCCESSFUL と表示されます。

動作確認

ビルドが完了したら動作確認します。

次のコマンドを実行して CrowdWalk のヘルプが表示されれば OK です。

sh quickstart.sh -h

スクリーンショット保存用ディレクトリの作成

スクリーンショット保存用のディレクトリをあらかじめ作成しておきます。プロパティファイルの設定により別のディレクトリにする事も可能です。

mkdir screenshots

アップデートの方法

CrowdWalk の作業ディレクトリに移動します。

cd ~/CrowdWalk/crowdwalk

次のコマンドを実行してソースコードを最新の状態に更新します。

git pull

ビルドコマンドを実行して再ビルドします。

./gradlew

サンプルの実行

sample ディレクトリにシミュレーションのサンプルファイルがいくつか用意されています。
_{※サンプルの中にはログファイルを出力するものもあるため注意してください。}

以下に実行手順を二つ示します。操作方法についても簡単に説明します。いずれも実行は CrowdWalk の作業ディレクトリ(~/CrowdWalk/crowdwalk)からおこないます。

basic-sample

三つの部屋と廊下を一次元空間モデルで表現したものです。各部屋からエージェントが発生し、右端にある出口に向かいます。

実行してみましょう。3D グラフィックモードでシミュレータを起動します。

sh quickstart.sh sample/basic-sample/properties.json -g

シミュレータが起動してウィンドウが開きます。

basic_sample_window01

3d_step_button ボタンをクリックしてください。シミュレーションがスタートしてエージェントが発生します。

basic_sample_window02

緑色で丸く表示されているのがエージェントです。一直線上に並んでいないのはレーン数分並列に歩行しているためです。(もともと表示がちょっとズレる傾向もあります)
エージェントは移動速度によって緑から赤へと色が変化します。

3d_step_button ボタンを何度かクリックしてください。シミュレーションが1秒ずつ進行していきます。これをステップ実行といいます。

basic_sample_window03

次に 3d_start_button ボタンをクリックしてください。ボタンが 3d_pause_button ボタンに切り替わり、シミュレーションが一瞬で最後まで進んで終了します。

basic_sample_window04

3d_pause_button ボタンをクリックして 3d_start_button に戻してから 3d_reset_button ボタンをクリックしてください。シミュレータが一旦終了して再起動します。

wait と表示されたスクロールバーを右端まで移動して値を 300 にしてから 3d_start_button ボタンをクリックしてください。今度はシミュレーションがゆっくり進行していきます。ステップ毎に 300 ミリ秒時間を置いているためです。

basic_sample_window05

シミュレーションが終了する前に 3d_pause_button ボタンをクリックしてください。シミュレーションが一時停止します。 3d_start_button ボタンをクリックするとシミュレーションが再開します。

マップが表示されている画面上でマウスの左ボタンを押しながらドラッグしてください。画面の中心を基準にしてマップが回転します。右ボタンを押しながらドラッグした場合にはマップが水平移動します。

basic_sample_window06

次にマウスホイールを前後に回してください。表示スケールが変わってマップに近づいたり遠ざかったりしている様に見えるはずです。

basic_sample_window07

次に 3d_view_tab をクリックしてタブパネルを View に切り替えてください。

basic_sample_window08

3d_centering_with_scaling ボタンをクリックすると最初の表示状態に戻ります。

basic_sample_window09

Help メニューの Quick reference でシミュレータの操作方法の一覧を確認する事が出来ます。

basic_sample_window10

stop-sample2

関門海峡花火大会を門司港側で見物していた観客の帰宅時の移動をシミュレーションしたものです。
観客は電車に乗って帰宅するため全員門司港駅に向かいます。門司港駅の入り口がゴールです。
道路上の複数の地点で交通整理(通行止/解除)がおこなわれます。また駅構内の混雑防止のため電車の発着に合わせて入構制限がおこなわれます。(残念ながら電車の発着の様子は表示されません)

今回はエージェント数が多いため、3D グラフィックモードよりも表示処理が軽い 2D グラフィックモードでシミュレータを起動します。また重要性の低い動作ログの表示を抑制するため -lError オプションを付加します。

sh quickstart.sh sample/stop-sample2/properties.json -g2 -lError

背景地図表示用の画像をダウンロードするため、シミュレータが起動するまでに2分半ほど時間が掛かります。一度ダウンロードした画像はキャッシュディレクトリに保存されるため以後ダウンロードされる事はありません。
シミュレータが起動してウィンドウが表示されると同時にシミュレーションがスタートします。

stop_sample_01

View タブの Show background map チェックボックスを ON にしてください。背景地図として写真(※)が表示されます。
※出典：国土地理院ウェブサイト

stop_sample_02

設定により背景地図を標準地図(※)にしたり、より解像度の高い写真にする事も出来ます。

stop_sample_03

現在、カメラワーク機能が有効になっています。この状態では設定データにより視点が決められ、マップの回転や拡大・縮小操作は無効となります。確認してみてください。
カメラワーク機能を解除するには Camera タブの Replay チェックボックスを OFF にします。

stop_sample_04

シミュレーションの準備

必須ファイル

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 で使用した必須ファイルを実際に作成しながら解説を進めていきます。

マップファイルの作成

この画像を基にマップファイルを作成します。
rooms
次の手順で作業を進めます。

準備。
グループの作成。
基となる画像を背景にセット。
画像の上にノードを作成。(仮置き)
ノードをつないでリンクを作成。
ノード・リンクの位置調整。
リンク幅を設定。
ノードとリンクにタグを付加。

始めにマップファイルを作成するための準備として保存先のディレクトリを作成します。
このディレクトリにはマップファイル以外にも各種設定ファイルやデータファイルが保存されます。まず、マップの元となる画像ファイルをコピーします。

コマンドラインで以下のコマンドを実行してください。

cd ~/CrowdWalk/crowdwalk
mkdir practice
cp sample/basic-sample/rooms.png practice

コマンドラインで次のコマンドを実行してマップエディタを起動します。CrowdWalk をオプションなしで起動するとマップエディタのウィンドウが開きます。

sh quickstart.sh

editor01

階層を持つ建物などの編集を容易にするため、ネットワークマップは内部をグループ化する構造を持っています。マップエディタは通常、グループ単位で編集をおこないます。
なおグループ構造はシミュレーションには一切影響を与えません。

現在の状態は root グループが存在するだけの、空のネットワークマップです。(空のネットワークマップでも root グループだけは存在します)
root グループに直接マップを作成すると後からグループを追加する事が出来なくなってしまうため、新たにグループを作ってそこにマップを作成します。
グループ名は "FLOOR" とします。

Groups タブの root を右クリックして Add group を選択してください。

editor_add_group

Add group ダイアログが表示されたら Tag フィールドに "FLOOR" と入力して OK ボタンをクリックしてください。

editor_add_group_dialog

FLOOR グループが追加され、カレントグループ(現在編集中のグループ)も FLOOR に変わりました。

editor02

マップエディタにはアンドゥー/リドゥー機能があり、操作の取り消し/再操作をする事が出来ます。Edit メニューで Undo または Redo を選択してもよいですが、Ctrl キーを押しながら Z でアンドゥー、Y でリドゥーと覚えておくと便利です。
アンドゥー回数に制限はありませんがマップファイルの保存をおこなうとリセットされます。また、ネットワークマップの変更を伴わない操作(表示スケールの変更など)にはアンドゥーは適用されません。

ここで一旦セーブしてマップファイルを作成します。マップファイルが存在していないと次の手順でおこなう背景画像のセット機能が使えないためです。

File メニューで Save map を選択してください。ファイル選択ダイアログが表示されたら、先程作成した "practice" ディレクトリに "test_model.xml" というファイル名で保存してください。

Save map メニューの選択でファイル選択ダイアログが表示されましたが、これはマップファイルがまだ存在していなかったためです。マップファイルが存在している場合にはファイル選択ダイアログは表示されず直ちに上書き保存となります。
Save map as メニューを選択すれば常にファイル選択ダイアログが表示されます。

次に背景画像のセットをおこないますが、その前に編集画面のスケールを、作成するマップに合わせておきます。

View メニューで Show grid を選択してください。編集画面にグリッドが表示されます。

editor03

左上に表示されている通り、グリッドのスケールは 10m × 10m です。
通路の長さは 20m なので表示スケールをこれに合わせて変更します。また、マップはなるべく座標原点付近に作る様にします。

画面上でマウスの右ボタンを押しながら右斜め下方向にドラッグしてください。座標原点を示す赤いクロスが現れます。

editor04

マウスカーソルを原点(クロスの交点)に合わせてマウスホイールを回転してください。
表示スケールが変わってグリッドの間隔が変化している事が分かります。ウィンドウ下側のステータスラインには現在のスケール値が表示されます。
適当な表示スケールになるまでマウスホイールを回します。

editor05

Mode ラインの 3d_background_image_button ボタンをクリックして編集モードを Background Image に切り替えます。

editor06

マウスカーソルを原点に合わせてから右クリックして、Set background image を選択してください。

editor07

ファイル選択ダイアログが表示されたら "practice" ディレクトリの画像ファイル "rooms.png" を選択してください。先ほど右クリックした時の位置に背景画像としてセットされます。

editor08

Background Image モードではマウスホイールを回転すると背景画像が拡大・縮小されます。Ctrl キーを押しながらマウスホイールを回転すると微調整(1/10単位での拡大・縮小)になります。
また、Shift キーを押しながらマウスの左ボタンを押してドラッグすると背景画像を移動する事が出来ます。
これらの操作を組み合わせて通路の長さが 20m になる様に拡大し、部屋の左上の角が原点に当たる様に位置を調整します。

editor09

背景画像のセットはこれで完了です。

次にノードを作成します。
Mode ラインの 3d_add_node_button ボタンをクリックして編集モードを Add Node に切り替えます。

editor10

Add Node モードではマウスを左クリックするとカーソル位置にノードが作成されます。
必要なノード(全部で12個)を作成します。作成する順番は特に気にする必要はありません。後で位置を調整するので正確に配置する必要もありません。

editor11

次にリンクを作成します。
Mode ラインの 3d_add_link_button ボタンをクリックして編集モードを Add Link に切り替えます。
Add Link モードでは、まずリンクを設置したいノードを選択します。ノード上でマウスを左クリックするとそのノードが選択されます。
ノードが選択されるとマウスカーソルの移動に伴って設置可能なリンクが仮のリンク線として表示されます。

editor12

マウスを左クリックすると決定となり、リンクが作成されます。リンクの長さと幅はステータスラインの length 値と width フィールドの値になります。リンクの幅は後でまとめて設定するので width 値は入力しません。

リンクが作成されると選択状態が反対側のノードに移ります。ノードの選択を解除するにはマウスを右クリックするか ESC キーを押します。

editor13

必要なリンクをすべて作成します。

editor14

次にグリッドのスナップ機能を使ってノード・リンクの水平・垂直を整えます。
View メニューで Set grid を選択してください。グリッドの設定ダイアログが表示されます。

set_grid

Grid width(m) と Grid height(m) の値を 0.2 に変更して OK ボタンをクリックしてください。
グリッドのスケールが変更されて細かくなります。

editor15

作業がし易くなる様に表示を少し拡大します。
View メニューで Centering with scaling を選択してください。丁度よいサイズにスケーリングされます。
なおスケーリングは自分で作業がし易くなる様に自由に変更して構いません。

editor16

Mode ラインの edit_node_button ボタンをクリックして編集モードを Edit Node に切り替えます。
Edit Node モードでは Shift キーを押しながらノード上でマウスの左ボタンを押してドラッグする事により、そのノードを移動する事が出来ます。グリッドのスナップ効果でノードは 20cm 単位で移動します。
ドア近くのノードから位置を整えていくと作業がし易いです。

editor17

すべてのノードの位置を整えて、リンクが水平または垂直になる様にします。

editor18

ノードを移動してもリンクの長さは変化しません。
リンク長がノード座標を元に計算した値と 10cm 以上差があると、リンクがオレンジ色で表示されます。
正しいリンク長にするため再計算して更新する必要があります。

Mode ラインの edit_link_button ボタンをクリックして編集モードを Edit Link に切り替えます。
次にマウスカーソルをマップ画面上に移動してから Ctrl キーを押しながら A を押してください。リンクが全て選択状態となり色が赤に変わります。

editor19

マウスを右クリックして Recalclate link length を選択してください。Recalclate link length ダイアログが表示されます。

recalc_link_length

そのまま OK をクリックしてください。これですべてのリンク長が再計算されて更新されました。

マウスカーソルをクリックしてリンクの選択を解除してください。オレンジ色だったリンクが黄色になっている事が確認できます。

editor21

次にリンクの幅を設定します。
下の図を参考にします。(長さの方は無視してください)

editor22

まず各部屋のリンクの幅を 6m に設定します。
Ctrl キーを押しながら Room 1, Room 2, Room 3 のリンクをマウスで左クリックしてください。3本のリンクが選択されたはずです。
リンクの選択状態を維持したまま、マウスを右クリックして Set link attributes を選択します。

editor23

リンク設定ダイアログが表示されたら width フィールドに 6.0 をセットして右側の Set ボタンをクリックしてください。

set_link_attr1

これで3つのリンクの幅が 6m に設定されました。

同じように通路上の4つのリンクの幅を 3m に設定します。
各部屋と通路の出入り口にあるドアのリンク幅は元々 1m なので設定する必要はありません。

次にノードとリンクにタグを付加します。

ここで付加するタグは、ジェネレーションファイルでエージェントの発生地点やゴール地点を設定するための識別子として使用します。

Room 1 のリンク上でマウスを右クリックして Set link attributes を選択します。リンク設定ダイアログが表示されたら Add tag フィールドに "ROOM1" と入力して Add ボタンをクリックしてください。

set_link_attr2

タグが付加されたためマウスカーソルをリンクに重ねると ROOM1 と表示される様になります。

editor26

同じように Room 2, Room 3 のリンクにも "ROOM2", "ROOM3" とタグを付加してください。
また Room 1 と Room 2 の間の通路には "HALLWAY_1"、Room 2 と Room 3 の間の通路には "HALLWAY_2" とタグを付加してください。

editor27

次にノードにタグを付加します。

edit_node_button ボタンをクリックして Edit Node モードに切り替えます。
Exit の上に配置したノード上でマウスを右クリックして Set node attributes を選択します。

editor28

ノード設定ダイアログが表示されたら Add tag フィールドに "EXIT" と入力して Add ボタンをクリックしてください。

editor29

タグが付加されてノードに EXIT と表示されます。

editor30

editor_nodes_tab_button タブをクリックしてください。
ノードタブに切り替わってノードの各パラメータが表示されます。EXIT タグが存在する事を確認してください。

editor31

次に editor_links_tab_button タブをクリックしてください。
リンクタブに切り替わってリンクの各パラメータが表示されます。リンク幅やタグが正しくセットされている事を確認してください。

editor32

タブ画面のテーブルに表示されているノードやリンクをマウスで左クリックすると、マップ画面でクリックした時と同様に選択する事が出来ます。
右クリックした時も同様にコンテキストメニューを表示して操作する事が出来ます。

ネットワークマップはこれで完成です。
File メニューで Save map を選択してマップファイルに保存してください。(何も反応はありませんが保存されています)

マップエディタには沢山の機能があります。Help メニューの Quick reference で機能の一覧を確認する事が出来ます。

editor_reference

ジェネレーションファイルの作成

設定項目

ジェネレーションファイルには以下の設定項目があります。

生成ルール(rule)
ルール名(name)
エージェントクラス名(agentType/className)
速度モデル(speedModel)
発生場所(startPlace)
発生時刻(startTime)
発生終了判定時刻(everyEndTime) - TIMEEVERY 専用
発生時刻間隔(everySeconds) - TIMEEVERY 専用
発生期間(duration)
発生人数(total)
各リンク・ノードから発生するエージェント数の上限(maxFromEach) - EACHRANDOM 専用
ゴール(goal)
経由地(plannedRoute)
エージェントに付与するタグ(condition)
個別パラメータ(individualConfig) - INDIVIDUAL 専用

1. 生成ルール

エージェントの生成ルールです。

設定のキー: rule
設定値: EACH, RANDOM, TIMEEVERY, INDIVIDUAL, RUBY
デフォルト値: EACH

EACH
指定したタグを持つすべてのリンクとノードから、それぞれ発生人数(total)のエージェントが発生する。
エージェントの総数は、発生したリンク・ノード数×発生人数(total)となる。
RANDOM
指定したタグを持つすべてのリンクとノードから、ランダムにエージェントが発生する。
エージェントの総数は発生人数(total)となる。
EACHRANDOM
RANDOMと同じだが、タグを持つ各リンク・ノードからは、最低1エージェントは発生する。（エージェントの発生しないリンク・ノードはない）
TIMEEVERY
発生時刻(startTime)から発生終了判定時刻(everyEndTime)までの間、発生時刻間隔(everySeconds)周期でエージェントが発生する。
エージェントの総数は、発生人数(total)×エージェント発生サイクル数となる。
INDIVIDUAL
individualConfig によって、個別のパラメータ、開始時刻でエージェントが生成される。
individualConfig によって指定されないものは、ルール共通のパラメータが指定される。
RUBY
Ruby script による generation を行う。
"class" で指定された Ruby のクラス(AgentFactoryBase class の派生クラス) のインスタンスが生成される。
"config" に、このルール専用のパラメータをJSONで指定できる。

2. ルール名

ルールの識別に使われる名前です。
省略すると rule の index (前から順につけられた番号の文字列)が付けられます。

設定のキー: name
設定値: 任意の文字列

3. エージェントクラス名

エージェントの性質を表す名前です。
CrowdWalk のソースコードのエージェントクラス名に相当します。

設定のキー: agentType/className
設定値: NaiveAgent, CapriciousAgent, BustleAgent, RationalAgent, RubyAgent
デフォルト値: NaiveAgent

NaiveAgent
素朴なエージェント。各種エージェントクラスのベースにするもの。
CapriciousAgent
気まぐれなエージェント。
BustleAgent
せわしないエージェント。
RationalAgent
理性のある、ルールに基づいて行動するエージェント。
RubyAgent
制御に Ruby スクリプトを呼び出すエージェント。

クラス継承関係と追加パラメータ:

NaiveAgent
- CapriciousAgent
  "margin" : double - 距離コストに重畳するノイズの大きさ。一様乱数。
- BustleAgent
  "weight" : double - 混雑度合いの重視度を表す値。
  "trail" : double - すでに通った道を避ける度合い。
  - RationalAgent
    "margin" : double - 距離コストに重畳するノイズの大きさ。一様乱数。
    "rule" : ThinkRule - 思考ルール: Rational Agent と ThinkEngine 参照。
    - RubyAgent
      "rubyAgentClass" : String - Ruby 内でのクラス名

4. 速度モデル

エージェントの速度計算モデルです。

設定のキー: speedModel
設定値: LANE, PLAIN, CROSSING
デフォルト値: CROSSING

LANE
前方一人の SocialForce しか考えない。
PLAIN
ある程度前方までの順方向・逆方向の SocialForce を計算。
CROSSING
PlainModel に加え、node における交差する人流の force も計算。

5. 発生場所

エージェントを発生させるリンクまたはノードです。

設定のキー: startPlace
設定値: リンクまたはノードのタグ

6. 発生時刻

エージェントの発生を開始する時刻です。

設定のキー: startTime
設定値: 時:分(07:30) または時:分:秒(07:30:00) 形式

7. 発生終了判定時刻

生成ルールが TIMEEVERY の時に、エージェント発生サイクルの終わりを判定する時刻です。(エージェントの発生を終了する時刻ではありません)
発生周期毎の時刻 ≦ everyEndTime の間、エージェントの発生が繰り返されます。

設定のキー: everyEndTime
設定値: 時:分(08:30) または時:分:秒(08:30:00) 形式

8. 発生時刻間隔

生成ルールが TIMEEVERY の時の、エージェント発生サイクルの周期です。
発生期間(duration)よりも短くならない様にしてください。

設定のキー: everySeconds
設定値: 秒数

9. 発生期間

エージェントの発生を開始してから全員の発生が完了するまでの期間です。
発生時刻になったら一度に全員を発生させる場合は 1 にします。
発生時刻から60秒間かけて(07:30 に発生開始なら 07:30:00～07:30:59)発生させる場合は 60 にします。

設定のキー: duration
設定値: 秒数

10. 発生人数

発生するエージェントの数です。
生成ルールが TIMEEVERY の時には、発生するエージェントの総数は「この数×エージェント発生サイクル数」となります。

設定のキー: total
設定値: 人数

11. 各リンク・ノードから発生するエージェント数の上限

生成ルールが EACHRANDOM の時に、指定したタグを持つ各リンク・ノードから発生するエージェント数の上限です。
「この数×指定したタグを持つリンク・ノード数」が発生人数(total)よりも小さかった場合には、発生するエージェントの総数は「この数×指定したタグを持つリンク・ノード数」になります。

設定のキー: maxFromEach
設定値: 人数

12. ゴール

エージェントの最終的な目的地のノードです。
該当するノードが複数あった場合には最も近いノードに向かいます。

設定のキー: goal
設定値: ノードのタグ

13. 経由地

エージェントがゴールに到着するまでに経由するノードまたはリンク(待機設定時)です。
経由地にはノードタグまたは待機設定を混在させて複数指定する事が出来ます。

経由地を複数指定した場合には、指定した順番に経由して行きます。
該当するタグの経由地が複数ある場合には最短の経由地へと向かい、それ以外は無視します。

設定のキー: plannedRoute
設定値: ノードタグまたは待機設定の配列

13-1. 待機設定

特定のリンク内にエージェントを一時的に留めておくための設定です。
以下の設定項目があります。

待機名(): WAIT_FOR または WAIT_UNTIL
- WAIT_FOR はエージェントが待機リンクに入ってから待機時間の間待機させます。
- WAIT_UNTIL はエージェントが待機リンクに入ってから、待機リンクにトリガータグが付加されるまで待機させます。
  トリガータグの付加設定はシナリオファイルでおこないます。
待機リンク(target): 待機させるリンクのタグを指定します。
待機方法(how): エージェントが待機している間の並び方を SCATTER または PACK で指定します。
- SCATTER はリンク内で前後の間隔を均等に空けて待機します。
- PACK はリンク内で前方に詰めて待機します。
待機時間(until): WAIT_FOR での待機時間を秒数で指定します。
トリガー(until): WAIT_UNTIL での待機を解除するトリガーとなるタグを指定します。

14. エージェントに付与するタグ

設定のキー: condition
設定値: タグの配列

15. 個別パラメータ

INDIVIDUAL 専用。

設定のキー: individualConfig

エージェントの発生からゴールまでのシナリオ

ジェネレーションファイルの作成に当たって、まず basic-sample でのエージェントの発生条件・振る舞い・目的地を具体的に定義してみます。

07:30:00 に三つの部屋(ROOM1, ROOM2, ROOM3)でそれぞれ5人のエージェントが発生する。それ以後エージェントは発生しない。
全員が出口(EXIT)を目指して(寄り道せずに)進む。
1番目の部屋(ROOM1)で発生したエージェントは、途中の廊下(HALLWAY_1)に入ると前後の間隔を均等に空けて 07:30:50 まで留まり、その後再び歩き出す。
2番目の部屋(ROOM2)で発生したエージェントは、途中の廊下(HALLWAY_2)に入ると前方に詰めて30秒間留まり、その後再び歩き出す。

以上がエージェントの発生からゴールまでのシナリオとなります。
このシナリオに従ってジェネレーションファイルを作成します。

ＣＳＶ形式のジェネレーションファイル作成

CSV 形式のジェネレーションファイルは旧形式のため詳細な設定は出来ません。しかし Excel 等を使って表形式で編集する事が可能なため、大量の設定を含むジェネレーションファイルの作成やメンテナンスが楽に出来るというメリットがあります。

基本的な書式は次の通りです。条件の異なる設定を何行でも書く事が出来ます。

生成ルール,発生場所,発生時刻,発生期間,発生人数,ゴール,経由地/待機設定,...
                            EACHRANDOM の場合は
EACHRANDOM,発生場所,発生時刻,発生期間,発生人数,発生数の上限,ゴール,経由地/待機設定,...
                            TIMEEVERY の場合は
TIMEEVERY,発生場所,発生時刻,発生終了判定時刻,発生時刻間隔,発生期間,発生人数,ゴール,経由地/待機設定,...

まず生成ルールを指定します。
決まった場所から一定時間内(この場合は1秒間)に一定数のエージェントを発生させる生成ルールは EACH です。
EACH はデフォルトの生成ルールなので省略します。

次に発生場所のリンクまたはノードを指定します。指定にはマップエディタで付加したタグを使います。
この場合は ROOM1, ROOM2, ROOM3 ですが、まとめて指定する事は出来ないため設定を複数行に分けてそれぞれの行で指定します。

次に発生時刻を指定します。
07:30:00 とそのまま指定するか秒を省略して 07:30 とします。

次に発生期間を指定します。
発生時刻の 07:30:00 に発生人数分を全員発生させるので 1 (秒間)となります。

次に発生人数を指定します。
発生場所ごとに5人なので 5 とします。

次にゴールを指定します。
EXIT ノードがゴールなので EXIT とします。

最後に経由地/待機設定を指定します。
ROOM1 と ROOM2 で発生したエージェントは途中の廊下で一定時間待機するので、その設定を待機設定でおこないます。
待機設定の CSV 形式の書式は次の通りです。

WAIT_FOR(待機リンク,待機方法,待機時間)
            または
WAIT_UNTIL(待機リンク,待機方法,トリガー)

ROOM1 で発生したエージェントは途中の廊下(HALLWAY_1)に入ると前後の間隔を均等に空けて 07:30:50 まで留まるので、

WAIT_UNTIL を使用
待機リンクは HALLWAY_1
待機方法は SCATTER
トリガータグは RESUME とする

以上により WAIT_UNTIL(HALLWAY_1,SCATTER,RESUME) となります。

ROOM2 で発生したエージェントは途中の廊下(HALLWAY_2)に入ると前方に詰めて30秒間留まるので、

WAIT_FOR を使用
待機リンクは HALLWAY_2
待機方法は PACK
待機時間は 30 秒

以上により WAIT_FOR(HALLWAY_2,PACK,30) となります。

ROOM3 で発生したエージェントはそのまま EXIT に向かうのでこの設定はありません。

以上の設定をまとめるとジェネレーションファイルの内容は次の様になります。

ROOM1,07:30,1,5,EXIT,WAIT_UNTIL(HALLWAY_1,SCATTER,RESUME)
ROOM2,07:30,1,5,EXIT,WAIT_FOR(HALLWAY_2,PACK,30)
ROOM3,07:30,1,5,EXIT

この内容をテキストエディタで作成して "practice" ディレクトリに "test_generation.csv" というファイル名で保存してください。

ＪＳＯＮ形式のジェネレーションファイル作成

JSON 形式のジェネレーションファイルの書式は、先頭行に #{"version": 2} を付けて(省略不可)、配列の中に個々の設定をオブジェクトで記述します。AgentFactoryList.java の、冒頭のコメントを参照してください。

生成ルールは EACH なので "rule":"EACH" とします。
表記方法を明示するため今回はデフォルト値でも省略はしません。

エージェントクラス名はデフォルトエージェントの NaiveAgent を使用するので "agentType":{"className":"NaiveAgent"} とします。

速度モデルもデフォルト値を使用して "speedModel":"CROSSING" とします。

発生場所はそれぞれ "startPlace":"ROOM1", "startPlace":"ROOM2", "startPlace":"ROOM3" とします。

発生時刻は "startTime":"07:30" とします。

発生期間は "duration":1 とします。

発生人数は "total":5 とします。

ゴールは "goal":"EXIT" とします。

経由地/待機設定は ROOM1 が

"plannedRoute":[{
    "":WAIT_UNTIL,
    "target":"HALLWAY_1",
    "how":"SCATTER",
    "until":"RESUME"
}]

ROOM2 が

"plannedRoute":[{
    "":WAIT_FOR,
    "target":"HALLWAY_2",
    "how":"PACK",
    "until":30
}]

ROOM3 には経由地も待機設定もないので "plannedRoute":[] とします。
いずれもインデントや改行は任意です。

以上の設定をまとめるとジェネレーションファイルの内容は次の様になります。

#{"version": 2}
[
    {
        "rule":"EACH",
        "agentType":{"className":"NaiveAgent"},
        "speedModel":"CROSSING",
        "startPlace":"ROOM1",
        "startTime":"07:30",
        "duration":1,
        "total":5,
        "goal":"EXIT",
        "plannedRoute":[{
            "":WAIT_UNTIL,
            "target":"HALLWAY_1",
            "how":"SCATTER",
            "until":"RESUME"
        }]
    },
    {
        "rule":"EACH",
        "agentType":{"className":"NaiveAgent"},
        "speedModel":"CROSSING",
        "startPlace":"ROOM2",
        "startTime":"07:30",
        "duration":1,
        "total":5,
        "goal":"EXIT",
        "plannedRoute":[{
            "":WAIT_FOR,
            "target":"HALLWAY_2",
            "how":"PACK",
            "until":30
        }]
    },
    {
        "rule":"EACH",
        "agentType":{"className":"NaiveAgent"},
        "speedModel":"CROSSING",
        "startPlace":"ROOM3",
        "startTime":"07:30",
        "duration":1,
        "total":5,
        "goal":"EXIT",
        "plannedRoute":[]
    }
]

この内容をテキストエディタで作成して "practice" ディレクトリに "test_generation.v2.json" というファイル名で保存してください。

シナリオファイルの作成

イベント

シナリオファイルの中で使用できるイベントには以下のものがあります。

Initiate
Finish
Alert
AddTag
RemoveTag
ShutOff
OpenGate
CloseGate
Dump
Null
Pause

1. Initiate

シミュレーションを開始します。

書式:

{
    "type" : "Initiate",
    "atTime" : __Time__
}

Time ::= "hh:mm:ss"

2. Finish

シミュレーションを終了します。

書式:

{
    "type" : "Finish",
    "atTime" : __Time__
}

Time ::= "hh:mm:ss"

3. Alert

指定した場所のエージェントにメッセージを伝えます。

書式:

{
    "type" : "Alert",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
    ("onoff" : ( true | false ),)?
    "message" : __String__
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかを指定する。
"message" の利用は RationalAgent の listenAlert を参照。

4. AddTag

リンクまたはノードにタグを追加します。

書式:

{
    "type" : "AddTag",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
    ("onoff" : ( true | false ),)?
    "noticeTag" : __Tag__
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかを指定する。

5. RemoveTag

リンクまたはノードからタグを除去します。

書式:

{
    "type" : "RemoveTag",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
    ("onoff" : ( true | false ),)?
    "noticeTag" : __Tag__
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかを指定する。

6. ShutOff

指定した場所のエージェント生成をやめます。

書式:

{
    "type" : "ShutOff",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかを指定する。

7. OpenGate

指定したタグを持つリンク・ノードの、指定したタグのゲートを開きます。

書式:

{
    "type" : "OpenGate",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
    "gateTag" : __Tag__
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかで場所を指定する。

8. CloseGate

指定したタグを持つリンク・ノードの、指定したタグのゲートを閉じます。

書式:

{
    "type" : "CloseGate",
    "atTime" : __Time__,
    ("placeTag" : __Tag__, | "placeId" : __Int__,)
    "gateTag" : __Tag__
}

Time ::= "hh:mm:ss"
"placeTag" もしくは "placeId" のいずれかで場所を指定する。

9. Dump

This event cause to interrupt simulation and make a log dump.

書式:

{
    "type" : "Dump" 
    "atTime" : __Time__,
    "format" : "GenerationFile",
    "filename" : __FileName__
}

Time ::= "hh:mm:ss"

10. Null

An event to do nothing. All attributes are ignored. So, it can be used as an commented event.

書式:

{
    "type" : "None",
    ...
}

11. Pause

An event to pause the running simulation. This is effective only in Gui mode. In Cui mode, it will be ignored.

書式:

{
    "type" : "Pause",
    "atTime" : __Time__
}

Time ::= "hh:mm:ss"

シミュレーションのシナリオ

シナリオファイルの作成に当たって basic-sample でのシミュレーションのシナリオを定義してみます。

シミュレーションを開始する。
エージェントの発生からゴールまでのシナリオが進行する。
WAIT_UNTIL によるエージェントの待機を 07:30:50 に解除する。

このシナリオに従ってシナリオファイルを作成します。

ＪＳＯＮ形式のシナリオファイル作成

シナリオファイルには CSV 形式と JSON 形式がありますが、CSV 形式は扱い難く機能も制限されるため解説は省略します。
JSON 形式のジェネレーションファイルの書式は、配列の中に個々のイベント設定をオブジェクトで記述します。インデントや改行は任意です。

[
    __Event__,
    __Event__,
    ...
]

まずシミュレーション開始のイベントを記述します。
07:30 に最初のエージェントが発生するので、シミュレーションの開始も 07:30 にします。(もっと前に開始しても構いません)

    {
        "type"      : "Initiate",
        "atTime"    : "07:30:00"
    }

エージェントの発生からゴールまでのシナリオは、主にジェネレーションファイルの担当です。

次に、ジェネレーションファイルの WAIT_UNTIL 設定によるエージェントの待機を解除するためのイベントを記述します。
07:30:50 にリンク HALLWAY_1 にタグ RESUME を追加します。

    {
        "type"      : "AddTag",
        "atTime"    : "07:30:50",
        "placeTag"  : "HALLWAY_1",
        "noticeTag" : "RESUME"
    }

以上の設定をまとめるとシナリオファイルの内容は次の様になります。

[
    {
        "type"      : "Initiate",
        "atTime"    : "07:30:00"
    },
    {
        "type"      : "AddTag",
        "atTime"    : "07:30:50",
        "placeTag"  : "HALLWAY_1",
        "noticeTag" : "RESUME"
    }
]

この内容をテキストエディタで作成して "practice" ディレクトリに "test_scenario.json" というファイル名で保存してください。

プロパティファイルの作成

ＪＳＯＮ形式のプロパティファイルの書式

{
    "設定項目" : 設定値,
            ・
            ・
            ・
    "設定項目" : 設定値
}

プロパティファイルの設定項目

プロパティファイルには以下の設定項目があります。

設定必須項目
- map_file
- generation_file
- scenario_file
基本的な設定
- fallback_file
- randseed
- all_agent_speed_zero_break
- exit_count
- mental_map_rules
- use_relative_path_from_prop
- disable_no_hint_for_goal_log
- legacy
Rubyスクリプトに関する設定
- use_ruby
- ruby_load_path
- ruby_init_script
- ruby_simulation_wrapper_class
災害データに関する設定
- pollution_file
- interpolation_interval
- pollution_type
- pollution_color_saturation
- pollution_color
ログ出力に関する設定
- evacuated_agents_log_file
- node_order_of_evacuated_agents_log
- agent_movement_history_file
- agent_trail_log
- individual_pedestrians_log_dir
- create_log_dirs
GUIシミュレータに関する設定
- スクリーンショットに関する設定
  - record_simulation_screen
  - screenshot_dir
  - clear_screenshot_dir
  - screenshot_image_type
- シミュレーションの進行に関する設定
  - simulation_window_open
  - auto_simulation_start
  - defer_factor
  - exit_with_simulation_finished
- カメラワークの設定
  - camera_file
  - camera_2d_file
- 表示に関する設定
  - link_appearance_file
  - node_appearance_file
  - polygon_appearance_file
  - agent_appearance_file
  - background_color
  - vertical_scale
  - agent_size
  - agent_size_2d
  - agent_size_3d
  - zoom
  - show_links_at_actual_width
  - outline_color
  - show_background_image
  - color_depth_of_background_image
  - coastline_file
  - show_the_sea
  - centering_by_node_average
  - change_agent_color_depending_on_speed
  - drawing_agent_by_triage_and_speed_order
  - show_status
  - show_logo
- 背景地図表示に関する設定
  - zone
  - gsi_tile_name
  - gsi_tile_zoom
  - show_background_map
  - color_depth_of_background_map
マップエディタに関する設定
- rotation_angle
- rotation_angle_locking
- osm_conversion_file

設定必須項目

map_file

マップファイルへのパス

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
generation_file

ジェネレーションファイルへのパス

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
scenario_file

シナリオファイルへのパス

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。

基本的な設定

fallback_file

Fallback ファイル(デフォルトセッティング値を記述した JSON ファイル) へのパス
このファイルの内容はリソースデータ "fallbackParameters.json" の内容よりも優先される。

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
デフォルト値：なし
randseed

乱数発生のシード

設定値：整数値
デフォルト値：なし(シード指定なし)
all_agent_speed_zero_break

全エージェントが停止したらシミュレーションを止めるかどうか。

設定値： true | false
デフォルト値： true
exit_count

シミュレーションを終了するステップ値

設定値： 0 以上の整数
デフォルト値： 0(自然に終了させる)
mental_map_rules
- 探索において、各リンクの主観的距離の変更ルールを記述。
設定値：ルールを表す JSON 形式の式。
デフォルト値： null
ルールの記述方法：PathChooser
use_relative_path_from_prop

各種ファイルの指定の相対パスが、このプロパティファイルの位置からの相対パスを使うかどうか。
false に設定するとカレントディレクトリからの相対パスとなる。

設定値： true | false
デフォルト値： true
disable_no_hint_for_goal_log

ワーニングメッセージ [No hint for goal] の出力を抑制する。

設定値： true | false
デフォルト値： false
legacy

legacy モードで実行する。
GUI シミュレータで "POLYGON", "OCEAN", "STRUCTURE" タグが従来通りポリゴン(と色付け)の識別子として扱われる。

設定値： true | false
デフォルト値： false

Rubyスクリプトに関する設定

use_ruby

Ruby Engine を使うかどうか。

設定値： true | false
デフォルト値： false
ruby_load_path

Ruby の標準の LOAD_PATH に追加するパス。
複数のパスを追加する場合には、改行で区切る。

設定値：改行区切りの path 文字列。
デフォルト値： ""
ruby_init_script

Ruby Engine 初期化のスクリプト。
一般に、"require 'file'" 等を指定するが、基本、ruby の式なら何でもOK。

設定値： ruby の script の文字列。
デフォルト値： ""
ruby_simulation_wrapper_class

updateEveryTick() などのシミュレーション実行制御用のRubyクラス。
CrowdWalkSimulator クラスを継承していることが望ましい。
シミュレーションの初期化でインスタンスが作成され、EvacuationSimulatorのインスタンスが @body にセットされる。
updateEveryTick() の先頭で preCycle(time) が、終わりに postCycle(time) が呼ばれる。
空文字列もしくは null なら、インスタンスは生成しない。

設定値： ruby クラス名。
デフォルト値： null

災害データに関する設定

pollution_file

Obstructer ファイル(ポリューションファイル)へのパス
この設定をおこなうとシミュレーションに災害状況が反映される様になる。

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
デフォルト値：なし
interpolation_interval

Obstructer データを時間ごとに線形補間する間隔(秒数)

設定値： 0 補間なし
　　　　 1 ～この間隔で補間する
デフォルト値： 0
pollution_type

Obstructer type の設定

設定値： Flood 浸水によるエージェントへの影響
　　　　 Pollution ガスによるエージェントへの影響
デフォルト値： Flood
pollution_color_saturation

彩度100%に相当する Obstructer データの値
pollution_color が blue で pollution_color_saturation が 5.0 ならば、Obstructer データが 5.0(水位 5m)以上は完全な青で表示される。

設定値： 0.0 ～
デフォルト値： 0.0
pollution_color

Obstructer の表示色
Obstructer データの値が大きいほど濃い色で表示される。

設定値： hsv 色相の変化
　　　　 red 赤
　　　　 blue 青
　　　　 orange オレンジ色
デフォルト値： orange

ログ出力に関する設定

evacuated_agents_log_file

ゴールノード別の脱出エージェント数をステップごとに記録するログ
ログファイルのパス設定をするとログが出力される。

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
デフォルト値：なし
node_order_of_evacuated_agents_log

evacuated_agents_log の出力カラムの並び順

設定値：ゴールノードを示すタグをカンマで区切って並べる。
　　　　ゴールノードがすべて揃っている必要はない
デフォルト値：なし
agent_movement_history_file

ゴールまでたどり着いた各エージェントの発生時刻、到着時刻、移動時間のログ。
ログファイルのパス設定をするとログが出力される。

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
デフォルト値：なし
ログの記述内容：AgentHandler.agentMovementHistoryLoggerFormatter
agent_trail_log

ゴールまでたどり着いたエージェントのゴールした時点でのJSON形式のログ。

ログの記述内容：AgentHandler.agentTrailLogFormatter
設定値：AgentHandler.setupAgentTrailLogger()
デフォルト値：なし
individual_pedestrians_log_dir

個別のエージェントに対するログデータを保管する場所の指定
ディレクトリを指定した時のみログを収集する。

設定値：ディレクトリへの絶対パス | 相対パス
デフォルト値：なし
ログの記述内容：AgentHandler.individualPedestriansLoggerFormatter
create_log_dirs

ログおよびスクリーンショットのディレクトリがなかった時、自動生成するかどうか。

設定値： true | false
デフォルト値： false

GUIシミュレータに関する設定

スクリーンショットに関する設定
- record_simulation_screen
  
  シミュレーション画面のスクリーンショットを記録する
  ※clear_screenshot_dir が true ではなく、かつ出力先ディレクトリに画像ファイルが存在する場合はエラー終了する。
  ※この設定をtrueにすると、シミュレーションが遅くなる。
  
  設定値： true | false
  デフォルト値： false
- screenshot_dir
  
  シミュレーション画面のスクリーンショットを保存するディレクトリ
  
  設定値：ディレクトリへの絶対パス | 相対パス
  デフォルト値： screenshots
- clear_screenshot_dir
  
  スクリーンショットディレクトリに存在する画像ファイル(.bmp|.gif|.jpg|.png)をすべて削除する。
  ※有効にするためには screenshot_dir の設定が必要
  
  設定値： true | false
  デフォルト値： false
- screenshot_image_type
  
  スクリーンショットの画像ファイル形式
  
  設定値： bmp | gif | jpg | png
  デフォルト値： png
シミュレーションの進行に関する設定
- simulation_window_open
  
  CrowdWalk をオプションなしで起動した時に、マップエディタの起動とともにシミュレーションウィンドウも開く
  
  設定値： true | false
  デフォルト値： false
- auto_simulation_start
  
  起動とともにシミュレーションを開始する
  
  設定値： true | false
  デフォルト値： false
- defer_factor
  
  1ステップごとの待ち時間(ミリ秒単位)
  この設定値を小さくするとシミュレーションは早く進み、大きくするとシミュレーションは遅く進む。
  早 0←--------→299 遅
  
  設定値： 0～299
  デフォルト値： 0
- exit_with_simulation_finished
  
  シミュレーションの終了とともにプログラムを終了する
  
  設定値： true | false
  デフォルト値： false
カメラワークの設定
- camera_file
  
  3D シミュレーション画面のカメラワーク設定ファイルへのパス
  3D シミュレーションウィンドウのオープン時に読み込んで Replay チェックボックスを ON にする。
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。デフォルト値：なし
- camera_2d_file
  
  2D シミュレーション画面のカメラワーク設定ファイルへのパス
  2D シミュレーションウィンドウのオープン時に読み込んで Replay チェックボックスを ON にする。
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。デフォルト値：なし
表示に関する設定
- link_appearance_file
  
  リンクの表示設定ファイルへのパス
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
  デフォルト値：なし
- node_appearance_file
  
  ノードの表示設定ファイルへのパス
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
  デフォルト値：なし
- polygon_appearance_file
  
  ポリゴンの表示設定ファイルへのパス
  ポリゴンデータの作り方参照。
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
  デフォルト値：なし
- agent_appearance_file
  
  エージェントの表示設定ファイルへのパス
  Agent appearance の設定方法参照。
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
  デフォルト値：なし
- background_color
  
  3D シミュレーション画面の背景色
  
  設定値：標準のHTML色名 | 16進RGB値("#ffffff")
  デフォルト値： white
- vertical_scale
  
  3D シミュレーション画面のマップに対する垂直方向のスケールの大きさ
  
  設定値： 0.1～10.0
  デフォルト値： 1.0
- agent_size
  
  シミュレーション画面上のエージェントサイズ(共通)
  2D シミュレーション画面：ピクセル単位
  3D シミュレーション画面： m 単位
  
  設定値： 0.1～30.0
  デフォルト値： 1.0
- agent_size_2d
  
  2D シミュレーション画面上のエージェントサイズ
  
  設定値： 0.1～30.0 (ピクセル単位)
  デフォルト値： 1.0
- agent_size_3d
  
  3D シミュレーション画面上のエージェントサイズ
  
  設定値： 0.1～30.0 (m 単位)
  デフォルト値： 1.0
- zoom
  
  シミュレーション画面全体の表示倍率
  
  設定値： 0.0～9.9
  デフォルト値： 1.0
- show_links_at_actual_width
  
  3D シミュレーション画面で道幅を持つリンクを表示する。
  
  設定値： true | false
  デフォルト値： false
- outline_color
  
  3D シミュレーション画面で Obstructer 領域を確認するための色
  
  設定値：標準のHTML色名 | 16進RGB値("#ffffff")
  デフォルト値： lime
- show_background_image
  
  2D シミュレーション画面で背景画像を表示する。
  
  設定値： true | false
  デフォルト値： false
- color_depth_of_background_image
  
  背景画像の色の濃さ
  
  設定値： 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1.0
  デフォルト値： 1.0
- coastline_file
  
  海岸線データファイル(GeoJSON形式)のパス名
  複数の海岸線データが必要な場合(マップが2県にまたがる等)にはファイルのパス名をカンマ(,)で区切って並べる。
  
  設定値：絶対パス | 相対パス
  　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
  デフォルト値：なし
- show_the_sea
  
  シミュレータ起動時の海面表示の ON/OFF
  
  設定値： true | false
  デフォルト値： false
- centering_by_node_average
  
  3D シミュレーション画面のマップの中心点を従来の方法(全ノード位置の平均)で算出する。
  デフォルトはマップ全体に外接する矩形の中心点。
  
  設定値： true | false
  デフォルト値： false
- change_agent_color_depending_on_speed
  
  エージェントの移動速度によってエージェントの色を変化させる(図8,9)
  
  設定値： true | false
  デフォルト値： true
- drawing_agent_by_triage_and_speed_order
  
  エージェントをトリアージレベルと移動速度でソートして表示する。
  エージェントが重なっている時には、より重症な(Greenの場合は速度が遅い)エージェントが表示される様になる。
  
  設定値： true | false
  デフォルト値： true
- show_status
  
  シミュレーション画面上にステータスラインを表示する。
  通常のシミュレーション画面にはステータスラインは常に表示されているが、この設定を有効にするとスクリーンショットにもステータスラインが表示される(図10,11)。
  
  設定値： none | top | bottom
  　　　　 none：表示しない
  　　　　 top：上側に表示する
  　　　　 bottom：下側に表示する
  デフォルト値： none
- show_logo
  
  シミュレーション画面に AIST ロゴを表示する(図12)
  
  設定値： true | false
  デフォルト値： false
背景地図表示に関する設定
- zone
  
  マップデータの平面直角座標系の系番号
  
  国土地理院の地理院タイルを用いた背景地図表示を有効にする。
  マップファイルのルートタグに zone 属性があれば省略可能。
  マップ範囲の地理院タイルを読み込むために、初回のみ国土地理院の Web サイトへのアクセスが発生する。(読み込んだ画像は CrowdWalk/crowdwalk/cache ディレクトリにキャッシュされる)
  
  設定値： 1～19
  デフォルト値：なし
- gsi_tile_name
  
  地理院タイルのタイル名(データID)
  
  背景地図の表示に使用する地理院タイルを指定する。
  標準地図/淡色地図/English/数値地図25000（土地条件）/白地図/色別標高図/写真が選択可能。
  ≪地理院タイル一覧≫参照。
  
  設定値： std | pale | english | lcm25k_2012 | blank | relief | ort
  デフォルト値： pale
- gsi_tile_zoom
  
  地理院タイルのズームレベル
  
  背景地図の表示に使用する地理院タイルのズームレベルを指定する。
  ≪地理院タイル仕様≫参照。
  
  設定値： 5～18(タイル名により有効範囲が異なる)
  デフォルト値： 14
- show_background_map
  
  シミュレーション画面に背景地図を表示する。
  
  設定値： true | false
  デフォルト値： false
- color_depth_of_background_map
  
  背景地図の色の濃さ
  
  設定値： 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1.0
  デフォルト値： 1.0

マップエディタに関する設定

rotation_angle

マップエディタで表示されるマップの回転角度の初期値

設定値： -180.0～180.0
デフォルト値： 0.0
rotation_angle_locking

マップエディタで表示されるマップの回転角度をロックする

設定値： true | false
デフォルト値： false
osm_conversion_file

マップエディタで OpenStreetMap データを読み込む際に使用する設定ファイルのパス名

設定値：絶対パス | 相対パス
　　　　相対パスの基準ディレクトリは use_relative_path_from_prop の設定による。
デフォルト値：なし

プロパティファイルの設定内容の洗い出し

プロパティファイルの作成に当たって basic-sample でのプロパティファイルの設定内容を洗い出してみます。

マップファイルは "test_model.xml" を使用する。
ジェネレーションファイルは "test_generation.csv" または "test_generation.v2.json" を使用する。
シナリオファイルは "test_scenario.json" を使用する。

その他に、以下の設定も加えます。

出口ノードの表示サイズを 50cm にする。
デフォルトサイズの 1.5m では大きすぎるためです。(3D シミュレータでの表示が前提)
乱数のシードを決める。
これを設定しないとシミュレーションの再現性が無くなってしまいます。何でもよいので 2525 とします。
全エージェントが停止してもシミュレーションを止めない様に設定する。
出口の手前でつかえたエージェントの速度が一時的にすべて 0 になる事があるため、そこでシミュレーションが終了してしまわない様にするためです。
エージェントの表示サイズを 40cm にする。
デフォルトサイズの 1.0m では大きすぎるためです。(3D シミュレータでの表示が前提)

この内容に従ってプロパティファイルを作成します。

ＪＳＯＮ形式のプロパティファイル作成

プロパティファイルには JSON 形式と XML 形式がありますが、XML 形式は既に使われていないため解説は省略します。
JSON 形式の書式はただ一つのオブジェクトです。インデントや改行、コロン(:)前後の空白は任意です。
最後の設定値の後ろにはカンマ(,)が付かない様に注意してください。

{
    "設定項目" : 設定値,
            ・
            ・
            ・
    "設定項目" : 設定値
}

マップファイルの設定は "map_file": "test_model.xml" となります。

ジェネレーションファイルの設定は "generation_file": "test_generation.csv" となります。

シナリオファイルの設定は "scenario_file": "test_scenario.json" となります。

ノードの表示サイズを変更する場合はノードの表示設定ファイルで設定をおこないますが、その方法についての解説は省略します。
プロパティファイルではノードの表示設定ファイルのパスを設定する必要があるので "node_appearance_file": "node_appearance.json" とします。

乱数のシードの設定は "randseed": 2525 となります。

エージェントが停止してもシミュレーションを止めない設定は "all_agent_speed_zero_break": false となります。

エージェントの表示サイズを 40cm にする設定は "agent_size": 0.4 となります。

以上の設定をまとめるとプロパティファイルの内容は次の様になります。

{
    "map_file": "test_model.xml",
    "generation_file": "test_generation.csv",
    "scenario_file": "test_scenario.json",
    "node_appearance_file": "node_appearance.json",
    "randseed": 2525,
    "all_agent_speed_zero_break": false,
    "agent_size": 0.4
}

この内容をテキストエディタで作成して "practice" ディレクトリに "properties.json" というファイル名で保存してください。
またノードの表示設定ファイル "node_appearance.json" を basic-sample ディレクトリからコピーするため、コマンドラインで次のコマンドを実行してください。

cp sample/basic-sample/node_appearance.json practice

シミュレーションの実行

シミュレータには3つのモードがあります。
それぞれのモードでシミュレータを直接起動する方法は以下の通りです。

CUI モード

sh quickstart.sh practice/properties.json -c

2D グラフィックモード

sh quickstart.sh practice/properties.json -g2

3D グラフィックモード

sh quickstart.sh practice/properties.json -g

ログレベル

シミュレーションの実行中に情報や警告のメッセージ表示でコンソールが溢れてしまう場合には、ログレベルを指定する事により表示を抑制する事が出来ます。(ここで言う「ログ」はシミュレーションの進捗情報や警告・エラー表示の事で、ログ出力とは別の物です)

ログレベルには内容の重要度(深刻度)が高くなる順に、

Trace
Debug
Info
Warn
Error
Fatal

があります。

ログレベルの指定は -l オプションでおこないます。
指定したログレベル未満のメッセージが表示されなくなります。

Error 未満のメッセージ表示を抑制するコマンドは以下の通りです。

sh quickstart.sh practice/properties.json -g -lError

ログ出力

basic-sample では使用していませんがシミュレーションでは通常、ログ出力をおこないます。

ログの種類と出力フォーマット

1. agent movement history

ゴールまでたどり着いた各エージェントの発生時刻、到着時刻、移動時間のログ。

agentMovementHistoryLogger の CSV フォーマットは以下の通り。
各行のカラムの順：
    "GenerationFileの情報"
    "エージェントID"
    "発生時刻1"
    "発生時刻2"
    "到着時刻1"
    "到着時刻2"
    "移動時間1"
    "移動時間2"

2. agent trail

ゴールまでたどり着いたエージェントのゴールした時点でのJSON形式のログ。

agentTrailLogger の JSON フォーマット。

 { "agentId": _AgentID_,
   "generatedBy": _RuleName_,
   "generatedAbsTime": _TimeStr_,
   "generatedRelTime": _TimeInSec_,
   "evacuatedAbsTime": _TimeStr_,
   "evacuatedRelTime": _TimeInSec_,
   "travelTime": _TimeInSec_,
   "tags": [ _tag_, _tag_, ... ],
   "trail": [ {"placeId": _PlaceID_, "time": _TimeInSec_} * ]
 }
 
指定の方法は、properties file において、

  "agent_trail_log" :
    {
      "file":",Log/agentTrail.log",
      "members": ["agentId", "evacuatedRelTime"]
    },
 
という形で指定する。  
これ以外に、CrowdWalkWrapper クラスにおいて、新規の項目を追加できる。

3. individual pedestrians

ステップ毎の各エージェントの状態を個別に記録するログ。ログファイルのサイズが巨大になる傾向がある。(GB over)

individualPedestriansLogger のCSVフォーマットは以下の通り。

各行のカラムの順：
    "pedestrianID"
    "current_position_in_model_x"
    "current_position_in_model_y"
    "current_position_in_model_z"
    "current_position_for_drawing_x"
    "current_position_for_drawing_y"
    "current_position_for_drawing_z"
    "current_acceleration"
    "current_velocity"
    "current_linkID"
    "current_nodeID_of_forward_movement"
    "current_nodeID_of_backward_movement"
    "current_distance_from_node_of_forward_movement"
    "current_moving_direction"
    "generated_time"
    "current_traveling_period"
    "current_exposure"
    "amount_exposure"
    "current_status_by_exposure"
    "next_assigned_passage_node"
※ 以下のものはデフォルトでは出力されない。（以下の方法で指定すれば出力）
    "waiting"
    "in_search_target_link"
    "current_time"

標準の出力カラムはリソースデータ "fallbackParameters.json" の agentHandler/logColumnsOfIndividualPedestrians で定義されている。  
プロパティファイルに指定する Fallback file で再定義する事により出力カラムが変更できる。

4. evacuated agents

ステップ毎の脱出エージェント数をゴール別に記録するログ。

ゴールノードごとの脱出したエージェント数を各時刻毎に出力する。  
CSV の時のフォーマットは、

    先頭行：各目的地の名前（タグ）のリスト
    2行目以降：最初のサイクルより、各時刻毎の出口の人数を、各欄に出力。

ログを出力する

実際に agent movement history ログを出力してみます。
プロパティファイルに次の設定を挿入してください。(カンマの整合性に気を付けてください)

    "agent_movement_history_file": "log/agent_movement_history.csv",

また、ジェネレーションファイルは以下の様に CSV 形式を使う様に設定してください。agent movement history ログの場合はログファイルの読みやすさに影響してきます。

    "generation_file": "test_generation.csv",

以上の設定を加えたらシミュレーションを実行してください。経過を見る必要はないので CUI モードでよいでしょう。

sh quickstart.sh practice/properties.json -c

シミュレーションが終了したらログファイルが出力されている事を確認します。
"practice" ディレクトリの中に "log" ディレクトリが作成され、その中に "agent_movement_history.csv" ファイルが出来ているはずです。
"agent_movement_history.csv" ファイルをエディタで開いて中を確認してください。次の様に表示されるはずです。

GenerationFileの情報,エージェントID,発生時刻1,発生時刻2,到着時刻1,到着時刻2,移動時間1,移動時間2
ROOM3 07:30 1 5 EXIT,ag00014,07:30:00,0,07:30:08,8,00:00:08,8
ROOM3 07:30 1 5 EXIT,ag00010,07:30:00,0,07:30:10,10,00:00:10,10
ROOM3 07:30 1 5 EXIT,ag00012,07:30:00,0,07:30:12,12,00:00:12,12
ROOM3 07:30 1 5 EXIT,ag00013,07:30:00,0,07:30:14,14,00:00:14,14
ROOM3 07:30 1 5 EXIT,ag00011,07:30:00,0,07:30:15,15,00:00:15,15
ROOM2 07:30 1 5 EXIT WAIT_FOR(HALLWAY_2 PACK 30),ag00006,07:30:00,0,07:30:38,38,00:00:38,38
ROOM2 07:30 1 5 EXIT WAIT_FOR(HALLWAY_2 PACK 30),ag00009,07:30:00,0,07:30:41,41,00:00:41,41
ROOM2 07:30 1 5 EXIT WAIT_FOR(HALLWAY_2 PACK 30),ag00005,07:30:00,0,07:30:43,43,00:00:43,43
ROOM2 07:30 1 5 EXIT WAIT_FOR(HALLWAY_2 PACK 30),ag00007,07:30:00,0,07:30:45,45,00:00:45,45
ROOM2 07:30 1 5 EXIT WAIT_FOR(HALLWAY_2 PACK 30),ag00008,07:30:00,0,07:30:47,47,00:00:47,47
ROOM1 07:30 1 5 EXIT WAIT_UNTIL(HALLWAY_1 SCATTER RESUME),ag00001,07:30:00,0,07:31:02,62,00:01:02,62
ROOM1 07:30 1 5 EXIT WAIT_UNTIL(HALLWAY_1 SCATTER RESUME),ag00003,07:30:00,0,07:31:02,62,00:01:02,62
ROOM1 07:30 1 5 EXIT WAIT_UNTIL(HALLWAY_1 SCATTER RESUME),ag00002,07:30:00,0,07:31:03,63,00:01:03,63
ROOM1 07:30 1 5 EXIT WAIT_UNTIL(HALLWAY_1 SCATTER RESUME),ag00004,07:30:00,0,07:31:05,65,00:01:05,65
ROOM1 07:30 1 5 EXIT WAIT_UNTIL(HALLWAY_1 SCATTER RESUME),ag00000,07:30:00,0,07:31:06,66,00:01:06,66

"agent_movement_history.csv" ファイルを ~/CrowdWalk/crowdwalk/log ディレクトリに出力したい場合は設定を次の様に変えてください。

    "agent_movement_history_file": "../log/agent_movement_history.csv",

その他のログの出力方法についてはログ出力に関する設定を参照してください。

CrowdWalk チュートリアル

このチュートリアルの内容

ＣｒｏｗｄＷａｌｋとは

特徴

ネットワークマップ

エージェント

機能紹介

マップエディタ

シミュレータ(CUI モード)

シミュレータ(2D グラフィックモード)

シミュレータ(3D グラフィックモード)

ログの出力

動作環境

インストールとアップデート

ダウンロード

ビルド

動作確認

スクリーンショット保存用ディレクトリの作成

アップデートの方法

サンプルの実行

basic-sample

stop-sample2

シミュレーションの準備

必須ファイル

マップファイル

ジェネレーションファイル

シナリオファイル

プロパティファイル

その他のファイル

マップファイルの作成

ジェネレーションファイルの作成

設定項目

1. 生成ルール

2. ルール名

3. エージェントクラス名

4. 速度モデル

5. 発生場所

6. 発生時刻

7. 発生終了判定時刻

8. 発生時刻間隔

9. 発生期間

10. 発生人数

11. 各リンク・ノードから発生するエージェント数の上限

12. ゴール

13. 経由地

13-1. 待機設定

14. エージェントに付与するタグ

15. 個別パラメータ

エージェントの発生からゴールまでのシナリオ

ＣＳＶ形式のジェネレーションファイル作成

ＪＳＯＮ形式のジェネレーションファイル作成

シナリオファイルの作成

イベント

1. Initiate

2. Finish

3. Alert

4. AddTag

5. RemoveTag

6. ShutOff

7. OpenGate

8. CloseGate

9. Dump

10. Null

11. Pause

シミュレーションのシナリオ

ＪＳＯＮ形式のシナリオファイル作成

プロパティファイルの作成

ＪＳＯＮ形式のプロパティファイルの書式

プロパティファイルの設定項目

設定必須項目

map_file

generation_file

scenario_file

基本的な設定

fallback_file

randseed

all_agent_speed_zero_break

exit_count

mental_map_rules

use_relative_path_from_prop