样例使用说明¶

准备工作¶

版本需求：>= 4.7.0+3960

如果你在阅读这篇文档，那大概率你还在开发阶段，请确保更新到最新版本的工具，老版本的开发问题不受支持（线上应用不受影响）。

准备Unity环境¶

阅读 EasyAR Sense Unity 插件平台需求，了解EasyAR Sense Unity Plugin支持的系统和Unity版本，然后从Unity官方获取并安装Unity。

如果你是初次使用，建议使用Unity官方的长期支持版本。

准备Mega Studio及插件包¶

请访问EasyAR网站下载页面，登录后下载 EasyAR Mega Studio 及 EasyAR Sense Unity Plugin（Mega预发布版本） 。

你将只能下载当前最新的版本，历史版本不可访问。

你需要先申请试用，在通过审核后才可访问。

下载后会得到两个zip文件。

获取许可证授权¶

使用EasyAR Sense之前需要先在官网 www.easyar.cn 注册并获取许可证授权。

请注意这段内容所描述的网页内容和操作可能会因为网页迭代更新而有变化，请以网页使用为准。

登录后，进入 SDK授权管理 页面，点击 我需要一个新的Sense许可证密钥

根据具体需要选择许可证类型，如果是试用一般可以选择 EasyAR Sense 4.x 个人版 。

根据需要选择是否需要使用稀疏空间地图。Mega与稀疏空间地图无关，因此可以选择 否 。

填写 应用名称 和 Bundle ID 等，如果填写错误可以在之后修改，但需注意有修改次数限制。Lincense 不支持更换 Bundle ID ，如需要多个应用请购买并创建多个license。

注意

此处包名需和实际打包包名一致。

从页面上 复制 License Key

创建空Unity工程¶

创建工程时，Template 选择 3D。如果你在使用URP，请务必参考配置 Universal Render Pipeline (URP) 来进行配置。

导入工具和SDK¶

解压Mega Studio及Unity插件¶

解压下载的两个zip文件，解压后将获得一些tgz文件及txt readme文件。（注意：请勿解压tgz文件）

.
├── EasyARMegaStudio_**.zip                    ：EasyAR Mega Studio
│   ├── com.easyar.mega-**.tgz                     ：包含标注工具及Block浏览工具
│   ├── readme.cn.txt
│   └── readme.en.txt
└── EasyARSenseUnityPlugin_**.zip              ：EasyAR Sense Unity 插件
   ├── com.easyar.sense-**.tgz                    ：包含EasyAR Sense及Unity插件
   ├── com.easyar.sense.ext.arfoundation-**.tgz   ：包含EasyAR Sense Unity插件ARFoundation扩展
   ├── com.easyar.sense.ext.hmdtemplate-**.tgz    ：包含EasyAR Sense 头显插件的模板扩展（开发app请勿使用）
   ├── com.easyar.sense.ext.nreal-**.tgz          ：包含EasyAR Sense Unity插件Nreal扩展
   ├── readme.cn.txt
   └── readme.en.txt

（**代表版本号，请以最新发布版为准，版本号格式为：Major.Minor.Patch+BuildNum.BuildHash）

注意

除非与EasyAR确认，任何版本号中BuildNum不一致的文件都不能正常使用，如果你拿到了版本号不一致的文件，请仔细阅读前面说明确保下载了正确的文件。每次更新都会全部更新。

导入package（UPM包）¶

Mega Studio 及插件使用 Unity's package 组织文件，通过 tarball 文件分发。

将三个tgz文件放在Unity项目 Packages 文件夹内，然后通过Unity的 Package Manager window 来使用本地tarball文件，导入如下文件：

com.easyar.sense-**.tgz
com.easyar.mega-**.tgz

导入后弹窗点OK

注意

导入后tgz文件不可删除或移动（如文件在Unity项目文件夹内，可以随Unity项目一起移动）。

注意

如不使用AR Foundation，请勿导入com.easyar.sense.ext.arfoundation包。

