.. _3 快速开始:

3.快速开始
===============================

此文档帮助开发者使用SDK快速开始创建一个可以在 **Rhino X** 上运行的MR程序，了解SDK的使用流程以及文件结构，快速熟悉SDK。

关于SDK的详细功能、组件以及API，请查看后面的章节。

.. attention::
    此SDK只支持Rhino X头显，请勿在RhinoX Pro头显上使用此SDK

3.1 快速使用SDK
----------------------

1.下载 SDK
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

在开发者网站选择UnitySDK，点击 **“下载最新版”** 下载SDK，下载后将压缩包解压，会得到如下3个版本的Unitypackage

.. image:: _static/SDK_download.png

然后根据你需要使用的Unity编辑器版本选择对应的SDK包，切忌使用错误的Unity编辑器版本打开。

.. note::
    使用2019版本时，Unity版本必须是2019.4或以上版本，且必须使用URP


2.创建新项目
^^^^^^^^^^^^^^^^^^^^^^^^

1.通过Unity Hub创建新项目，创建时选择需要使用的Unity版本、选择3D模板、设置Project Name、选择Project路径

.. image:: _static/Create_Project.png

2.创建新项目之后，在新项目窗口选择 **Assets** -> **Import Package** -> **Custom Package...** 来导入SDK

.. note:: 
    选择的Unitypackage必须与刚才创建项目所选的Untiy编辑器版本一致

3.导入SDK,选择 **All** ，然后点击 **Import**

.. image:: _static/Import_SDK.png



3.UnitySDK 配置
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. SDK初始化

初次导⼊ SDK 进 Unity 项目中之后，必须通过 **RhinoX SDK/Initialize** 完成初始化。点击此按钮将初始化 RhinoX SDK 所需要的设置。 

.. image:: _static/unitysdk_init.jpg

.. note:: 
    -设置URP(2019.3、2019.4及以上版本需要)，参考 `unity2019设置URP的官方文档`_
    
    -如果未进行初始化，可能会出现显示异常

.. _unity2019设置URP的官方文档: https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@7.1/manual/InstallURPIntoAProject.html

2.项目设置

先在 **File** -> **Build Settings** 中将打包平台切换为Android

.. image:: _static/Switch_Platform.png

接下来在Player Settings中按照如下图设置：

.. image:: _static/Player_setting.png


4.打包应用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

RhinoX - Interaction - Demo - Two Hands demo场景展示了SDK的所有主要交互功能，您只需要打包此场景即可，请忽略其他Scene。

将需要打包的场景添加build场景中，然后勾选场景，点击右下角Build即可打包出一个apk文件。

您可以在Player Setting中设置修改Product Name以及Package Name，避免重复。

.. image:: _static/unitysdk_demo_build.png



5.安装运行应用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

参见 
:ref:`1.4.2 安装运行RhinoX应用 <1.4.2 安装运行RhinoX应用>`



3.2 SDK Demo介绍
-------------------

此章节详细介绍SDK里面的主要demo的文件结构，帮助您快速了解SDK的基本使用方法，如果您对具体的组件使用方法理解起来有困难
可以参考此demo进行详细对比，或者直接在此demo基础上进行改造。

3.2.1 文件结构
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

用 Unity 打开 sdk 项目以后⽂件路径结构如下:

.. image:: _static/unitysdk_file_list.jpg

.. tip::
    如上面文件结构所示，SDK 的所有内容都在 Plugins 文件夹中，如需在其他项目中使用SDK，只需复制粘贴 Plugins 文件夹中所有内容到其他 Unity 项目中的 Plugins 文件夹中即可。

**Plugins/Android ⽂件夹**

AndroidManifest.xml：此⽂件定义RhinoX所必须的所有权限请求， 默认权限请不要修改，如需其他权限请自行添加。 

Plugins/Android/assets：所有可追踪物体的标定⽂件(json 和 dat⽂件) 必须被存放在此路径中。 实际内容可能和此图有不同。 

