通过 Android 应用或浏览器使用 Scene Viewer 在 AR 中显示交互式 3D 模型

Scene Viewer 是一款沉浸式查看器,可在您的网站或 Android 应用中实现 3D 和 AR 体验。它可让 Android 移动设备用户在其环境中轻松预览、放置、查看 Web 托管的 3D 模型并与之互动。

大多数 Android 浏览器都支持 Scene Viewer。许多 Google 合作伙伴都成功实现了 Scene Viewer,以可靠地支持 3D 和 AR 体验。同时还为 Google 搜索的这些体验提供了支持。

植入过程非常简单:

  • 基于网络的体验要求网页上只有格式正确的链接。

  • 只需集成几行 Java 代码即可实现基于应用的体验。

Scene Viewer 运行时要求

要通过 Scene Viewer 体验 AR,用户必须满足以下条件:

  • 搭载 Android 7.0 Nougat(API 级别 24)或更高版本的支持 ARCore 的设备
  • 面向 AR 的 Google Play 服务的最新(最新)版本。该服务会在大多数支持 ARCore 的设备上自动安装并保持最新状态。
  • Google 应用的最新版本。此应用已预安装,还会在大多数支持 ARCore 的设备上自动保持更新。

如需应对“面向 AR 的 Google Play 服务”或“Google 应用”不存在或安装的版本过旧的情况,您可以指定用于启动备选体验的后备网址,例如网页、错误消息或您构建的回退体验。

支持的用例

预期用例 推荐应用 优势
通过网站或 Android 应用中的按钮或链接,启动 3D 模型的原生 AR 视图。

如果设备上没有“面向 AR 的 Google Play 服务”,请妥善回退,在由 Scene Viewer 提供支持的 3D 模式下显示模型。
使用 Google 搜索软件包的显式 intent 启动 Scene Viewer,然后选择相应的 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 服务”,请控制回退行为。
使用面向 Google Play AR (ARCore) 服务的显式 intent 启动 Scene Viewer,然后选择相应的 mode 设置以显示 3D 模型。
  • ar_preferred:始终在 AR 查看器中启动,并且用户可以手动切换到 3D 查看器。如果面向 AR 的 Google Play 服务不存在,Scene Viewer 会回退到您配置的行为。
  • ar_only:始终仅在 AR 查看器中显示,无法切换到 3D 查看器。如果“面向 AR 的 Google Play 服务”不存在,则回退到您配置的行为。 例如,您可以启动自己的全屏 3D 体验,或显示一条友好的错误消息,指明用户的设备尚不支持 AR 功能。
使用您自己的 3D 模型查看器,或针对非 AR 用例提供自己设计的其他回退响应。
在您的网站上托管 3D 模型的内嵌视图,并允许用户手动进入全屏原生 AR 模式。 使用 <model-viewer> 或任何其他基于网络的 3D 查看器启动 Scene Viewer,以原生方式在 AR 中显示 3D 模型。
  • 直接从网页中嵌入的 3D 模型在 AR 中以原生方式启动 Scene Viewer。
  • 在您拥有和控制的平台上为用户提供 3D 体验,在了解用户意图后,您可以选择逐渐将他们过渡到更身临其境的 AR 体验。

使用显式 intent(3D 或 AR)启动 Scene Viewer

为了支持尽可能多的 Android 设备,请使用显式 Android intent 启动 Scene Viewer。显式 intent 可以从 HTML 页面或原生 Android 应用触发。该 intent 将由支持 ARCore 的 Android 设备上预安装的 Google 应用处理。

根据配置的 intent 参数和设备功能,可以将互动式 3D 模型放入用户的环境中,也可以回退到在 3D 查看器中显示。

  • 如果设备上存在面向 AR 的 Google Play 服务(最新的版本),Scene Viewer 将在 AR 原生视图或 3D 视图中显示模型。

  • 如果面向 AR 的 Google Play 服务不存在或不是最新版本,Scene Viewer 会妥善回退为在 3D 视图中显示模型。

  • 如果 3D 模型无法显示(例如,因为未安装 Google 应用或者模型是旧版本),系统将改为使用 S.browser_fallback_url 参数显示后备网页。

通过 HTML 或 Java 启动 Scene Viewer

HTML

如需从 HTML 触发显式 intent,请使用以下语法:

<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,请使用以下代码:

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);

intent 版本控制

intent 版本由 arvr.google.com/scene-viewer 后面的版本号指示。例如,初始版本使用版本 1.0。当需要使用较新的 Scene Viewer 功能时,您可以使用与所需功能对应的更高 intent 版本启动 Scene Viewer。

