4.15 C99 CoordinateSystem Interface

Overview

C99 CoordinateSystem manages user coordinate systems and tool coordinate systems. It supports list queries, detail queries, add, update, delete, and coordinate system pose calculation from teaching points.

Corresponding header:

include/c_arm_coordinate.h

Interface Signatures

`Arm_CoordinateSystem_GetList`

int Arm_CoordinateSystem_GetList(ArmHandle* h, int coordinateSystemType, ArmCoordinateInfo* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Queries the coordinate system list
Request Parameters	`h` : `ArmHandle` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `outArray` : `ArmCoordinateInfo` , output array allocated by the caller `maxCount` : `size_t` , output array capacity, meaning the maximum number of elements the caller can receive `outCount` : `size_t*` , output count pointer. On success, receives the actual count
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes
Notes	The caller allocates the output array. `maxCount` is the capacity, and `outCount` returns the actual count

`Arm_CoordinateSystem_Get`

int Arm_CoordinateSystem_Get(ArmHandle* h, int coordinateSystemType, int32_t id, ArmCoordinate* outCoordinate);

Item	Description
Description	Queries coordinate system details
Request Parameters	`h` : `ArmHandle` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `id` : `int32_t` , coordinate system ID `outCoordinate` : `ArmCoordinate` , output structure pointer for coordinate system details
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes

`Arm_CoordinateSystem_Add`

int Arm_CoordinateSystem_Add(ArmHandle* h, int coordinateSystemType, const ArmCoordinate* coordinate);

Item	Description
Description	Adds a coordinate system
Request Parameters	`h` : `ArmHandle` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `coordinate` : `const ArmCoordinate` , coordinate system detail structure pointer
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes

`Arm_CoordinateSystem_Update`

int Arm_CoordinateSystem_Update(ArmHandle* h, int coordinateSystemType, const ArmCoordinate* coordinate);

Item	Description
Description	Updates a coordinate system
Request Parameters	`h` : `ArmHandle` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `coordinate` : `const ArmCoordinate` , coordinate system detail structure pointer
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes

`Arm_CoordinateSystem_Delete`

int Arm_CoordinateSystem_Delete(ArmHandle* h, int coordinateSystemType, int32_t id);

Item	Description
Description	Deletes a coordinate system
Request Parameters	`h` : `ArmHandle*` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `id` : `int32_t` , coordinate system ID
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes

`Arm_CoordinateSystem_Calculate`

int Arm_CoordinateSystem_Calculate(ArmHandle* h, int coordinateSystemType, const ArmCoordinate* coordinates, size_t count, ArmCoordinatePose* outPose);

Item	Description
Description	Calculates coordinate system pose from teaching points
Request Parameters	`h` : `ArmHandle` , C99 session handle, usually from `Arm_Create()` ; business APIs require connection first `coordinateSystemType` : `int` , coordinate system type, user frame or tool frame `coordinates` : `const ArmCoordinate` , teaching point array used to calculate the coordinate system `count` : `size_t` , number of array elements `outPose` : `ArmCoordinatePose*` , output pose structure pointer
Return Value	STATUS_CODE integer value; `0` means success, other values should be handled as status codes

Types and Rules

`ArmCoordinateSystemType`

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

`ArmCoordinatePose`

Field	Type	Description
`x`	`double`	X-axis position
`y`	`double`	Y-axis position
`z`	`double`	Z-axis position
`a`	`double`	A orientation angle
`b`	`double`	B orientation angle
`c`	`double`	C orientation angle

`ArmCoordinateInfo`

Field	Type	Description
`id`	`int32_t`	Coordinate system ID
`name`	`char[128]`	Coordinate system name
`comment`	`char[256]`	Coordinate system comment
`groupId`	`int32_t`	Group ID

`ArmCoordinate`

Field	Type	Description
`id`	`int32_t`	Coordinate system ID
`name`	`char[128]`	Coordinate system name
`comment`	`char[256]`	Coordinate system comment
`groupId`	`int32_t`	Group ID
`data`	`ArmCoordinatePose`	Coordinate system pose

Prerequisites and Failure Semantics

Scenario	Return
Not connected or invalid handle	`OTHER_ERR`
Invalid coordinate system type	`INVALID_PARAMETER`
`Arm_CoordinateSystem_Calculate()` is missing robot model information	`INVALID_PARAMETER`
Required input or output pointer is null	`INVALID_PARAMETER`
`outArray == NULL` in `Arm_CoordinateSystem_GetList()`	Count-only mode; writes `outCount` on success
Insufficient buffer capacity in `Arm_CoordinateSystem_GetList()`	`BUFFER_TOO_SMALL`

Arm_CoordinateSystem_Calculate() depends on robot model information obtained after connection. Callers must complete Arm_Connect() first and pass the coordinate point array used for calibration.

Cartesian Angle Wrap-Around

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

When comparing whether two poses are close, x / y / z can be compared directly by difference. a / b / c must first be normalized over the 360 degree period to avoid false deviation across the boundary.

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

Minimal Call Example

#include <stdio.h>     // printf for printing coordinate count
#include "c_arm_api.h" // C99 SDK umbrella header

int main(void)
{
    ArmHandle* h = Arm_Create();
    ArmCoordinateInfo infos[8] = {0};
    size_t count = 0U;
    if (h == NULL) {
        return 1;
    }

    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {
        Arm_Destroy(h);
        return 1;
    }

    int ret = Arm_CoordinateSystem_GetList(h, ARM_COORDINATE_SYSTEM_USER_FRAME, infos, 8, &count);
    printf("coordinate_count=%zu\n", count);
    Arm_Disconnect(h);
    Arm_Destroy(h);
    return ret == 0 ? 0 : 1;
}

Scenario Examples

ArmCoordinateInfo infos[8] = {0};
ArmCoordinate coord = {0};
ArmCoordinatePose pose = {0};
size_t coordCount = 0U;
int listRet = Arm_CoordinateSystem_GetList(h, ARM_COORDINATE_SYSTEM_USER_FRAME, infos, 8, &coordCount);
int getRet = Arm_CoordinateSystem_Get(h, ARM_COORDINATE_SYSTEM_USER_FRAME, 1, &coord);
int calcRet = Arm_CoordinateSystem_Calculate(h, ARM_COORDINATE_SYSTEM_USER_FRAME, &coord, 1, &pose);
/* int addRet = Arm_CoordinateSystem_Add(h, ARM_COORDINATE_SYSTEM_USER_FRAME, &coord); */
/* int updateRet = Arm_CoordinateSystem_Update(h, ARM_COORDINATE_SYSTEM_USER_FRAME, &coord); */
/* int deleteRet = Arm_CoordinateSystem_Delete(h, ARM_COORDINATE_SYSTEM_USER_FRAME, 1); */
(void)listRet;
(void)getRet;
(void)calcRet;

Example code:

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

4.15 C99 CoordinateSystem Interface

Overview

Interface Signatures

`Arm_CoordinateSystem_GetList`

`Arm_CoordinateSystem_Get`

`Arm_CoordinateSystem_Add`

`Arm_CoordinateSystem_Update`

`Arm_CoordinateSystem_Delete`

`Arm_CoordinateSystem_Calculate`

Types and Rules

`ArmCoordinateSystemType`

`ArmCoordinatePose`

`ArmCoordinateInfo`

`ArmCoordinate`

Prerequisites and Failure Semantics

Cartesian Angle Wrap-Around

Minimal Call Example

Scenario Examples

4.15 C99 CoordinateSystem Interface ​

Overview ​

Interface Signatures ​

Arm_CoordinateSystem_GetList ​

Arm_CoordinateSystem_Get ​

Arm_CoordinateSystem_Add ​

Arm_CoordinateSystem_Update ​

Arm_CoordinateSystem_Delete ​

Arm_CoordinateSystem_Calculate ​

Types and Rules ​

ArmCoordinateSystemType ​

ArmCoordinatePose ​

ArmCoordinateInfo ​

ArmCoordinate ​

Prerequisites and Failure Semantics ​

Cartesian Angle Wrap-Around ​

Minimal Call Example ​

Scenario Examples ​

4.15 C99 CoordinateSystem Interface

Overview

Interface Signatures

`Arm_CoordinateSystem_GetList`

`Arm_CoordinateSystem_Get`

`Arm_CoordinateSystem_Add`

`Arm_CoordinateSystem_Update`

`Arm_CoordinateSystem_Delete`

`Arm_CoordinateSystem_Calculate`

Types and Rules

`ArmCoordinateSystemType`

`ArmCoordinatePose`

`ArmCoordinateInfo`

`ArmCoordinate`

Prerequisites and Failure Semantics

Cartesian Angle Wrap-Around

Minimal Call Example

Scenario Examples