Table of Contents

Mega トラッキング過程を制御する

この記事では、Mega トラッキング過程における各機能とパラメーターを制御し、異なるアプリケーションシーンの要件を満たす方法を紹介します。

始める前に

tracker のワークフロー

tracker のワークフローは次のとおりです。

flowchart LR
  subgraph startup_graph[開始]
    direction TB
    sstart((session 開始))
    create[ネイティブ作成]
    load(target をロード)
    init_g[[初期化]]
  end
  
  subgraph init_graph[初期化]
    direction TB
    init_{6DoF 初期化成功<br>または非 6DoF}
    init[[ローカルトラッキング初期化プロセス]]
    localization_g[[初期ローカライゼーション]]
  end

  subgraph localization_graph[初期ローカライゼーション]
    direction TB
    localize__{ローカライゼーションが有効で<br>リクエスト間隔を超過}
    localize[クラウドローカライゼーション]
    localize_{block にローカライズ済みで<br>block ロード済み}
    tracking_g[[トラッキング]]
  end
  
  subgraph tracking_graph[トラッキング]
    direction TB
    tracking[[継続トラッキング]]
  
    localizet_{ローカライゼーションが有効で<br>リクエスト間隔を超過}
    localize2[クラウドローカライゼーション]
    localize2_{block にローカライズ済みで<br>block ロード済み}
    localization_g2[[初期ローカライゼーション]]
  end

  subgraph stopping_graph[停止]
    direction TB
    unload(target をアンロード)
    dispose[ネイティブ破棄]
    sstop([session 停止])
  end

  sstart --> create --> load --> init_g
  init --> init_ --> |Yes| localization_g
  localize --> localize_ --> |Yes| tracking_g
  localize_ --> |No| localize__ --> |Yes| localize
  unload --> dispose --> sstop
  init_ --> |No| init

  tracking --> localizet_ --> |Yes| localize2 --> localize2_ --> |Yes| tracking
  localizet_ --> |No| tracking
  localize2_ --> |No| localization_g2

  startup_graph --> init_graph
  init_graph --> localization_graph
  localization_graph --> tracking_graph
  tracking_graph --> localization_graph
  tracking_graph --> stopping_graph

フローは大まかにいくつかの段階に分かれます。

  • 起動：
    • session 起動後、ネイティブ層の tracker が作成されます。
    • target 自身の Start() の後、対応する tracker に読み込まれます。
  • 初期化：
    • 6DoF frame source を使用する場合、ローカルトラッキング初期化過程に入ります。
    • 非 6DoF frame source を使用する場合、初期化段階はスキップされ、初期ローカライズ段階に直接入ります。
    • この過程には時間がかかる場合があります。シーンの複雑さとデバイス性能に関連し、通常は frame source の低レイヤーで使用されるアルゴリズムとも関係します。
    • デフォルト設定では、この段階の内容は表示されません。ActiveController コンポーネントオプションでこの挙動を制御できます。
  • 初期ローカライズ：
    • ローカライズが有効で、リクエスト間隔を超えている場合、tracker はクラウドへローカライズリクエストを送信します。
      • ローカライズ成功後、ローカライズサービスが返した id に対応する block が読み込み済みであればトラッキング段階に入ります。block が未読み込みの場合、block の読み込み完了を待ち、次回のローカライズリクエストを待ちます。
      • ローカライズ失敗後、tracker は次回のローカライズリクエストを待ち続けます。
    • この過程には時間がかかる場合があります。シーンのローカライズしやすさ、データ収集およびマッピング品質、ネットワーク状況に依存します。
    • デフォルト設定では、この段階の内容は表示されません。ActiveController コンポーネントオプションでこの挙動を制御できます。
  • トラッキング：
    • tracker は現在の block を継続的にトラッキングします。
    • ローカライズが有効で、リクエスト間隔を超えている場合、tracker はクラウドへローカライズリクエストを送信します。
      • ローカライズ成功後、ローカライズサービスが返した id が変化していなければ、トラッキングを継続します。id が変化し、かつ block が読み込み済みであれば、新しい block に切り替えてトラッキングを継続します。id が変化し、かつ block が未読み込みの場合、block の読み込み完了を待ち、次回のローカライズリクエストを待ちます。
      • ローカライズ失敗後、tracker は現在の block のトラッキングを継続し、次回のローカライズリクエストを待ちます。
    • デフォルト設定では、トラッキング状態（TargetController.IsTracked == true）の target ノード下のコンテンツのみ表示されます。ActiveController コンポーネントオプションでこの挙動を制御できます。
  • 停止：
    • session 停止後、target はアンロードされ、ネイティブ層の tracker は破棄されます。

