為 Android NDK 應用程式啟用地理空間 API (C)

調整應用程式設定，讓應用程式使用 Geospatial API。

必備條件

請務必先瞭解基本 AR 概念，以及如何設定 ARCore 工作階段，然後再繼續操作。

如果您要執行可示範以下所述功能的範例應用程式，請參閱 Java 適用的 ARCore 地理空間快速入門導覽課程。快速入門導覽課程中的範例應用程式是以 Java 編寫。本文件中的程式碼範例適用於 C 中所編寫的相同功能。

如要進一步瞭解地理空間 API，請參閱「地理空間 API 簡介」。

如果您是第一次使用 ARCore 進行開發，請參閱入門指南，瞭解軟體和硬體需求、必要條件，以及所用平台專屬的其他資訊。

請確認您的開發環境符合 ARCore SDK 需求，如 Java 適用的快速入門導覽課程中所述。

啟用 ARCore API

在應用程式中使用視覺定位系統 (VPS) 之前，您必須先在新的或現有的 Google Cloud 專案中啟用 ARCore API。這項服務負責代管、儲存及解析地理空間錨點。

建議提供無金鑰授權，不過系統也支援 API 金鑰授權。

在應用程式中新增必要程式庫

授權應用程式呼叫 ARCore API 後，您必須新增程式庫，才能在應用程式中啟用地理空間功能。

在應用程式的 build.gradle 檔案中設定 Google Play 服務，納入 Play 服務位置程式庫。

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

在工作階段設定中啟用地理空間功能

建立工作階段前，請將工作階段設定中的 GeospatialMode 變更為 ENABLED：

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

當地理空間模式設為 ENABLED 時，應用程式可以從視覺定位系統 (VPS) 取得地理資訊。

提示使用者允許使用裝置資料

使用 ARCore Geospatial API 的應用程式必須向使用者顯示提示，確認並允許使用裝置中的資料。詳情請參閱「使用者隱私權規定」。

檢查裝置相容性

並非所有支援 ARCore 的裝置也支援地理空間 API，詳情請參閱 Java quickstart。

如要檢查使用者的裝置相容性，請呼叫 ArSession_isGeospatialModeSupported()。如果傳回 false，則未嘗試設定工作階段 (如下所述)，這會導致 ArStatus 回報 AR_ERROR_UNSUPPORTED_CONFIGURATION。

在執行階段要求使用者授予位置存取權

應用程式必須在執行階段要求位置存取權。

如要使用 ARCore Geospatial API，應用程式必須註冊下列額外權限：

  • ACCESS_FINE_LOCATION 可準確判斷使用者的位置。

  • ACCESS_COARSE_LOCATION 無法準確判斷使用者的位置，並符合使用者隱私權規定。但是，地理空間 API 無法設定為使用概略位置，且當使用者設定這項權限時，API 要求就會失敗。詳情請參閱下方內容。

  • ACCESS_INTERNET 可聯絡 ARCore Geospatial API 服務。

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

在搭載 Android 12 以上版本的裝置上，使用者可以要求應用程式只存取概略位置資訊。如要配合這項要求，應用程式必須設定 ACCESS_COARSE_LOCATION 權限以及 ACCESS_FINE_LOCATION，如上所示。您必須設定這兩個位置存取權。

但是，如果使用者指定概略位置，則地理空間 API 就無法取得所需的精確位置。如果應用程式只授予大概位置，則地理空間服務無法自行設定。您的應用程式不得在概略位置使用地理空間 API。

查看裝置目前位置的地理空間可用性

由於地理空間 API 會結合 VPS 和 GPS 來判定地理空間位置，因此只要裝置能判斷出其位置，即可使用該 API。在 GPS 準確度偏低的地區 (例如室內空間和人口密集的都市環境)，API 就會仰賴 VPS 覆蓋範圍來產生高精確度姿勢。在一般情況下，VPS 的位置精確度可達到約 5 公尺，旋轉精確度為 5 度。使用 ArSession_checkVpsAvailabilityAsync() 判斷特定位置是否有 VPS 涵蓋率。

地理空間 API 也可用於沒有 VPS 涵蓋範圍的區域。在幾乎沒有俯瞰障礙的戶外環境中，GPS 可能足以產生具有高準確度的姿勢。

後續步驟