FLARToolKit

FLARManger version 1.0

Section 13 FLARManager config file

FLARManagerでは外部設定ファイル「config.xml」によって、さまざまな設定ができるようになっています。

FLARManagerの中でも重要な部分であり、抑えておく必要があります。 この設定を工夫することで、認識率が向上したり、デバッグ作業がしやすくなります。
その一方で、正しく設定しないと動作が安定しない、マーカーが認識されない、認識率が低いなどのトラブルが発生しやすくなります。

英語版のドキュメントを参考に、動作検証の結果を含めて説明していきます。

英語版ドキュメント

http://words.transmote.com/wp/flarmanager/flarmanager-documentation/

API Document

http://transmote.com/flar/reference/

基本

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

今回説明に使用する設定ファイルは以下の内容になります。

config.xml

<flar_config>
    <flarSourceSettings
        sourceWidth="640"
        sourceHeight="480"
        displayWidth="640"
        displayHeight="480"
        framerate="30"
        trackerToSourceRatio="0.5"
        loaderPath=""
        useProxy="false" />

    <flarManagerSettings
        mirrorDisplay="true"
        sampleBlurring="1"
        inverted="false"
        markerUpdateThreshold="80"
        markerRemovalDelay="1"
        markerExtrapolation="true"
        smoothing="3"
        adaptiveSmoothingCenter="10" >
        <smoother
            className="FLARMatrixSmoother_Average"
            positionToRotationRatio="0.5" />
        <thresholdAdapter
            className="DrunkHistogramThresholdAdapter"
            speed="0.3" />
    </flarManagerSettings>

    <trackerSettings>
        <flarToolkitSettings
            cameraParamsFile="../resources/flarToolkit/FLARCameraParams.dat"
            labelAreaMin="70"
            labelAreaMax="100000"
            thresholdSourceDisplay="false">
            <patterns resolution="8"
                patternToBorderRatioX="50"
                patternToBorderRatioY="50"
                minConfidence="0.5" >
                <pattern
                    path="../resources/flarToolkit/patterns/pat8/patt001.pat"
                    siez="80"/>
                <pattern
                    path="../resources/flarToolkit/patterns/pat8/patt002.pat"
                    siez="80"/>
            </patterns>
        </flarToolkitSettings>
    </trackerSettings>
</flar_config>

FLARManagerに標準で付属しているconfig.xmlをベースに今回の解説に不要な要素を削除し、省略されている要素を全て追加しています。
要素を省略した場合、デフォルト値が使用されるか無視されます。

各要素説明

flarSourceSettings

ウェブカメラからの入力ならびに出力について定義しています。

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

属性は下記の通りです。

sourceWidth

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

sourceHeight

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

displayWidth

表示サイズの幅を設定。
カメラの入力サイズ(sourceWidth)と異なる場合は、拡大/縮小して表示されます。

displayHeight

表示サイズの高さを設定。
カメラの入力サイズ(sourceHeight)と異なる場合は、拡大/縮小して表示されます

framerate

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

trackerToSourceRatio

v0.7までの「downsampleRatio」です。
カメラからの入力画像を解析画像に変換する際のスケールを指定します。スケールを小さくすると処理は早くなりますが、マーカーの認識率が落ちます。
「1.0」ではカメラの入力画像をそのまま解析します。「0.5」ではカメラの入力画像を半分に縮小して解析します。
デフォルトは「0.5」、最大は「1.0」です。

loaderPath

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

useProxy

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

カメラの入力サイズと表示サイズ「trackerToSourceRatio」について

設定によっては背景画像がきれいになる、認識率が向上するなどの効果がでる箇所になります。
しかし、負荷が上がる場合もありますので気をつけてください。

では、flarSourceSettingsの一部の属性を下記のケースで見てみましょう。

Case A

sourceWidth="640" sourceHeight="480"
displayWidth="640" displayHeight="480"
trackerToSourceRatio="0.5"

Case B

sourceWidth="320" sourceHeight="240"
displayWidth="640" displayHeight="480"
trackerToSourceRatio="1.0"

