联想晨星SDK文档

中文

English

中文

English

颜色外观

stARkit for Cross-platform ​

工作流程 ​

基于stARkit for Cross-platform的识别包含两个步骤：

  1. 制作目标。针对待识别对象进行数据采集（上传或扫描），然后在后台服务器进行离线训练，生成目标特征文件。

  2. 实时识别。将待识别目标对应的特征文件导入设备，基于相机实时视频流识别目标，估计其空间位姿，进而实现虚实叠加。

    stARkit for Cross-platform包括三部分——晨星扫描仪、开发者网站和SDK。

    晨星扫描仪负责采集待识别三维物体的信息并上传到平台云端，通过训练生成识别所需的特征数据；

    开发者网站负责用户管理目标，以及用户上传数据制作目标；

    stARkit for Cross-platform SDK则运行在设备上，负责从云端加载特征数据，并进行识别与跟踪，实时输出相机与目标在三维空间中的相对姿态（位移和旋转）。

支持的识别对象 ​

stARkit for Cross-platform支持4类目标的识别与追踪。包括物体目标、环境目标、图片目标和模型目标。

  • 物体目标: 普通3D物体，通过3D扫描仪采集数据生成的识别目标，需要其具有丰富纹理的物体。
  • 环境目标：一个空间区域，通过晨星扫描仪采集数据生成的识别目标。
  • 图片目标：通过上传图片生成的识别目标，将图片按设定尺寸打印后可识别。
  • 模型目标：通过上传物体3D模型生成的识别目标，可识别模型对应的实物。

产品性能与工作条件说明 ​

目标类型规格说明

物体属性：不透明刚体，纹理丰富且不重复
物体尺寸：5cm x 5cm x 5cm ~ 3m x 3m x 3m

可识别距离：物体在图像中面积占比15%~90%
可识别角度：扫描角度范围内可识别

云端训练时间<5分钟
可识别最大目标数：20个
可同时跟踪8个物体

空间环境属性：纹理丰富且不重复，避免大片玻璃等反光材质，扫描路线避免重复场景。
支持最大区域：200平方米

可识别角度：扫描角度范围内可识别

训练时间<5分钟

物体属性：不透明刚体
物体尺寸：5cm x 5cm x 5cm ~ 10m x 10m x 10m

可识别距离：物体在图像中面积占比20%~90%
背景与目标颜色需要有明显差异

支持模型大小：200M
支持模型格式：OBJ / FBX / DAE
云端训练时间<5分钟
可识别最大目标数：3个

物体属性：无形变的打印图片,纹理丰富且不重复
物体尺寸：5cm x 5cm ~ 10m x 10m

可识别距离：物体在图像中面积占比15%~90%
可识别角度：相机视线与图片法向夹角在75°内

支持上传图片格式：bmp / jpg / jpeg / png / tif
云端训练时间<2分钟
可识别最大图片数：80张
可同时跟踪8张图片

目标制作 ​

物体目标 ​

用户想识别一个物体，但没有其对应的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_ARFoundation和无SLAM的D_WebCamera设备必选)

/Assets/Recognition/TargetReco/Prefabs/SRTargetReco.prefab

/Assets/Recognition/TargetReco/Prefabs/SRTargetManager.prefab

/Assets/Recognition/TargetReco/Prefabs/SRNotification.prefab (可选)

具体配置：

点击场景中的SRApplication，并在右侧属性列表输入服务器网址以及应用的APP Key和Secret，请务必填入自己APP对应的Key和Secret,获取途径参考此处。

点击SRFrameManager，选择相应的设备类型。SRTargetReco建议使用如图配置。

添加目标到场景中 ​

点击场景中的SRTargetManager，右侧属性面板点击"添加目标"按钮，在弹出的对话框中，找到从开发者网站下载的目标文件zip包，点击"打开"即可将该目标添加到场景中，加载一个SRTargetModel_tag[xxx]预制件。同时在SRTargetManager面板的目标列表会显示当前场景中的目标，通过点击“删除”按钮可将对应目标移除。

叠加虚拟模型 ​

如上述操作添加目标后，相应SRTargetModel预制件中会附着一个目标3D模型作为子物体，此处可以根据具体业务需求，在该3D模型下挂着各种虚拟资源（模型、视频、图片等），这样在识别到该物体时便会自动显示加入的虚拟资源。

运行程序 ​

在PC上插入一台摄像机，点击Unity顶部开始按钮，即可进行识别。或者将其打包为Windows应用运行，需要注意的是编译Windows物体识别应用前需在Project Settings->Graphics->Always Included Shaders中添加Unlit/Texture。

