使用場景查看器從 Android 應用程序或瀏覽器在 AR 中顯示交互式 3D 模型

Scene Viewer 是一種身臨其境的查看器,可通過您的網站或 Android 應用程序實現 3D 和 AR 體驗。它讓 Android 移動設備的用戶可以輕鬆地預覽、放置、查看其環境中的 Web 託管 3D 模型並與之交互。

大多數 Android 瀏覽器都支持 Scene Viewer。許多 Google 合作夥伴已成功實施 Scene Viewer,以可靠地支持 3D 和 AR 體驗。它還為 Google 搜索提供這些體驗。

實現很簡單:

  • 基於 Web 的體驗只需要網頁上格式正確的鏈接。

  • 基於應用程序的體驗只需要集成幾行 Java 代碼。

場景查看器運行時要求

要使用 Scene Viewer 體驗 AR,用戶必須具備:

  • 一個ARCORE支持的設備運行Android 7.0牛軋糖(API等級24)或更高版本。
  • 一個最新(最近)版本的谷歌遊戲服務AR 。此服務會在絕大多數支持 ARCore 的設備上自動安裝並保持最新狀態。
  • 一個到的最新版本谷歌應用程序。此應用程序已預先安裝,並且還會在絕大多數支持 ARCore 的設備上自動保持最新狀態。

如果 Google Play Services for AR 或 Google 應用程序不存在或安裝的版本太舊,您可以指定啟動替代體驗的回退 URL,例如網頁、錯誤消息、或您建立的後備體驗。

支持的用例

預期用例推薦應用好處
通過網站或 Android 應用程序上的按鈕或鏈接,啟動 3D 模型的原生 AR 視圖。

如果設備上不存在用於 AR 的 Google Play 服務,請優雅地回退到以場景查看器驅動的 3D 模式顯示模型。
啟動現場查看器使用的明確意圖到谷歌搜索包,並選擇適合的mode用於顯示3D模型設置。
  • ar_preferred :始終開始在AR瀏覽器,並且用戶可以手動切換到3D查看器。如果不存在用於 AR 的 Google Play 服務,則優雅地回退到在 3D 查看器中啟動。
  • 3d_preferred :總是開始在3D查看器,用戶可以手動地切換到AR查看器。如果不存在用於 AR 的 Google Play 服務,用戶將無法從 3D 查看器中切換出來。
  • 3d_only :始終顯示僅在3D查看器,沒有辦法讓用戶切換到AR查看器。
  • 支持盡可能廣泛的設備。
  • 對於非 AR 用例,自​​動回退到 Scene Viewer 的原生 3D 模式。
通過網站或 Android 應用程序上的按鈕或鏈接,啟動 3D 模型的原生 AR 視圖。

如果設備上不存在適用於 AR 的 Google Play 服務,請控制回退行為。
啟動現場查看器使用一個明確的意圖,谷歌播放服務AR(ARCORE) ,並選擇適合的mode用於顯示3D模型設置。
  • ar_preferred :始終開始於AR瀏覽器,並且用戶可以手動切換到3D查看器。如果不存在適用於 AR 的 Google Play 服務,Scene Viewer 將退回到您配置的行為。
  • ar_only :始終顯示僅在AR查看器,沒有能力切換到3D查看器。如果 Google Play Services for AR 不存在,則退回到您配置的行為。例如,您可能會啟動自己的全屏 3D 體驗或顯示一條友好的錯誤消息,指示用戶的設備尚不支持 AR 功能。
使用您自己的 3D 模型查看器或為非 AR 用例提供您自己設計的另一個後備響應。
在您的網站上託管 3D 模型的內嵌視圖,並允許用戶手動進入全屏原生 AR 模式。使用<model-viewer>或任何其他基於Web的3D查看器即可啟動現場查看器本身顯示在AR 3D模型。
  • 直接從嵌入在網頁中的 3D 模型在 AR 中本地啟動 Scene Viewer。
  • 在您擁有和控制的表面上為用戶提供 3D 體驗,一旦您了解他們的意圖,就可以選擇逐漸將他們過渡到更加身臨其境的 AR 體驗。

使用明確的意圖(3D 或 AR)啟動場景查看器

