使用 Scene Viewer 透過 Android 應用程式或瀏覽器在 AR 中顯示互動式 3D 模型

Scene 檢視器是一種沉浸式檢視器,可讓您透過網站或 Android 應用程式提供 3D 和 AR 體驗。Android 行動裝置的使用者可透過這個檢視器,在自己的環境中輕鬆預覽、放置、查看及與網頁代管的 3D 模型互動。

大部分 Android 瀏覽器都支援 Scene Viewer。許多 Google 合作夥伴成功實作 Scene Viewer,以穩定支援 3D 和 AR 體驗。這項設定也能為這些 Google 搜尋提供技術支援。

導入程序簡單明瞭:

  • 網頁式體驗只需要網頁上的連結格式正確。

  • 以應用程式為基礎的體驗只需要整合幾行 Java 程式碼。

場景檢視器執行階段需求

如要使用場景檢視器體驗 AR,使用者必須符合以下條件:

  • ARCore 支援的裝置,搭載 Android 7.0 Nougat (API 級別 24) 以上版本。
  • 安裝最新版 AR 專用 Google Play 服務。在大部分支援 ARCore 的裝置上,這項服務會自動安裝並保持最新狀態。
  • 最新版本的 Google 應用程式。這個應用程式已預先安裝,也會在絕大多數支援 ARCore 的裝置上自動更新。

如要提供適用於 AR 適用的 Google Play 服務或 Google 應用程式過舊或安裝版本過舊時,您可以指定會啟動替代體驗的備用網址,例如網頁、錯誤訊息或您建構的備用體驗。

支援的用途

預期用途 推薦應用程式 優點
使用網站或 Android 應用程式中的按鈕或連結,啟動 3D 模型的原生 AR 檢視畫面。

如果裝置上沒有 Google Play 服務 - AR 適用,請妥善回頭地選擇在採用 Scene Viewer 技術的 3D 模式下顯示模型。
以明確意圖啟動 Google 搜尋套件的 Scene Viewer,然後選擇適當的 mode 設定來顯示 3D 模型。
  • ar_preferred:一律以 AR 檢視器啟動,且使用者可以手動切換至 3D 檢視器。如果沒有「Google Play 服務 - AR 適用」,請在 3D 檢視器中優雅地改回使用 AR 服務。
  • 3d_preferred:一律從 3D 檢視器開始,且使用者可以手動切換至 AR 檢視器。如果沒有「Google Play 服務 - AR 適用」,使用者就無法切換 3D 檢視器。
  • 3d_only:一律顯示在 3D 檢視器中,使用者無法切換至 AR 檢視器。
  • 支援最廣泛的裝置。
  • 針對非 AR 用途,自動改回使用 Scene 檢視器的原生 3D 模式。
使用網站或 Android 應用程式中的按鈕或連結,啟動 3D 模型的原生 AR 檢視畫面。

如果裝置上沒有 Google Play 服務 - AR 服務,請控制備用行為。
以明確意圖啟動 Scene 檢視器,適用於「Google Play 服務 - ARCore」(ARCore),並選擇適當的 mode 設定來顯示 3D 模型。
  • ar_preferred:一律以 AR 檢視器啟動,而且使用者可以手動切換至 3D 檢視器。如果沒有 Google Play Services for AR,場景檢視器會改回您設定的行為。
  • ar_only:一律顯示在 AR 檢視器中,無法切換至 3D 檢視器。如果沒有 Google Play 服務 - AR 服務,就會改回設定的行為。舉例來說,您可能會啟動自己的全螢幕 3D 體驗,或顯示友善的錯誤訊息,指出使用者的裝置尚未支援 AR 功能。
使用您自己的 3D 模型檢視器,或是針對非 AR 用途,提供您自己的設計其他備用回應。
在網站代管 3D 模型的內嵌檢視畫面,並允許使用者手動進入全螢幕原生 AR 模式。 使用 <model-viewer> 或任何其他網頁式 3D 檢視器啟動 Scene 檢視器,以原生方式在 AR 中顯示 3D 模型。
  • 直接從網頁上的 3D 模型以 AR 原生啟動 Scene 檢視器。
  • 在您擁有及控管的平台上為使用者提供 3D 體驗,並在瞭解使用者意圖後,選擇逐步將他們轉換至更身歷其境的 AR 體驗。

使用明確意圖啟動 Scene Viewer (3D 或 AR)

如要支援大多數 Android 裝置,請使用明確的 Android 意圖啟動 Scene Viewer。明確意圖可以從 HTML 網頁或原生 Android 應用程式觸發。該意圖將由預先安裝在 ARCore 支援 Android 裝置上的 Google 應用程式處理。