编译方法参考打包PC应用。编译完成后直接运行exe默认开启设备上第一个相机，若需要开启其他外接相机可在\“Product Name”_Data\StreamingAssets\CameraName路径下的CameraDeviceName.txt文件中指定RGB相机名字，再运行exe进行识别。

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中的场景模型。

如果只用本地重定位功能需要将云端下载zip包中的xxxx_ld.dat文件放到\Assets\StreamingAssets\MapConfig路径下一起编译。

运行示例场景apk可看到如下界面，选择“Loc”，取消勾选“UseCloud”，在“请输入map id”输入框中输入id；

点击”开始识别“界面会有提示->(id)重定位中；

移动camera进行环境重定位，成功后界面会有提示->(id)重定位成功，同时放在上述unity开发场景中的对应model会贴附到真实环境中，也可观察屏幕右下方重定位前后的坐标信息。

云端识别+本地重定位请选择“RecoOnly”，其他选项默认。”获取云环境列表“可查看或删除晨星扫描仪上传到云端的环境目标id；

点击”开始识别“界面会有提示->正在识别中；

移动camera进行环境识别，识别到界面会有提示->识别成功，随后会提示->(id)重定位中；

继续移动camera进行环境重定位，成功后界面会有提示->(id)重定位成功。

为通用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 Driver下的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具体流程如下：

  1. 在Unity中，从顶部菜单中打开Build Settings（File->Build Settings）。
  2. 点击左侧平台列表中的iOS并选择窗口底部的“Switch Platform”。
  1. 点击 Build 并指定路径以生成 Xcode 工程。
  1. 点击系统提示右上角的向下箭头将其展开，然后点击New Folder。
  2. 当系统提示选择一个名字是，输入“Builds”并点击Create。这将在你的工程的根目录下创建一个名为“Builds”的新文件夹。
  3. 在标记为Save As的文字输入栏中，输入“iOS”并点击Save。
  1. 一旦Unity构建了Xcode工程，将打一个工程位置的Finder窗口，双击.xcodeproj文件以使用Xcode打开工程。
  2. 点击File->New->File->Swift File。
  1. 在左上方，选择Unity-iPhone查看工程设置。打开并选择“Signing & Capabilities”选项，勾选”Automatically manage signing“，从“Team” 弹出式菜单中选取一个团队。
  1. 用USB将设备连到电脑，在Xcode左上角选择自己的设备后点击Run按钮。等待Xcode顶部中心栏中显示“Build succeeded”的消息且将应用加载设备上。此时注意设备不要为锁屏状态。

Xcode构建运行到设备参阅在模拟器中或设备上运行您的 App和准备分发您的 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预制件配置说明 ​

SRApplicationSDK 通用预制件
Domain Host设置平台网站域名，通常为https://daystar.lenovo.com, 私有云用户的具体修改值需联系服务器管理员
App Key需要识别的APP对应的Key
App Secret需要识别的APP对应的Secret
SRFrameManagerSDK 通用预制件
Device Type

设备类型
D_WebCamera: windows PC
D_ARFoundation:Android设备和iOS设备
D_Hololens: 微软的HoloLens眼镜
D_Starkit:晨星AR眼镜连接拯救者手机和基于光学透视的晨星AR眼镜

Display Mode

M_Video_See: 视频透视模式，通常PC、手机平板等需要选择该模式
M_Optic_See: 光学透视模式，AR眼镜选择该模式会有更好的体验，推荐选择

Camera ID相机设备ID。通常为从0开始的整数
Resolution相机分辨率
Auto Open Camera是否自动开关相机
SRTargetRecoTargetReco预制件
AutoGetFrameTrue：自动获取图像，无需用户传图像 False：用户需自主传入图像帧
AutoStartRecoTrue：应用启动时自动开始识别 False：用户手动调用接口开启识别
SRTrackingMode

TARGET_TRACKING:物体跟踪，建议在手机、PC等设备上使用
ENV_TRACKING:环境跟踪，建议在晨星AR眼镜上使用，适用于物体静止的场景

Roi Width Ratio识别感兴趣区的宽度与图像宽度比例
Roi Height Ratio识别感兴趣区的高度与图像高度比例
SRTargetModelTargetReco预制件
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()，通过该方法获取类实例后即可调用其中的接口控制算法行为。其中控制识别算法的接口主要有：

目标操作接口

csharp
//========================================================
//action有4种类型：
//    TARGET_ACTION_ADD     —— 加载目标
//    TARGET_ACTION_REMOVE  —— 删除目标
//    TARGET_ACTION_ENABLE  —— 激活目标
//    TARGET_ACTION_DISABLE —— 冻结目标
//========================================================
public void TargetDoAction(string tag, SRTargetAction action);

一个目标需要先被加载，然后激活后才可以被识别和跟踪。

