JSON C++/Python SDK_关节角度使用手册

1. 概述

1.1. 功能

本SDK基于JSON传输格式获取手部各关节角度数据,支持Windows和Linux两种环境。

1.2. 文件下载

(下载目录中的Angle文件,已开源)

  • Windows版:

  • Linux版(支持arm):可参照示例使用或自行编译运行(提取码: gna4

1.3. HandDriver端设置

  • 勾选“数据发送”,即打开数据发送开关。

  • 如需传输IMU数据(仅支持带IMU的手套),点选IMU选项,否则不传输IMU数据。

  • 选择发送帧率,支持120Hz、90Hz、60Hz三种帧率,发送帧率默认为120Hz。

  • 点击目标地址中的“+”图标,填入接收端的IP地址和端口号,方可进行数据发送(本地发送填写127.0.0.1)。

  • 端口号默认为5555,如有修改,请保持与SDK端一致。

  • 设置完成后,点击“应用”按钮进行保存。

1.3.1. HandDriver2.2.2之后

传输格式请选择JSON,使用本SDK时数据内容请选择“欧拉角”,请勿勾选旧插件。

1.3.2. HandDriver2.2.1之前

  • 数据格式欧拉角、四元数、VMC为三选一,三者为互斥选项。使用本SDK时请选择“欧拉角”。

  • 勾选“旧插件”时,按照HandDriver2.1.1之前版本传输角度值,详见这里

2. 坐标系及数据定义

2.1. 坐标系和数据说明

2.1.1. HandDriver2.1.2之后版本

坐标系和数据说明请查看:UDEXREAL HandDriver手部模型关节说明

2.1.2. HandDriver2.1.1之前版本

发送的数据参考右手坐标系标准,如下图所示。

2.2. 数据格式

发送的数据格式如下图所示,包括角色名、标定状态、手指节旋转角度、IMU四元数(当手套带有IMU并勾选IMU发送时才有)、控制器(摇杆按键)等数据。

2.3. 接收的角度说明

关于接收的角度值,可参考HandDriver端数据页,此页数据与SDK接收数据一致:

3. C++ SDK - Windows版

本DLL中编写了一个 GloveSDK 类,用于创建单独的接收线程,接受和解析HandDriver通过数据广播或转发的数据,可以直接获得手指各关节角度数据(不含控制器数据)。

3.1. 数据结构定义

3.1.1. 角色列表

数据结构说明:储存接收的角色数据。

参数说明:GloverData为一个角色的信息。

3.1.2. 手套数据

数据结构说明:储存角色的名字和手数据。

参数说明:handDatas为一个角色的手部数据。

3.1.3. 手数据

数据结构说明:储存角色骨骼数据和手指关节数据。

参数说明:bones为角色的骨骼数据,fingerJoints为角色的手指关节数据。

3.1.4. 骨骼数据

数据结构说明:储存骨骼数据。

参数说明:用于适配UE的数据格式,信息目前没有使用。

3.1.5. 手指关节数据

数据结构说明:储存角色双手指关节数据包括手标定状态。

参数说明:fingerJoint_L为角色左手数据,fingerJoint_R为角色右手数据。

3.2. 数据调用

3.2.1. 获取手套的数据

  1. 获取手套设备信息

获取设备信息示例,获取设备其他信息以此类推。

  1. 获取手套手指节旋转数据

GloveSDK 类中有一个数据格式为 GloveData的数组 gloveDataList ,储存所有的手套,访问时请用下标,例如:glovePtr->gloveDataList[0].handDatas.fingerJoints.fingerJoint_L[6].value (访问了0号设备左手食指第二指节俯仰角数据,其中fingerJoint_L[6]对应的参数在数据格式中查看)。

3.3. 接口函数定义

3.3.1. 初始化

函数说明:根据参数创建一个Socket,若成功则开启一个线程接收数据。

参数说明:udp_ip 为接受数据的IP地址, udp_port为端口号,与发送端HandDriver一样即可。

返回值说明:若成功则返回true,失败返回false。

3.3.2. 关闭线程

函数说明:用于关闭接收线程,清理Socket。

参数说明:

返回值说明:

3.3.3. 注册回调函数

函数说明:用于注册回调函数,在程序解析完json数据后调用。

参数说明:callback 一个类型为GloveCallBack的函数,函数的参数类型可在.h中修改。

返回值说明:无。

3.3.4. 打印所有的数据

函数说明:用于打印一个角色的所有数据,检查数据情况。

参数说明:inputGloveData一个类型为GloveData 的函数,在调用时输入一个GloveData 对象。

返回值说明:无。

3.4. Windows示例Demo及说明

3.4.1. Demo工程说明

HandDriver_x64_Cpp_Angle工程包含HandDriver_x64_Cpp_Angle文件夹和HandDriver_x64_Cpp_Angle.sln文件,其中HandDriver_x64_Cpp_Angle文件夹里包含有库文件,如需单独使用可以在此处复制。Visual Studio 的版本为 vs2019(使用高版本时按照修改即可),c++14。运行 HandDriver_x64_Cpp_Angle.sln,选择 x64 平台,即可运行示例程序。

3.4.2. 代码流程简介

  1. 声明一个函数用于注册回调

  1. 创建一个GloveSDK的实例

  1. 注册回调函数

  1. 创建Socket并检测是否成功,成功则开始接收数据并解析

  1. 开启打印线程,打印glove_sdk的数据

  1. 调用只打印帧数函数

  1. 等待输入 保存程序

  1. 结束,关闭清理socket

4. C++ SDK - Linux版

4.1. 文件目录

Linux Cpp SDK文件夹内包含:include文件夹(包含Json解析所需头文件),lib文件夹(包含libjsoncpp.so, libjsoncpp.so.27 必要Json动态库),UDEServer.h(SDK头文件),UDEServer.cxx(方法实现)main.cxx(运用实例),build.sh(示例build文件),CMakeLists.txt,ReadMe.txt

4.2. 数据结构定义

与前文相同,可点击这里查看。

4.3. 数据调用

需要先引用UDEServer.h的头文件,并完成服务端的初始化。 随后可以获取接收到的角色名列表方法如下:

服务端的默认端口号为5555,可以通过方法获取当前端口号或设置端口:

服务器监听中可以关闭数据接收或是获取当前状态:

根据指定角色名,能够获取所有指关节数据,类型为vector,根据GloveDataHeaders内的索引次序对应取得手指关节名称以及欧拉角数组。同时也可以获取控制器数据,根据ControllerHeaders内的索引次序取得类型为float的数组,对应为控制器参数。

取得的对应条目示例如下:

指关节名称规则为Left/Right(左手/右手)+ Thumb/Index/Middle/Ring/Pinky(拇指/食指/中指/无名指/小指)+ 1/2/3(第一关节/第二关节/第三关节),角度数组顺序为{俯仰角,偏航角,旋转角}。

控制器数据中Joy X和Joy Y对应为摇杆参数,范围是(-1,1)的浮点数,其余所有按钮的参数为了统一也定为浮点数0或1,对应为未触发或触发。

4. 接口函数定义

  • 初始化

函数说明:Socket初始化,包含创建服务器所需声明及调用。

返回值说明:若成功则返回0,失败返回-1。

  • 设置端口号

函数说明:设置服务器监听端口号。

参数说明:int整数型端口号

  • 获取端口号

函数说明:获取服务器监听端口号。

返回值说明:int整数型端口号

  • 开启服务器监听

函数说明:开启服务器监听方法,能在循环中获取参数。

  • 关闭服务器监听

函数说明:关闭服务器监听方法。

  • 获取服务器状态

函数说明:取得当前服务器状态。

返回值说明:ServerStatus枚举参数,0对应 NO_INIT 未初始化,1对应 READY 准备就绪,2对应 IN_LISTENING 正在监听,3对应 END 监听终止。

  • 获取角色名列表

函数说明:取得接收到的所有角色名的字符串列表。

返回值说明:名称字符串数组

  • 获取指关节数据

函数说明:取得指定角色的指关节数据。

参数说明:字符串类型角色名

返回值说明:与GloveDataHeaders中字符索引相同排序的欧拉角数组

  • 获取控制器数据

函数说明:取得指定角色的控制器数据。

参数说明:字符串类型角色名

返回值说明:与ControllerHeaders中字符索引相同排序的float数组

4.5. 范例

main.cxx中提供了一个在主方法内调用SDK接口接收并打印数据的范例,可以通过运行build.sh后生成可执行文件。

  1. 启动终端,进入SDK文件夹根目录,运行如下build命令:

  1. 由此能生成可执行范例ServerSample,在同一目录下,用如下命令运行服务器范例:

随后可以在build文件夹中找到项目的链接库libUDEServer.so。

5. Python SDK - Linux/Win版

该SDK也能在windows中运行。

5.1. 数据结构定义

与前文相同,可点击这里查看。

5.2. 数据调用

获取接收到的角色名列表方法如下:

服务端的默认端口号为5555,可以通过方法获取当前端口号或设置端口:

服务器监听中可以关闭数据接收或是获取当前状态:

根据指定角色名,能够获取所有指关节数据,类型为Vector3Float,根据GloveDataHeaders内的索引次序对应取得手指关节名称以及欧拉角数组。同时也可以获取控制器数据,根据ControllerHeaders内的索引次序取得类型为float的数组,对应为控制器参数。

取得的对应条目示例如下:

指关节名称规则为Left/Right(左手/右手)+ Thumb/Index/Middle/Ring/Pinky(拇指/食指/中指/无名指/小指)+ 1/2/3(第一关节/第二关节/第三关节),角度数组顺序为{俯仰角,偏航角,旋转角}。

控制器数据中Joy X和Joy Y对应为摇杆参数,范围是(-1,1)的浮点数,其余所有按钮的参数为了统一也定为浮点数0或1,对应为未触发或触发。

5.3. 接口函数定义

  • 初始化

函数说明:Socket初始化,包含创建服务器所需声明及调用。

返回值说明:若成功则返回0,失败返回-1。

  • 设置端口号

函数说明:设置服务器监听端口号。

参数说明:int整数型端口号

  • 获取端口号

函数说明:获取服务器监听端口号。

返回值说明:int整数型端口号

  • 开启服务器监听

函数说明:开启服务器监听方法。

  • 关闭服务器监听

函数说明:关闭服务器监听方法。

  • 获取服务器状态

函数说明:获取当前服务器状态。

返回值说明:ServerStatus枚举参数,0对应 NO_INIT 未初始化,1对应 READY 准备就绪,2对应 IN_LISTENING 正在监听,3对应 END 监听终止。

  • 获取角色名列表

函数说明:取得接收到的所有角色名的字符串列表。

返回值说明:名称字符串数组

  • 获取指关节数据

函数说明:取得指定角色的指关节数据。

参数说明:字符串类型角色名

返回值说明:与GloveDataHeaders中字符索引相同排序的欧拉角数组

  • 获取控制器数据

函数说明:取得指定角色的控制器数据。

参数说明:字符串类型角色名

返回值说明:与ControllerHeaders中字符索引相同排序的float数组

5.4. 范例

在.py文件所在目录下打开终端,运行以下命令:

Last updated