通讯与算法接口

1. set_receive_error_or_warnning_message_callback - 设置错误警告回调

方法： set_receive_error_or_warnning_message_callback(socket_fd: int, callback_func: function)

功能描述： 向控制器常规指令通道注册一个异步监听的回调函数（Callback）。当机械臂在运行或待机过程中触发任意红色的错误报错（Error）或黄色的警告信息（Warning）时，控制器会通过此通道实时异步推送数据，自动触发该回调方法。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
callback_func（底层输出函数指针）：用户自定义的回调函数。该回调函数必须严格具备以下三个底层写入的形参：
- messageType：消息类型，整型（int）。通常用以区分 1（错误）与 2（警告）。
- message：具体的中文/英文错误或警告文本描述，字符串格式（str）。
- messageCode：底层的标准错误代码，整型（int）。

返回值：

bool：执行结果布尔值
- True：回调函数注册成功。
- False：注册失败。句柄无效、底层网络事件循环未就绪、接口返回错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 显式定义接收实时报警的异步处理函数
def my_error_handler(msg_type, msg_text, msg_code):
    prefix = "【实时报警】" if msg_type == 1 else "【实时警告】"
    print(f"{prefix} 代码: {msg_code} | 详情: {msg_text}")

# 2. 调用底层注册接口
# 注意：在实际项目类中，务必先用 self.ref = my_error_handler 锁住内存，此处以极简调用为例
ret = nrc.set_receive_error_or_warnning_message_callback(socket_fd, my_error_handler)

# 3. 校验注册状态
if ret is None or ret == 0:
    print("成功: 回调函数注册成功，系统进入实时异常监控状态。")
else:
    print("错误: 无法注册异常监听回调")

2. get_origin_coord_to_target_coord - 正解算法

方法： get_origin_coord_to_target_coord_robot(socket_fd: int, robot_id: int, origin_coord: int, origin_pos: VectorDouble, target_coord: int, target_pos: VectorDouble)

功能描述： 调用机器人控制器内部的运动学核心矩阵算法，实现跨坐标系的空间坐标转换。该接口纯粹进行数学几何层面的正解（Forward Kinematics）、逆解（Inverse Kinematics）或基座/工具/用户系之间的坐标变换，不会引起机械臂发生真实的物理运动。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
robot_id：机器人编号，整型格式（int）。默认传 1。
origin_coord：源坐标系类型代号，整型格式（int）。
input_vector（底层输入参数）：存放待转换坐标的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。
target_coord：目标坐标系类型代号，整型格式（int）。
- 0：关节坐标系（Joint）。数据表示为各轴的物理旋转角度（°）。
- 1：直角坐标系 / 基座坐标系（Base）。数据表示为[X,Y,Z,RX,RY,RZ]。
- 2：工具坐标系（Tool）。相对于当前工具中心点（TCP）的偏置坐标。
- 3：用户坐标系（User）。相对于自定义工件基准面的相对坐标。
output_vector（底层输出参数）：用于接收转换结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。由方法内部自动创建，并开辟 7 位空间用于承载计算结果。

返回值：

list：空间坐标结果列表
- [float, ...]：计算成功。返回包含 7 位双精度浮点数的标准 Python 列表（通常前 6 位为有效三维空间或角度数据）。
- []（空列表）：计算失败。句柄无效、传入的坐标点处于机械臂运动学死锁奇异点、属于物理不可达的超限位点、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 声明并填充源坐标容器 (例如将一组关节角度进行正解计算)
src_angles = [10.0, 20.0, 0.0, 90.0, 0.0, 0.0]
input_vector = nrc.VectorDouble()
for val in src_angles:
    input_vector.push_back(float(val))
# 补齐 7 位
input_vector.push_back(0.0)

# 2. 初始化输出接收容器并预分配 7 位空间
output_vector = nrc.VectorDouble()
for _ in range(7):
    output_vector.push_back(0.0)

