3.15 CoordinateSystemManager Management

Overview

Arm::coordinateSystem manages user coordinate systems and tool coordinate systems. Its public capabilities include:

Querying the coordinate system list
Querying details for one coordinate system
Adding, updating, and deleting coordinate systems
Calculating a coordinate system pose

Public Methods

cpp

GetCoordinateList(coordinate::COORDINATE_SYS_TYPE coordinateSysType) -> std::pair<std::vector<coordinate::CoordinateInfo>, STATUS_CODE>
Get(coordinate::COORDINATE_SYS_TYPE coordinateSysType, int32_t id) -> std::pair<coordinate::Coordinate, STATUS_CODE>
Add(coordinate::COORDINATE_SYS_TYPE coordinateSysType, coordinate::Coordinate coordinate) -> STATUS_CODE
Update(coordinate::COORDINATE_SYS_TYPE coordinateSysType, coordinate::Coordinate coordinate) -> STATUS_CODE
Delete(coordinate::COORDINATE_SYS_TYPE coordinateSysType, int32_t id) -> STATUS_CODE
Calculate(coordinate::COORDINATE_SYS_TYPE coordinateSysType, std::vector<coordinate::Coordinate> coordinate) -> std::pair<CartesianPosition, STATUS_CODE>

Method	Input	Output	Description
`GetCoordinateList`	Coordinate system type	`std::pair<std::vector<coordinate::CoordinateInfo>, STATUS_CODE>`	Gets the list
`Get`	Coordinate system type, ID	`std::pair<coordinate::Coordinate, STATUS_CODE>`	Gets details
`Add`	Coordinate system type, coordinate object	`STATUS_CODE`	Adds a coordinate system
`Update`	Coordinate system type, coordinate object	`STATUS_CODE`	Updates a coordinate system
`Delete`	Coordinate system type, ID	`STATUS_CODE`	Deletes a coordinate system
`Calculate`	Coordinate system type, calibration point list	`std::pair<CartesianPosition, STATUS_CODE>`	Calculates the coordinate system pose

Type Scope

`coordinate_system_model::COORDINATE_SYS_TYPE`

Header: include/coordinate_sys_type.h

coordinate::COORDINATE_SYS_TYPE tells the coordinate system APIs whether the current operation targets a user coordinate system or a tool coordinate system. All Get / Add / Update / Delete / Calculate APIs require it.

Enum	Value	Description
`USER_FRAME`	`0`	User coordinate system, used for workpieces, stations, and other user-defined frames
`TOOL_FRAME`	`1`	Tool coordinate system, used for the TCP frame of the end effector

`coordinate_system_model::CoordinateInfo`

Field	Type	Description
`id`	`int32_t`	Coordinate system ID
`name`	`std::string`	Coordinate system name
`comment`	`std::string`	Comment
`groupId`	`int32_t`	Group ID, default `1`

`coordinate_system_model::Coordinate`

Field	Type	Description
`id`	`int32_t`	Coordinate system ID
`name`	`std::string`	Coordinate system name
`comment`	`std::string`	Comment
`groupId`	`int32_t`	Group ID, default `1`
`data`	`CartesianPosition`	Coordinate system pose, expressed as `x/y/z/a/b/c`

Prerequisites

Arm::Connect() must complete first.
Calculate() depends on robot model information filled after connection; it fails if connection is not complete or the model is unavailable.
Coordinate system requests on the same Arm session are still executed serially on the shared network thread.

Failure Semantics

Scenario	Return
Not connected, or the interface module is not initialized	`OTHER_ERR`
Invalid coordinate system type	`INVALID_PARAMETER`
`Calculate` is missing model information	`INVALID_PARAMETER`

Note: Cartesian Angle Wrap-Around

In the CartesianPosition returned by Calculate() , orientation components a / b / c (Euler angles) are in the range [-180°, 180°]. The same physical orientation may be represented as either -180° or 180°; the two are equivalent.

When comparing whether two poses are "close", position components ( x / y / z ) can be compared directly with absolute differences, but orientation components must first be normalized around the 360° period. Otherwise, a false 360° deviation can appear.

Recommended comparison:

cpp

