坐标系与用户坐标管理接口

头文件：include/tl_interface.h
相关示例代码：examples\cpp\ex_coord_transform.cpp

1. set_user_coordinate_data - 设置用户坐标

方法：Result set_user_coordinate_data(SOCKETFD socketFd, int userNum, const UserCoordParam& param);

功能描述：设置（标定）用户坐标系参数。推荐使用 UserCoordParam 结构体重载版本（含类型/联动信息），旧版 vector<double> 参数已废弃。

参数：

socketFd：已连接的句柄。
userNum：用户坐标编号。
param：用户坐标参数结构体，可设置以下成员：
- location_type：用户坐标类型，0：静态 1：联动 2：动态
- name：用户坐标名称
- position[6]：用户坐标参数 [X, Y, Z, A, B, C]
- related_type：联动对象类型，0：机器人 1：外部轴
- related_num：联动对象编号
- related_coord_type：联动坐标类型，0：直角 1：工具 2：用户
- related_coord_num：联动坐标编号

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置用户坐标系（编号 1，与基坐标重合）
    int userNum = 1;
    tl::UserCoordParam user_coord;
    user_coord.location_type = 0;          // 静态
    user_coord.name          = "USER01";
    user_coord.position[0]   = 0.0;        // X (mm)
    user_coord.position[1]   = 0.0;        // Y (mm)
    user_coord.position[2]   = 0.0;        // Z (mm)
    user_coord.position[3]   = 0.0;        // A (rad)
    user_coord.position[4]   = 0.0;        // B (rad)
    user_coord.position[5]   = 0.0;        // C (rad)

    auto ret = tl::set_user_coordinate_data(socket_fd, userNum, user_coord);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置用户坐标系失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置用户坐标系成功" << std::endl;

2. set_user_coord_number - 设置用户坐标编号

方法：Result set_user_coord_number(SOCKETFD socketFd, int userNum);

功能描述：设置当前使用的用户坐标编号，后续运动将基于该用户坐标系。

参数：

socketFd：已连接的句柄。
userNum：用户坐标编号。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置用户坐标编号为 2
    int userNum = 2;
    auto ret = tl::set_user_coord_number(socket_fd, userNum);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置用户坐标编号失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置用户坐标编号成功" << std::endl;

3. get_user_coord_para - 获取当前使用的用户坐标的参数

方法：Result get_user_coord_para(SOCKETFD socketFd, int userNum, UserCoordParam& param);

功能描述：查询指定编号的用户坐标参数（返回 UserCoordParam 结构体，含类型/联动信息），旧版 vector<double> 输出已废弃。

参数：

socketFd：已连接的句柄。
userNum：用户坐标编号。
param：输出，用户坐标参数结构体（UserCoordParam）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取用户坐标参数（编号 1）
    int userNum = 1;
    tl::UserCoordParam user_para;
    auto ret = tl::get_user_coord_para(socket_fd, userNum, user_para);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取用户坐标参数失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 用户坐标名称: " << user_para.name << std::endl;
    std::cout << "[信息] 用户坐标位置: ["
              << user_para.position[0] << ", "
              << user_para.position[1] << ", "
              << user_para.position[2] << ", "
              << user_para.position[3] << ", "
              << user_para.position[4] << ", "
              << user_para.position[5] << "]" << std::endl;

4. get_user_coord_number - 获取当前使用的用户坐标编号

方法：Result get_user_coord_number(SOCKETFD socketFd, int& userNum);

功能描述：获取当前使用的用户坐标编号。

参数：

socketFd：已连接的句柄。
userNum：输出，当前使用的用户坐标编号。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取当前用户坐标编号
    int userNum = 0;
    auto ret = tl::get_user_coord_number(socket_fd, userNum);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取用户坐标编号失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 当前用户坐标编号: " << userNum << std::endl;

5. get_current_coord - 获取当前工作坐标系

方法：Result get_current_coord(SOCKETFD socketFd, Coord& coord);

功能描述：获取机器人当前工作坐标系（推荐使用 Coord 枚举重载版本，int 输出旧版已废弃）。

参数：

socketFd：已连接的句柄。
coord：输出，当前工作坐标系，Coord 枚举（JOINT / BASE / TOOL / USER）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取当前工作坐标系
    tl::Coord coord;
    auto ret = tl::get_current_coord(socket_fd, coord);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取当前工作坐标系失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 当前坐标系编号: " << static_cast<int>(coord) << std::endl;

6. set_current_coord - 切换示教运动坐标系

方法：Result set_current_coord(SOCKETFD socketFd, Coord coord);

功能描述：切换示教运动坐标系（推荐使用 Coord 枚举重载版本，int 旧版已废弃）。

参数：

socketFd：已连接的句柄。
coord：目标坐标系，Coord 枚举（JOINT / BASE / TOOL / USER）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 切换当前工作坐标系为基坐标系
    auto ret = tl::set_current_coord(socket_fd, tl::Coord::BASE);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置当前工作坐标系失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置当前工作坐标系成功" << std::endl;