如不使用Nreal，请勿导入com.easyar.sense.ext.nreal包。

请勿导入com.easyar.sense.ext.hmdtemplate包，这是给硬件厂商的对接模板，并不用来直接支持任何设备或做任何应用开发。

导入sample到工程¶

样例随EasyAR Sense Unity Plugin一起分发。可以使用 Unity的 Package Manager window 将样例导入工程中。

初次使用建议导入EasyAR Sense Unity Plugin的所有sample并都运行一下，

如果你对EasyAR比较熟悉，也可以只导入需要的sample，

需要注意的是，以上两种导入方式不能同时进行，否则文件会发生冲突导致sample不可用。如需要切换请先删除导入的sample之后重新导入。

注意

头戴显示设备的sample不在这个地方，但建议在开发头显设备之前先使用手机开发了解流程，请阅读下面说明。

注意

升级SDK之后，必须删除原来的sample再导入，否则可能会出错。

导入头戴显示设备SDK和EasyAR扩展（Pico、Qiyu、Rokid、Nreal等）¶

版本需求：>= 4.7.0+3283

EasyAR和头显SDK的关系¶

EasyAR的功能与头显的功能大部分是不重叠的。所以大部分情况下，EasyAR不会代理头显的功能，当你需要使用头显的一些功能，比如手势识别等的时候，你需要按照对应头显官方的做法来使用，并从其官方了解这些功能的具体使用方法和适用范围。

对EasyAR来说，头显SDK提供了在其设备上的运动跟踪能力，EasyAR也只利用了头显的这部分功能。请阅读运动跟踪与EasyAR功能来了解EasyAR功能与运动跟踪的关系，以及EasyAR的什么功能可以在有运动跟踪时使用。

对Pico、Qiyu、Rokid、Nreal等等这些AR/VR显示设备来说，设备自身运行不会使用EasyAR，EasyAR补足了这些设备在一些场景下的能力。

EasyAR 支持的头显 SDK 版本及设备请阅读头显兼容性。

导入头显SDK¶

从设备官方获取SDK并使用官方方法导入。这里列出几个已知头显的官方下载或文档链接，如有变化或链接失效请与头显官方确认。

PICO Unity Integration SDK
QIYU ToB SDK ，未公开发布，如需使用请联系Qiyu或EasyAR官方
Rokid UXR2 SDK ，请联系Rokid获取准确文档位置
Nreal SDK

确保头显自身的 demo 可以使用¶

如果在当前工程中第一次使用某个头显的SDK，请务必先在没有EasyAR的情况下使用它自身的demo，通常来讲这些demo都需要一些特殊的工程配置，请参考其官方文档来使用。许多设备SDK都提供物理相机输入的demo，比如Rokid的 RKCameraPreview。由于EasyAR需要物理相机的输入，而很多其它demo并没有使用到物理相机，所以其它一些sample或设备本身可以显示内容并不说明已经准备好了。

小技巧

默认情况下，EasyAR会在相机前显示一些运行信息，如果头显SDK配置正确，它必然会显示出来。很多时候，使用EasyAR但看不到任何显示都是因为设备SDK配置不正确，而其本身的Demo也无法合理运行。比如，在Nreal SDK的一些版本中，你需要先解决Nreal菜单 NRSDK > Project Tips 所显示的所有错误。其它眼镜有时候也有类似配置。

导入EasyAR Sense Unity Plugin头显扩展¶

不同的设备SDK需要使用不同的扩展，所有扩展都需要通过Unity的 Package Manager window 来使用本地tarball文件安装插件。这里列出已知一些头显扩展的包名及对应下载文件名。

