CrowdWalk チュートリアル

CrowdWalk とは

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

CrowdWalk の特徴

ネットワークマップ

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

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-sample

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

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

sh quickstart.sh sample/stop-sample/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 形式なのでテキストエディタを使って編集する事も可能です。

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

ジェネレーションファイルは、エージェントの特性や発生場所、発生時刻、移動ルートなどを定義したファイルです。
CSV 形式(旧形式)と JSON 形式があります。

シナリオファイル

シナリオファイルは、シミュレーション実行中に発生させるイベントのスケジュールを定義したファイルです。
CSV 形式(旧形式)と JSON 形式があります。

プロパティファイル

プロパティファイルは、上記の3ファイルを含む各種設定ファイルのパス指定やシミュレータの各種パラメータを設定したファイルです。
XML 形式(旧形式)と JSON 形式があります。

その他のファイル

その他、必要に応じて以下のファイルも使用します。

背景画像ファイル
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 グループにマップを作る事も出来ますが後からグループを追加する事が不可能になってしまうため、新たにグループを追加します。
1階層しか持たない構造物なのでグループ名は "FLOOR" とします。

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

editor_add_group

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

editor_add_group_dialog

Provide feedback

Saved searches

Use saved searches to filter your results more quickly