為了支持Android設備的範圍最廣,使用一個明確的Android意圖發動現場查看器。顯式意圖可以從 HTML 頁面或原生 Android 應用程序觸發。這樣做的目的將被處理谷歌的應用程序自帶預裝在ARCORE支持的Android設備。

根據配置的意圖參數和設備功能,交互式 3D 模型可以放置在用戶的環境中或回退到在 3D 查看器中顯示。

  • 如果設備上存在用於 AR 的 Google Play 服務,則是最新的,Scene Viewer 將在 AR 原生視圖或 3D 視圖中顯示模型。

  • 如果用於 AR 的 Google Play 服務不存在或不是最新的,Scene Viewer 會優雅地回退到以 3D 視圖顯示模型。

  • 如果無法顯示3D模型,例如,由於谷歌的應用程序沒有安裝,或者是舊的版本, S.browser_fallback_url參數將被用來代替顯示後備網頁。

從 HTML 或 Java 啟動場景查看器

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 觸發顯式意圖,請使用以下代碼:

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 功能時,您可以使用與您需要的功能相對應的更高意圖版本啟動 Scene Viewer。

意向1.1版增加了支持intent://鏈接,可以直接發射到一個Android應用程序,而不是一個URL。如果您想現場查看器,以保證啟動時此功能是可用的,並且不能以其他方式發射,發射現場觀眾的意圖, intent://arvr.google.com/scene-viewer/1.1

支持的意圖參數

對於 Google 搜索包的顯式意圖,支持以下參數。

意圖參數允許值註釋
file (要求)有效的網址此 URL 指定應加載到 Scene Viewer 中的 glTF 或 glb 文件。這應該是 URL 轉義的。
S.browser_fallback_url (用於基於HTML的意圖)有效的網址這是一項 Google Chrome 功能,僅支持基於 Web 的實現。當谷歌應用程序是不存在的設備上,這是谷歌瀏覽器導航到該URL。
mode (可選) 3d_preferred (默認)現場查看器顯示在3D模式下的模型與你的空間按鈕查看



如果谷歌播放服務AR是不存在的設備上,在你的空間按鈕查看被隱藏。

3d_only即使設備上存在用於 AR 的 Google Play 服務,Scene Viewer 也會以 3D 模式顯示模型啟動。在你的空間按鈕的看法是永遠不會顯示。

ar_preferred Scene Viewer 以 AR 原生模式作為入口模式啟動。給予用戶通過查看你的空間查看選項AR和3D模式之間切換的3D按鈕。



如果不存在用於 AR 的 Google Play 服務,Scene Viewer 會優雅地回退到 3D 模式作為入口模式。

ar_only當使用此值,則應該通過推出明確的Android的意圖com.google.ar.core

注意:不要使用ar_only通過啟動模式時明確Android的意圖,以谷歌應用程序

link (可選)有效的網址外部網頁的 URL。如果存在,將在 UI 中顯示一個按鈕,單擊該按鈕時會指向此 URL。

title (可選)有效字符串模型的名稱。如果存在,它將顯示在 UI 中。名稱將在 60 個字符後用省略號截斷。

聲音(可選)有效的網址與 glTF 文件中嵌入的第一個動畫同步的循環音軌的 URL。它應該與具有匹配長度的動畫的 glTF 一起提供。如果存在,則在加載模型後循環播放聲音。這應該是 URL 轉義的。
resizable (可選) true (默認)

false

當設置為false ,用戶將不能夠擴展在AR經驗模型。縮放在 3D 體驗中正常工作。
enable_vertical_placement (可選) false (默認)

true

如果設置為true ,用戶將能夠對模型放置在垂直面上。

用戶體驗指導

為了為用戶提供最佳的 UX,我們建議通過可見的號召性用語傳達用戶即將進入沉浸式環境的信息。

對於3D觀賞體驗,我們建議3D視圖號召行動,看起來像下面的圖像之一:

使用針對 AR 的 Google Play 服務的明確意圖啟動 Scene Viewer(僅限 AR 模式)

Scene Viewer 中的 AR 模式由適用於 AR 的 Google Play 服務提供支持。

為了確保AR是在場景瀏覽器可用,您可以使用一個明確的Android意圖從網站或原生的Android應用推出現場查看器通過com.google.ar.core package ,並提供browser_fallback_url 。通過這種方式,您可以確保所有用戶通過 Scene Viewer 獲得原生 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 Services for AR 包的顯式意圖,支持以下參數。

