Wikitude SDK APIリファレンス

バージョン: 8.1.0
表示:

ImageTrackableクラス

継承元: ARObject
モジュール: AR

ImageTrackableは、ターゲットコレクション内の特定のターゲットにバインドされた仮想オブジェクトを表します。ターゲットはカメラのシーンでトラッキングされ、Drawablesは可視になるとすぐにターゲットに投影され、シーンで検出されます。ImageTrackableは、特定のターゲットコレクション内の1つのターゲットにリンクされています。

ImageTrackable

  • トラッカー内の1つのトラッカーと1つのターゲットに関連付けられています。
  • Drawablesを関連付けることができます。これらのDrawableは、カメラビューのImageTrackableを表します。
  • それに関連付けられたトリガーを持つことができます。特定のイベントを発生させ、これらのアクションに反応する関数を実行します。

作成時には、トラッカーへの参照と、トラッカー内のターゲットの名前を渡す必要があります。ターゲット名は、正確な名前でも正規表現でもかまいません。たとえば、「*」は指定されたトラッカーに含まれるすべてのターゲットと一致します。この場合、onImageRecognizedイベントは認識されたターゲット名をパラメータとして渡します。

ImageTrackableを有効または無効にすることができます（ARObject.enabledを参照）。Enabledは、ImageTrackableがカメラ内のオブジェクトのトラッキングで考慮され、トリガーが適切なイベントで発生することを意味します。ImageTrackableが無効になっている場合、トラッキング処理は考慮されず、トリガーも起動しません。ImageTrackableをトラッキングするためには、関連付けられたトラッカーも有効にする必要があります。

作成時に、セットアップパラメータを渡してImageTrackableのプロパティをカスタマイズすることができます。

クライアント認識例:
// a circle used for representation
var circle = new AR.Circle(5);
// the referenced tracker
var targetCollectionResource = new AR.TargetCollectionResource("http://myserver.com/targetCollection1.wtc");
var tracker = new AR.ImageTracker(targetCollectionResource);
// a ImageTrackable using the "car" target in the tracker, using the circle as the digital representation.
var ImageTrackable = new AR.ImageTrackable(tracker, "car", {
    drawables : {
        cam : circle
    }
});
クラウド認識例:
// a circle used for representation
var circle = new AR.Circle(5);
// the referenced tracker
var cloudRecognitionService = new AR.CloudRecognitionService("__your_client_token__", "__target_collection_id__");
var tracker = new AR.ImageTracker(cloudConnection);
// a ImageTrackable using the "car" target in the tracker, using the circle as the digital representation.
var ImageTrackable = new AR.ImageTrackable(tracker, "car", {
    drawables : {
        cam : circle
    }
});

<添付されているDrawableのレンダーサイズについては、SDUを参照してください。

コンストラクター

ImageTrackable

(
  • tracker
  • targetName
  • options
)

パラメーター:

  • tracker ImageTracker

    ターゲットが保存されているImageTracker

  • targetName String

    トラッカー内のターゲットの名前

  • options Object オプション

    追加のオブジェクトプロパティをカスタマイズするためのパラメーター。

    設定可能なプロパティは以下のとおりです。

    • enabled （デフォルト値: true） Boolean オプション
    • renderingOrder （デフォルト値: 0） Number オプション
    • onImageRecognized Function オプション
    • onImageLost Function オプション
    • onClick Function オプション
    • onDragBegan Function オプション
    • onDragChanged Function オプション
    • onDragEnded Function オプション
    • onPanBegan Function オプション
    • onPanChanged Function オプション
    • onPanEnded Function オプション
    • onRotationBegan Function オプション
    • onRotationChanged Function オプション
    • onRotationEnded Function オプション
    • onScaleBegan Function オプション
    • onScaleChanged Function オプション
    • onScaleEnded Function オプション
    • drawables.cam Drawable[] オプション
    • distanceToTarget.changedThreshold Number オプション
    • distanceToTarget.onDistanceChanged Function オプション
    • enableExtendedTracking Boolean オプション
    • extendedTarget String オプション
    • extendedTrackingQualityChanged Function オプション
    • snapToScreen.onDelayedSnapInterruption Function optional
    • distanceToTarget.changedThreshold Number optional
    • distanceToTarget.onDistanceChanged Function optional
    • enableExtendedTracking Boolean optional
    • extendedTarget String optional
    • onExtendedTrackingQualityChangedTriggerActive Function optional