Case Aは入力画像と表示画像のサイズが同じですが、trackerToSourceRatioが0.5になっています。 この場合、背景画像は入力サイズと同じ640x480で表示されるので綺麗になります。 しかし、マーカーを認識するための映像は縮小して320x240で解析をしています。

もう一つのCase Bは入力画像に対して表示画像が大きいため、背景画像を拡大して表示します。 そのため、Case Aに比べて画面が粗くなります。
解析画像は、trackerToSourceRatioが1.0なので「入力画像=解析画像」、つまり320x240で解析しています。

FLARToolKitは解析画像のサイズによっても負荷が変わるので、このCase AとCase Bでは同等の負荷になります。 そのため基本的にはCase Aを使う事をお勧めします。

上：Case A、下：Case B(同じ環境下で撮影)

なお、認識率を上げたい場合は、Case AでtrackerToSourceRatioを0.75にしてみるとよいでしょう。 しかし、負荷も上がるのでバランスを見て設定してください。

flarManagerSettings

FLARManagerで独自に実装されている機能に関する設定です。 FLARToolKitの動きをどうするかを自動設定するための設定も含まれます。

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

“config.xml”

<!-- FLARManager関係の設定 -->
<flarManagerSettings
    mirrorDisplay="true"
    sampleBlurring="1"
    inverted="false"
    markerUpdateThreshold="80"
    markerRemovalDelay="1"
    markerExtrapolation="true"
    smoothing="3"
    adaptiveSmoothingCenter="10" >
    <smoother
        className="FLARMatrixSmoother_Average"
        positionToRotationRatio="0.5" />
        <thresholdAdapter
            className="DrunkHistogramThresholdAdapter"
            speed="0.3" />
</flarManagerSettings>

属性は下記の通りです。

mirrorDisplay

trueの場合は、入力ビデオ、検出マーカーのデータを水平方向に反転します。つまり、鏡写しに表示します。標準でtrueになっているので、通常のFLARToolKitと同様に表示にするには、falseを設定します。

sampleBlurring

カメラ画像の解析時に画像にぼかしをかけます。検出精度の調整に使用します。

inverted

trueの場合、マーカーの白黒を反転します。通常のマーカーは黒枠に白領域ですが、白枠に黒領域のマーカーが使用できます。反転マーカーを使用する場合はマーカー周囲が暗い色であることが条件になります。

markerUpdateThreshold

検出されたマーカーの位置が、1フレーム前に検出されたマーカーの位置から、この長さ(pixels)の範囲内であるならば、検出されたマーカーは1フレーム前のマーカーと同じものであると認識します。範囲外ならば、1フレーム前のマーカーとは別のもの、つまり新規マーカーとして認識します。
マーカーやカメラを動かす場合は、この値を増やしてください。同時に認識できるマーカーの数は減りますが、1つのマーカーを追従しやすくなります。
また、この値を減少させると、同一マーカーをより多く認識できるようになります。

markerRemovalDelay

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

markerExtrapolation

trueの場合、マーカー推定機能を使用します。マーカーの移動が早く、ぼけが生じてマーカーを見失うなどした場合、マーカーの移動速度と方向からマーカーの位置を推定します。この推定処理はmarkerRemovalDelayで指定したフレーム間実行します。 (markerRemovalDelayが0ならば、markerExtrapolationの効果は得られません)

smoothing

画像を解析して得られるマーカーの位置情報をFLARToolKitの情報に変換する際に、指定された数値のフレーム数だけ段階的に変換するオプションです。
解析したマーカーの位置から現在位置までの差分を指定したフレーム数で割ったピクセル数ずつ移動するので、座標移動が滑らかになります。値が大きいほど、時間(フレーム数)をかけて移動もしくは回転することになるので、滑らかな動きになります。
また、マーカーの位置変化が少ないほど滑らかな動きになります。0の場合は機能をOFFにします。この機能を使用することで、表示オブジェクトのジッタ(がたつきやぶれ)を抑える効果が期待できます。
マーカーの位置に関して影響するだけなので、マーカー上に表示するオブジェクト内に設定されているアニメーションなどには影響はありません。(動画の再生速度が遅くなったり、3Dモデルのアニメーションがスローになったりはしません)

