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

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

VPS Coverage APIには、マップに表示したり、 ARLocationManager のローカライゼーションターゲットとして使用するために、ランタイム時にARロケーションを検出する機能が含まれています。

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($"ローカライズターゲットを取得しました。: {result.Target.Name}, anchor payload: {result.Target.DefaultAnchor}");
            maxCount--;
            if (maxCount == 0)
            {
                break;
            }
        }
    }
    else
    {
        Debug.LogError($"カバレッジクエリが失敗しました。ステータス: {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は非同期での呼び出しが推奨されています。 また、すべての画像を同時にダウンロードして処理するのではなく、ダウンロードする画像の数を制限することをお勧めします。

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

近くの AreaTargets のリストを取得した後、ユーザーやアプリケーションは特定の LocalizationTarget を選択して、 ARLocation としてトラッキングに使用できます。 以下の例では、レスポンスリストの最初の結果をトラッキングする 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を使用してテストスキャンを表示する​

Adding Test Scans

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

テストスキャンを作成し、インポートする方法については、テストスキャンを管理するを参照してください。

詳細情報​