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 模型。
|
|
使用網站或 Android 應用程式中的按鈕或連結,啟動 3D 模型的原生 AR 檢視畫面。 如果裝置上沒有 Google Play 服務 - AR 服務,請控制備用行為。 |
以明確意圖啟動 Scene 檢視器,適用於「Google Play 服務 - ARCore」(ARCore),並選擇適當的 mode 設定來顯示 3D 模型。
|
使用您自己的 3D 模型檢視器,或是針對非 AR 用途,提供您自己的設計其他備用回應。 |
在網站代管 3D 模型的內嵌檢視畫面,並允許使用者手動進入全螢幕原生 AR 模式。 | 使用 <model-viewer> 或任何其他網頁式 3D 檢視器啟動 Scene 檢視器,以原生方式在 AR 中顯示 3D 模型。 |
|
使用明確意圖啟動 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 ,使用者將無法在 AR 體驗中調整模型。縮放功能在 3D 體驗中可以正常運作。 |
enable_vertical_placement (非必要) |
false (預設)
|
如果設為 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 ,使用者將無法在 AR 體驗中調整模型。縮放功能在 3D 體驗中可以正常運作。 |
disable_occlusion (非必要) |
false (預設)
|
設為 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 ,使用以下擴充功能:
|
動畫 |
glTF 檔案包含多個動畫,場景檢視器只會播放第一個動畫。 |
建議限制 |
資產的整體效能取決於設定限制,並決定頂點、材質、紋理解析度、每種材質的網狀解析度和其他因素。請參考下列指南調整素材資源。
|
陰影支援 | 放置物件時,Scene 檢視器會自動算繪硬陰影,因此建議不要在模型中烘焙陰影。 |
紋理支援 |
|
材質 | 對戰 |
載入檔案 | HTTPS |
情境 |
|
使用預覽工具驗證 3D 模型
為了確保您的 3D 模型檔案能在場景檢視器中正確顯示,請使用我們的線上預覽工具工具驗證電腦上的檔案。
驗證 3D 模型
如要驗證模型,預覽工具需要一個 glb 或 glTF 檔案、任何相關聯的圖片和特徵分塊檔案,以及選用的音訊檔案。音訊檔案將循環播放 0。
您可以選取多個個別檔案,也可以視需要將 glb 或 glTF 及其相關檔案放入 ZIP 檔案中。(ZIP 檔案方法不支援音訊檔案)。
如何驗證 3D 模型:
在瀏覽器中開啟線上預覽工具。
請使用下列其中一種方法將檔案新增至預覽工具:
拖曳。選取 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 檔案。
在瀏覽器中開啟模型編輯器工具。
請使用下列其中一種方法將檔案新增至預覽工具:
如要拖曳檔案進行驗證,請複選 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 規格就不一定要有這個屬性。如果兩者皆未使用,則材質會使用預設值,而這可能會產生非預期的行為。 |