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接收数据一致:
正负一致
具体数值在HandDriver中显示时以整数表达
详细说明请查看这里:UDEXREAL HandDriver手部模型关节说明

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. 获取手套的数据
获取手套设备信息
获取设备信息示例,获取设备其他信息以此类推。
获取手套手指节旋转数据
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. 代码流程简介
声明一个函数用于注册回调
创建一个GloveSDK的实例
注册回调函数
创建Socket并检测是否成功,成功则开始接收数据并解析
开启打印线程,打印glove_sdk的数据
调用只打印帧数函数
等待输入 保存程序
结束,关闭清理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后生成可执行文件。
启动终端,进入SDK文件夹根目录,运行如下build命令:
由此能生成可执行范例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