視設定的意圖參數和裝置功能而定,互動式 3D 模型可以放置在使用者的環境中,或者回到 3D 檢視器中顯示。

  • 如果裝置上有 Google Play 服務 - AR 功能並符合最新版本,場景檢視器會在 AR 原生檢視畫面或 3D 檢視畫面中顯示模型。

  • 如果 Google Play Services for AR 不存在或不是最新版本,場景檢視器會順利改回在 3D 檢視畫面中顯示模型。

  • 如果無法顯示 3D 模型 (例如因為沒有安裝 Google 應用程式或版本過舊),系統會改用 S.browser_fallback_url 參數顯示備用網頁。

從 HTML 或 Java 啟動 Scene 檢視器

HTML

如要從 HTML 觸發明確意圖,請使用下列語法:

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>

Java

如要從 Java 觸發明確意圖,請使用下列程式碼:

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
sceneViewerIntent.setData(Uri.parse("https://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"));
sceneViewerIntent.setPackage("com.google.android.googlequicksearchbox");
startActivity(sceneViewerIntent);

意圖版本管理

意圖版本會以 arvr.google.com/scene-viewer 之後的版本號碼指出。舉例來說,初始版本使用的是 1.0 版。如果需要較新的場景檢視器功能,您可以依據需要的功能,推出相對應的意圖版本較高的 Scene Viewer。

意圖版本 1.1 新增了對 intent:// 連結的支援,以便直接將連結啟動至 Android 應用程式,而非網址。如果您希望 Scene Viewer 確保此功能在啟動後可供使用,但在其他情況下無法啟動,請使用意圖為 intent://arvr.google.com/scene-viewer/1.1 啟動場景檢視器。

支援的意圖參數

針對 Google 搜尋套件的明確意圖,系統支援下列參數。

意圖參數 接受的值 留言
file (必填) 有效網址 這個網址會指定應載入 Scene Viewer 的 glTF 或 glb 檔案。這必須是網址逸出的。
S.browser_fallback_url (以 HTML 為基礎的意圖為必要項目) 有效網址 這是 Google Chrome 的功能,僅適用於網頁式實作。 如果裝置上沒有 Google 應用程式,這是 Google Chrome 會前往的網址。
mode (非必要) 3d_preferred (預設) 場景檢視器會以 3D 模式顯示模型,以及「在空間中檢視」按鈕。



如果裝置上沒有 Google Play 服務 - AR 服務,「在空間中查看」按鈕會隱藏。

3d_only 即使裝置上有 Google Play 服務 - AR 功能,系統仍會以 3D 模式顯示的模型啟動場景檢視器。系統一律不會顯示「在你的聊天室中檢視」按鈕。

ar_preferred 場景檢視器會在 AR 原生模式中啟動,做為進入模式。使用者可以選擇透過「在空間中檢視」和「3D 模式」按鈕,在 AR 和 3D 模式之間切換。



如果沒有「Google Play 服務 - AR 適用」,場景檢視器可正常切換回 3D 模式進入模式。

ar_only 使用這個值時,您應透過對 com.google.ar.core明確 Android 意圖啟動。

注意:如果是透過明確 Android 意圖傳送至 Google 應用程式,請勿使用 ar_only 模式。

link (非必要) 有效網址 外部網頁的網址。如果這個按鈕存在,使用者按一下意圖後,使用者介面就會顯示一個按鈕。

title (非必要) 有效字串 模型的名稱。如果有的話,就會顯示在使用者介面中。 名稱會在 60 個字元後以刪節號截斷。

音效 (選用) 有效網址 循環音軌的網址,該音軌與 glTF 檔案中嵌入的第一個動畫保持同步。建議一併提供 glTF 和長度相符的動畫。如果已設定此屬性,系統會在模型載入後循環音效。這必須是網址逸出的。
resizable (非必要) true (預設)

false

如果設為 false,使用者將無法在 AR 體驗中調整模型。縮放功能在 3D 體驗中可以正常運作。
enable_vertical_placement (非必要) false (預設)

true

如果設為 true,使用者就能將模型置於垂直表面上。

使用者體驗指南

為了盡可能為使用者提供最佳使用者體驗,建議您顯示可見的行動號召,告知使用者即將進入沉浸式環境。

針對 3D 檢視器體驗,建議您加入標示為「在 3D 中檢視」的行動號召,如下列其中一個圖片所示:

使用明確意圖啟動 Scene 檢視器 (僅限 AR 模式使用「Google Play 服務 - AR 模式」)