# 3. 调用底层核心转换接口 (从 0:关节系 变换到 1:直角基座系)
ret = nrc.get_origin_coord_to_target_coord_robot(socket_fd, 1, 0, input_vector, 1, output_vector)

# 4. 校验计算状态
if ret == 0:
    result_list = list(output_vector)
    print(f"成功: 正解计算成功！直角 X 坐标为: {result_list[0]} mm")
else:
    print("错误: 空间坐标系转换计算失败，请确认输入的点位是否在机械臂工作范围内")

3. get_quat2rpy - 四元数转欧拉角

方法： get_quat2rpy(socket_fd: int, quat_vector: VectorDouble, rpy_res: VectorDouble)

功能描述： 调用机器人控制器内部的姿态算法核心，将空间运动学中的四元数表达形式快速转换为人类易读、常用于直角坐标系的欧拉角（RPY / 翻滚、俯仰、偏航角）。该接口纯粹进行数学几何层面的姿态解算，不会触发机械臂产生任何物理动作。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
quat_vector（底层输入参数）：存放四元数待转换数据的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。调用前须按顺序添加四位浮点数，分别代表四元数姿态的[w, x, y, z]。
rpy_res（底层输出参数）：用于接收欧拉角转换结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。由方法内部自动创建，并在调用前通过 push_back(0.0) 预先分配 3 位内存缓冲区。解算成功后，输出的 [RX, RY, RZ]（弧度值 rad 格式）将顺序覆写至该容器内。

返回值：

list：欧拉角结果列表
- [float, float, float]：转换成功。返回包含 3 位双精度浮点数的标准 Python 列表，分别对应直角坐标系下的绕 X 轴旋转角度（RX）、绕 Y 轴旋转角度（RY）、绕 Z 轴旋转角度（RZ）。
- []（空列表）：转换失败。句柄无效、传入的四元数不满足归一化条件（非法奇异数学矩阵）、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化四元数输入容器并添加数据 [w, x, y, z]
input_quat = [0.7071, 0.0, 0.7071, 0.0]
quat_vector = nrc.VectorDouble()
for val in input_quat:
    quat_vector.push_back(float(val))

# 2. 初始化欧拉角输出接收容器并开辟 3 位缓冲空间
rpy_res = nrc.VectorDouble()
for _ in range(3):
    rpy_res.push_back(0.0)

# 3. 调用底层变换接口进行纯数学解算
ret = nrc.get_quat2rpy(socket_fd, quat_vector, rpy_res)

# 4. 校验计算状态
if ret == 0:
    euler_angles = list(rpy_res)
    print(f"成功: 四元数转换欧拉角完毕！当前目标 RX 弧度为: {euler_angles[0]} rad")
else:
    print("错误: 四元数解算失败，请确认输入的四元数姿态矩阵合法性")

4. get_rpy2quat - 欧拉角转四元数

方法： get_rpy2quat(socket_fd: int, rpy_vector: VectorDouble, quat_res: VectorDouble)

功能描述： 调用机器人控制器内部的运动学算法，将直角坐标系下人类易读的欧拉角表达形式（RPY / 翻滚、俯仰、偏航角）逆向解算为空间几何学中的四元数表达形式。该接口纯粹进行数学层面的姿态矩阵转换，不会触发机械臂产生任何物理动作。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
rpy_vector（底层输入参数）：存放欧拉角待转换数据的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。调用前须按顺序添加三位浮点数，分别代表直角坐标系下的 [RX, RY, RZ]（弧度值 rad 格式）。
quat_res（底层输出参数）：用于接收四元数转换结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。由方法内部自动创建，并在调用前通过 push_back(0.0) 预先分配 4 位内存缓冲区。解算成功后，输出的 [w, x, y, z] 姿态矩阵数据将顺序覆写至该容器内。

返回值：

