バージョン： 3.5

ランタイムにARロケーションのVPSカバレッジをクエリする

VPSカバレッジAPIは、実行時にARロケーションを発見し、マップ上に表示したり、ARLocationManagerのローカライズターゲットとして使用するための機能を提供します。

CoverageClientManagerの設定

CoverageClientManagerは、Unityエディタでシーンに追加するか、AddComponentを通して実行時に追加します。 ARLocationは、ユーザーの現在のGPS位置か、ユーザーが指定した位置（例えば、地図上の都市をリモートで表示する）の周辺にあるARLocationを問い合わせることができます。また、CoverageClientManagerは、GPS位置の周囲を照会する半径（メートル単位）を定義するQueryRadiusの設定を提供します。

備考

Unityプロジェクトでは、ビルドターゲットに対してロケーション使用権限を設定する必要があります。 iOSの場合、Project SettingsにLocation Usage Descriptionが必要です。 Androidの場合、ユーザーはACCESS_FINE_LOCATIONパーミッションを与える必要があり、CoverageClientManagerは使用時にこれを要求します。

以下のコードスニペットは、ユーザーの現在地から 1km 以内にある ARLocation をクエリする CoverageClientManager の設定と構成を示しています。

クリックして CoverageClientManagerExample.cs を開く

using Niantic.Lightship.AR.VpsCoverage;
using UnityEngine;

public class CoverageClientManagerExample : MonoBehaviour
{
    [SerializeField]
    private CoverageClientManager CoverageClientManager;

    public void QueryAroundUser()
    {
        // 提供されていない場合は、現在のゲームオブジェクトに作成する
        if (!CoverageClientManager)
        {
            CoverageClientManager = gameObject.AddComponent<CoverageClientManager>();
        } // デバイスの現在位置を使用する。

        // カバレッジをクエリするには、デバイスの現在位置を使用します。クエリ半径は1000メートルに設定されています。
        CoverageClientManager.UseCurrentLocation = true;
        CoverageClientManager.QueryRadius = 1000;
        
        CoverageClientManager.TryGetCoverage(OnCoverageResult);
    }

    private void OnCoverageResult(AreaTargetsResult result)
    {
        // 現在は何もしません
    }
}

カバレッジ結果の使用

AreaTargetsResult クラスは、VPS Coverage API クエリからの情報を返します。 StatusがSuccessであることを確認するか、必要に応じて失敗ケースを処理する。 VPS Coverage APIクエリの関連データのほとんどは、AreaTargetsリストに含まれる。

エリアターゲットとその内容

各AreaTargetは、CoverageAreaとLocalizationTargetの2つのフィールドを含みます。

CoverageAreaは、Location ARがサポートされる実世界空間の2次元多角形を定義します。例えば、Shape プロパティは LatLng ポイントを使用して地図上にオーバーレイを描くために使用することができ、LocalizabilityQuality プロパティはそのエリアにおけるトラッキングの全体的な品質をレポートします。

LocalizationTargetは、VPSのローカライゼーションがサポートされる実世界空間の点を定義します。 Nameプロパティと ImageURL プロパティは特定の場所に関する情報カードを作成するために使用でき、DefaultAnchor プロパティはトラッキングを開始するために ARLocationManager に渡すことができます。

これらのフィールドとそのプロパティの詳細については、API ドキュメントを参照。

このスニペットはCoverageAreaとLocalizationTargetのデータを組み合わせて、AreaTargetsResultsをソートして使用可能なリストにフィルタリングします：

エリア・ターゲットのサンプル・スクリプトを表示するにはクリックしてください。

using Niantic.Lightship.AR.VpsCoverage;
using UnityEngine;

public class CoverageClientManagerExample : MonoBehaviour
{
    [SerializeField]
    private CoverageClientManager CoverageClientManager;

    public void QueryAroundUser()
    {
        CoverageClientManager.TryGetCoverage(OnCoverageResult);
    }

    private void OnCoverageResult(AreaTargetsResult areaTargetsResult)
    {
        if (areaTargetsResult.Status == ResponseStatus.Success)
        {
            // クエリ位置からの距離でエリアターゲットをソートする
            areaTargetsResult.AreaTargets.Sort((a, b) =>
                a.Area.Centroid.Distance(areaTargetsResult.QueryLocation).CompareTo(
                    b.Area.Centroid.Distance(areaTargetsResult.QueryLocation));

            // 最も近い 5 つの生産品質エリアのみを考慮する
            var maxCount = 5;
            foreach (var result in areaTargetsResult.AreaTargets)
            {
                if (result.Area.LocalizabilityQuality != CoverageArea.Localizability.PRODUCTION)
                {
                    continue;
                }
                
                Debug.Log($"Got a localization target: {result.Target.Name}, anchor payload: {result.Target.DefaultAnchor}");
                maxCount--;
                if (maxCount == 0)
                {
                    break;
                }
            }
        }
        else
        {
            Debug.LogError($"Coverage query failed with status: {areaTargetsResult.Status}");
        }
    }
}

ヒント画像のダウンロード

それぞれのLocalizationTargetはImageURLを含んでおり、これはLocalizationTargetに対応するホストされたヒント画像を指しています。この情報は、ローカライズするためにユーザーを実世界の場所に誘導するために使用することができる。 CoverageClientManagerには、ヒント画像をダウンロードしてTextureを作成するユーティリティメソッドがいくつかあります：

クリックするとヒント画像のコードスニペットが表示されます。

using Niantic.Lightship.AR.VpsCoverage;
using UnityEngine;

public class CoverageClientManagerExample : MonoBehaviour
{
    [SerializeField]
    private CoverageClientManager CoverageClientManager;