adaptiveSmoothingCenter

マーカーの変化速度に応じて、smoothinの値を最適化するオプションです。マーカーの変化速度が遅い場合は、smoothingの値を増やして、ジッタ(がたつきやぶれ)をより緩和します。マーカーの変化速度が速い場合は、smoothingの値を減らして、マーカーへの追従を高速化します。0の場合は機能をOFFにします。（smoothingの最適化機能をOFFにするだけで、smoothing機能がOFFになるわけではありません）
ここで指定するのは、変化速度です。変化速度は1フレーム間でのX/Y座標間のベクトルの長さや、回転角度の量を示します。
詳しくは、FLARMarker.asの関数：adaptSmoothingを参照してください。

smoother(子要素)

smoothingで指定した値を使用するsmootherクラスを指定します。デフォルトはFLARMatrixSmoother_Averageです。

開発者はインターフェース：IFLARMatrixSmootherを使用して独自のアルゴリズムを実装することができます。詳しい情報はこちらを参照ください。(英語サイトに飛びます)

FLARManagerに付属しているSmootherのクラスは、FLARMatrixSmoother_Average、FLARMatrixSmoother_AverageSimpleの2種類です。FLARMatrixSmoother_AverageSimpleが、v0.7までのFLARMatrixSmoother_Averageに相当します。

className

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

追加パラメーター

classNameで指定したクラスで使用するパラメーターを指定することができます。新たにSmootherのクラスを作成した場合など、独自にパラメータを拡張することができます。

positionToRotationRatio

classNameが「FLARMatrixSmoother_Average」の場合の追加パラメーターです。
回転角度の変化に対して位置の移動をどうするか決めるのに使用します。初期値は「0.5」で、これは回転の変化に対して移動の変化量が半分になります。つまり、回転変化はすばやく位置変化は滑らかにという動きになります

thresholdAdapter(子要素)

閾値を周囲の環境にあわせて動的に変化させることで、様々な環境下でのマーカー認識を安定させることができます。
ウェブアプリケーションのように、ユーザーがどのような環境で使用するのか開発側がコントロールできない場合、閾値の自動調節機能は必要です。 閾値はカメラの画像を解析用の画像に変換する際に使用します。解析用に白黒の2階調化する際、「白」になるか「黒」になるかの境界値のことです。
詳細は別途説明します。

className

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

追加パラメータ

speed

classNameがDrunkHistogramThresholdAdapter、DefaultThresholdAdapter、DrunkWalkThresholdAdapterの場合の追加パラメーターです。
閾値変動処理の実行速度を指定します。 値を大きくすると安定しない光源下におけるマーカー検出を向上する事ができます。 しかし、マーカー検出の不安定性も上がる可能性があります。指定できる値は0以上です。初期値は0.3です。 0の場合は、閾値変動機能がOFFになります。

bias

classNameがDrunkWalkThresholdAdapterの場合の追加パラメーターです。
閾値変動処理が働く方向を「-1.0」～「+1.0」の範囲で指定します。 -1に近づくほど、暗い環境に対応した閾値変動処理を行います。(閾値を下げる方向に調節します) +1に近づくほど、明るい環境に対応した閾値変動処理を行います。(閾値を上げる方向に調節します) 0の場合は、明るい環境/暗い環境どちらの方向にも対応できるように、ランダムで処理を行います。デフォルトは-0.1です。
一般家庭の照明環境は、開発作業を行うオフィスよりも暗めの環境になりやすいなどあるので、想定環境に応じて調整してください。

それぞれの設定項目が挙動に影響しやすいので、理由を考えながら設定を調整してください。

「smoothing」「markerRemovalDelay」について

モデルのがたつきを抑えたり、ちらつき防止などかなり便利な機能ですが、指定する値がフレーム数であることに注意が必要です。
開発サイドのPCスペックが高性能でフレームレートが高い場合は、この値を大きくしても効果を実感しにくいので注意が必要です。 PCが高スペックの場合、値を大きく指定しがちになりますが、ユーザー側の環境でフレームレートが低い場合は、モデルがマーカーに追従しなかったり、マーカーが見えなくなってもいつまでもモデルが表示されたままになるなどの現象が発生します。
そのため、過度に高い値を指定しないことをお勧めします。