double posDiff = std::abs(pose1.x - pose2.x);
double angleDiff = std::fmod(std::abs(pose1.a - pose2.a), 360.0);
if (angleDiff > 180.0) {
    angleDiff = 360.0 - angleDiff;
}

This rule applies to every API that returns a Cartesian pose, including the MotionControl , TrajectoryManager , and CoordinateSystemManager modules.

Scenario Examples

The snippets below cover query, calculation, add/update, and delete operations. They assume that the arm object is already connected. Add, update, and delete operations change controller coordinate system configuration; run them only after confirming the target.

Query Coordinate System List and Details

cpp

auto [userList, listRet] = arm.coordinateSystemManagerSystem.GetCoordinateList(
    coordinate::COORDINATE_SYS_TYPE::USER_FRAME
);
auto [userCoord, getRet] = arm.coordinateSystemManagerSystem.Get(
    coordinate::COORDINATE_SYS_TYPE::USER_FRAME,
    1
);
if (listRet == STATUS_CODE::OK || getRet == STATUS_CODE::OK) {
    std::cout << "coordinate_count=" << userList.size() << " name=" << userCoord.name << "\n";
}

Calculate Coordinate System Pose

cpp

coordinate::Coordinate point;
point.data = CartesianPosition{0, 0, 0, 0, 0, 0};
std::vector<coordinate::Coordinate> samplePoints = {point, point, point};
auto [calculatedPose, calculateRet] = arm.coordinateSystemManagerSystem.Calculate(
    coordinate::COORDINATE_SYS_TYPE::USER_FRAME,
    samplePoints
);

Add and Update a Coordinate System

cpp

coordinate::Coordinate coord;
coord.id = 1;
coord.name = "sdk_user_frame";
coord.comment = "created by sdk example";
coord.groupId = 1;
coord.data = CartesianPosition{0, 0, 0, 0, 0, 0};
// STATUS_CODE addRet = arm.coordinateSystemManagerSystem.Add(coordinate::COORDINATE_SYS_TYPE::USER_FRAME, coord);
coord.comment = "updated by sdk example";
// STATUS_CODE updateRet = arm.coordinateSystemManagerSystem.Update(coordinate::COORDINATE_SYS_TYPE::USER_FRAME, coord);

Delete a Coordinate System

cpp

// STATUS_CODE deleteRet = arm.coordinateSystemManagerSystem.Delete(coordinate::COORDINATE_SYS_TYPE::USER_FRAME, 1);

Examples

cpp17/coordinate_system_basic/src/main.cpp

cpp

#include "query_coordinate_systems/run.h"
#include "calculate_user_frame/run.h"
#include "write_coordinate_systems/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunCoordinateSystemBasicQueryCoordinateSystems();
    // return RunCoordinateSystemBasicCalculateUserFrame();
    // return RunCoordinateSystemBasicWriteCoordinateSystems();
}

c99/coordinate_system_basic/src/main.cpp

cpp

#include <stdio.h>
#include <string.h>

extern "C" {
#include "c_arm_api.h"
}

