4.10 Coordinate Systems

Overview

The CoordinateSystem module manages the robot’s User Frames (UF) and Tool Frames (TF), offering a unified API to add, delete, update, query, and calculate frames.
Via coordinate_system.UF/TF you can maintain the controller’s frame list or quickly solve a new frame from taught points, ensuring a consistent spatial reference when switching tools or debugging multi-station setups.

4.10.1 Get User/Tool Coordinate Summary List

Method Name	coordinate_system.UF/TF.get_coordinate_list() -> tuple[List[Coordinate], StatusCodeEnum]
Description	Get the summary list of user/tool coordinate systems.
Request Parameters	None
Return Value	UserCoordSummaryList: A list of coordinate system summary information. StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

4.10.2 Add a User/Tool Coordinate System

Method Name	coordinate_system.UF/TF.add( coordinate : Coordinate) -> StatusCodeEnum
Description	Add a coordinate system to the current user/tool coordinate set.
Request Parameters	coordinate : Coordinate The coordinate system information to add.
Return Value	StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

4.10.3 Delete a User/Tool Coordinate System from the Current System

Method Name	coordinate_system.UF/TF.delete( index : int) -> StatusCodeEnum
Description	Delete a coordinate system from the current user/tool coordinate set.
Request Parameters	index : int The coordinate system index.
Return Value	StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

4.10.4 Update a User/Tool Coordinate System in the Current System

Method Name	coordinate_system.UF/TF.update( coordinate : Coordinate) -> StatusCodeEnum
Description	Update a coordinate system in the current user/tool coordinate set.
Request Parameters	coordinate : Coordinate The updated coordinate system information.
Return Value	StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

4.10.5 Get a User/Tool Coordinate System from the Current System

Method Name	coordinate_system.UF/TF.get( index : int) -> tuple[Coordinate, StatusCodeEnum]
Description	Get a specified coordinate system from the current user/tool coordinate set.
Request Parameters	index : int The coordinate system index.
Return Value	Coordinate: Coordinate system information. StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

4.10.6 Calculate User/Tool Coordinate Information

Method Name	coordinate_system.UF/TF.calculate(pose: List[Position]) -> tuple[Position, StatusCodeEnum]
Description	Calculate user/tool coordinate information based on the input poses and return the calculated pose.
Request Parameters	pose : List[Position] List of input poses.
Return Value	Position: Calculated pose information. StatusCodeEnum: Result of the function execution.
Compatible robot software version	Collaborative (Copper): v7.5.0.0+ Industrial (Bronze): v7.5.0.0+

Example Code

coordinate_system.py

#!python
"""
Copyright © 2016 Agilebot Robotics Ltd. All rights reserved.
Instruction: 坐标系系统使用示例 / Example of coordinate system usage
"""

from Agilebot import Arm, Coordinate, Position, StatusCodeEnum

# [ZH] 初始化捷勃特机器人
# [EN] Initialize the robot
arm = Arm()

# [ZH] 连接捷勃特机器人
# [EN] Connect to the robot
ret = arm.connect("10.27.1.254")
if ret != StatusCodeEnum.OK:
    print(f"机器人连接失败，错误代码 / Robot connection failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("机器人连接成功 / Robot connected successfully")

# [ZH] 定义位姿数据用于计算工具坐标系
# [EN] Define pose data for calculating tool coordinate system
pose_data = [
    Position(341.6861424047297, -33.70972073115479, 430.1721970894897, 0.001, 6.745, -180.000),
    Position(365.4597874970455, 77.95089759481547, 441.39040857936857, -7.343, 12.620, 138.857),
    Position(410.64702354574865, 10.394172666192766, 468.26089261578807, 18.719, 29.151, 155.585),
    Position(483.2519847999948, 112.71925218513972, 448.39071038067624, 33.947, 69.714, 133.597),
]

# [ZH] 根据位姿数据计算工具坐标系
# [EN] Calculate tool coordinate system based on pose data
pose, ret = arm.coordinate_system.TF.calculate(pose_data)
if ret != StatusCodeEnum.OK:
    print(f"计算工具坐标系失败，错误代码 / Calculate tool coordinate system failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("计算工具坐标系成功 / Calculate tool coordinate system successfully")
print(f"计算得到的位姿 / Calculated pose：X={pose.x}, Y={pose.y}, Z={pose.z}, A={pose.a}, B={pose.b}, C={pose.c}")

# [ZH] 创建工具坐标系对象
# [EN] Create tool coordinate system object
tf = Coordinate(5, "test_tf", "测试工具坐标系", pose)

# [ZH] 删除可能存在的ID为5的坐标系（避免冲突）
# [EN] Delete coordinate system with ID 5 if exists (avoid conflict)
arm.coordinate_system.TF.delete(5)

# [ZH] 添加工具坐标系名字 / Add tool coordinate system
ret = arm.coordinate_system.TF.add(tf)
if ret != StatusCodeEnum.OK:
    print(f"添加工具坐标系失败，错误代码 / Add tool coordinate system failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("添加工具坐标系成功 / Add tool coordinate system successfully")

# [ZH] 获取工具坐标系列表
# [EN] Get tool coordinate system list
tf_list, ret = arm.coordinate_system.TF.get_coordinate_list()
if ret != StatusCodeEnum.OK:
    print(f"获取工具坐标系列表失败，错误代码 / Get tool coordinate system list failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("获取工具坐标系列表成功 / Get tool coordinate system list successfully")
print(f"工具坐标系列表 / Tool coordinate system list: {tf_list}")

# [ZH] 获取指定的工具坐标系
# [EN] Get a specific tool coordinate system
tf, ret = arm.coordinate_system.TF.get(5)
if ret != StatusCodeEnum.OK:
    print(f"获取工具坐标系失败，错误代码 / Get tool coordinate system failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("获取工具坐标系成功 / Get tool coordinate system successfully")
print(f"  TF ID: {tf.id}")
print(f"  TF Name: {tf.name}")
print(f"  TF Comment: {tf.comment}")
print(f"  X: {tf.data.x}, Y: {tf.data.y}, Z: {tf.data.z}")
print(f"  A: {tf.data.a}, B: {tf.data.b}, C: {tf.data.c}")

# [ZH] 更新工具坐标系的名称
# [EN] Update tool coordinate system name
tf.name = "updated_test_tf"
ret = arm.coordinate_system.TF.update(tf)
if ret != StatusCodeEnum.OK:
    print(f"更新工具坐标系失败，错误代码 / Update tool coordinate system failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("更新工具坐标系成功 / Update tool coordinate system successfully")

# [ZH] 删除工具坐标系
# [EN] Delete tool coordinate system
ret = arm.coordinate_system.TF.delete(5)
if ret != StatusCodeEnum.OK:
    print(f"删除工具坐标系失败，错误代码 / Delete tool coordinate system failed, error code: {ret.errmsg}")
    arm.disconnect()
    exit(1)

print("删除工具坐标系成功 / Delete tool coordinate system successfully")

# [ZH] 断开捷勃特机器人连接
# [EN] Disconnect from the robot
arm.disconnect()
print("机器人断开连接成功 / Robot disconnected successfully")

---