PICO Unity Integration SDK: 下载文件 EasyARSenseUnityPluginPicoExtension_*.zip ，Unity插件包 com.easyar.sense.ext.pico-*.tgz
QIYU ToB SDK: 下载文件 EasyARSenseUnityPluginQiyuExtension_*.zip ，Unity插件包 com.easyar.sense.ext.qiyu-*.tgz
Rokid UXR2 SDK: 下载文件 EasyARSenseUnityPluginRokidExtension_*.zip ，Unity插件包 com.easyar.sense.ext.rokid.uxr-*.tgz
Nreal SDK: 下载文件 EasyARSenseUnityPlugin_*.zip ，Unity插件包 com.easyar.sense.ext.nreal-*.tgz

导入EasyAR Sense Unity Plugin头显扩展的sample工程¶

样例随对应的头显扩展一起分发（注意：不在Mega Studio里面）。可以使用 Unity的 Package Manager window 将样例导入工程中。

以Pico为例，

填写许可证（License Key）¶

从Unity菜单中选择 EasyAR > Sense > Configuration 。该页面也可以通过 Edit > Project Settings > EasyAR > Sense 进入。

然后在打开的 Project Settings 窗口中填写从网站上复制的license key

Mega云定位服务全局配置¶

在配置Mega云定位服务前，需要先在Mega云定位库内添加你需要用于现场空间识别定位的Mega Block。该步骤请查看配置定位服务

并将添加好Mega Block的云定位库的各项信息配置到Unity，就能对该Mega Block对应地区进行现场空间识别定位了。

从Unity菜单中选择 EasyAR > Sense > Configuration 打开配置页面并填写配置。

Mega云定位库配置可以从EasyAR开发中心获取。

需要注意查看API Key是否有 Mega Block 的权限，如果没有需要进行更改或重新创建一个API Key。

上述方法是全局配置，配置之后对使用全局配置的所有 MegaBlockTrackerFrameFilter 有效。

Mega云定位服务自定义加载¶

如果你的APP需要使用多个不同Mega云定位库内的Mega Block时，可以通过场景或自定义脚本进行云定位服务选择控制，可以在 MegaBlockTrackerFrameFilter 上进行配置。

先取消勾选Use Globe Service，并在下方配置云定位库信息

导入工具并摆放3D内容¶

提示

使用sample MegaBlock_Ema 时可以跳过这一步，这个sample在代码里创建了方块和球体等物体。要使用这个sample，你需要在另外一个Unity项目中使用标注工具导出ema文件，然后根据sample代码提示将导出的ema文件放到 Assets/StreamingAssets/EasyAR.Mega.Annotation.ema 即可。

在开发中需要频繁使用工具 Block浏览工具（Unity开发） ，这里会简要说明关键步骤，关于该工具的完整的说明可以参考其操作手册。

打开sample场景¶

添加工具：Block浏览工具（Unity开发）¶

在 Hierachy 面板空白处右键点击，选择 EasyAR Mega > Block Viewer for Unity Developer (Edit Mode)

添加后会多出来两个节点：

访问Mega定位服务¶

登录EasyAR账号

选中 EasyAR.Mega.BlockViewer (Dev) 节点，在 Inspector 面板中填写账号信息并登录

选择服务

点击 Mega Cloud Service 右侧按钮

选择 Mega 定位服务

加载 Block¶

注意

工具连接的是云服务，你永远无法下载所有云服务数据到Unity工程中。如果你看不到block数据，说明云服务配置有问题，请参考配置定位服务正确配置之后再使用工具加载。服务操作后，需点击刷新按钮进行刷新从云服务获取最新数据。

在选择服务之后，当前库中的Block列表会显示在 MegaBlocks 节点下，并显示在工具面板上。

点击加载选择Block

加载完成后，Block会显示在 Scene 窗口中。

载入后，可以在 Scene 窗口中操作，调整查看的视角位置。同时检查下Block文件是否可用（比如Block坐标系是否正常，是否过于模糊而无法找到位置摆放AR资源等）

注意

在这里可以查看的数据并不能直接反映Mega 定位服务的效果

参考 Block摆放3D物体¶

注意

3D物体必需摆放在工具自动生成的 Block_* 节点（ MegaBlocks 的子节点）下面，否则运行时物体显示的位置有可能会是不对的。这个节点的名字和local transform是不能修改的，它由工具所管理。