場景檢視器的 AR 模式是由 Google Play 服務 - AR 技術提供。

為了確保場景檢視器中的 AR 可用,您可以使用網站或原生 Android 應用程式中的明確 Android 意圖,透過 com.google.ar.core package 啟動 Scene Viewer,並提供 browser_fallback_url。這樣一來,您就能確保所有使用者都能透過 Scene 檢視器或您自行建構的備用體驗,享有原生 AR 體驗。例如,您可以建構備用體驗,例如自己的 3D 檢視器或優雅的錯誤訊息。

如要從 HTML 觸發明確意圖,請使用下列語法:

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf&mode=ar_only#Intent;scheme=https;package=com.google.ar.core;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>;

如要從 Java 觸發明確意圖,請使用下列程式碼:

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
Uri intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.0").buildUpon()
    .appendQueryParameter("file", "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf")
    .appendQueryParameter("mode", "ar_only")
    .build();
sceneViewerIntent.setData(intentUri);
sceneViewerIntent.setPackage("com.google.ar.core");
startActivity(sceneViewerIntent);

支援的意圖參數

針對「Google Play 服務 for AR 套件」的明確意圖,系統支援下列參數。

意圖參數 接受的值 留言
browser_fallback_url (以 HTML 為基礎的意圖為必要項目) 有效網址 這項功能僅適用於網站式導入。如果裝置上沒有「Google Play 服務 - AR 適用」或不是最新版,則這是指系統會導向的網址。
mode (非必要) ar_only 場景檢視器一律會在原生 AR 檢視畫面中啟動 3D 模型,並隱藏任何 UI,方便切換至場景檢視器 3D 檢視器。

如果找不到 AR 適用的 Google Play 服務,場景檢視器會啟動您在 browser_fallback_url 中設定的網址,用於網頁式體驗。針對以應用程式為基礎的體驗,Sene 檢視器會改回使用替代體驗,例如錯誤訊息或您自行建構的其他體驗。

ar_preferred 場景檢視器會在 AR 原生模式下啟動,做為進入模式,讓使用者可以透過「在空間中檢視」和「3D 模式」按鈕,切換 AR 和 3D 模式。

如果找不到 AR 適用的 Google Play 服務,場景檢視器會啟動您在 browser_fallback_url 中設定的網址,用於網頁式體驗。針對以應用程式為基礎的體驗,Sene 檢視器會改回使用替代體驗,例如錯誤訊息或您自行建構的其他體驗。

   

link (非必要) 有效網址 外部網頁的網址。如果這個按鈕存在,使用者按一下意圖後,使用者介面就會顯示一個按鈕。



1.1 版在 Scene 檢視器中新增對 intent:// 連結的支援,讓場景檢視器的造訪按鈕直接觸發其他應用程式。請注意,請謹慎指定這個做法,且應只在保證會針對特定意圖都有意圖處理常式時指定。
title (非必要) 有效字串 模型的名稱。如果有的話,就會顯示在使用者介面中。 名稱會在 60 個字元後以刪節號截斷。



1.1 版開始支援標題內容的 HTML 樣式,且支援任意數量的文字。請注意,標題必須逸出。
sound (非必要) 有效網址 循環音軌的網址,該音軌與 glTF 檔案中嵌入的第一個動畫保持同步。這應與 glTF 一併提供,且內容長度為相符長度的動畫。如果已設定此屬性,系統會在模型載入後循環音效。
resizable (非必要) true (預設)

false

如果設為 false,使用者將無法在 AR 體驗中調整模型。縮放功能在 3D 體驗中可以正常運作。
disable_occlusion (非必要) false (預設)

true