7. calibration_oxy - 三点法自动设置用户坐标系

方法：Result calibration_oxy(SOCKETFD socketFd, int userNum, std::string xyo);

功能描述：三点法用户坐标系标定。依次手动移动机械臂到原点 O、X 方向点、Y 方向点，分别调用本接口标定，最后用 calculate_user_coordinate 计算用户坐标。

参数：

socketFd：已连接的句柄。
userNum：用户坐标编号。
xyo：标定类型，取值 'X' / 'Y' / 'O'。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 三点法标定（需先手动移动机械臂到对应位置）
    // 步骤1: 移动到原点 O，标定 O
    auto ret = tl::calibration_oxy(socket_fd, 1, "O");
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 标定原点 O 失败，错误码: " << ret << std::endl;
        return -1;
    }

    // 步骤2: 移动到 X 方向点，标定 X
    ret = tl::calibration_oxy(socket_fd, 1, "X");
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 标定 X 方向点失败，错误码: " << ret << std::endl;
        return -1;
    }

    // 步骤3: 移动到 Y 方向点，标定 Y
    ret = tl::calibration_oxy(socket_fd, 1, "Y");
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 标定 Y 方向点失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 三点标定完成，下一步请调用 calculate_user_coordinate 计算坐标" << std::endl;

8. calculate_user_coordinate - 计算用户坐标

方法：Result calculate_user_coordinate(SOCKETFD socketFd, int userNumber);

功能描述：根据三点法标定的 O / X / Y 数据计算用户坐标系（需先完成 calibration_oxy 标定）。

参数：

socketFd：已连接的句柄。
userNumber：用户坐标编号。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 计算用户坐标（三点法标定完成后调用）
    auto ret = tl::calculate_user_coordinate(socket_fd, 1);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 计算用户坐标失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 用户坐标计算成功" << std::endl;

9. get_target_coord_pos_value - 获取目标坐标位置值

方法：Result get_target_coord_pos_value(SOCKETFD socketFd, std::string name, Coord targetCoord, std::vector<double>& targetPos);

功能描述：获取指定点位在目标坐标系下的位置值（推荐使用 Coord 枚举重载版本，int 旧版已废弃）。

参数：

socketFd：已连接的句柄。
name：点位名（P 点、GP 点、E 点、GE 点），如 "GP0001"。
targetCoord：目标坐标系，Coord 枚举（JOINT / BASE / TOOL / USER）。
targetPos：输出，转换后的位置，14 位点位（坐标系, 角度/弧度, 形态/左右手, 工具号, 用户坐标号, 预留, 预留, 1~7 轴）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取全局点位 GP0001 在基坐标系下的位置值
    std::vector<double> target_pos;
    auto ret = tl::get_target_coord_pos_value(socket_fd, "GP0001", tl::Coord::BASE, target_pos);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取目标坐标位置值失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] GP0001 在基坐标系下的位置（共 " << target_pos.size() << " 位）:" << std::endl;
    for (size_t i = 0; i < target_pos.size(); ++i) {
        std::cout << "  [" << i << "] " << target_pos[i] << std::endl;
    }

10. get_local_pos_p_value - 获取本地位置变量 P 值

方法：Result get_local_pos_p_value(SOCKETFD socketFd, std::string name, std::vector<double>& pos);

功能描述：获取本地位置变量 P 点的位置值。

参数：

socketFd：已连接的句柄。
name：点位名，范围 P0001 - P9999。
pos：输出，转换后的位置，14 位点位（坐标系, 角度/弧度, 形态/左右手, 工具号, 用户坐标号, 预留, 预留, 1~7 轴）。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 获取本地位置变量 P0001 的值
    std::vector<double> pos;
    auto ret = tl::get_local_pos_p_value(socket_fd, "P0001", pos);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 获取本地位置变量 P 值失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] P0001 的位置（共 " << pos.size() << " 位）:" << std::endl;
    for (size_t i = 0; i < pos.size(); ++i) {
        std::cout << "  [" << i << "] " << pos[i] << std::endl;
    }

11. set_default_cartesian_params - 设置笛卡尔参数为默认值

方法：Result set_default_cartesian_params(SOCKETFD socketFd);

功能描述：将机械臂末端（笛卡尔）相关参数恢复为默认值。

参数：

socketFd：已连接的句柄。

返回值：

0：成功。
非0：失败。

使用示例：

C++

    // 设置机械臂末端参数为默认值
    auto ret = tl::set_default_cartesian_params(socket_fd);
    if (ret != tl::Result::SUCCESS) {
        std::cerr << "[ERROR] 设置笛卡尔参数为默认值失败，错误码: " << ret << std::endl;
        return -1;
    }
    std::cout << "[信息] 设置笛卡尔参数为默认值成功" << std::endl;