The Sixwish project

config file

読み込みはFLARManagerを初期化する時にファイル名を指定して読み込み、使用しています。

// FLARManagerの設定ファイルを引数に、インスタンスを生成
this.flarManager = new FLARManager("./data/config.xml");

前回使用したconfigファイルを編集したりしながら内容を確認していきます。

基本

設定ファイルはXMLで書かれています。
FLASHではXMLを使う事が多いと思うので、XMLについての説明と用語説明は省略します。

構造的にはflar_configノードの中に、入力ソース、マネージャの設定、カメラパラメータ、マーカーパターンの設定ノードがあります。
前回使った内容は以下の通りです。

<!-- this file specifies configurations for FLARManager. -->
<!-- to use this file to initialize FLARManager, pass its path into FLARManager.initFromFile(). -->
<!-- note that all relative paths listed here must be relative to the .swf location; absolute paths may also be used. -->

<flar_config>
	<!-- source settings -->
	<flarSourceSettings
		sourceWidth="320"
		sourceHeight="240"
		displayWidth="640"
		displayHeight="480"
		framerate="30"
		downsampleRatio="1" />

	<!-- miscellaneous FLARManager settings -->
	<flarManagerSettings
		mirrorDisplay="true"
		smoothing="3">
		<smoother className="FLARMatrixSmoother_Average" />
		<thresholdAdapter className="DrunkWalkThresholdAdapter" speed="0.3" bias="-0.1" />
	</flarManagerSettings>
	
	<!-- location of camera parameters file, e.g. FLARCameraParams.dat or camera_para.dat. -->
	<cameraParamsFile path="./data/FLARCameraParams.dat" />
	
	<!-- list of file paths of patterns for FLARToolkit to detect. -->
	<!-- @resolution specifies the resolution at which the patterns were generated. -->
	<patterns resolution="8" patternToBorderRatio="0.5" minConfidence="0.5">
		<pattern path="../resources/flar/patterns/pat8/patt001.pat" />
	</patterns>
	
</flar_config>

省略された要素や属性はデフォルト値を使用するか無視されます。

さて、ここからは一つ一つ見ていきます。

flarSourceSettings

要素名から推測できると思いますが、ウェブカメラからの入力ならびに出力について定義しています。

<!-- 入出力についての設定 -->
<flarSourceSettings
	sourceWidth="320"
	sourceHeight="240"
	displayWidth="640"
	displayHeight="480"
	framerate="30"
	downsampleRatio="1"
	loaderPath=""
	useProxy="false"
	 />

属性は下記の通りです。

sourceWidth

ウェブカメラからの入力時のサイズ(幅)を指定。 この値は、FLARCameraSource.asのCamera.setMode()に渡されます。

sourceHeight

ウェブカメラからの入力時のサイズ(高さ)を指定。 この値は、FLARCameraSource.asのCamera.setMode()に渡されます。

displayWidth

表示サイズの幅を設定。
sourceと分かれているのは、拡大表示などが可能になっているため。 小さいサイズでマーカー認識専用にして、アトラクションに拘る時に活用できる。

displayHeight

表示サイズの高さを設定

framerate

このフレームレートでキャプチャします。 この値は、FLARCameraSource.asのCamera.setMode（）に渡されます。

downsampleRatio

解析する画像のサイズをどうするかを決める部分です。 大きい画像を処理するとPCの負荷が高くなりますが、解析画像のサイズを小さくすれば軽くなります。 背景画像は綺麗なままで、負荷を高くしたくない場合はこの数値を調整します。 しかし、反作用としてマーカーの認識率が落ちる場合があります。

loaderPath

少し特殊な属性で、これを使用することは少ないと思います。 この属性は、FLARManagerのFLARLoaderSourceが標準で呼び出すFLARCameraSourceの変わりに使用するライブラリを指定するものです。 ここまでで設定してきた属性のデフォルト値などはFLARCameraSourceに書かれているものが多くあります。 標準の物と異なる値を設定する場合は、ここを修正し、FLARCameraSourceに変わる物を実装することになります。

useProxy