你也可以使用全景图环境预览功能，参考全景图进行内容摆放和查看。

配置Mega Block Tracker使用的Block根节点¶

提示

使用sample MegaBlock_Ema 时可以跳过这一步，这个sample在代码里创建并添加了Block。要使用这个sample，你需要在另外一个Unity项目中使用标注工具导出ema文件，然后根据sample代码提示将导出的ema文件放到 Assets/StreamingAssets/EasyAR.Mega.Annotation.ema 即可。

展开 AR Session ，选择 Mega Block Tracker 并设置 Block Root 为工具生成的 MegaBlocks 节点。

Block Root Source 应保持默认的 External ，只有在不使用工具预生成的Block数据而是动态创建的时候才能选择其它选项（比如 MegaBlock_Ema ）。

编辑器中使用Session验证工具运行：使用EIF文件¶

如果你过去做过EasyAR Sense相关开发，可能你会想直接在电脑上使用电脑相机运行，但Mega的使用略有不同，你需要先通过移动设备录制EIF数据，然后在电脑上使用EIF数据运行，才能看到完整的运行效果。

如果你在使用头显设备的SDK，比如Pico、Qiyu、Rokid、Nreal等，那通常它不能在编辑器中运行。但如果你从未使用过编辑器运行，请导入Mega Studio的basic sample熟悉常规流程。虽然头显工程通常不能直接在编辑器中使用，但使用basic sample在编辑器中运行是了解Mega开发流程所必要的。

录制Mega使用的EIF可以使用 Mega Toolbox，具体使用方法可以阅读其操作手册。

或者你也可以使用 Mega的sample或你自己的app进行录制。sample中的“Record EIF”按钮就可以用来录制eif。你也可以在运行Mega程序时，进入开发者模式进行录制（默认点击8次屏幕可开启）。需要注意的是，录制eif的session中必须有Mega的跟踪组件，否则录制的eif不能在Mega功能中使用。

录制好的EIF数据应包含.eif文件和.eif.json文件才能使用。

配置 AR Session 的 Session Validation Tool ，选择打开 Frame Player ，

然后就点击工具栏按钮在编辑器上运行了，

点击 Session Validation Tool 工具上的运行按钮也可以，效果是一样的，

运行之后会弹出提示框，请注意阅读理解

打开新的eif文件，

正常打开后它会自动播放，你可以使用工具栏进行暂停/继续等控制，

运行之后可以看到这样的效果，由于在场景中加载了Block模型，Block模型也会显示出来。这在进行位置比对或是未放置模型的地方查看定位效果的情况下还是有用的。

一般来说可以将工具 EasyAR.Mega.BlockViewer (Dev) 关闭（active设成false或删除节点），然后运行看到的就是在现实场景中叠加了虚拟物体的效果。

默认设置下，启动后，在第一次定位到Block之前，整个 MegaBlocks 及其子节点的active都是false，内容不会显示。

在定位到之后，上述节点的active会变成true，内容会显示出来并不断更新位置。

如果要改变相关行为，或是更加自由的控制active行为，可以参考如下两个接口说明：

运行之后需要关注屏幕上显示的诊断信息，一般建议在应用开发初期都在屏幕上显示这些信息，以便快速定位开发中遇到的问题。

重要

在使用时，你一定会注意到运行时显示在屏幕上或目视前方的诊断信息文字，请仔细阅读弹出消息处理及错误围栏以及会话状态显示及转储，仔细斟酌在开发阶段、测试阶段、应用上线之后应该采取何种配置，以及保留何种控制开关。请注意，与EasyAR的沟通通常需要提供这些信息，建议多利用而不是立马关闭。

编辑器中运行：使用PC相机（不建议）¶

如果没有EIF文件，又想快速做些验证（比如与跟踪效果不相关的流程开发），可以使用这种方式。如果你使用的是头显设备，比如Pico、Qiyu、Rokid、Nreal等，那通常它不能在编辑器中运行。