メソッド

addImageTargetCamDrawables

(
  • imageTarget
  • arrayOfDrawables
  • position
)

ImageTargetのImageTrackableにAR.Drawablesを追加します。 これにより、同じターゲット画像（同じターゲット画像を持つ複数のターゲット）に対して異なるAR.Drawablesが可能になります。

パラメーター:

destroy

()

継承元: ARchitectObject

オブジェクトを破棄します。

drawables.addCamDrawable

(
  • drawable
  • position
)

継承元: ARObject

カメラのARObjectにDrawablesを追加します。

パラメーター:

  • drawable Drawable | Drawable[]

    カメラに追加するDrawable。1つのDrawableまたはDrawableの配列のいずれかになります。

  • position Number オプション

    Drawableを追加する配列の位置。指定しない場合、配列の最後にDrawableが追加されます。整数でなければなりません。

drawables.removeCamDrawable

(
  • drawable|position
)

継承元: ARObject

カメラのARObjectからDrawablesを削除します。

パラメーター:

  • drawable|position Drawable | [Drawable] | Number

    1つのDrawableまたはDrawablesの配列が指定された場合、これらのDrawableは配列から削除されます。整数が指定されると、指定された位置のDrawableが削除されます。

isVisible

() Boolean

継承元: ARObject

ARObjectの現在の可視性の状態を返します。ARObjectの位置（ジオロケーションまたはビジュアルトラッカー）の少なくとも1つが現在スクリーン上に表示されているスクリーン座標に投影されるとARObjectトが表示されます。

戻り値:

Boolean:

オブジェクトが現在画面に表示されているか（true）、または表示されていない（false）かを示します。

removeImageTargetCamDrawables

(
  • imageTarget
  • drawables|position
)

ImageTargetのImageTrackableでAR.Drawablesを削除します。

パラメーター:

stopExtendedTracking

()

拡張トラッキングを直ちに停止します。ターゲット画像が既に視野の外側にある場合、これはシーンのトラッキングを停止します。拡張トラッキングを再開することは、関連するターゲット画像の1つが再び認識される場合にのみ可能です。

プロパティ

aspectRatio

Number

幅/高さとして定義されたターゲットのアスペクト比。このプロパティは読み取り専用で、ターゲットがロードされた後に生成されます。参照されたトラッカーがまだロードされていない場合、プロパティーは未定義です。

destroyed

Boolean

継承元: ARchitectObject

オブジェクトがすでに破棄されているかどうかを示します。

distanceToTarget.changedThreshold

Number

変更イベントをトリガーするために必要な距離しきい値（mm単位）。

デフォルト値: 0

distanceToTarget.onDistanceChanged

Function

<

ユーザーとターゲット間の距離が変わったときに呼び出される関数。更新された距離がこの関数にパラメーターとして渡されます。

デフォルト値: null

drawables.cam

Drawable[]

継承元: ARObject

カメラビューでARObjectを表すために使用されるDrawables。配列内のDrawableはDrawableで始まる位置0に印刷され、後のインデックスのDrawablesが以前に描画されたDrawableと重なるようになります。

注意:

変更内容がネイティブアプリケーションに伝播することが保証されないため、配列の内容は[]演算子で操作しないでください。プロパティはarobject.drawables.addCamDrawable()およびarobject.drawables.removeCamDrawable()で操作するか、arobject.drawables.cam = new Array（...）;で直接設定する必要があります。

enabled

Boolean

継承元: ARObject

ARObjectを有効または無効にするブール値のフラグ。

デフォルト: true

enableExtendedTracking

Boolean