設為 true 時,位於場景中的物件一律會顯示在場景的實際物件前方。詳情請參閱 [啟用遮蔽](/ar/develop/depth#enable_occlusion)。

使用者體驗指南

為了盡可能為使用者提供最佳使用者體驗,建議您按照下列指南操作。

  • 如果是 AR 體驗,可見的行動號召應告知使用者即將進入沉浸式環境。建議您使用「在聊天室中查看」行動號召:

  • 使用者可能沒有在裝置上安裝 Google Play 服務 - AR 服務。以下是 <model-viewer> 處理備用方式的方式,您隨時可以使用該程式碼片段做為起點。

    // Check whether this is an Android device.
    const isAndroid = /android/i.test(navigator.userAgent);
    // This fallback URL is used if the Google app is not installed and up to date.
    const fallbackUrl = 'https://arvr.google.com/scene-viewer?file=https%3A%2F%2Fstorage.googleapis.com%2Far-answers-in-search-models%2Fstatic%2FTiger%2Fmodel.glb&link=https%3A%2F%2Fgoogle.com&title=Tiger';
    
    // This intent URL triggers Scene Viewer on Android and falls back to
    // fallbackUrl if the Google app is not installed and up to date.
    const sceneViewerUrl = 'intent://arvr.google.com/scene-viewer/1.0?file=https://storage.googleapis.com/ar-answers-in-search-models/static/Tiger/model.glb&title=Tiger#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=' +
        fallbackUrl + ';end;';
    
    // Create a link.
    var a = document.createElement('a');
    a.appendChild(document.createTextNode('Tiger'));
    // Set the href to the intent URL on Android and the fallback URL
    // everywhere else.
    a.href = isAndroid ? sceneViewerUrl : fallbackUrl;
    // Add the link to the page.
    document.body.appendChild(a);
    

使用 <model-viewer> 啟動 Scene Viewer

只要使用 ar 屬性加入 <model-viewer> 網頁元件,即可在網站上啟用 Scene Viewer。

<model-viewer ar
              ar-modes="scene-viewer webxr quick-look"
              alt="A 3D model of an astronaut."
              src="Astronaut.gltf"></model-viewer>

在支援 ARCore 的 Android 裝置上查看時,包含 <model-viewer> 元件且帶有 ar 屬性的網站會顯示一個按鈕,如以下範例所示。

ar-modes 中使用 scene-viewer 模式時,系統會切換至原生 AR 檢視畫面,並邀請使用者使用場景檢視器將模型放到自己的環境中。

如果沒有 Google Play 服務支援 AR,輕觸這個按鈕就會在 <model-viewer> 的 3D 檢視器中顯示模型。

如要進一步瞭解如何開始使用 <model-viewer>,請參閱 <model-viewer> 的說明文件

模型的檔案相關規定

Scene Viewer 對模型的支援與限制如下。

支援的檔案格式 glTF 2.0/glb,使用以下擴充功能:
  • KHR_materials_unlit
  • KHR_texture_transform
動畫
  • 循環骨架動畫
  • 循環播放硬性動畫
  • 循環轉換動畫
動畫將循環播放。如果 glTF 檔案包含多個動畫,場景檢視器只會播放第一個動畫。
建議限制 資產的整體效能取決於設定限制,並決定頂點、材質、紋理解析度、每種材質的網狀解析度和其他因素。請參考下列指南調整素材資源。
  • 三角形數量:建議上限是 100,000 個三角形,但只要指定數量下限,場景檢視器中的效能就會維持良好。30,000 到 50,000 是理想範圍。
  • 材質數量:建議上限為 10 種材質,兩種可以是 Alpha 值。請盡可能指定最低數量,以維持素材資源成效。
  • 每種材質的網狀網格:1
  • 最大紋理解析度:2048 × 2048
  • 骨頭 (包括非加權的關節):254 (硬性限制)
  • 每個頂點限制的骨架重量:4 (嚴格限制)
  • UV:每個網格 1 個 UV (嚴格限制)
  • 模型大小:10 MB (大型模型可能會導致使用者體驗不佳)。
陰影支援 放置物件時,Scene 檢視器會自動算繪硬陰影,因此建議不要在模型中烘焙陰影。
紋理支援
  • PNG 格式:PNG-24,索引 PNG-8。
    由於透明度會縮減,所以沒有透明度,因此建議使用 JPG。
  • 色域:sRGB
材質 對戰
載入檔案 HTTPS
情境
  • 軸:右手,包含以下屬性:
    • +X 為右側
    • +Y 上升
    • - Z 指從原點前進 (也就是說,資產的「正面」應朝向 +Z)
  • 比例:1 個單位 = 1 公尺 (根據 glTF 規格的定義,可確保模型以 AR 規格放置)

使用預覽工具驗證 3D 模型

為了確保您的 3D 模型檔案能在場景檢視器中正確顯示,請使用我們的線上預覽工具工具驗證電腦上的檔案。

驗證 3D 模型

如要驗證模型,預覽工具需要一個 glb 或 glTF 檔案、任何相關聯的圖片和特徵分塊檔案,以及選用的音訊檔案。音訊檔案將循環播放 0。

您可以選取多個個別檔案,也可以視需要將 glb 或 glTF 及其相關檔案放入 ZIP 檔案中。(ZIP 檔案方法不支援音訊檔案)。

如何驗證 3D 模型:

  1. 在瀏覽器中開啟線上預覽工具

  2. 請使用下列其中一種方法將檔案新增至預覽工具:

    • 拖曳。選取 glb 或 glTF 檔案及所有相關檔案 (或包含這些檔案的 ZIP 檔案),然後將所選檔案或 ZIP 檔案拖曳至預覽工具工具。

    • 透過預覽工具。在預覽工具中,依序選擇「Scene Viewer」>「Load File」。選取 glb 或 glTF 檔案及其所有相關聯的檔案 (或包含這些檔案的 ZIP 檔案),然後按一下「Open」

將含有 3D 模型的檔案載入預覽工具後,瀏覽器底部的主控台會顯示結果 (包括任何錯誤訊息)。

新增 3D 模型進行驗證

如要驗證 3D 模型,請將組成 3D 模型的檔案新增至我們的模型編輯器工具

如要驗證模型,預覽工具需要模型的 glb 或 glTF 檔案、任何相關聯的圖片和 bin 檔案,以及選用的音訊檔案。您可以一次選取多個檔案,或新增一個 ZIP 檔案。

新增 ZIP 檔案時,預覽程式會載入找到的第一個 glb 或 glTF,以及該 ZIP 檔案中的關聯圖片和 bin 檔案。

  1. 在瀏覽器中開啟模型編輯器工具

  2. 請使用下列其中一種方法將檔案新增至預覽工具:

    • 如要拖曳檔案進行驗證,請複選 glb 或 glTF 檔案和所有相關檔案 (或選取包含這些檔案的 ZIP 檔案),然後拖曳至預覽工具。

    • 從預覽工具選取檔案。在預覽工具中,依序選擇「Scene Viewer」>「Load File」。多選取 glb 或 glTF 檔案及其所有相關聯的檔案 (或包含這些檔案的 ZIP 檔案),然後按一下「Open」

驗證錯誤

錯誤代碼 嚴重性 訊息 目前支援的值
INVALID_INPUT_FILE_EXTENSION 錯誤 驗證工具不支援輸入檔案 [filename] 的副檔名。 ['.glb', '.gltf']
REC_INPUT_BINARY_SIZE_EXCEEDED 警告 提供的使用者輸入二進位檔大小超過 Scene Viewer 規格建議的限制 (建議大小上限為 [size] MB)。 10
MAX_INPUT_BINARY_SIZE_EXCEEDED 錯誤 提供的使用者輸入二進位檔大小超過 Scene Viewer 規格支援的上限,上限為 [size] MB。 15
UNSUPPORTED_GLTF_EXTENSION_USED 錯誤 Scene Viewer 規格不支援 glTF 中的擴充功能 [ext]。 ['KHR_materials_pbrSpecularGlossiness', 'KHR_materials_unlit', 'KHR_texture_transform']
ANIMATION_LIMIT_EXCEEDED 錯誤 glTF 中的動畫數量超過 Scene Viewer 規格支援的限制,上限為 [num] 個動畫。 1
MORPH_TARGET_USED 錯誤 glTF 包含 Scene Viewer 規格不支援的變形目標。
MATERIAL_LIMIT_EXCEEDED 警告 glTF 中的材質數量超過 Scene Viewer 規格建議的限制,上限為 [num] 個材質。 10
TEXTURE_RESOLUTION_LIMIT_EXCEEDED 警告 glTF 中索引 [idx] 的圖片解析度超過 Scene Viewer 規格建議的限制,解析度上限為 [res] x [res]。 2048 x 2048
UV_LIMIT_EXCEEDED 錯誤 glTF 中每個網格的 UV 數量超過 Scene Viewer 規格支援的限制,上限為每個網格 [num] UV。 1
VERTEX_COLOR_USED 錯誤 glTF 包含 Scene Viewer 規格不支援的頂點顏色。
JOINT_LIMIT_EXCEEDED 錯誤 glTF 中的節點數超過 Scene Viewer 規格支援的限制,上限為 [num] 個連接點。 254
TRIANGLE_LIMIT_EXCEEDED 警告 glTF 中的三角形數量超過 Scene Viewer 規格建議的限制,上限為 [num] 個三角形。 100,000 人
PRIMITIVE_MODE_UNSUPPORTED 錯誤 Scene Viewer 規格不支援基本模式 [mode]。 {4 : 三角形清單, 5 : 三角形條紋, 6 : 三角扇}
MISSING_PBR_METALLIC_ROUGHNESS 資訊 索引 [idx] 的材質缺少 pbrMetallicRoughness 屬性。如果改用金屬和粗糙度係數,Scene Viewer 規格就不一定要有這個屬性。如果兩者皆未使用,則材質會使用預設值,而這可能會產生非預期的行為。