从零创建可运行的工程

这篇文章将详细描述如何使用 EasyAR Sense Unity Plugin 快速创建一个Mega应用的过程。

准备工作

准备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

导入工具

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

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

注意:EasyAR并不需要使用AR Foundation才能运行。

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

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项目一起移动)。


配置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

创建EasyAR Mega场景

创建含有Camera的场景

创建场景或使用工程自动创建的场景,确保场景中含有Camera。

../../_images/image_gs2_1.png

配置相机(如果你在使用 AR FoundationAR Engine Unity SDKNreal SDK ,这些数值通常会由这些package所预设),

../../_images/image_gs2_2.png
  • Tag: 如果Camera不是来自 AR FoundationAR Engine Unity SDKNreal SDK ,可以设置Camera Tag为 MainCamera,这样它会在AR Session启动时被frame source所选用。或者,你也可以通过在Inspector面包设置 FrameSource.Camera 来修改 FrameSource 的 Camera 为这个Camera。

  • Clear Flags: 需要选择为 Solid Color 以确保Camera图像可以正常渲染。如果选择为 Skybox ,Camera图像将无法显示。

  • Background: 这个非必需配置,考虑到使用体验,建议将背景颜色设为 黑色 以便在Camera设备打开前和切换时以黑色显示。

  • Clipping Planes: 根据实际需要(物理空间的长度)设置。这里设置Near为0.1(米)以避免相机离物体较近时无法显示。

创建 EasyAR AR Session

你可以使用预设来创建 AR Session,也可以逐节点创建 AR Session。

  1. 使用预设创建 AR Session

使用 EasyAR Sense > Mega > AR Session (Mega Preset) (或 EasyAR Mega > Sense > AR Session (Mega Preset) )来创建AR Session。

../../_images/image_gs2_3.png
  1. 逐节点创建 AR Session

如果 AR Session 预设不满足你的需求,你也可以逐节点创建 AR Session,并根据情况选择合适的组件。

比如,如果要创建一个与上述预设相同的AR Session,可以这样操作:

首先使用 EasyAR Sense > AR Session (Preset) > AR Session (Empty) 创建一个空的 ARSession

../../_images/image_gs2_4.png

然后在session中添加 FrameSource 。为了使用 Mega ,你需要一个表示运动跟踪设备的 FrameSource ,这通常在不同设备上会运行不同的 frame source。这里我们使用 EasyAR Sense > Motion Tracking > Frame Source Group : AR Foundation First 来创建一个 Frame Source Group ,session使用的 frame source 会在运行时选择。你可以根据具体需求添加不同的 frame source 组或单个 frame source 到session中。

../../_images/image_gs2_5.png

在添加 frame source 之后,你需要添加 session 需要使用的 frame filter ( MegaTrackerFrameFilter )。通过 EasyAR Sense > Mega > Frame Filter : Mega Tracker 来完成。

../../_images/image_gs2_6.png

有时你需要在设备上录制 input frame (EIF文件) 然后在PC上回放,以便在 Unity 编辑器中运行然后查看效果或诊断问题,这时你可以在session中添加 FramePlayerFrameRecorder 。(当然,如果要使用这些功能的话,你需要根据情况修改 ARComponentPicker.FramePlayerARComponentPicker.FrameRecorder 。)

../../_images/image_gs2_7.png

最后,AR Session 会是这样,

../../_images/image_gs2_8.png

显示Debug信息(开发提示)

在开发过程中,大部分情况下,你需要将一些debug信息打印到log或显示在屏幕上,以便在开发中分析问题。可以参考 MegaTracking_Basic 的场景和脚本,添加Canvas并在脚本的Update中添加实时更新的debug信息。

../../_images/image_gs2_10.png ../../_images/image_gs2_11.png

运行时这些信息是非常有助于了解系统运行状态和分析问题的。

../../_images/image_gs2_12.png

导入工具并摆放3D内容

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

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

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

../../_images/image_g4_11.png

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

../../_images/image_gs2_9.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根节点

../../_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

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