このプロパティがtrueに設定されている場合、このトラッキングが可能なオブジェクトは拡張トラッキングモードをトリガーします。拡張トラッキングモードでは、トラッカーは3Dシーンをトラッキングし、ターゲットが見えなくなってもアクティブなままです。このプロパティは読み取り専用で、作成時にのみ設定できます。

extendedTarget

String

このプロパティを使用して、ImageTrackableのどのターゲットを拡張ターゲットとして扱うかどうかを定義します。ワイルドカードを使用してtargetNameを定義する場合、このプロパティは同じワイルドカード設定（ '*'と '？'）も使用できます。このプロパティはいつでも変更できます。進行中の拡張トラッキングが失われたり、stopExtendedTracking関数が呼び出されるとすぐに変更が反映されます。

onExtendedTrackingQualityChanged

Function

この関数が定義されている場合は、拡張トラッキングの品質が変更されるたびに呼び出されます。拡張トラッキング品質は、3つの値があります。

    * -1 ：拡張トラッキングの品質は悪く、拡張トラッキングはほとんど機能しない可能性があります。
    * 0 :拡張されたトラッキング品質はそれほど良好ではありませんが、拡張トラッキングは機能する可能性があります。
    * 1 :拡張トラッキングの品質は良好であり、拡張トラッキングはおそらく有効です。
このコールバック関数には3つのパラメータがあることに注意してください。最初の1つ目はトラッキングされた拡張ターゲット名です。2つ目は以前に拡張されたトラッキング品質です。3つ目は拡張トラッキング品質です。

renderingOrder

Number

継承元: ARObject

異なるARObjects の描画可能オブジェクトが重複する可能性があります。この場合、renderingOrderはARObjectのDrawablesのレンダリング順序を定義します。より高いrenderingOrder値を持つARObjectsは、drawOleder値が低いARObjectsのDrawableの上にDrawablesを描画します。2つのARObjectsが同じrenderingOrderを設定している場合、Drawablesは距離に基づいてレンダリングされ、オブジェクトに近いところでオブジェクトをオーバーラップさせます。
たとえば、特定のARObjectのDrawablesを最前面に持ってくる場合、対応するARObjectのrenderingOrder値を非常に高い値に設定します。

同じARObject内のDrawablesの印刷順序については、Drawable2D.zOrderを参照してください。


整数でなければなりません。

デフォルト: 0

snapToScreen.enabled

Boolean

継承元: ScreenSnapper

trueに設定した場合、すべての拡張オブジェクトが、snapToScreen.snapContainer要素によって指定されたdivにレンダリングされます。このとき、Trackable2DObjectはonEnterFieldOfVision状態にある必要があります。そうでない場合、enabledをtrueに設定しても効果はありません。その代わりに、onEnterFieldOfVision状態にないときにenabledをfalseに設定することは有効です。したがって、Trackable2DObjectをカメラビューに固定表示できるのはターゲットが認識されているときだけですが、固定表示されているTrackable2DObjectはいつでも通常に戻すことができます。

デフォルト値: false

snapToScreen.enableDelayed

Number

継承元: ScreenSnapper

onEnterFieldOfVisionトリガーが実行されてからアタッチされたDrawableがカメラビューに固定表示されるまでの遅延時間。負の値を設定すると固定表示が無効になります。遅延中にターゲットが失われると、onDelayedSnapInterruptionトリガーが実行されます。

デフォルト値: -1

snapToScreen.enableOnExitFieldOfVision

Boolean

継承元: ScreenSnapper

trueに設定した場合、onExitFieldOfVisionトリガーが発生したときに、関連付けられた拡張オブジェクトがカメラビューに固定表示されます。このプロパティを使用すると、ターゲットがカメラビューから外れた場合にも拡張オブジェクトをカメラビューに固定表示できます。このような動作はenabledプロパティでは実現できません。固定表示を無効にするには、たとえば、onEnterFieldOfVisionトリガーなどの任意の時点でenabledプロパティをfalseに設定します。

デフォルト値: false

snapToScreen.snapContainer