「thresholdAdapter」について

デフォルトはDrunkHistogramThresholdAdapterを使用します。
なお、FLARManagerに付属しているthresholdAdapterのクラスは5種類あります。

DefaultThresholdAdapter(=DrunkHistogramThresholdAdapter)

<thresholdAdapter className="DefaultThresholdAdapter" speed="0.3" />

DrunkHistogramThresholdAdapter

<thresholdAdapter className="DrunkHistogramThresholdAdapter" speed="0.3" />

DrunkWalkThresholdAdapter

<thresholdAdapter className="DrunkWalkThresholdAdapter" speed="0.3" bias="-0.1" />

HistogramThresholdAdapter

<thresholdAdapter className="HistogramThresholdAdapter" />

IntegralImageThresholdAdapter

<thresholdAdapter className="IntegralImageThresholdAdapter" />

各処理の違いは、ソースコードやAPIドキュメントを参照してください。

なお、マーカーの認識が安定しない場合、この機能が関係している可能性が高いです。
閾値を自動調節してくれるのは便利なのですが、上手く設定しないと影響が強く出てマーカーが認識されにくくなります。
FLARManagerではマーカーが見つからない場合、マーカーを認識するまでthresholdAdapterで設定したクラスのアルゴリズムに沿って閾値を少しずつ変化させていきます。 そのため、適切な閾値を見つけるまで、数フレームかかります。 マーカー認識中は閾値を継続利用するのですが、マーカーを見失うと1から自動調節を繰り返すので、再び認識されるまで時間を要することがあります。

手元30cm以内で使用するなら、閾値は100程度を固定でも何とかなることが多いので、どうしても安定しない場合は思い切ってFLARManager.asの中を修正してこの機能をOFFにするのも手だと思います。

遠距離で使用する場合は自動調節機能がないと厳しいので、この機能に関してはある程度独自カスタマイズが必要になってくるのではないかと思います。

また、開発者はインターフェース：IThresholdAdapterを使用して独自のアルゴリズムを実装することができます。
詳しい情報はこちらを参照してください。(英語サイトに飛びます)

trackerSettings

マーカーのトラッキングに関する設定です。
version1.0以降、複数のトラッキングエンジンを使用できるようになったため、名称も変わり、設定項目も増えた部分になります。

今回は、FLARToolKitを使う場合に特化して説明します。

config.xml

<trackerSettings>
    <flarToolkitSettings
        cameraParamsFile="../resources/flarToolkit/FLARCameraParams.dat"
        labelAreaMin="70"
        labelAreaMax="100000"
        thresholdSourceDisplay="false">
        <patterns
            resolution="8"
            patternToBorderRatioX="50"
            patternToBorderRatioY="50"
            minConfidence="0.5" >
            <pattern
                path="../resources/flarToolkit/patterns/pat8/patt001.pat"
                siez="80"/>
            <pattern
                path="../resources/flarToolkit/patterns/pat8/patt002.pat"
                siez="80"/>
        </patterns>
    </flarToolkitSettings>
</trackerSettings>

flarToolkitSettingsについて説明します。

cameraParamsFile

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

カメラの入力サイズのアスペクト比が16:9の場合は、FLARToolKit本体に付属しているカメラパラメーターファイルcamera_para_16x9.datを使用してください。

labelAreaMin

解析用画像の中からマーカー候補として扱う矩形の最小サイズを指定します。
指定する値は白領域の部分の面積(width*height)です。ここで指定した値よりも小さな面積の矩形はマーカーとして扱われません。 そのため、値を大きくすることで検出数が減り比較処理が少なくなるので、処理速度が向上しますが、画面上に表示されているマーカーのサイズがlabelAreaMinよりも小さいと、マーカーとして検出されなくなります。

labelAreaMax

解析用画像の中からマーカー候補として扱う矩形の最大サイズを指定します。
指定する値は白領域の部分の面積(width*height)です。ここで指定した値よりも大きな面積の矩形はマーカーとして扱われません。
そのため、画面上に表示されているマーカーのサイズがlabelAreaMaxよりも大きいとマーカーが検出されなくなります。 近い場合は認識させたくない場合に使用します。