但一个目标暂时不需要识别时，可以将其冻结，若后续都不再需要使用，则建议将其删除以节约系统资源。一个目标被加载后默认处于冻结状态。

在RecognitionTutorial的SRTargetBehaviour.cs脚本文件中有调用示例。

识别流程控制接口

csharp
//========================================================
//暂停识别，调用接口后，识别回调事件将不会被触发
//========================================================
public void TargetRecoPause();

//========================================================
//恢复识别
//========================================================
public void TargetRecoResume();

TargetReco自定义回调事件 ​

stARkit识别在每个主要接口调用完成后，会触发相应的回调事件。用户可以通过注册回调的方式触发自定义行为。

SDK初始化完成

在SDK初始化完成后会触发，通常仅在应用启动后触发一次。该事件在SRTargetBehaviour.cs脚本有调用示例，用于在初始化完成后自动加载目标。

csharp
回调事件：SRTargetRecoBehaviour.InitializeEvent
回调函数：void SRInitializeFinishedCallback(int errCode);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败

目标操作完成

每次目标操作完成后触发。该事件在SRTargetBehaviour.cs脚本有调用示例，用于加载目标后自动激活目标。

csharp
回调事件：SRTargetRecoBehaviour.DoActionEvent
回调函数：void SRDoActionFinishedCallback(int errCode, string tag, SRTargetAction action);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败
		 tag —— 操作目标的tag
		 action —— 操作类型

SDK销毁完成

在SDK销毁完成后会触发，通常仅在应用退出前触发一次

csharp
回调事件：SRTargetRecoBehaviour.DestroyEvent
回调函数：void SRDestroyFinishedCallback(int errCode);
参数说明：errCode —— 初始化错误码，0：成功， 非0：失败

单帧识别完成

每帧识别完成后都会触发一次，可根据回调的识别目标信息来判断该帧图像的识别情况。该事件在SRTargetBehaviour.cs脚本有调用示例，在每帧识别完后，实时更新虚拟模型的在场景中的位姿信息。

csharp
回调事件：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中提供了一个接口供外部传入图像数据：

csharp
void SubmitFrame(ref SRRecoFrame frame)；
frame —— 图像帧数据

同时，若要主动调用该接口，需要在SRTargetReco prefab中把“自动获取图像”的复选框去除勾选。

TargetReco其他接口说明 ​

stARkit for Cross-platform SDK 接口中还提供了2个接口，用于获取SDK相关的状态：

SDK版本获取接口

csharp
//用于获取算法SDK的版本信息
public string GetVersion();

错误描述信息获取接口： 每个回调事件中都会附带一个错误码，用于标识本次接口调用是否成功，当错误码非0时，可以调用GetErrorDescription函数获取错误信息，辅助定位失败原因。

csharp
//获取错误码对应的描述
public string GetErrorDescription(int errCode);

SceneReco接口调用 ​

stARkit for Cross-platform SDK中SceneReco提供的接口类为SRSceneRecoBehaviour，该类提供了实例获取方法public static SRTargetRecoBehaviour Instance(bool cloud)，参数为是否使用云服务，通过该方法获取类实例后即可调用其中的接口控制算法行为。其中控制识别算法的接口主要有：

识别流程控制接口

csharp
//========================================================
//开启识别或重定位
//"relocTimeoutMS":识别或重定位的时长
//"mapid":-2 识别加重定位，-1 仅识别；>=0 仅重定位
//"localMapPathDirectory"：本地存放id特征文件的路径
//========================================================
public virtual SRRestultCode SceneRecoStart(float relocTimeoutMS,int mapid=-2,string localMapPathDirectory = null)

//========================================================
//停止识别或重定位
//========================================================
 public virtual SRRestultCode SceneRecoStop()
csharp
//========================================================
//获取环境id列表
//========================================================
  public virtual SRRestultCode GetSceneList(int pageNo, int pageSize)
  
//========================================================
//根据环境id删除对应特征文件
//========================================================
  public virtual SRRestultCode DeleteSceneData(int mapId)
csharp
//========================================================
//传数据
//========================================================
public virtual SRRestultCode SubmitFrame(SRFrameData[] frameDatas,List<byte[]> datas)

SceneReco自定义回调事件 ​

stARkit环境识别提供了一组注册接收回调和取消回调注册。用户可以通过注册回调的方式触发自定义行为。

csharp
//========================================================
//注册接收回调
//"SRBaseSceneRecivedData":识别或重定位过程中的状态信息
//========================================================
 public void RegisterRecived (Action<SRBaseSceneRecivedData> recived)
 
//========================================================
//取消回调注册
//========================================================
 public void UnRegisterRecived(Action<SRBaseSceneRecivedData> recived)

版权所有 © 2019-2025 Daystar