注意

在PC上使用相机运行看到的效果与实际效果完全无关，请勿以PC上看到的效果进行判断。

要使用PC相机，如果 Session Validation Tool 中打开了 Frame Player ，运行之前需要关闭，

连接相机并运行，你会看到屏幕上有几个警告信息。

注意

这些警告信息是无法关闭的，因为这种使用方式并不能反映真实效果，我们限制这种方式只能在开发过程中使用，且开发人员应该清楚这样使用的影响。

如果看到屏幕上显示的诊断信息中时间戳在不断更新，就说明系统已经正常在运行了。

可以使用相机对着图片或视频运行，如果定位成功，将会看到3D物体贴屏显示并跳跃更新。由于在场景中加载了Block模型，Block模型也会显示出来。

注意

上述运行效果与实际使用无关，只能用来做一些与跟踪效果不相关的开发和调试。

如果将工具 EasyAR.Mega.BlockViewer (Dev) 关闭（active设成false或删除节点），看到的就是在现实场景中叠加了虚拟物体的效果。

注意

同样地，上述运行效果与实际使用无关，只能用来做一些与跟踪效果不相关的开发和调试。

重要

在使用时，你一定会注意到运行时显示在屏幕上或目视前方的诊断信息文字，请仔细阅读弹出消息处理及错误围栏以及会话状态显示及转储，仔细斟酌在开发阶段、测试阶段、应用上线之后应该采取何种配置，以及保留何种控制开关。请注意，与EasyAR的沟通通常需要提供这些信息，建议多利用而不是立马关闭。

手机等移动设备上运行¶

配置GPS输入方式¶

根据是否在现场运行调整设置。

如果在现场运行，设置 LocationInputMode 为 Onsite

如果不在现场运行，设置 LocationInputMode 为 Simulator

不影响使用但应该了解的¶

Block浏览工具（Unity开发） 可以保留工具在场景中，但是通常仍建议在最终发布时删除。保留在场景中的工具在设备上是不能使用的。工具加载的block模型数据不会被保留在场景中，如有需求使用block模型，请导出obj后使用建模工具或Unity编辑器按其正常使用方式使用。

Session Validation Tool 的选项只影响编辑器上使用，不影响手机上的行为，你可以根据情况进行修改。

配置权限¶

从Unity菜单中选择 EasyAR > Sense > Configuration 打开配置页面，配置需要的权限。

打开 Camera Device。
关闭 Video Recording，除非你确需使用。
打开 Mega。

Android工程配置¶

关于EasyAR Sense Unity Plugin的详尽的配置说明可以参考 Android 工程配置文档，这里列出使用Mega时的通常配置。

API Level

EasyAR Sense 需要 Android API Level 21 或以上。在Player Settings面板设置如下。

Package Name

设置Android应用的Package Name。在Player Settings面板设置如下。

注意

Package Name要与创建License Key时填写的一致

Target Architecture

选择IL2CPP编译并选择ARM64支持。在Player Settings面板设置如下。

ARCore 配置

为了在支持ARCore的手机上使用Mega，需要正确配置ARCore。

一般情况下，建议使用EasyAR的ARCore SDK，如果工程中有AR Foundation，而你又不直接使用，建议删除AR Foundation。如果你确实需要使用AR Foundation，请参考其文档正确配置。需要注意的是，使用EasyAR的ARCore SDK时并 不需要 配置Graphics API为某个特殊的值。

注意

不需要单独安装ARCore或AR Foundation来使用ARCore。

务必不要在不支持ARCore的手机上安装ARCore服务，这会引起Google ARCore SDK工作异常从而导致黑屏等问题。

针对 Unity 2019 的Gradle 配置

如果你在使用Unity 2019，需要严格按照 Google的说明或 EasyAR 的说明来更新工程使用的Gradle版本。这里就不再赘述。

iOS工程配置¶

关于EasyAR Sense Unity Plugin的详尽的配置说明可以参考 iOS 工程配置文档，这里列出使用Mega时的通常配置。