デバイス対応レベルを調整する

MegaTrackerFrameFilter の MegaTrackerFrameFilter.MinInputFrameLevel プロパティは、Mega がサポートする最低デバイスレベルを指定するために使用されます。

alt text

Mega はほぼすべての種類のフレームデータソース上で実行できますが、異なるフレームデータソースはトラッキング結果に異なる影響を与えます。

デフォルトでは、Mega はデバイスがサポートする最高レベルのフレームデータソースを選択してトラッキングします。デフォルト設定で Mega をサポートする session には、6DoF と 5DoF をサポートするフレームデータソースがすでに設定されています。

Mega 実行時にあるレベルのフレームデータソースをサポートするには、2 つの条件を満たす必要があります。

たとえば、デフォルト session で 3DoF トラッキングをサポートするには、次が必要です。

別の例として、デフォルト session から 5DoF トラッキングサポートを削除するには、次が必要です。

条件を満たす利用可能なフレームデータソースがない場合、session の組み立ては失敗します。

現在のシステム状態を理解する

デフォルトの session 設定では、UI メッセージ が画面上に表示され、その中に Mega トラッキング状態の情報が含まれます。

ローカライズ成功時、Mega サービス情報には Found 状態テキストが含まれます。ローカライズ失敗時、Mega サービス情報には NotFound 状態テキストが含まれます。

読み込み済みの block は Block [scnObj=<objName>] (<trackingStatus>): <name> (<id>) と表示されます。ここで <objName> は block に対応するシーンオブジェクト名、<name> は block の名称、<id> は block の ID です。trackingStatus は Tracking または NotTracking であり、それぞれ現在の block がトラッキング中かどうかを示します。

alt text alt text

ローカライズ成功時、ローカライズされたが未読み込みの block 情報は Block [scnObj=?]: <name> (<id>) と表示されます。

alt text

ヒント

NotFound は正常な状態であり、Mega の動作全体を通して頻繁に現れます。この状態が表示されてもトラッキングは継続しています。通常、アプリ開発では NotFound 状態に特別な処理を行う必要はありません。

MegaTrackerFrameFilter.LocalizationRespond イベントを使用すると、現在のローカライズ状態を取得し、システムが現在トラッキングターゲットを見つけているかを把握できます。

次のコードは、このイベントの使用方法と、アプリが注目すべき一般的な異常状態の処理方法を示しています。

private void Awake()
{
    megaTracker.LocalizationRespond += HandleLocalizationStatusChange;
}
        
private void HandleLocalizationStatusChange(MegaLocalizationResponse response)
{
    var status = response.Status;
    wakingUpCount = status == MegaTrackerLocalizationStatus.WakingUp ? wakingUpCount + 1 : 0;
    if (wakingUpCount >= 5)
    {
        // サービスを起動中のため、エンドユーザーに待機してもらう必要があります
    }

    if (status == MegaTrackerLocalizationStatus.QpsLimitExceeded)
    {
        // QPS の上限を超えています。一部のエンドユーザーでランダムにローカライズが失敗します（全体的な tracking 品質が低下します）
        // この場合、通常は現在のユーザー数で tracking 品質を確保するため、料金を支払って QPS 上限を引き上げる必要があります
    }

    if (status == MegaTrackerLocalizationStatus.ApiTokenExpired)
    {
        // Token が期限切れです。これは Token インターフェイスでサービスへアクセスする場合にのみ発生します
        // この問題を解決するには、アプリケーションが自分のバックエンドに Token を要求し、MegaTrackerFrameFilter.UpdateToken を呼び出して更新する必要があります
    }
}