    public void QueryAroundUser()
    {
        CoverageClientManager.TryGetCoverage(OnCoverageResult);
    }

    private async void OnCoverageResult(AreaTargetsResult areaTargetsResult)
    {
        if (areaTargetsResult.Status == ResponseStatus.Success)
        {
            foreach (var result in areaTargetsResult.AreaTargets)
            {
                if (string.IsNullOrEmpty(result.Target.ImageURL)).
                {
                    continue;
                }

                var hintTexture = await CoverageClientManager.TryGetImageFromUrl(result.Target.ImageURL);
                
                // テクスチャで何かする
            }.
        }
        else
        {
            Debug.LogError($"Coverage query failed with status: {areaTargetsResult.Status}");
        }.
    }
}

ダウンロードとテクスチャ生成のブロックがパフォーマンスに影響するため、このAPIは非同期で呼び出すことを推奨します。また、レスポンス内のすべての画像を処理するのではなく、一度にダウンロードする画像の数を制限することをお勧めします。

ARLocationManagerでCoverageClientManagerの出力を使用する

近くのAreaTargetsのリストを取得した後、ユーザーまたはアプリケーションは、追跡するARLocationとして使用する特定のLocalizationTargetを選択することができます。以下の例では、応答リストの最初の結果を、追跡するARLocationとして選択している。

クリックしてスクリプト例を表示

using Niantic.Lightship.AR.LocationAR;
using Niantic.Lightship.AR.PersistentAnchors;
using Niantic.Lightship.AR.VpsCoverage;
using UnityEngine;

public class CoverageClientManagerExample : MonoBehaviour
{
    [SerializeField]
    private CoverageClientManager CoverageClientManager;

    [SerializeField]
    private ARLocationManager ArLocationManager;

    public void QueryAroundUser()
    {
        CoverageClientManager.TryGetCoverage(OnCoverageResult);
    }

    private void OnCoverageResult(AreaTargetsResult areaTargetsResult)
    {
        if (areaTargetsResult.Status == ResponseStatus.Success)
        {
            var firstResult = areaTargetsResult.AreaTargets[0];
            var anchorPayloadString = firstResult.Target.DefaultAnchor;

            if (string.IsNullOrEmpty(anchorPayloadString))
            {
                // このエリアにアンカーペイロードがない場合は何もしない
                // 実際のアプリケーションでは別のエリアターゲットを選択する
                Debug.LogError($"No anchor found for {firstResult.Target.Name}");
                return;
            }

            var anchorPayload = new ARPersistentAnchorPayload(anchorPayloadString);

            var locationGameObject = new GameObject();
            var arLocation = locationGameObject.AddComponent<ARLocation>();
            arLocation.Payload = anchorPayload;
                
            ArLocationManager.SetARLocations(arLocation);
            ArLocationManager.StartTracking();
        }
        else
        {
            Debug.LogError($"Coverage query failed with status: {areaTargetsResult.Status}");
        }
    }
}

CoverageClientManagerを使用してテスト・スキャンを浮上させる

CoverageClientManagerは、クエリーロケーション周辺のパブリックVPSロケーションのみを表示します。しかし、テストスキャンを手動でCoverageClientManagerに追加して、場所に関係なくAreaTargetsResultレスポンスに表示させることができる。 CoverageClientManager PrivateARLocations 配列を使用してテストスキャンの ARLocationManifest を追加すると、実行時にクエリされたかのように AreaTargetsResult 応答に追加されます。これにより、パブリックVPSロケーションの検出とプライベートテストスキャンに同じフローを使用できます。

テスト・スキャンの作成と重要性の詳細については、テスト・スキャンの管理方法を参照してください。

詳細情報

Lightship VPS特集ページ

CoverageClientManagerの設定​

カバレッジ結果の使用​

エリアターゲットとその内容​

ヒント画像のダウンロード​

ARLocationManagerでCoverageClientManagerの出力を使用する​

CoverageClientManagerを使用してテスト・スキャンを浮上させる​

詳細情報​