样例使用说明

准备工作

准备Unity环境

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

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

准备Mega Studio及插件包

请登录EasyAR账号,并进入EasyAR开发中心后下载查看。

你将只能看到当前最新的版本,历史版本不可访问。

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

../../_images/image_gs1_1.png ../../_images/image_gs1_2.png

如登录后看不到上图的下载链接,请联系与你对接的工作人员。

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

../../_images/image_gs1_3.png

获取许可证授权

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

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

../../_images/image_gs1_4.png

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

../../_images/image_gs1_5.png

根据具体需要选择许可证类型,如果是试用一般可以选择 EasyAR Sense 4.0 个人版

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

填写 应用名称Bundle ID 等,这些也可以在之后修改,但需注意有修改次数限制。

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

../../_images/image_gs1_6.png

从页面上 复制 License Key


创建空Unity工程

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

../../_images/image_gs1_7.png

导入工具和sample

导入第三方SDK(如有需要)

如果你需要使用AR Foundation、Nreal设备等,需要先导入对应的文件。如果不需要可以跳过这一步。

注意:EasyAR并不需要使用AR Foundation才能运行。所以一般并不需要导入。

如果你需要使用Nreal设备,请确保在导入Nreal Unity Asset Package之后再打开sample场景,否则可能会出现异常。如果在这之前已经打开并保存了场景,建议删除并重新导入。

Nreal官方 获取Nreal SDK的 unitypackage 文件,通过 Unity > Assets > Import Package 来导入Nreal SDK。

然后创建虚拟的 Nreal Unity Package。注意, Unity Package 不是指 .unitypackage 文件,而是在Unity工程目录下 Packages 目录及相关文件,由 Unity的 Package Manager 所管理。

在Unity工程的 Packages 文件夹中创建一个文件夹 com.nreal.sdk ,并在该文件夹中创建文件 package.json ,其内容如下,注意其中 version 字段值需与你获取的Nreal SDK的版本号一致。

{
    "name": "com.nreal.sdk",
    "displayName": "Nreal MR SDK for Unity",
    "version": "1.7.0",
    "unity": "2019.4",
    "description": "",
    "keywords": [],
    "dependencies": {}
}

在创建完上述文件之后,Unity工程目录中的文件结构会是这样的

.
├── Assets
└── Packages
   └── com.nreal.sdk
       └── package.json

然后再在Unity的Package Manager中可以查看到 Nreal MR SDK for Unity

../../_images/image_gs1_48.png

解压Mega Studio及Unity插件

解压下载的两个zip文件,解压后将获得一些tgz文件及txt readme文件。(注意:请勿解压tgz文件)

.
├── EasyARMegaStudio_**.zip            :EasyAR Mega Studio
│   ├── com.easyar.mega-**.tgz             :包含标注工具及Block浏览工具
│   ├── com.easyar.mega.validation-**.tgz  :包含验证工具
│   ├── readme.cn.txt
│   └── readme.en.txt
└── EasyARSenseUnityPlugin_**.zip      :EasyAR Sense Unity 插件
    ├── com.easyar.sense-**.tgz            :包含EasyAR Sense及Unity插件
    ├── readme.cn.txt
    └── readme.en.txt

(**代表版本号,请以最新发布版为准)

导入package(UPM包)

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

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

com.easyar.sense-**.tgz
com.easyar.mega-**.tgz
com.easyar.mega.validation-**.tgz
../../_images/image_gs1_8.png

注意:导入后tgz文件不可删除或移动(如文件在Unity项目文件夹内,可以随Unity项目一起移动)。

导入sample到工程

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

../../_images/image_gs1_9.png

如果需要导入Nreal的sample,请先确保按照 在 Nreal 设备上使用 的说明对工程进行配置,然后再导入。否则将出现无法恢复的错误。


配置SDK和服务

填写许可证(License Key)

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

../../_images/image_gs1_10.png

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

../../_images/image_gs1_11.png

配置Mega定位服务

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

../../_images/image_gs1_12.png

Mega定位服务配置可以从EasyAR网站上获取。

../../_images/image_gs1_13.png

需要注意查看API Key有 云定位 的权限,如果没有需要进行更改或重新创建一个API Key。

../../_images/image_gs1_14.png

导入工具并摆放3D内容

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

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

打开sample场景

../../_images/image_gs1_15.png

添加工具:Block浏览工具(Unity开发)

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

../../_images/image_g4_11.png

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

../../_images/image_gs1_16.png

访问Mega定位服务

  1. 登录EasyAR账号

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

../../_images/image_g4_41.png
  1. 选择服务

点击 Mega Cloud Service 右侧按钮

../../_images/image_g4_61.png

选择 Mega 定位服务

../../_images/image_g2_131.png

加载 Block

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

../../_images/image_g4_81.png

点击加载选择Block

../../_images/image_g2_92.png

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