DOM Element

継承元: ScreenSnapper

固定表示が有効な場合にこのTrackable2DObjectに関連付けられたすべての拡張オブジェクトを収容するDOM要素。すべての拡張オブジェクトがこの要素に収まるように、拡張オブジェクトにスケーリングを適用しなければならない場合があります。また、DOM要素のアスペクト比も確認する必要があります。

デフォルト値: null

targetName

String

ターゲットコレクション内の参照先のターゲットの名前。これは、ImageTrackableがどのターゲットイメージに反応するかを定義します。値は、イメージの実際の名前か、または複数に一致するワイルドカードのいずれかです。次のワイルドカードがサポートされています：*と？正規表現と同じ方法で使用することができます。このプロパティは読み取り専用で、作成時にのみ設定できます。

tracker

ImageTracker

このImageTrackableによって参照されるターゲットを含むImageTracker。このプロパティは読み取り専用で、作成時にのみ設定できます。

イベント

onClick

継承元: ARObject

ARObjectのDrawableのいずれかがクリックされ、クリックされたDrawablesのonClick()トリガ（他のARObjectによって参照される可能性もあります）がクリックチェインを終了するように設定されている時に実行されます。ARObject.onClick()は、Drawable.onClick()トリガーが実行された後に実行されます。

クリックによって複数のARObjectがヒットした場合、実行の順序は、ARObjectのクリックトリガーが最初に実行された状態で、ARObjectのユーザーまでの距離によって定義されます。

関数の戻り値は、このARObjectに対してonClick()関数が実行された後、キュー内の次のARObjectに対してonClick()を実行し続けるかどうかを決定します。キュー内の最後のARObjectが依然としてクリックキューを継続することを要求した場合、context.onScreenClick()が実行されます。

関数の戻り値は、次に何をするかを決定します。falseの場合、このARObjectでクリックキューを停止しません。したがって、次のARObjectのonClick()関数が実行されます。戻り値が設定されていないか、あるいはこのARObjectに対して関数が定義されていない場合はデフォルト値になります。trueの場合、キューの実行は現在のARObjectで停止し、ARObjectsはonClick()呼び出しを受け取りません。

onDragBegan

継承元: ARObject

ユーザーが1本の指で1つ以上のDrawableをドラッグし始めたときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離。ドラッグジェスチャへの変更が発生していない場合、onDragBeganは常に0です。

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離。ドラッグジェスチャへの変更が発生していない場合、onDragBeganは常に0です。

onDragChanged

継承元: ARObject

ユーザーが1本の指で少なくとも1つのDrawableをドラッグすると実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離

onDragEnded

継承元: ARObject

ユーザーが1本の指で1つ以上のDrawableをドラッグして停止したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離。onDragChangedで受信した最新の距離と常に同じ

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離。onDragChangedで受信した最新の距離と常に同じ

onEnterFieldOfVision

非推奨

非推奨：代わりにonImageRecognizedを使用してください。

トリガは、ImageTrackableの可視性が不可視から可視に変更されたときに発生します。

このトリガーのデフォルト値はnullであり、トリガーが発生したときに何もアクションは実行されません。開発者は、onEnterFieldOfVisionにカスタム関数を割り当てることによって、カスタム機能を追加できます。

イベントペイロード:

  • targetName String

    認識されたターゲットの名前を保持します。targetNameにワイルドカードを組み合わせて使用します。

onExitFieldOfVision

非推奨

非推奨：代わりにonImageLostを使用してください。

ImageTrackableの可視性が可視から不可視に変更されたときに実行されます。

このトリガーのデフォルト値はnullであり、トリガーが発生したときに何もアクションは実行されません。開発者は、カスタム関数をonExitFieldOfVisionに割り当てることによって、カスタム機能を追加できます。

イベントペイロード:

  • targetName String

    視野から外れたターゲットの名前を保持します。

onImageLost

ImageTrackableの可視性が可視から不可視に変更されたときに実行されます。

