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

Scene Viewer 是一款沉浸式查看器，可让用户通过网站或 Android 应用体验 3D 和 AR 内容。借助它，Android 移动设备用户可以轻松预览、放置、查看和互动位于其环境中的网络托管 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 服务，请控制回退行为。 		使用指向面向 AR 的 Google Play 服务 (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> 或任何其他基于 Web 的 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 版本控制

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

Intent 版本 1.1 添加了对 intent:// 链接的支持，该链接可直接启动到 Android 应用，而不是启动到网址。如果您希望 Scene Viewer 保证在启动时此功能可用，否则无法启动，请使用 intent://arvr.google.com/scene-viewer/1.1 的 intent 启动 Scene Viewer。

支持的 intent 参数

对于指向 Google 搜索软件包的显式 intent，支持以下参数。

意图参数 允许的值 评论
file（必需） 有效网址 此网址用于指定应加载到 Scene Viewer 中的 glTF 或 glb 文件。此值应采用网址转义格式。
S.browser_fallback_url（基于 HTML 的 intent 所必需） 有效网址 这是一项 Google Chrome 功能，仅支持基于 Web 的实现。 如果设备上没有 Google 应用，Google Chrome 会导航到此网址。
mode（可选） 3d_preferred（默认） Scene Viewer 会以 3D 模式显示模型，并提供在您身处的空间内查看按钮。



如果设备上没有“面向 AR 的 Google Play 服务”，在您的空间中查看按钮会处于隐藏状态。

3d_only 即使设备上存在面向 AR 的 Google Play 服务，Scene Viewer 也会以 3D 模式显示模型。 系统绝不会显示在您身处的空间内查看按钮。

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



如果“Google Play 服务 - AR”不存在，Scene Viewer 会以 3D 模式作为入口模式正常回退。

ar_only 使用此值时，您应通过显式 Android intent 启动到 com.google.ar.core。

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

link（可选） 有效网址 外部网页的网址。如果存在，界面中会显示一个按钮，点击该按钮会启动指向此网址的 intent。

title（可选） 有效字符串 模型的名称。如果存在，则会显示在界面中。 名称在 60 个字符后会被截断并显示省略号。

声音（可选） 有效网址 一个网址，指向与嵌入在 glTF 文件中的第一个动画同步的循环播放音轨。应与具有匹配长度动画的 glTF 一起提供。如果存在，则在模型加载后循环播放声音。此值应采用网址转义格式。
resizable（可选） true（默认）

false

 如果设置为 false，用户将无法在 AR 体验中缩放模型。在 3D 体验中，缩放功能可正常使用。
enable_vertical_placement（可选） false（默认）

true

 如果设置为 true，用户将能够将模型放置在垂直表面上。

用户体验指南

为了给用户提供尽可能出色的用户体验，我们建议您在可见的行动号召中传达用户即将进入沉浸式环境的信息。

对于 3D 查看器体验，我们建议使用标签为 View in 3D（以 3D 模式查看）的行动号召，该号召应类似于以下图片之一：

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

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

为确保 AR 在 Scene Viewer 中可用，您可以使用来自网站或原生 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 参数

以下参数适用于针对 Google Play Services for AR 软件包的显式 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 中为基于 Web 的体验设置的网址。 对于基于应用实现的体验，Scene Viewer 会回退到替代体验，例如错误消息或您自行构建的其他体验。

ar_preferred Scene Viewer 以 AR 原生模式作为入口模式启动，并为用户提供通过在您身处的空间内查看和以 3D 模式查看按钮在 AR 模式和 3D 模式之间切换的选项。

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

   

link（可选） 有效网址 外部网页的网址。如果存在，界面中会显示一个按钮，点击该按钮会启动指向此网址的 intent。



版本 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

您可以通过在网站中添加带有 ar 属性的 <model-viewer> Web 组件来启用 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 设备上查看时，包含 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 只会播放第一个动画。
建议的限制 素材资源的整体性能取决于设置限制以及在顶点、材质、纹理分辨率、每个材质的网格和其他因素之间进行权衡。请按照以下准则优化素材资源。
  • 三角形数量：建议的上限为 10 万个三角形，但以最低数量为目标可确保 Scene Viewer 中的高性能。3 万到 5 万是理想范围。
  • 材质数量：建议的上限为 10 种材质，其中 2 种可以是 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 规范不会要求提供该属性。如果这两者均未使用，该材质会使用默认值，这可能会导致意外行为。