../../_images/image_g3_191.png

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

注意:在这里可以查看的数据并不能直接反应Mega 定位服务的效果。

参考 Block摆放3D物体

../../_images/image_gs1_17.png

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


配置Mega Tracker使用的Block根节点

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

../../_images/image_gs1_18.png

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


编辑器中运行:使用EIF文件

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

录制Mega使用的EIF需要使用 Mega Toolbox的 EIF录制工具,具体使用方法可以阅读其 操作手册

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

../../_images/image_gs1_19.png

配置 AR Session 使用 Frame Player,选择 First Available Active Child

../../_images/image_gs1_20.png

配置 Frame Player 中EIF文件的路径,

../../_images/image_gs1_21.png

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

../../_images/image_gs1_22.gif

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

../../_images/image_gs1_23.gif

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

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

../../_images/image_gs1_24.png

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

../../_images/image_gs1_25.png

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


编辑器中运行:使用PC相机(不建议)

如果没有EIF文件,又想快速做些验证(比如与跟踪效果不相关的流程开发),可以使用这种方式。

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

要使用PC相机,如果使用过 Frame Player播放EIF,需要确保Frame Player被关闭。配置 AR Session 关闭 Frame Player,选择 Disable

../../_images/image_gs1_26.png

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

../../_images/image_gs1_27.png

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

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

../../_images/image_gs1_28.gif

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

../../_images/image_gs1_29.gif

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

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

../../_images/image_gs1_30.gif

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


配置在手机等移动设备上运行:通用配置

删除Block浏览工具(Unity开发)

删除工具节点 EasyAR.Mega.BlockViewer (Dev)

../../_images/image_gs1_31.png

如果你希望在下次打开时保留当前状态,可以在删除前将 EasyAR.Mega.BlockViewer (Dev) 保存成prefab然后再删除。

如果不删除工具就运行,你会看到屏幕上有警告信息。这个警告信息是无法关闭的。因为这种使用方式会有可能使运行效果异常。

../../_images/image_gs1_32.png

关闭Frame Player

如果在PC上的测试中使用过 Frame Player播放EIF,需要确保Frame Player被关闭。配置 AR Session 关闭 Frame Player,选择 Disable

../../_images/image_gs1_26.png

配置权限

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

../../_images/image_gs1_44.png
  • 打开 Camera Device

  • 关闭 Video Recording,除非你确需使用。

  • 打开 Mega

Android工程配置

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

  1. API Level

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

../../_images/image_gs1_41.png
  1. Package Name

设置Android应用的Package Name, 注意Package Name要与创建License Key时填写的一致 。在Player Settings面板设置如下。

../../_images/image_gs1_42.png
  1. Target Architecture

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

../../_images/image_gs1_43.png
  1. ARCore 配置

为了在支持ARCore的手机上使用Mega,需要正确配置ARCore。 不需要单独安装ARCore或AR Foundation来使用ARCore。

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

  1. 针对 Unity 2019 的Gradle 配置

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

iOS工程配置

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

  1. Bundle ID

设置iOS应用的Bundle ID, 注意Bundle ID要与创建License Key时填写的一致 。在Player Settings面板设置如下。

../../_images/image_gs1_45.png
  1. Target Architecture

在 Player Settings 中修改 architecture 为 ARM64。 注意:不可使用Universal。

../../_images/image_gs1_46.png
  1. 权限配置使用说明

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

../../_images/image_gs1_47.png

添加场景

打开 Build Settings

../../_images/image_gs1_34.png

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

../../_images/image_gs1_35.png

手机等移动设备上运行:在现场

配置退化选项

  • 关闭 AllowNoTracking,它用于使用PC相机运行或使用特殊设备运行,在手机等移动设备上运行需要关闭。

  • 关闭 AllowNonEifRemote,用于在不使用EIF数据的时候进行远程测试,在现场运行需关闭。

../../_images/image_gs1_33.png

运行

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

../../_images/image_gs1_36.png ../../_images/image_gs1_37.png

运行效果大致如下,

../../_images/image_gs1_39.gif

手机等移动设备上运行:不在现场(不建议)

如果不在现场,又想在手机等移动设备上快速做些验证(比如与跟踪效果不相关的流程开发),可以使用这种方式。

需要注意的是,对着视频或图片运行看到的效果与实际效果完全无关,请勿以对着视频或图片看到的效果进行判断。

配置退化选项

  • 关闭 AllowNoTracking,它用于使用PC相机运行或使用特殊设备运行,在手机等移动设备上运行需要关闭。

  • 打开 AllowNonEifRemote,用于在不使用EIF数据的时候进行远程测试,不在现场运行需打开。

../../_images/image_gs1_38.png

运行

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

../../_images/image_gs1_36.png ../../_images/image_gs1_37.png

可以对着视频或图片运行,运行效果大致如下,

../../_images/image_gs1_40.gif

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