intent 1.1 版增加了对 intent:// 链接的支持,此类链接可以直接启动到 Android 应用,而不是直接启动到网址。如果您希望 Scene Viewer 能保证此功能在启动时可用,而不是在其他情况下无法启动,请启动包含 intent://arvr.google.com/scene-viewer/1.1 intent 的场景查看器。

支持的 intent 参数

Google 搜索软件包的显式 intent 支持以下参数。

intent 参数 允许的值 评论
file(必需) 有效网址 此网址用于指定应加载到 Scene Viewer 中的 glTF 或 glb 文件。这应该是网址转义的。
S.browser_fallback_url(对于基于 HTML 的 intent 是必需的) 有效网址 这是一项 Google Chrome 功能,仅适用于基于网络的实现。如果设备上不存在 Google 应用,Google Chrome 就会导航到该网址。
mode(可选) 3d_preferred(默认) Scene Viewer 以 3D 模式显示模型,并且有一个 View in your space 按钮。



如果设备上没有面向 AR 的 Google Play 服务,系统会隐藏在您所在的空间中查看按钮。

3d_only 即使设备上提供了面向 AR 的 Google Play 服务,Scene Viewer 也会使用以 3D 模式显示的模型一起启动。 系统从不显示在您所在的空间中查看按钮。

ar_preferred Scene Viewer 以 AR 原生模式作为进入模式启动。用户可以通过在您的空间内查看以 3D 模式查看按钮在 AR 和 3D 模式之间切换。



如果没有面向 AR 的 Google Play 服务,Scene Viewer 会优雅地回退到 3D 模式作为进入模式。

ar_only 使用此值时,您应通过显式 Android intentcom.google.ar.core 启动。

注意:通过显式 Android intent 启动到 Google 应用时,请勿使用 ar_only 模式。

link(可选) 有效网址 外部网页的网址。如果存在,则会在界面中显示一个按钮,点击该按钮可转到此网址。

title(可选) 有效字符串 模型的名称。如果存在,则会显示在界面中。 名称在 60 个字符后将被截断并以省略号代替。

声音(可选) 有效网址 指向与 glTF 文件中嵌入的第一个动画同步的循环音轨的网址。它应与具有长度匹配的动画的 glTF 一起提供。如果存在,则声音将在模型加载后循环播放。这应该是网址转义的。
resizable(可选) true(默认)

false

设置为 false 时,用户将无法在 AR 体验中缩放模型。缩放操作在 3D 体验中可以正常运行。
enable_vertical_placement(可选) false(默认)

true

设置为 true 时,用户将能够将模型放置在垂直表面上。

用户体验指南

为了尽可能为用户提供最佳用户体验,我们建议在显眼的号召性用语中传达用户即将进入沉浸式环境的讯息。

对于 3D 查看器体验,我们建议使用标签为以 3D 模式查看的号召性用语,如下所示:

使用面向 Google Play 服务的 AR 服务显式 intent 启动 Scene Viewer(仅限 AR 模式)

Scene Viewer 中的 AR 模式由面向 AR 的 Google Play 服务提供支持。

为确保 Scene Viewer 提供 AR 功能,您可以使用网站或原生 Android 应用中的显式 Android intent,通过 com.google.ar.core package 启动 Scene Viewer 并提供 browser_fallback_url。这样,您就可以确保所有用户都能通过 Scene Viewer 获得原生 AR 体验,或获得您自行构建的回退体验。例如,您可以构建回退体验,例如自己的 3D 查看器或优雅的错误消息。

如需从 HTML 触发显式 intent,请使用以下语法:

<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,请使用以下代码:

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);

支持的 intent 参数

“面向 AR 的 Google Play 服务”软件包的显式 intent 支持以下参数。

intent 参数 允许的值 评论
browser_fallback_url(对于基于 HTML 的 intent 是必需的) 有效网址 只有基于网络的实现支持此操作。 如果设备上没有面向 AR 的 Google Play 服务或不是最新版本,这就是设备导航到的网址。
mode(可选) ar_only Scene Viewer 始终在原生 AR 视图中启动 3D 模型,并隐藏用于切换到 Scene Viewer 3D 查看器的任何界面。

如果“面向 AR 的 Google Play 服务”不存在,Scene Viewer 会启动您在 browser_fallback_url 中为基于网络的体验设置的网址。 对于基于应用的体验,Scene Viewer 会回退到备用体验,例如错误消息或您自己构建的其他体验。

