stARkit for Cross-platform
stARkit for Cross-platform
工作流程
基于stARkit for Cross-platform的识别包含两个步骤：
制作目标。针对待识别对象进行数据采集（上传或扫描），然后在后台服务器进行离线训练，生成目标特征文件。
实时识别。将待识别目标对应的特征文件导入设备，基于相机实时视频流识别目标，估计其空间位姿，进而实现虚实叠加。
stARkit for Cross-platform包括三部分——晨星扫描仪、开发者网站和SDK。
晨星扫描仪负责采集待识别三维物体的信息并上传到平台云端，通过训练生成识别所需的特征数据；
开发者网站负责用户管理目标，以及用户上传数据制作目标；
stARkit for Cross-platform SDK则运行在设备上，负责从云端加载特征数据，并进行识别与跟踪，实时输出相机与目标在三维空间中的相对姿态（位移和旋转）。
支持的识别对象
stARkit for Cross-platform支持4类目标的识别与追踪。包括物体目标、环境目标、图片目标和模型目标。
- 物体目标: 普通3D物体，通过3D扫描仪采集数据生成的识别目标，需要其具有丰富纹理的物体。
- 环境目标：一个空间区域，通过晨星扫描仪采集数据生成的识别目标。
- 图片目标：通过上传图片生成的识别目标，将图片按设定尺寸打印后可识别。
- 模型目标：通过上传物体3D模型生成的识别目标，可识别模型对应的实物。
产品性能与工作条件说明
| 目标类型 | 规格说明 |
|---|---|
 | 物体属性：不透明刚体，纹理丰富且不重复 |
 | 空间区域属性：纹理丰富且不重复 |
 | 物体属性：不透明刚体 |
 | 物体属性：无形变的打印图片,纹理丰富且不重复 |
