本文へスキップ
バージョン： 3.5

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

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

CoverageClientManagerの設定​

Coverage Client Manager

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}");
    }.
}

</details>

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

各 **LocalizationTarget** には、**LocalizationTarget** に対応するホストされたヒント画像を指す [ImageURL](../apiref/Niantic/Lightship/AR/VpsCoverage/LocalizationTarget/index.mdx#ImageURL)が含まれています。この情報は、ローカライズする実世界の場所をユーザーに案内するために使用できます。CoverageClientManager**には、ヒント画像をダウンロードして `Texture` を作成するユーティリティメソッドがいくつか含まれています：

<details>
<summary>Click to reveal the hint image code snippet</summary>

```cs
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 : Mono Behavour.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を使用してテスト・スキャンを浮上させる​

Adding Test Scans

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

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

詳細情報​