ar_preferred Scene Viewer 作为入口模式以 AR 原生模式启动,并可让用户通过在您所在的空间内查看以 3D 模式查看按钮在 AR 和 3D 模式之间切换。

如果“面向 AR 的 Google Play 服务”不存在,Scene Viewer 会启动您在 browser_fallback_url 中为基于网络的体验设置的网址。 对于基于应用的体验,Scene Viewer 会回退到备用体验,例如错误消息或您自己构建的其他体验。

   

link(可选) 有效网址 外部网页的网址。如果存在,则点击该按钮后,界面中会显示一个按钮,该按钮指向此网址。



版本 1.1 在 Scene Viewer 中添加了对 intent:// 链接的支持,以允许 Scene Viewer 访问按钮直接触发到其他应用。请注意,使用时应格外小心,只有当给定 intent 保证存在 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 体验,可见的号召性用语应传达给用户即将进入沉浸式环境。我们建议您使用在您的聊天室中查看号召性用语:

  • 用户可能未在设备上安装面向 AR 的 Google Play 服务。下面介绍了 <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

您可以在网站上启用 Scene Viewer,只需使用 ar 属性添加 <model-viewer> Web 组件即可。

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

在支持 ARCore 的 Android 设备上查看时,包含具有 ar 属性的 <model-viewer> 组件的网站会显示一个按钮,如以下示例所示。

ar-modes 中使用 scene-viewer 模式时,它会切换到原生 AR 视图,并邀请用户使用 Scene Viewer 将模型放置在其环境中。

如果“支持 AR 的 Google Play 服务”不存在,则点按此按钮会在 <model-viewer> 的 3D 查看器中显示该模型。

如需详细了解如何开始使用 <model-viewer>,请参阅 <model-viewer> 的文档

模型的文件要求

Scene Viewer 对模型提供以下支持和限制。

文件格式支持 glTF 2.0/glb,使用以下扩展程序:
  • KHR_materials_unlit
  • KHR_texture_transform
动画
  • 循环播放骨架动画
  • 循环播放刚性动画
  • 循环转换动画
动画将循环播放。如果 glTF 文件包含多个动画,Scene Viewer 仅播放第一个动画。
建议的限制 资源的整体性能取决于设置限制条件,并在顶点、材质、纹理分辨率、每种材质的网格及其他因素之间进行权衡。请按照以下准则优化素材资源。
  • 三角形的数量:建议的三角形数量上限为 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
Material PBR
文件加载 HTTPS
场景
  • 轴:右手,具有以下属性:
    • +X 是正确答案
    • +Y 有所上涨
    • - Z 从原点指向前方(也就是说,素材资源的“前端”应朝向 +Z)
  • 缩放:1 个单位 = 1 米(如 glTF 规范所定义,旨在确保模型以真实比例放置在 AR 中)

使用预览工具验证 3D 模型

为确保您的 3D 模型文件可在 Scene Viewer 中正确显示,请使用我们的在线预览器工具验证您的 PC 上的文件。

验证 3D 模型

如需验证模型,预览工具需要一个 glb 或 glTF 文件、所有关联的图片和 bin 文件,以及一个可选的音频文件。音频文件将与动画 0 一起循环播放。

您可以选择单个文件,也可以将 glb 或 glTF 及其关联文件放入一个 ZIP 文件中。(ZIP 文件方法不支持音频文件)。

要验证 3D 模型,请执行以下操作:

  1. 在浏览器中打开在线预览工具

  2. 您可以使用以下方法之一将文件添加到预览工具中:

    • 拖放。选择 glb 或 glTF 文件及其所有关联文件(或包含这些文件的 zip 文件),然后将所选文件或 ZIP 文件拖动到预览工具中。

    • 通过预览工具。在预览工具中,依次选择 Scene Viewer > Load File。选择一个 glb 或 glTF 文件及其所有关联文件(或包含这些文件的 zip 文件),然后点击打开

将包含 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 文件),然后点击打开

验证错误

错误代码 严重程度 消息 当前支持的值
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] 个三角形。 100000
PRIMITIVE_MODE_UNSUPPORTED 错误 Scene Viewer 规范不支持基元模式 [mode]。 {4 : 三角形列表, 5 : 三角带, 6 : 三角形扇}
MISSING_PBR_METALLIC_ROUGHNESS 信息 索引 [idx] 中的材质缺少 pbrMetallicRoughness 属性。如果改用金属和粗糙度系数,Scene Viewer 规范不需要这样做。如果这两种情况都未使用,该材质将使用默认值,这可能会导致意外行为。