アプリで MegaTrackerLocalizationStatus.RequestTimeout 状態が頻繁に発生する場合、通常はデバイスとサービス間のネットワーク接続状況が良くないことを示します。トラッキング品質を向上させるため、ネットワーク環境の最適化を推奨します。ネットワーク状況を改善できないシーンでは、リクエストタイムアウト時間を増やすことを検討できます。

注記

このイベントを通じてローカライズが返す pose を取得することはできません。

実際には、ローカライズが返す pose はアプリ開発では不要です。EasyAR はローカライズ結果が返った後、ローカルアルゴリズムにより、より正確な pose を計算して開発者へ返します。この pose はすでに block の transform に反映されています。session の実行結果を取得する を参照できます。

一時停止と再開

Mega のトラッキング機能とローカライズ機能は、それぞれ一時停止および再開できます。

トラッキングを一時停止する

MegaTrackerFrameFilter.enabled を false に設定すると、トラッキングを一時停止できます。

デフォルトでは、トラッキングが一時停止された後、すべての block ノード下のコンテンツが非表示になります。

ローカライズを一時停止する

MegaTrackerFrameFilter.EnableLocalization を false に設定すると、ローカライズを一時停止できます。

警告

ローカライズの一時停止はトラッキング結果に影響します。通常は変更を推奨しません。EasyAR テクニカルサポートの指導のもとで使用してください。

アプリケーション実行中にローカライズを一時停止したことがある場合、EasyAR に問題を報告する際は必ずその点を説明してください。

サービスとリクエスト制御

MegaTrackerFrameFilter コンポーネントのパラメーターを変更することで、サービスリクエストの挙動を制御できます。

ローカライズライブラリを選択する

session 下の Mega Tracker オブジェクトを選択し、Service 下のオプションを変更すると、接続するローカライズライブラリを調整できます。このオプションは session 起動前に設定する必要があります。

デフォルト設定では、Access Source は Global Config です。サービス設定はグローバル設定を使用し、サービスパラメーターは Project Settings の EasyAR > Sense > Mega > Mega Block で変更できます。この設定は、このグローバル設定を使用するすべての session に影響します。

alt text

ヒント

サービス設定は EasyAR 開発センターから取得できます。
Mega Config Detail

異なる session で異なるローカライズライブラリを使用する必要がある場合、Access Source を API Key に設定し、その下のサービスパラメーターを変更できます。

alt text

スクリプトでは、MegaTrackerFrameFilter.ServiceAccessSource と MegaTrackerFrameFilter.ServiceAccessData を変更して同じ効果を得られます。

たとえば、次のコードは session 起動前に実行時パラメーターを使用してサービスへ接続するよう tracker を設定する方法を示しています。

megaTracker.ServiceType = easyar.MegaApiType.Block;
megaTracker.ServiceAccessSource = easyar.MegaServiceAccessSourceType.APIKey;
megaTracker.ServiceAccessData = new easyar.APIKeyAccessData
{
    ServerAddress = serverAddress,
    APIKey = apiKey,
    APISecret = apiSecret,
    AppID = appID
};

リクエスト間隔とタイムアウト

session 下の Mega Tracker オブジェクトを選択し、Request Time Parameters 下のオプションを変更すると、サービスリクエストの時間間隔とタイムアウト時間を調整できます。

alt text

スクリプトでは、MegaTrackerFrameFilter.RequestTimeParameters を変更して同じ効果を得られます。

警告

リクエスト間隔の変更はトラッキング結果に影響します。通常は変更を推奨しません。EasyAR テクニカルサポートの指導のもとで使用してください。

アプリケーション実行中にリクエスト間隔を変更したことがある場合、EasyAR に問題を報告する際は必ずその点を説明してください。

ローカライズライブラリを切り替える

MegaTrackerFrameFilter.SwitchEndPoint を使用すると、実行時にローカライズライブラリを切り替えられます。このインターフェースを使用しても、カメラ映像および session は中断されません。

関連トピック