int main(void)
{
    // [ZH] 本示例直接在源码中写死连接地址，不解析命令行参数。
    // [EN] This example hard-codes the connection addresses in the source code and does not parse command-line arguments.
    // [ZH] 创建并连接 SDK 句柄。
    // [EN] Create the SDK handle and connect to the robot.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_coordinate] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_coordinate] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_coordinate] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 读取工具坐标系列表与第一个坐标系详情。
    // [EN] Read the tool-frame list and the first frame detail.
    ArmCoordinateInfo infoList[8] = {0};
    size_t infoCount = 0U;
    ret = Arm_CoordinateSystem_GetList(handle, ARM_COORDINATE_SYSTEM_TOOL_FRAME, infoList, 8U, &infoCount);
    printf("[c99_coordinate] GetList 状态码 / GetList status code: %d, 数量 / Count: %zu\n", ret, infoCount);
    if (infoCount > 0U) {
        ArmCoordinate detail = {0};
        ret = Arm_CoordinateSystem_Get(handle, ARM_COORDINATE_SYSTEM_TOOL_FRAME, infoList[0].id, &detail);
        printf("[c99_coordinate] Get 状态码 / Get status code: %d, id=%d, name=%s\n", ret, detail.id, detail.name);
    }

    // [ZH] 构造 3 点并计算用户坐标系。
    // [EN] Build three points and calculate a user frame.
    ArmCoordinate calculatePoints[3] = {0};
    for (int index = 0; index < 3; ++index) {
        calculatePoints[index].id = index + 1;
        calculatePoints[index].groupId = 1;
        snprintf(calculatePoints[index].name, sizeof(calculatePoints[index].name), "p%d", index + 1);
        snprintf(calculatePoints[index].comment, sizeof(calculatePoints[index].comment), "sdk example");
        calculatePoints[index].data.x = 1.0 + index * 3.0;
        calculatePoints[index].data.y = 2.0 + index * 3.0;
        calculatePoints[index].data.z = 3.0 + index * 3.0;
        calculatePoints[index].data.a = 10.0 + index * 30.0;
        calculatePoints[index].data.b = 20.0 + index * 30.0;
        calculatePoints[index].data.c = 30.0 + index * 30.0;
    }
    ArmCoordinatePose pose = {0};
    ret = Arm_CoordinateSystem_Calculate(handle, ARM_COORDINATE_SYSTEM_USER_FRAME, calculatePoints, 3U, &pose);
    printf("[c99_coordinate] Calculate 状态码 / Calculate status code: %d, 位姿 / Pose: [%.6f, %.6f, %.6f, %.6f, %.6f, %.6f]\n",
        ret,
        pose.x,
        pose.y,
        pose.z,
        pose.a,
        pose.b,
        pose.c);

    // [ZH] 顺序执行新增、更新和删除接口。
    // [EN] Execute the add, update, and delete APIs in sequence.
    ArmCoordinate userFrame = {0};
    userFrame.id = 10;
    userFrame.groupId = 1;
    snprintf(userFrame.name, sizeof(userFrame.name), "user_demo");
    snprintf(userFrame.comment, sizeof(userFrame.comment), "sdk example");
    userFrame.data = pose;
    ret = Arm_CoordinateSystem_Add(handle, ARM_COORDINATE_SYSTEM_USER_FRAME, &userFrame);
    printf("[c99_coordinate] Add 状态码 / Add status code: %d\n", ret);
    ret = Arm_CoordinateSystem_Update(handle, ARM_COORDINATE_SYSTEM_USER_FRAME, &userFrame);
    printf("[c99_coordinate] Update 状态码 / Update status code: %d\n", ret);
    ret = Arm_CoordinateSystem_Delete(handle, ARM_COORDINATE_SYSTEM_USER_FRAME, userFrame.id);
    printf("[c99_coordinate] Delete 状态码 / Delete status code: %d\n", ret);

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_coordinate] 示例结束 / Example finished\n");
    return 0;
}

1 Overview and Setup

2 Data Structures

3 Methods

4 C99 API

6 Other Language Integration

3.15 CoordinateSystemManager Management

Overview

Public Methods

Type Scope

`coordinate_system_model::COORDINATE_SYS_TYPE`

`coordinate_system_model::CoordinateInfo`

`coordinate_system_model::Coordinate`

Prerequisites

Failure Semantics

Note: Cartesian Angle Wrap-Around

Scenario Examples

Query Coordinate System List and Details

Calculate Coordinate System Pose

Add and Update a Coordinate System

Delete a Coordinate System

Examples

3.15 CoordinateSystemManager Management ​

Overview ​

Public Methods ​

Type Scope ​

coordinate_system_model::COORDINATE_SYS_TYPE ​

coordinate_system_model::CoordinateInfo ​

coordinate_system_model::Coordinate ​

Prerequisites ​

Failure Semantics ​

Note: Cartesian Angle Wrap-Around ​

Scenario Examples ​

Query Coordinate System List and Details ​

Calculate Coordinate System Pose ​

Add and Update a Coordinate System ​

Delete a Coordinate System ​

Examples ​

3.15 CoordinateSystemManager Management

Overview

Public Methods

Type Scope

`coordinate_system_model::COORDINATE_SYS_TYPE`

`coordinate_system_model::CoordinateInfo`

`coordinate_system_model::Coordinate`

Prerequisites

Failure Semantics

Note: Cartesian Angle Wrap-Around

Scenario Examples

Query Coordinate System List and Details

Calculate Coordinate System Pose

Add and Update a Coordinate System

Delete a Coordinate System

Examples