意圖參數允許值註釋
browser_fallback_url (用於基於HTML的意圖)有效的網址這僅支持基於 Web 的實現。當用於 AR 的 Google Play 服務不在設備上或不是最新版本時,這就是它導航到的 URL。
mode (可選) ar_only場景查看器始終在原生 AR 視圖中啟動 3D 模型,並隱藏用於切換到場景查看器 3D 查看器的任何 UI。

如果谷歌播放服務AR不存在,場景觀察器啟動您在設定的URL browser_fallback_url基於Web的體驗。對於基於應用程序的體驗,Scene Viewer 回退到替代體驗,例如錯誤消息或您自己構建的其他體驗。

ar_preferred現場查看器AR本機模式的推出為輸入模式,並提供用戶通過在你的3D按鈕空間查看查看選項AR和3D模式之間切換。

如果谷歌播放服務AR不存在,場景觀察器啟動您在設定的URL browser_fallback_url基於Web的體驗。對於基於應用程序的體驗,Scene Viewer 回退到替代體驗,例如錯誤消息或您自己構建的其他體驗。



link (可選)有效的網址外部網頁的 URL。如果存在,將在 UI 中顯示一個按鈕,單擊該按鈕時會指向此 URL。



1.1版加入意向支持://鏈接在現場查看器,以便直接讓現場查看器訪問按鈕來觸發到其他應用程序。請注意,這應該謹慎使用,並且僅在保證給定意圖存在意圖處理程序時才應指定。
title (可選)有效字符串模型的名稱。如果存在,它將顯示在 UI 中。名稱將在 60 個字符後用省略號截斷。



1.1版增加了對HTML的標題內容的造型,與允許的文本任意數量。請注意,標題應該是 url 轉義的。
sound (可選)有效的網址一個指向循環音軌的 URL,它與嵌入在 glTF 文件中的第一個動畫同步。它應該與具有匹配長度的動畫的 glTF 一起提供。如果存在,則在加載模型後循環播放聲音。
resizable (可選) true (默認)

false

當設置為false ,用戶將不能夠擴展在AR經驗模型。縮放在 3D 體驗中正常工作。

用戶體驗指導

為了為用戶提供最佳的用戶體驗,我們建議遵循這些準則。

  • 對於 AR 體驗,可見的號召性用語應傳達用戶即將進入沉浸式環境的信息。我們建議您使用在空間的行動呼籲查看

  • 這有可能是用戶可能沒有谷歌播放服務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>啟動現場查看器

您可以從您的網站通過包括使場景觀察器<model-viewer>與Web組件ar屬性。

<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屬性顯示一個按鈕,如以下示例所示。

scene-viewer在使用模式ar-modes時,它切換到天然AR視圖,並邀請用戶將使用場景瀏覽器自己的環境模型。

如果谷歌播放服務與AR不存在,敲擊此按鈕顯示模型<model-viewer>的3D瀏覽器。

請參閱文件<model-viewer>關於如何開始使用開始更多信息<model-viewer>

模型文件要求

Scene Viewer 對模型有以下支持和限制。

文件格式支持glTF 2.0 / glb ,使用這些擴展:
  • KHR_materials_unlit
  • KHR_texture_transform
動畫片
  • 循環骨骼動畫
  • 循環剛性動畫
  • 循環變換動畫
動畫將循環播放。如果glTF文件中包含多個動畫,場景觀察器僅播放第一個動畫。
建議限制資產的整體性能取決於設置約束並在頂點、材質、紋理分辨率、每個材質的網格以及其他因素之間進行權衡。使用以下指南來優化您的資產。
  • 三角形數量:建議限制為 100,000 個三角形,但以最低數量為目標將在 Scene Viewer 中保持高性能。 30,000 到 50,000 是一個理想的範圍。
  • 材料數量:建議限制為 10 個材料,其中兩個可以是 alpha。以盡可能低的數字為目標,以保持資產表現良好。
  • 每種材料的網格數:1
  • 最大紋理分辨率:2048 × 2048
  • 骨骼(包括非負重關節):254(硬限制)
  • 每個頂點的骨骼權重限制:4(硬限制)
  • UV:每個網格 1 個 UV(硬限制)
  • 模型大小:10 MB(較大的模型可能會導致用戶體驗不佳。)