Bundle ID

设置iOS应用的Bundle ID。在Player Settings面板设置如下。

注意

Bundle ID要与创建License Key时填写的一致

Target Architecture

在 Player Settings 中修改 architecture 为 ARM64。

注意

不可使用Universal。

权限配置使用说明

添加 Camera Usage Description和Location Usage Description，请按你需要的文字进行添加，这里只是示例。

添加场景¶

打开 Build Settings ，

将当前场景添加到 Build Settings 中。

运行¶

切换到目标平台然后点击Build Settings的 Build 或 Build And Run 按钮或通过其它方式编译项目并在手机等移动设备上安装，运行时需允许相应权限。

在现场运行效果大致如下，

如果不在现场，又想在手机等移动设备上快速做些验证（比如与跟踪效果不相关的流程开发），可以对着视频或图片运行，运行效果大致如下，

重要

不在现场运行时，请务必正确配置GPS输入方式，否则将无法使用。

正确配置下，你会看到屏幕上始终显示警告信息，这段信息无法关闭，以确保应用不会以错误的配置发布到最终用户手中。

注意

对着视频或图片运行看到的效果与实际效果完全无关，请勿以对着视频或图片看到的效果进行判断。这种方式只能用来做一些与跟踪效果不相关的开发和调试。

重要

在使用时，你一定会注意到运行时显示在屏幕上或目视前方的诊断信息文字，请仔细阅读弹出消息处理及错误围栏以及会话状态显示及转储，仔细斟酌在开发阶段、测试阶段、应用上线之后应该采取何种配置，以及保留何种控制开关。请注意，与EasyAR的沟通通常需要提供这些信息，建议多利用而不是立马关闭。

补充说明¶

弹出信息显示、问题诊断与发布¶

请仔细阅读弹出消息处理及错误围栏以及会话状态显示及转储，仔细斟酌在开发阶段、测试阶段、应用上线之后应该采取何种配置，以及保留何种控制开关。请注意，与EasyAR的沟通通常需要提供这些信息，建议多利用而不是立马关闭。

关于AR Foundation¶

版本需求：>= 4.6.0+2885

早于 4.6.0+2885 的版本如果使用不好比较容易出问题，已不再支持。如果你在使用老版本，请立即升级，并使用新的方式来接入AR Foundation。很多常见的问题不会在新版本中出现。

使用EasyAR进行Mega开发并不需要使用AR Foundation。如果你有需要使用AR Foundation特殊功能的需求（比如人物遮挡、光照估计等），可以在场景中添加AR Foundation。如果你没有上述使用需求，建议不要在工程中添加AR Foundation，以简化开发和避免出错。

使用 AR Foundation 请参考与 AR Foundation 协同工作来安装对应的文件。该文档中 导入和使用sample 前面的部分完整说明了应该如何导入相关文件。

注意

AR Foundation的支持是通过EasyAR Sense的自定义相机实现的。使用个人版的EasyAR Sense license或使用试用版本的Mega服务时，如果运行时选择了自定义相机，EasyAR每次启动将只能使用100秒。使用付费版本的EasyAR Sense和付费的EasyAR Mega服务没有这个限制。

重要

如果你需要在所有支持ARCore的小米和红米手机上使用ARCore，请使用AR Foundation。由于小米厂商实现有bug，EasyAR的ARCore实现已经禁用部分小米手机，包括米9、米10、红米K20、红米K30、红米K40等系列（这里列出的不全）。在这些手机上，默认配置下将不会使用ARCore，在支持EasyAR云端跟踪的手机上会使用EasyAR运动跟踪。

关于头显的补充说明¶

EasyAR头显扩展及 EasyAR头显扩展样例说明对EasyAR Sense Unity Plugin中的头显的支持做了更多的描述，如果你想了解更多细节，比如如何在头显场景中添加EasyAR功能，或是如何在EasyAR场景中添加头显功能，可以阅读这些个文档。