Plugins/Android/libs： 存放usb权限请求⽂件。 此⽂件夹装载所有必须的代码库，这些库⽂件是视觉算法的核⼼⽂件， 请不要删除或者移动这些⽂件 

**Plugins/RhinoX ⽂件夹**

Plugins/RhinoX/Assets: 此文件夹中主要存放手柄交互相关资源，包括左右手柄的预制体，您可以直接通过他们来创建手柄交互组件

Plugins/RhinoX/OpenSource: 此文件夹里面主要存放RhinoX 交互系统代码，这些是开源⽂件，如果有需要⽤户可以修改这些⽂件

对应的Unity文件夹里面则存放SDK的DLL文件，建议不要改动此文件夹


3.2.2 初始化流程介绍
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
初始化内部⼯作流程: 

设置关键类的 execution order 

设置 PlayerSetting / MultiThread Rendering = False 

设置 QualitySetting / VysncCount = Don't Sync 

设置 Default Orientation = Landscape Left


3.2.3 场景介绍
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

此demo里面的主场景为 **RhinoX - Interaction - Demo - Two Hands demo** ，主要展示以下功能：


- 利用Beacon作为GroundPlane来定位虚拟场景的原点位置，同时支持1、2、3号Beacon

- 利用手柄提供6dof的交互功能，同时支持单手柄和双手柄

- 提供可供触碰、抓取、抛掷的Cube模型

场景结构如下：

.. image:: _static/unitysdk_demo_file.jpg

下面我们将介绍场景中最重要的几个GameObject模块，其他次要模块请您自行学习相关unity基础

**1. ARCameraRig** 

.. image:: _static/arcamera.jpg

ARCameraRig的子对象为ARCamera，他代表了我们的头显，因此场景必须有且只有一个 ARCamera 脚本存在。
   
ARCamera 脚本会让这个 Camera 以双目方式渲染，对可跟踪的物体进行识别，并且接受 VIO 算法的方位更新。
   
Tracking Config 下的选项可以让你控制头显的跟踪设置，如是否跟踪位置或者姿态，以及添加Tracking Profile

Reticle Config可以设置是否启用头瞄功能，可以通过反选Enable Reticle隐藏头显里面的小白点


.. warning::
    Tracking Profile必须包含需要跟踪的配置文件，不可为空。


**2. Ground Plane**

.. image:: _static/unitysdk_ground_plane.jpg

GroundPlane的作用是定位整个虚拟场景的地面位置，直接在场景的根目录下创建，可以创建多个，通常我们将他们的Transform设置（0，0，0）

我们通过Trackable Identity脚本来将GroundPlane与实际的定位信标进行绑定。通常我们将Beacon作为GroundPlane使用，即通过Beacon来控制场景的摆放位置。

GroundPlane脚本中的具体参数配置请查看 :ref:`Ground Plane<Ground Plane>` 介绍


**3. RxPlayerHand-RightHand** 

.. image:: _static/unitysdk_rxcontroller.jpg

此object代表我们的右手柄，left则代表左手柄，用于对场景中的对象进行交互

如果您需要创建新项目，建议您直接从下面路径导入手柄预制体，一般不需要您做修改，如果您对这个对象有兴趣，可以查看第4章文档
进行详细学习。

.. image:: _static/Controler_prefeb.png

手柄其实就是最典型的 :ref:`Dynamic Target<Dynamic Target>` 对象，所以此对象上挂载了Dynamic Target以及Trackable Identity脚本

其他脚本的详细信息请参考第4章 :ref:`RxController<RxController>` 。



**4. Touchable/Grabable/Throwable**

这些为可交互对象，分别为可触摸、可抓取、可抛掷，如果你需要使用类似功能，请参照demo进行创建

如果您对这些交互组件有疑问，或者使用上有困惑，请查看第4章，:ref:`交互组件<交互组件>`


**5. RxEventSystem**

当场景中添加 RxButtonEventTrigger 的时候被自动创建，是监听 RhinoX 硬件输入的系统模块，详细信息请查看 :ref:`事件系统<事件系统>`