thresholdSourceDisplay

trueの場合、2値化した画像を表示します。
この2値化した画像からマーカーを検出するので、マーカーが認識されないなどの問題に当たった場合は、とても役に立ちます。

patterns(子要素)

FLARToolKitで使用するマーカーの設定です。

resolution

マーカーパターンの解像度を指定します。パターンファイルを作成したときに指定する分割数です。パターンファイルを開き、横1列あたりに半角スペースで区切られた数値がいくつあるかでも判別できます。
1アプリケーション内で使用するパターンファイルは全て同じ解像度である必要があります。これはFLARToolKitで決められています。
FLARManagerの標準マーカーは「8」を、FLARToolKit本体に付属している標準マーカーは「16」を使用します。

patternToBorderRatioX

黒枠も含めたマーカーの幅のうち、白領域が占める割合を 20～80の間で指定します。標準マーカーでは「50」です。黒枠を細くする場合には値を小さくしてください。

patternToBorderRatioY

黒枠も含めたマーカーの高さのうち、白領域が占める割合を20～80の間で指定します。標準マーカーでは「50」です。黒枠を細くする場合には値を小さくしてください。

minConfidence

FLARToolKitでは検出したマーカー候補に対して、パターンマッチのアルゴリズムによって、 各パターンファイルとの一致率を、0.0～1.0の間で算出します。この値で最低限の一致率を指定します。
つまり、ここで指定した数値以下の一致率の場合はマーカーとして認識しません。誤検出を避けたい場合は高めに、検出率を上げたい場合は低めに指定してください。

pattern(子要素)

それぞれのpattern要素はFLARToolKitが検出を試みるマーカーを示します。
FLARToolKitは理論上は無制限な数のマーカーを探索できますが、ここで指定したパターンファイル全てに対してパターンマッチを行うため、数が多くなるほど処理は遅くなります。 1アプリケーションで使用するマーカー数はできるだけ少なくしたほうがいいでしょう。

path

パターンファイルへのパスを指定します。パスはswfファイルからの相対パスで指定します。

size

マーカーのサイズ(pixel)を指定します。マーカー上に表示するオブジェクトのサイズはこの値を基準とします。
マーカーに対してモデルが大きく見えるならばこの値を小さく、モデルが小さければ大きくしてください。初期値は80です。
例えば、マーカーサイズに80を指定している場合、1辺40ピクセルの立方体をマーカー上に表示すると、常にマーカーの半分の大きさに見えます。このときマーカーを1辺80cmで印刷していれば、1ピクセル=1mmとなり、1辺40ピクセルの立方体は1辺4cmの立方体として表示されます。

「cameraParamsFile」について

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

「labelAreaMin」「labelAreaMax」について

マーカーのみ撮影している状態では初期値のままでも問題ありませんが、マーカー以外のものが映るような環境では、この値を調節することで誤検出を抑えることができます。
紙面にマーカーが表示されている場合は文字に、遠距離で使用している場合は物陰などに反応することがあります。これらはlabelAreaMinを少し上げることで抑えられる可能性が高くなります。 また、認識できるサイズの上限と下限を狭めることで、マーカーがカメラに対して一定の距離内にある場合のみ認識するというように使用することもできます。

「patternToBorderRatioX」「patternToBorderRatioY」について

マーカーの黒枠の比率を縦横で変えることができます。つまり長方形マーカーを使用することができます。

図内のマーカーは左右で形が違います。ですが、白領域の部分は同じになります。
長方形タイプのマーカーとパターンファイルを作成する手順は以下の通りです。

1. 黒枠正方形の状態(図内左側)で白領域の内容を決めます。白領域は必ず正方形である必要があります。
2. 正方形のマーカーからパターンファイルを作成します。
3. 印刷したり配布したりする用のマーカーの黒枠の幅を変更(図内右側)します。
4. マーカー全体に対する白領域の割合を「patternToBorderRatioX」「patternToBorderRatioY」に指定します。

まとめ

設定項目と変更した場合の特性を抑えて、目的に合わせて設定してください。