全局路点管理接口

1. set_global_position - 新增/设置全局路点

方法： set_global_position(socket_fd: int, pos_name: str, pos_value: VectorDouble)

功能描述： 在机器人（默认编号）的控制系统内核或底层配置文件中，创建或修改一个持久化的全局位置变量（即全局路点）。该点位一旦被成功赋予特定的空间直角坐标或关节角度，不仅保存在当前内存中，还会被控制器持久化保存。后续在编写示教脚本或执行自动化逻辑时，可以直接通过注册的字符串名称（如 "test_point"）来引用或调用该目标路点，无需再重复录入繁琐的坐标数组。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
pos_name：全局路点变量的唯一标识名称，字符串格式（str）。
pos_list：位置坐标数据列表，Python 列表格式（list）。根据底层运动规划，要求传入 7 维双精度浮点数：
- 直角坐标系模式：承载 [X, Y, Z, RX, RY, RZ]，分别对应空间三维毫米位姿、欧拉角弧度。
- 关节坐标系模式：承载 1 ~ 7 轴的各关节目标运行度数。对于标准 6 轴机械臂，第 7 位请传入 0.0 作为物理占位符。

返回值：

int：执行结果
- 0：设置成功。代表命名的全局路点数据已被控制器安全接管并完成持久化文件同步。
- 非 0 整型值：设置失败。代表路点名称包含非法字符、数据维数不满足 7 维要求、或控制器只读文件系统权限受限。
- -1：网络未连接拦截（socket_fd 无效）或运行时未捕获的严重未知异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 坐标名称与 7 维目标位置数据
posName = "test_point"
target_pos = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]

# 2. 创建接收坐标的 vector 并转换数据类型
pos_info = nrc.VectorDouble()
for val in target_pos:
    pos_info.push_back(float(val))

# 3. 调用底层接口设置全局坐标并校验执行结果
ret = nrc.set_global_position(socket_fd, posName, pos_info)

if ret == 0:
    print(f"成功: 全局路点变量 [{posName}] 设置成功 -> 位置: {target_pos}")
    return True
else:
    print(f"错误: 设置全局路点变量 [{posName}] 失败，底层错误码: {ret}")
    return False

2. get_global_position - 查询全局 GP 点位

方法： get_global_position(socket_fd: int, pos_name: str, pos: VectorDouble)

功能描述： 通过已经初始化的机器人控制类对象，从单台机器人的系统内核或底层配置文件中，读取指定名称的全局位置变量的当前坐标数据。读取成功后，会将底层的双精度浮点数容器转换为标准 Python 列表返回。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
pos_name：需要读取的全局路点变量的唯一标识名称（例如 "test_point"），字符串格式（str）。

返回值：

list：坐标数据列表
- 7维浮点数列表：操作成功。返回当前路点的 7 维位姿数据（直角坐标 $[X, Y, Z, RX, RY, RZ, Ext]$ 或 7 轴关节角度）。
- []（空列表）：获取失败。代表网络连接无效、目标路点变量名不存在、或底层通信发生异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 准备需要获取的全局变量名称
posName = "test_point"

# 2. 创建接收坐标的 vector 容器
pos = nrc.VectorDouble()

# 3. 调用底层接口获取全局坐标并校验执行结果
ret = nrc.get_global_position(socket_fd, posName, pos)

if ret == 0:
    print(f"成功: 全局路点变量 [{posName}] 获取成功 -> 位置: {list(pos)}")
    return True
else:
    print(f"错误: 获取全局路点变量 [{posName}] 失败，底层错误码: {ret}")
    return False