影子支持放置對象時,Scene Viewer 會自動渲染硬陰影,因此我們建議不要將陰影烘焙到您的模型中。
紋理支持
  • PNG 格式:PNG-24,索引 PNG-8。
    當沒有透明度時,JPG 是首選,因為它們可以減小尺寸。
  • 色彩空間:sRGB
材料PBR
文件加載HTTPS
場景
  • 軸:右手,具有以下屬性:
    • +X 是對的
    • +Y 到了
    • -Z 從原點指向前方(換句話說,資產的“正面”應該面向 +Z)
  • 比例:1 單位 = 1 米(由 glTF 規範定義,以確保模型以真實比例放置在 AR 中)

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

為了確保您的3D模型文件將在現場查看器中正確顯示,使用我們的在線預覽工具來驗證您的PC上的文件。

驗證您的 3D 模型

要驗證模型,預覽器工具需要一個 glb 或 glTF 文件、任何關聯的圖像和 bin 文件,以及一個可選的音頻文件。音頻文件將與動畫 0 一起循環。

您可以多選單個文件,也可以選擇將 glb 或 glTF 及其關聯文件放入一個 zip 文件中。 (zip 文件方法不支持音頻文件。)

要驗證您的 3D 模型:

  1. 打開網上預覽工具,在瀏覽器中。

  2. 使用以下方法之一將文件添加到預覽器工具:

    • 拖放。選擇一個 glb 或 glTF 文件及其所有關聯文件(或包含這些文件的 zip 文件),然後將所選文件或 zip 文件拖到預覽器工具中。

    • 從預覽工具。在預覽工具,選擇場景瀏覽器>加載文件。選擇一個GLB或glTF文件及其所有相關的文件(或含有這些文件的zip文件),然後單擊打開

將包含 3D 模型的文件加載到預覽器工具中後,瀏覽器底部的控制台會顯示結果,包括所有錯誤消息。

添加 3D 模型進行驗證

為了驗證3D模型,添加組成3D模型給我們的文件模型編輯器工具

要驗證模型,預覽器需要模型的 glb 或 glTF 文件、任何關聯的圖像和 bin 文件以及可選的音頻文件。您可以多選單個文件或添加單個 zip 文件。

添加 zip 文件時,預覽器會加載它找到的第一個 glb 或 glTF,以及該 zip 文件中的關聯圖像和 bin 文件。

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

  2. 使用以下方法之一將文件添加到預覽器工具:

    • 要拖放文件以進行驗證,請多選 glb 或 glTF 文件和任何關聯文件(或選擇包含這些文件的 zip 文件),然後將其拖到預覽器工具中。

    • 從預覽工具選擇文件。在預覽工具,選擇場景瀏覽器>加載文件。多選擇GLB或glTF文件及其所有相關的文件(或含有這些文件的zip文件),然後單擊打開

驗證錯誤

錯誤代碼嚴重性信息當前支持的值
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錯誤場景查看器規範不支持 glTF 中的擴展名 [ext]。 ['KHR_materials_pbrSpecularGlossiness', 'KHR_materials_unlit', 'KHR_texture_transform']
ANIMATION_LIMIT_EXCEEDED錯誤glTF 中的動畫數量超過了 Scene Viewer 規範支持的限制,即最多 [num] 個動畫。 1
MORPH_TARGET_USED錯誤glTF 包含變形目標,場景查看器規範不支持該目標。
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 包含頂點顏色,場景查看器規範不支持該顏色。
JOINT_LIMIT_EXCEEDED錯誤glTF 中的關節數量超過了 Scene Viewer 規範支持的限制,即最多 [num] 個關節。 254
TRIANGLE_LIMIT_EXCEEDED警告glTF 中的三角形數量超過了 Scene Viewer 規範推薦的限制,即最多 [num] 個三角形。 100,000
PRIMITIVE_MODE_UNSUPPORTED錯誤場景查看器規範不支持原始模式 [mode]。 {4:三角形列表,5:三角帶,6:三角扇}
MISSING_PBR_METALLIC_ROUGHNESS信息在索引中的材料[IDX]缺少pbrMetallicRoughness屬性。如果改為使用金屬和粗糙度係數,則 Scene Viewer 規範不要求這樣做。如果這些都不使用,則材質將使用默認值,這可能會導致意外行為。