目标制作
物体目标
用户想识别一个物体，但没有其对应的3D模型，可以基于扫描的方式来制作识别目标。 该类型目标需要首先使用晨星扫描仪扫描采集待识别目标的数据后，上传到云端进行训练处理，进而生成目标识别信息，然后即可在平台网页端进行管理操作。 目标管理操作见这里。晨星扫描仪的使用方法参考此处。
环境目标
若需要识别的对象为一个空间区域，其制作目标的方式和物体目标类似，仅需在扫描仪中右上角切换为环境模式即可。
模型目标
模型目标通过在平台网页端上传目标对应的3D模型。在项目中点击“物体识别目标物”进入上传资源页面，再点击右上方"上传"-"模型"按钮，在弹出的对话框内填写目标名称后，选择本地模型文件和模型文件的单位，点击上传模型，即可将模型和相关信息上传到云端，从而进行自动处理，生成识别目标。
注意：模型文件格式目前支持obj、fbx和dae。若该识别应用是运行在AR眼镜，请务必选择正确的模型单位
图片目标
图片目标是指用户在平台上传一张图片，经云端自动处理后生成可用于stARkit for Cross-platform SDK识别的目标。然后用户将该图片打印出来后，SDK可直接识别打印的图片，进行叠加各种虚拟的信息。图片目标的制作流程与模型目标基本一样，仅在于上传时选择图片即可。 注意：若该识别应用是运行在AR眼镜，请务必填写正确的打印图片宽度
目标管理和下载
在项目页面点击“物体识别目标物”，进入目标管理页面后，可以看到当前项目中的所有目标及其信息。上述各类目标在经过平台处理后，显示为可用状态时，可以通过目标列表右侧的“下载”按钮，将制作好的目标下载到本地电脑中，用于后续的应用开发。 下载的目标为tag[id]_[rand_string].zip的形式，请不要更改文件名和内容。
基于Unity SDK进行物体识别应用开发
在Assets/Recognition/TargetReco中，提供了4个目标识别与跟踪的示例场景（见Assets/Recognition/TargetReco/Tutorial/Scenes），双击打开后既可在unity editor中修改配置运行或编译。
RecognitionTutorial For Smart Core：支持通用Android和iOS设备的目标识别示例场景。
RecognitionTutorial：支持PC端及unity editor的目标识别示例场景。
RecognitionTutorialForDaystar：支持晨星眼镜设备的目标识别示例场景。
RecognitionTutorialForHololens：支持HoloLens设备的目标识别示例场景。
若需要自己制作场景，请参考以下步骤，下列步骤以Unity2020.3.8f1c1为示例，不同版本unity的界面或选项存在一定差异。
开发场景配置
在Unity下方的项目窗口中，找到相关的预制件，将其拖拽添加到Unity场景中，注意各个预制件的层级，添加后状态见下图红框。需要添加的预制件包含：
/Assets/Common/Prefabs/SRApplication.prefab
/Assets/stARFrame/Prefabs/SRFrameManager.prefab
/Assets/stARFrame/Prefabs/SRBackground.prefab(D_WebCamera和D_ARFoundation设备必选)
/Assets/Recognition/Prefabs/SRTargetReco.prefab
/Assets/Recognition/Prefabs/SRTargetManager.prefab
/Assets/Recognition/Prefabs/SRNotification.prefab (可选)
具体配置：
点击场景中的SRApplication，并在右侧属性列表输入服务器网址以及应用的APP Key和Secret，请务必填入自己APP对应的Key和Secret,获取途径参考此处。
点击SRFrameManager，选择相应的设备类型。SRTargetReco建议使用如图配置。
添加目标到场景中
点击场景中的SRTargetManager，右侧属性面板点击"添加目标"按钮，在弹出的对话框中，找到从开发者网站下载的目标文件zip包，点击"打开"即可将该目标添加到场景中，加载一个SRTargetModel_tag[xxx]预制件。同时在SRTargetManager面板的目标列表会显示当前场景中的目标，通过点击“删除”按钮可将对应目标移除。
叠加虚拟模型
如上述操作添加目标后，相应SRTargetModel预制件中会附着一个目标3D模型作为子物体，此处可以根据具体业务需求，在该3D模型下挂着各种虚拟资源（模型、视频、图片等），这样在识别到该物体时便会自动显示加入的虚拟资源。
运行程序
在PC上插入一台摄像机，点击Unity顶部开始按钮，即可进行识别。
Unity SDK的环境识别应用
在Assets/Recognition/SceneReco中，提供了2个环境识别与跟踪的示例场景（见Assets/Recognition/SceneReco/Tutorial），双击打开后既可在unity editor中修改配置 运行或编译。
ARFoundationExample：支持通用Android和iOS设备的环境识别示例场景。
StARkitMapExample：支持晨星眼镜设备的环境识别示例场景。
若需要做精准虚实叠加，可以通过我们的平台网页下载所需的环境识别3D模型，将其置于unity场景中用于参考，确保3D模型的position和rotation在(0，0，0)，再将此model拖至[StARkitMapSession]下SR Scene Session中的场景模型。
运行示例场景apk可看到如下界面，选择“RecoOnly”，其他选项默认，此时这里的RecoOnly会”云端识别+本地重定位“。”获取云环境列表“可查看或删除晨星扫描仪上传到云端的环境目标id；
点击”开始识别“界面会有提示->正在识别中；
移动camera进行环境识别，识别到界面会有提示->(id)识别成功，随后会提示->(id)重定位中；
继续移动camera进行环境重定位，成功后界面会有提示->(id)重定位成功，同时放在上述unity开发场景中的对应model会贴附到真实环境中，也可观察屏幕右下方重定位前后的坐标信息。
为通用Android设备或iOS设备开发识别应用配置
通用Android设备的开发还需要ARFoundation和ARCore的支持。
在unity菜单栏点击Window中的Package Manager，在弹出的窗口中Packages选择Unity Registry，找到AR Foundation和ARCore XR Plugin建议安装4.1.1或以上的版本，需要保证ARFoundation和ARCore的版本一致。
装好后在Project Settings面板选择XR Plug-in Management，在安卓平台勾选ARCore，ARCore中的Requirement选择Optional。
Project Settings面板选择Player，在安卓平台下展开Other Settings，将Allow 'unsafe' Code勾选上。
iOS设备的开发则需要ARFoundation和ARKit的支持，与通用Android的配置大同小异，按如图配置：
要为通用Android或iOS开发场景，需在PC开发场景配置的基础上，将SRFrameManager下的设备类型改为D_ARFoundation，并添加AR Session和AR Session Origin两个预制体，在菜单栏点击GameObject中的XR可以看到这两个预制体：
点击AR Session Origin的子物体AR Camera，将Tracked Pose Device下的Update Type改为Update；ARFoundation较新版本，如4.1.7版本没有Tracked Pose Driver的组件，需要手动将AR Pose Driver组件替换成AR Pracked Pose Driver。
完成以上操作可将其打包为Android或iOS的应用，在相应设备上运行，SDK支持的Unity应用程序的构建及运行方式与Android、iOS的其他Unity应用程序的构建及运行方式相同。Android的具体流程见打包应用。
将构建平台切换到iOS，点击 Build 并指定路径以生成 Xcode 工程，Unity创建了Xcode项目后一个Finder窗口将在项目位置处打开，双击.xcodeproj文件， Xcode会打开该项目文件。Xcode构建运行到设备参阅在模拟器中或设备上运行您的 App。
为UWP开发物体识别应用的配置
确保按照 Microsoft 的安装工具 页面安装了最低支持的 Visual Studio 和 Unity版本 。
在HoloLens上开发物体识别应用，跟踪模式建议使用ENV_TRACKING。
使用Unity2019开发HoloLens需如下配置：
将SRFrameManager下的设备类型改为D_Hololens，在场景中添加MainCamera，确保场景中有且只有一个Camera，层次结构要在根节点，Camera的Clear Flags选择Solid Color，Background用黑色(0,0,0,0)。
点击菜单栏Edit下的Project Settings，在弹出的面板中选择Player,展开XR Settings将Virtual Reality Supported勾选上；
展开Publishing Settings将Capabilities下的WebCam勾选上。
使用Unity2020及以上开发HoloLens需如下配置：
在Package Manager中安装Windows XR Plugin。
装好后在Project Settings面板选择XR Plug-in Management，勾选Windows Mixed Reality；选择Player展开Publishing Settings将Capabilities下的WebCam勾选上。
SRFrameManager中的设备类型改为D_Hololens；在场景中添加MainCamera，确保场景中有且只有一个Camera，层次结构要在根节点，Camera的Clear Flags选择Solid Color，Background用黑色(0,0,0,0)，然后点击菜单栏GameObject→XR→Convert Main Camera To XR Rig，Camera Offset中的Camera Y Offset填为0。
完成以上操作可将其构建成Visual Studio工程进行UWP的打包或安装，SDK支持的Unity应用程序的构建及安装运行方式与UWP的其他Unity应用程序构建及安装运行方式相同。具体流程见打包应用。
将构建平台切换到UWP，点击 Build 并指定路径生成 Visual Studio 项目，等待Unity将VS工程打包到指定路径中。(右侧参数可以全部默认，后面会在VS中修改)。
打开Build出来的VS工程(.sln文件)，HoloLens2选择ARM64架构，在右侧解决方案资源管理器中选中项目并右键，选择发布(Publish)->创建应用程序包（当工程没有加载完毕时，发布中三项都是灰的，等工程加载完毕即可)。
为应用程序包进行设置，选择旁加载应用，下一步，使用当前证书，下一步。
配置包，只勾选ARM64，并选择Release(ARM64)，点击创建，等待创建完毕，VS会弹出如下图右侧提示框。
有关详细信息，请参阅 Microsoft 的 导出和构建 Unity Visual Studio 解决方案 和 使用 Visual Studio 部署和调试 教程。安装应用参见Microsoft 的使用 Windows 设备门户中的安装应用。
高级开发帮助
对于初级开发者，只需通过配置示例场景或放入并配置预制件即可完成基本的3D目标识别应用。但当需要在一个解决方案中使用stARkit for Cross-platform提供的功能时，应用开发者需要自行控制识别算法的启动结束时机，或者根据识别结果激活一些自定义的行为。这样的应用场景下，需要开发者主动调用SDK的接口和重新注册事件回调来实现。
unity预制件配置说明
| SRApplication | SDK 通用预制件 |
|---|---|
| Domain Host | 设置平台网站域名，通常为https://daystar.lenovo.com, 私有云用户的具体修改值需联系服务器管理员 |
| App Key | 需要识别的APP对应的Key |
| App Secret | 需要识别的APP对应的Secret |
| SRFrameManager | SDK 通用预制件 |
|---|---|
| Device Type | 设备类型 |
| Display Mode | M_Video_See: 视频透视模式，通常PC、手机平板等需要选择该模式 |
| Camera ID | 相机设备ID。通常为从0开始的整数 |
| Resolution | 相机分辨率 |
| Auto Open Camera | 是否自动开关相机 |
| SRTargetReco | TargetReco预制件 |
|---|---|
| AutoGetFrame | True：自动获取图像，无需用户传图像 False：用户需自主传入图像帧 |
| AutoStartReco | True：应用启动时自动开始识别 False：用户手动调用接口开启识别 |
| SRTrackingMode | TARGET_TRACKING:物体跟踪，建议在手机、PC等设备上使用 |
| Roi Width Ratio | 识别感兴趣区的宽度与图像宽度比例 |
| Roi Height Ratio | 识别感兴趣区的高度与图像高度比例 |
| SRTargetModel | TargetReco预制件 |
|---|---|
| Tag | 目标唯一标识，由云端系统生成 |
| Auto Add Target | 自动加载目标，取消勾选后需用户自行调用接口加载，适合高级开发者使用 |
| Auto Enable Target | 自动激活目标，取消候选后需用户自行调用接口激活 |
| [StARkitMapSession] | SceneReco预制件 |
|---|---|
| 场景模型(Scene Model) | 环境识别id对应的模型 |
| 云服务功能(Cloud service function) | Enabled：启用云服务 Disable：禁用云服务 |
| Map云端域名(Map cloud domain name) | 同SRApplication平台网站域名 |
TargetReco接口调用
stARkit for Cross-platform SDK中TargetReco提供的接口类为SRTargetRecoBehaviour，该类提供了实例获取方法public static SRTargetRecoBehaviour Instance()，通过该方法获取类实例后即可调用其中的接口控制算法行为。其中控制识别算法的接口主要有：
目标操作接口
//========================================================
//action有4种类型：
// TARGET_ACTION_ADD —— 加载目标
// TARGET_ACTION_REMOVE —— 删除目标
// TARGET_ACTION_ENABLE —— 激活目标
// TARGET_ACTION_DISABLE —— 冻结目标
//========================================================
public void TargetDoAction(string tag, SRTargetAction action);一个目标需要先被加载，然后激活后才可以被识别和跟踪。
但一个目标暂时不需要识别时，可以将其冻结，若后续都不再需要使用，则建议将其删除以节约系统资源。一个目标被加载后默认处于冻结状态。
在RecognitionTutorial的SRTargetBehaviour.cs脚本文件中有调用示例。
识别流程控制接口
//========================================================
//暂停识别，调用接口后，识别回调事件将不会被触发
//========================================================
public void TargetRecoPause();
//========================================================
//恢复识别
//========================================================
public void TargetRecoResume();TargetReco自定义回调事件
stARkit识别在每个主要接口调用完成后，会触发相应的回调事件。用户可以通过注册回调的方式触发自定义行为。
SDK初始化完成
在SDK初始化完成后会触发，通常仅在应用启动后触发一次。该事件在SRTargetBehaviour.cs脚本有调用示例，用于在初始化完成后自动加载目标。
回调事件：SRTargetRecoBehaviour.InitializeEvent
回调函数：void SRInitializeFinishedCallback(int errCode);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败目标操作完成
每次目标操作完成后触发。该事件在SRTargetBehaviour.cs脚本有调用示例，用于加载目标后自动激活目标。
回调事件：SRTargetRecoBehaviour.DoActionEvent
回调函数：void SRDoActionFinishedCallback(int errCode, string tag, SRTargetAction action);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败
tag —— 操作目标的tag
action —— 操作类型SDK销毁完成
在SDK销毁完成后会触发，通常仅在应用退出前触发一次
回调事件：SRTargetRecoBehaviour.DestroyEvent
回调函数：void SRDestroyFinishedCallback(int errCode);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败单帧识别完成
每帧识别完成后都会触发一次，可根据回调的识别目标信息来判断该帧图像的识别情况。该事件在SRTargetBehaviour.cs脚本有调用示例，在每帧识别完后，实时更新虚拟模型的在场景中的位姿信息。
回调事件：SRTargetRecoBehaviour.TargetPoseChangedEvent
回调函数：void SRTargetPoseChangedCallback(int errCode, SRAugTargets augTargets, IntPtr usrData);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败
augTargets —— 识别出的目标以及其位姿信息
usrData —— 用户自定义信息，默认情况为识别图像帧的一些附加信息TargetReco自定义相机数据
默认情况下，stARkit for Cross-platform SDK会自动打开相机获取画面进行识别，在某些情况下，开发者需要多个模块共用一个相机，因此需要其自行控制相机的开关，并将图像数据传到stARkit for Cross-platform SDK中。 SDK中提供了一个接口供外部传入图像数据：
void SubmitFrame(ref SRRecoFrame frame)；
frame —— 图像帧数据同时，若要主动调用该接口，需要在SRTargetReco prefab中把“自动获取图像”的复选框去除勾选。
TargetReco其他接口说明
stARkit for Cross-platform SDK 接口中还提供了2个接口，用于获取SDK相关的状态：
SDK版本获取接口
//用于获取stARkit for Cross-platform SDK的版本信息
public string GetVersion();错误描述信息获取接口： 每个回调事件中都会附带一个错误码，用于标识本次接口调用是否成功，当错误码非0时，可以调用GetErrorDescription函数获取错误信息，辅助定位失败原因。
//获取错误码对应的描述
public string GetErrorDescription(int errCode);SceneReco接口调用
stARkit for Cross-platform SDK中SceneReco提供的接口类为SRSceneRecoBehaviour，该类提供了实例获取方法public static SRTargetRecoBehaviour Instance(bool cloud)，参数为是否使用云服务，通过该方法获取类实例后即可调用其中的接口控制算法行为。其中控制识别算法的接口主要有：
识别流程控制接口
//========================================================
//开启识别或重定位
//"relocTimeoutMS":识别或重定位的时长
//"mapid":-2 识别加重定位，-1 仅识别；>=0 仅重定位
//"localMapPathDirectory"：本地存放id特征文件的路径
//========================================================
public virtual SRRestultCode SceneRecoStart(float relocTimeoutMS,int mapid=-2,string localMapPathDirectory = null)
//========================================================
//停止识别或重定位
//========================================================
public virtual SRRestultCode SceneRecoStop()//========================================================
//获取环境id列表
//========================================================
public virtual SRRestultCode GetSceneList(int pageNo, int pageSize)
//========================================================
//根据环境id删除对应特征文件
//========================================================
public virtual SRRestultCode DeleteSceneData(int mapId)//========================================================
//传数据
//========================================================
public virtual SRRestultCode SubmitFrame(SRFrameData[] frameDatas,List<byte[]> datas)SceneReco自定义回调事件
stARkit环境识别提供了一组注册接收回调和取消回调注册。用户可以通过注册回调的方式触发自定义行为。
//========================================================
//注册接收回调
//"SRBaseSceneRecivedData":识别或重定位过程中的状态信息
//========================================================
public void RegisterRecived (Action<SRBaseSceneRecivedData> recived)
//========================================================
//取消回调注册
//========================================================
public void UnRegisterRecived(Action<SRBaseSceneRecivedData> recived)