list：四元数结果列表
- [float, float, float, float]：转换成功。返回包含 4 位双精度浮点数的标准 Python 列表，对应空间旋转矩阵的 [w, x, y, z]。
- []（空列表）：转换失败。句柄无效、传入的欧拉角数据越界或非法、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化欧拉角输入容器并添加数据 [RX, RY, RZ]
input_rpy = [3.1416, 0.0, 1.5708] # 弧度制
rpy_vector = nrc.VectorDouble()
for val in input_rpy:
    rpy_vector.push_back(float(val))

# 2. 初始化四元数输出接收容器并开辟 4 位缓冲空间
quat_res = nrc.VectorDouble()
for _ in range(4):
    quat_res.push_back(0.0)

# 3. 调用底层变换接口进行纯数学逆向解算
ret = nrc.get_rpy2quat(socket_fd, rpy_vector, quat_res)

# 4. 校验计算状态
if ret == 0:
    quaternion = list(quat_res)
    print(f"成功: 欧拉角转换四元数完毕！目标四元数 w 项为: {quaternion[0]}")
else:
    print("错误: 欧拉角解算失败")

5. get_rpy2r - 欧拉角转旋转矩阵

方法： get_rpy2r(socket_fd: int, rpy_vector: VectorDouble, r_res: VectorDouble)

功能描述： 调用机器人控制器内部的运动学核心解算器，将直角坐标系下的欧拉角表达形式（RPY）转换为工业机器人高级动力学运算中所使用的 3×3 三维空间旋转矩阵。该接口纯粹进行数学层面的坐标姿态矩阵转换，不会触发机械臂产生任何物理动作。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
rpy_vector（底层输入参数）：存放欧拉角待转换数据的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble(3)）。调用前须按顺序写入 [RX, RY, RZ]（弧度值 rad 格式）。
r_res（底层输出参数）：用于接收旋转矩阵结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble(9)）。由方法内部自动创建并开辟 9 位内存缓冲区。解算成功后，输出的 3×3 旋转矩阵各分量将以行主序（Row-Major Order）的方式顺序覆写至该容器内。

返回值：

list：旋转矩阵结果列表
- [r00, r01, r02, r10, r11, r12, r20, r21, r22]：转换成功。返回包含 9 位双精度浮点数的标准 Python 列表。
- []（空列表）：转换失败。句柄无效、输入姿态参数异常、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化欧拉角输入容器并分配 3 位空间 [RX, RY, RZ]
rpy_vector = nrc.VectorDouble(3)
rpy_vector[0] = 3.1416  # RX (rad)
rpy_vector[1] = 0.0     # RY (rad)
rpy_vector[2] = 1.5708  # RZ (rad)

# 2. 初始化旋转矩阵输出接收容器并开辟 9 位缓冲空间
r_res = nrc.VectorDouble(9)

# 3. 调用底层变换接口进行纯数学姿态解算
ret = nrc.get_rpy2r(socket_fd, rpy_vector, r_res)

# 4. 校验计算状态并转换为标准 Python 列表
if ret == 0:
    matrix_elements = list(r_res)
    print("成功: 欧拉角转换旋转矩阵完毕！")
    print(f"矩阵第一行分量为: [{matrix_elements[0]}, {matrix_elements[1]}, {matrix_elements[2]}]")
else:
    print("错误: 欧拉角解算旋转矩阵失败")

6. get_tr2r - 位姿转旋转矩阵

方法： get_tr2r(socket_fd: int, tr_vector: VectorDouble, r_res: VectorDouble)

功能描述： 调用机器人控制器内部的矩阵运算核心，从一个完整的 4×4 齐次空间位姿矩阵中，剥离并提取出专门描述工具末端姿态的 3×3 空间旋转矩阵。该接口纯粹进行数学几何层面的矩阵数据裁剪，不会触发机械臂产生任何物理动作。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
tr_vector（底层输入参数）：存放 4×4 位姿矩阵待转换数据的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。调用前须按行主序（Row-Major）顺序填入 16 位浮点数分量。
r_res（底层输出参数）：用于接收提取结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。由方法内部自动创建，并在调用前通过 push_back(0.0) 预先分配 9 位内存缓冲区。剥离成功后，输出的 3×3 旋转矩阵各分量将顺序覆写至该容器内。