このトリガーのデフォルト値はnullであり、トリガーが発生したときに何もアクションは実行されません。開発者は、カスタム関数をonImageLostに割り当てることにより、カスタム機能を追加できます。

イベントペイロード:

  • target ImageTarget

    視野から外れたターゲットの名前を保持します。

    失われたターゲットを表すImageTarget。

onImageRecognized

トリガは、ImageTrackableの可視性が不可視から可視に変更されたときに発生します。

このトリガーのデフォルト値はnullであり、トリガーが発生したときに何もアクションは実行されません。開発者は、カスタム関数をonImageRecognizedに割り当てることによって、カスタム関数を追加できます。

イベントペイロード:

  • target ImageTarget

    認識されたターゲットを表すImageTarget。

    認識されたターゲットの名前を保持します。targetNameにワイルドカードを組み合わせて使用します。

onPanBegan

継承元: ARObject

ユーザーが2本の指で1つ以上のDrawableをドラッグし始めたときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離。パンジェスチャへの変更が発生していない場合、onPanBeganは常に0です。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離。パンジェスチャへの変更が発生していない場合、onPanBeganは常に0です。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

onPanChanged

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableをドラッグすると実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

onPanEnded

継承元: ARObject

ユーザーが2本の指で1つ以上のDrawableをドラッグして停止したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • xNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のX軸上の距離。onPanChangedで受信した最新の距離と常に同じです。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

  • yNormalized Number

    開始タッチ位置と更新タッチ位置[-1,1]との間のY軸上の距離。onPanChangedで受信した最新の距離と常に同じです。第1のタッチと第2のタッチとの間の中間点はスケールと回転のジェスチャーの同時動作のための距離の計算に使用されます。

onRotationBegan

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableの回転を開始したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • angle Number

    開始タッチ位置によって定義された線と更新されたタッチ位置[0,360]によって定義される線との間の角度でのCCW角度。回転ジェスチャの変更が発生していない場合、onRotationBeganでは常に0です。

onRotationChanged

継承元: ARObject

ユーザーが2本の指で1つ以上のDrawableを回転させたときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • angle Number

    開始タッチ位置によって定義される線と更新されたタッチ位置[0,360]によって定義される線との間の角度でのCCW角度。

onRotationEnded

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableの回転を停止したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • angle Number

    開始タッチ位置によって定義された線と更新されたタッチ位置[0,360]によって定義される線との間の角度でのCCW角度。onRotationChangedで受け取った最新の角度と常に同じ。

onScaleBegan

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableの拡大縮小を開始したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • scale Number

    スケール値は、開始タッチ間の距離にわたる更新されたタッチ間の距離の比[0、inf]を定義します。スケールジェスチャへの変更が発生していない場合、onScaleBeganは常に1です。

onScaleChanged

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableの拡大縮小したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • scale Number

    開始タッチと更新されたタッチ間の距離の比を定義した[0、inf]のスケール値。

onScaleEnded

継承元: ARObject

ユーザーが2本の指で少なくとも1つのDrawableの拡大縮小を停止したときに実行されます。このコールバックは、イベント伝播の流れとしてonClickコールバックと同じように動作します。

イベントペイロード:

  • scale Number

    開始タッチと更新されたタッチ間の距離の比を定義した[0、inf]のスケール値。onScaleChangedで受信した最新のスケールと常に同じ

snapToScreen.onDelayedSnapInterruption

Function

継承元: ScreenSnapper

固定表示が遅延中に、onExitFieldOfVisionイベントによってターゲットが失われたときに呼び出されるトリガー。

イベントペイロード:

  • interruptionTimestamp Number

    enabledDelayedプロパティによってアクティブ化されてからonExitFieldOfVisionイベントによって中断されるまでの経過時間（ミリ秒単位）。

snapToScreen.onSnappedToScreen

Function

継承元: ScreenSnapper

拡張オブジェクトの固定表示時に呼び出されるトリガー。

イベントペイロード:

  • element DOM Element

    拡張オブジェクトを固定表示する対象のDOM要素。