trueの場合、デフォルトのFLARCameraSourceの代わりにFLARProxyを生成します。 基本的には使わないと思います。

flarManagerSettings

FLARManagerの設定。FLARToolKitの動きをどうするかを自動設定するための物でもあります。 認識精度などの調整はこの項目を用いて行います。

なお、ここには子要素もあるので注意が必要。

<!-- FLARManager関係の設定 -->
<flarManagerSettings
	mirrorDisplay="true"
	smoothing="3"
	sampleBlurring="1"
	markerUpdateThreshold="80"
	markerRemovalDelay="1"
	minimumLabelSize="100">
	<smoother className="FLARMatrixSmoother_Average" />
	<thresholdAdapter className="DrunkWalkThresholdAdapter"
	                  speed="0.3"
	                  bias="-0.1" />
	</flarManagerSettings>

属性は下記の通りです。

mirrorDisplay

trueの場合は、入力ビデオ、検出マーカーのデータを水平方向に反転します。 falseの場合は通常通りの動作。
これは何が変わるかというと、自分を写した場合に鏡になるということと同義です。

smoothing

FLARToolKitによって生成する変換行列に平滑化アルゴリズムを適用します。 平滑化はFLARManagereが変換行列を平均化するフレーム数と等しい。数字が大きければ大きいほどスムーズなアニメーションになり、マーカー位置・方位変化の間の応用時間が遅ければ遅いほど、より滑らかになります。 0の場合は平滑化アルゴリズムは働きません。
変更することで、表示オブジェクトのマーカーへの追従速度が変化します。 数値が大きい場合はゆっくりとマーカーの移動した先に動いていきます。

sampleBlurring

マーカー検出のためにFLARToolKitに画像を送り解析しますが、その前にぼかしをかけてから処理させるための値です。値が大きいほどフレームレートを良くしますが、検出精度が下がります。

markerUpdateThreshold

検出されたマーカーがこの長さ(pixels)の範囲内でアクティブなマーカーであるならば、FLARManagerは、検出されたマーカーがアクティブなマーカーが更新されていると認識されます。 他の認識されたマーカーは新しいマーカーとして認識されます。 この値を増加されることで、より早くアクティブなマーカーを認識します。減少させるとスクリーン上の多くのマーカーを認識します。
つまり、最初に認識したマーカーと次に認識したマーカーが、ここで指定した範囲内にあれば、それは同一のものとしてみなしてくれるというものです。 再認識の速度が向上します。

markerRemovalDelay

MARKER_REMOVEDイベント……マーカーが認識できなくなった場合に、指定された数値のフレーム数だけ遅延して発行するオプション。ちらつき防止用。

minimumLabelSize

FLARLabeling_BitmapData.minimumLabelSizeの ソースイメージの黒枠領域の最小規模(幅*高さ)の条件を指定します。

smoother(子要素)

FLARToolKitによって生成された変換行列をIFLARMatrixSmootherを使った、Sommtherを指定するための物です。これはFLARMatrixSmoother_Averageをデフォルトとしますが、開発者はアルゴリズムを変更する事が可能です。 改良のための詳しい情報はFLARManagerの中を見てください。

className

クラス名を指定してください。 com.transmote.flar.utils.smoother以外の場所に新しいクラスを作る場合は、 完全修飾クラス名(fully-qualified class name)で指定してください。

thresholdAdapter(子要素)

順応型の閾値により、さまざまな証明範囲でのよりよいマーカー認識ができるようになります。 ウェブアプリケーションのように何処で使われるか分からない場合、この処理では開発者はほんの少ししか 制御する事ができません。ユーザーがどのような環境で使うか分かりませんから……
デフォルトのthresholdAdapterはDrunkWalkThresholdAdapterですが、 開発者は自分の順応型の閾値処理アルゴリズムを実装することができます。

className

順応型の閾値処理用のアダプタクラス名を指定する。 com.transmote.flar.utils.threshold以外に存在する場合は、 完全修飾クラス名(fully-qualified class name)で指定してください。

speed