返回值：

list：旋转矩阵分量列表
- [r00, r01, r02, r10, r11, r12, r20, r21, r22]：转换成功。返回包含 9 位双精度浮点数的标准 Python 列表。
- []（空列表）：转换失败。句柄无效、输入矩阵格式异常、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化一个包含平移信息的 4x4 位姿矩阵容器并按行主序填入 16 位数据
# 此处以单位矩阵并带有 XYZ 平移(100, 200, 300)为例
custom_tr = [
    1.0, 0.0, 0.0, 100.0,
    0.0, 1.0, 0.0, 200.0,
    0.0, 0.0, 1.0, 300.0,
    0.0, 0.0, 0.0, 1.0
]
tr_vector = nrc.VectorDouble()
for val in custom_tr:
    tr_vector.push_back(float(val))

# 2. 初始化旋转矩阵输出接收容器并开辟 9 位缓冲空间
r_res = nrc.VectorDouble()
for _ in range(9):
    r_res.push_back(0.0)

# 3. 调用底层变换接口剥离纯姿态分量
ret = nrc.get_tr2r(socket_fd, tr_vector, r_res)

# 4. 校验计算状态
if ret == 0:
    matrix_elements = list(r_res)
    print(f"成功: 位姿矩阵裁剪完毕！提取出的 3x3 矩阵第一个分量为: {matrix_elements[0]}")
else:
    print("错误: 从位姿矩阵中剥离旋转矩阵失败")

7. get_r2tr - 旋转矩阵转位姿矩阵

方法： get_r2tr(socket_fd: int, r_vector: VectorDouble, tr_res: VectorDouble)

功能描述： 调用机器人控制器内部的矩阵运算核心，将描述工具末端姿态的 3×3 空间旋转矩阵，填充并扩展为一个完整的 4×4 齐次空间位姿矩阵（默认平移分量为零）。该接口纯粹进行数学几何层面的矩阵数据扩展，不会触发机械臂产生任何物理动作。

参数：

socket_fd：已连接的机械臂控制器句柄，整型格式（int）。
r_vector（底层输入参数）：存放 3×3 旋转矩阵待转换数据的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。调用前须按行主序（Row-Major）顺序填入 9 位浮点数分量。
tr_res（底层输出参数）：用于接收扩展结果的 C++ 双精度浮点向量容器（对应 nrc.VectorDouble()）。由方法内部自动创建，并在调用前通过 push_back(0.0) 预先分配 16 位内存缓冲区。扩展成功后，输出的 4×4 位姿矩阵各分量将顺序覆写至该容器内。

返回值：

list：位姿矩阵分量列表
- [16位浮点数]：转换成功。返回包含 16 位双精度浮点数的标准 Python 列表（4×4 齐次矩阵，按行主序排列）。
- []（空列表）：转换失败。句柄无效、输入矩阵格式异常、接口返回非 0 错误码或触发通信异常。

使用示例：

Python

import nrc_interface as nrc

# 1. 实例化 3x3 旋转矩阵输入容器并按行主序填入 9 位数据
# 此处以单位旋转矩阵为例
custom_r = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
r_vector = nrc.VectorDouble()
for val in custom_r:
    r_vector.push_back(float(val))

# 2. 初始化位姿矩阵输出接收容器并开辟 16 位缓冲空间
tr_res = nrc.VectorDouble()
for _ in range(16):
    tr_res.push_back(0.0)

# 3. 调用底层变换接口扩展为 4x4 位姿矩阵
ret = nrc.get_r2tr(socket_fd, r_vector, tr_res)

# 4. 校验计算状态
if ret == 0:
    matrix_elements = list(tr_res)
    print(f"成功: 旋转矩阵扩展完毕！4x4 位姿矩阵左上角元素为: {matrix_elements[0]}")
else:
    print("错误: 旋转矩阵扩展位姿矩阵失败")