この値は順応型の閾値処理の変化速度を意味します。値を大きくすると、 安定しない光源下におけるマーカー検出を向上する事ができます。 しかし、マーカー検出の不安定性も上がる可能性があります。

bias

この値は順応型の閾値処理のバイアスです。 暗い場所では値を小さく、明るい場所では値を大きくします。

特定環境下で行い、かつ認識率などをアップさせたい場合、この設定を調整すればどうにかなるので、 FLASH CSが無くとも何とかなるのが良いのかも。
もっとも、展示会以外ではいろいろと微妙な気もしますが……

cameraParamsFile

カメラパラメーターの設定ファイルの位置を設定する物です。
この項目だけは必須です。必ず確認しましょう。

<!-- location of camera parameters file, e.g. FLARCameraParams.dat or camera_para.dat. -->
<cameraParamsFile path="./data/FLARCameraParams.dat" />

path

FLARToolkitカメラパラメータファイルへのパス（FLARCameraParams.datまたはcamera_para.dat）。 FLARToolkit初期化および実行するために、このファイルが必要です。

カメラパラメーターとは何か？ ARToolKitを継承してFLARToolKitがあるのですが、ARToolKitでも同様のファイルを必要としています。 ウェブカメラには焦点距離やレンズの歪みなどの特性があります。 このファイルはその特性記録しており、マーカーの位置計算などに対して補正するためのファイルです。
本来は使用するウェブカメラごとにこのファイルを生成して設定する必要があるのですが、 どのカメラを使っているか、使うのか分からない状態なので、付属している物を使っているということになります。 そのため、誤差が出ているのですがあまり気にならないのかも……
もし、特定環境下で使う場合は、ARToolKitのカメラキャリブレーションを行って、 ファイルを入れ替えてください。

patterns

マーカーのパターンファイルの設定になります。

<!-- list of file paths of patterns for FLARToolkit to detect. -->
<!-- @resolution specifies the resolution at which the patterns were generated. -->
<patterns resolution="8"
          patternToBorderRatio="50"
          minConfidence="0.5" >
	<pattern path="../resources/flar/patterns/pat8/patt001.pat" size="80" />
	<pattern path="../resources/flar/patterns/pat8/patt002.pat" size="80" />
</patterns>

resolution

マーカーパターンの最大解像度(幅/高さ)を指定します。すぺてのパターンは一つのアプリケーション内で 統一されている必要があります。これはFLARToolKitで義務付けられています。

patternToBorderRatio

マーカーは、黒枠とマーカー(黒枠内のデザイン部分)の占有量が一定量である事が定義されています。 この値は、0～100の間で定義され、黒枠内部の占有量を設定することになります。 つまり、黒枠を細くしたい場合はこの値を調整してください。
ですが、この機能はFLARToolKitでもマルチマーカーに対応していないので、FLARManagerでも対応していません

minConfidence

‘Confidence’は、FLARToolKitで検出されたマーカーに対して、パターンマッチのアルゴリズムによって、 認識された精度として、0.0～1.0の間で割り当てられます。
この値で最低限の認識精度を設定します。つまり、ここで設定された数値以下の認識精度の物は、 マーカーとして認識されません。誤検出を避けたい場合は高めに、誤検出上等という場合は低くしてください。

pattern(子要素)

それぞれのpattern要素はFLARToolKitが検出を試みるマーカーを示します。 FLARToolKitは理論上は無制限な数のマーカーを探索できますが、すべてのパターンに対して、 検出されたパターンマッチを行うとなると、相当なコストがかかり遅くなります。 開発者はできるだけこのリストを小さくするようにするべきです。

path

パターンファイルのパスを指定。

size

マーカーのサイズ指定(pixel)です。このサイズは、座標変換行列で用いる値です。 スクリーン上に見えるサイズを調整するのにも利用できます。 マーカーに対してモデルが大きく見えるならばこの値を小さく、モデルが小さければ大きくしてください。

まとめ

マニュアル的になっていますがご了承ください。 とりあえず、どういう設定項目がありどういう意味を持つのかが分かれば十分かと思い、 このような形式になっています。