GDK Data Types Documentation (Python)

Overview

GDK (Genie Development Kit) provides a rich set of data types for handling various kinds of data in the robot system. Through the Python interface, developers can conveniently use these data types for robot control, sensor data processing, map management, and other functionality.

Enum Types

1. GDKRes

GDK operation result status code.

Enum value	Description
kSuccess	Operation succeeded
kInvalidInput	Invalid input parameter
kInvalidOutput	Invalid output parameter
kRuntimeError	Runtime error
kUnknown	Unknown error

Example:

import agibot_gdk

result = agibot_gdk.gdk_init()
if result == agibot_gdk.GDKRes.kSuccess:
    print("GDK initialized successfully")
else:
    print(f"GDK initialization failed, error code: {result}")

2. CameraType

Camera type enum.

Enum value	Description
kCameraUnknown	Unknown camera
kHeadBackFisheye	Head rear fisheye camera
kHeadLeftFisheye	Head left fisheye camera
kHeadRightFisheye	Head right fisheye camera
kHeadStereoLeft	Head stereo left camera
kHeadStereoRight	Head stereo right camera
kHandLeftColor	Left hand camera
kHandRightColor	Right hand camera
kHeadColor	Head color camera
kHeadDepth	Head depth camera

Example:

import agibot_gdk

camera_type = agibot_gdk.CameraType.kHeadStereoLeft
print(f"Camera type: {camera_type}")

3. LidarType

Lidar type enum.

Enum value	Description
kLidarUnknown	Unknown lidar
kLidarFront	Front lidar
kLidarBack	Rear lidar

Example:

import agibot_gdk

lidar_type = agibot_gdk.LidarType.kLidarFront
print(f"Lidar type: {lidar_type}")

4. ImuType

IMU type enum.

Enum value	Description
kImuUnknown	Unknown IMU
kImuFront	Front IMU
kImuBack	Rear IMU
kImuChassis	Chassis IMU

Example:

import agibot_gdk

imu_type = agibot_gdk.ImuType.kImuChassis
print(f"IMU type: {imu_type}")

5. EndEffectorControlGroup

End effector control group enum.

Enum value	Description
kUnknown	Unknown group
kLeftArm	Left arm
kRightArm	Right arm
kBothArms	Both arms
kLeftArmWaistLift	Left arm + waist + lift
kRightArmWaistLift	Right arm + waist + lift
kBothArmsWaistLift	Both arms + waist + lift
kLeftArmWaistPitch	Left arm + waist pitch
kRightArmWaistPitch	Right arm + waist pitch
kBothArmsWaistPitch	Both arms + waist pitch
kLeftArmWaist	Left arm + waist
kRightArmWaist	Right arm + waist
kBothArmsWaist	Both arms + waist

Example:

import agibot_gdk

control_group = agibot_gdk.EndEffectorControlGroup.kBothArms
print(f"Control group: {control_group}")

6. SensorExtrinsicType

Sensor extrinsic type enum.

Enum value	Description
kUnknown	Unknown type
kHeadLeftStereoToHeadRightStereo	Head left stereo camera to right stereo camera
kLeftHandDepthToLeftHandColor	Left hand depth camera to color camera
kRightHandDepthToRightHandColor	Right hand depth camera to color camera
kHeadDepthToHeadColor	Head depth camera to color camera
kHeadLeftStereoToHeadLink3	Head left stereo camera to head link3
kHeadRightStereoToHeadLink3	Head right stereo camera to head link3
kHeadLeftFisheyeToHeadLink3	Head left fisheye camera to head link3
kHeadRightFisheyeToHeadLink3	Head right fisheye camera to head link3
kHeadBackFisheyeToHeadLink3	Head rear fisheye camera to head link3
kChassisFrontLidarToBaseLink	Chassis front lidar to base_link
kChassisBackLidarToBaseLink	Chassis rear lidar to base_link
kChassisBackLidarToChassisFrontLidar	Chassis rear lidar to front lidar
kChassisMid360ImuToChassisMid360Lidar	Chassis Mid360 IMU to lidar
kChassisImuToBaseLink	Chassis IMU to base_link
kLeftHandRGBDToArmLEndLink	Left hand RGBD to left arm end link
kRightHandRGBDToArmREndLink	Right hand RGBD to right arm end link
kHeadRGBDToHeadLink3	Head RGBD to head link3

Example:

import agibot_gdk

sensor_type = agibot_gdk.SensorExtrinsicType.kHeadLeftStereoToHeadRightStereo
print(f"Sensor extrinsic type: {sensor_type}")

Basic Data Types

1. Vector3

3D vector structure.

Attribute	Type	Description	Unit
x	float	X-axis component	meters
y	float	Y-axis component	meters
z	float	Z-axis component	meters

Example:

import agibot_gdk

vector = agibot_gdk.Vector3()
vector.x = 1.0
vector.y = 2.0
vector.z = 3.0
print(f"Vector: {vector}")

2. Quaternion

Quaternion structure.

Attribute	Type	Description	Unit
x	float	Quaternion X component	unitless
y	float	Quaternion Y component	unitless
z	float	Quaternion Z component	unitless
w	float	Quaternion W component	unitless

Example:

import agibot_gdk

quat = agibot_gdk.Quaternion()
quat.x = 0.0
quat.y = 0.0
quat.z = 0.0
quat.w = 1.0
print(f"Quaternion: {quat}")

3. Pose

Pose structure.

Attribute	Type	Description	Unit
position	Vector3	Position	meters
orientation	Quaternion	Orientation	unitless

Example:

import agibot_gdk

pose = agibot_gdk.Pose()
pose.position.x = 1.0
pose.position.y = 2.0
pose.position.z = 3.0
pose.orientation.w = 1.0
print(f"Pose: {pose}")

4. Twist

Velocity structure.

Attribute	Type	Description	Unit
linear	Vector3	Linear velocity	meters/second
angular	Vector3	Angular velocity	radians/second

Example:

import agibot_gdk

twist = agibot_gdk.Twist()
twist.linear.x = 0.5
twist.angular.z = 0.1
print(f"Velocity: {twist}")

5. Wrench

Force/torque structure.

Attribute	Type	Description	Unit
force	Vector3	Force	newtons
torque	Vector3	Torque	newton-meters

Example:

import agibot_gdk

wrench = agibot_gdk.Wrench()
wrench.force.z = 10.0
wrench.torque.z = 5.0
print(f"Force/torque: {wrench}")

Sensor Data Types

1. Image

Image data structure.

Attribute	Type	Description	Unit
width	int	Image width	pixels
height	int	Image height	pixels
timestamp_ns	int	Timestamp	nanoseconds
data	numpy.ndarray	Image data	bytes
encoding	Encoding	Encoding format	enum
color_format	ColorFormat	Color format	enum
bit_depth	int	Bit depth	bits

Example:

import agibot_gdk
import time

# Get image data
camera = agibot_gdk.Camera()
time.sleep(1.0)
image = camera.get_latest_image(agibot_gdk.CameraType.kHeadStereoLeft, 1000.0)

if image is not None:
    print(f"Image size: {image.width} x {image.height}")
    print(f"Timestamp: {image.timestamp_ns}")
    print(f"Data size: {image.data.size} bytes")
    print(f"Encoding format: {image.encoding}")
    print(f"Color format: {image.color_format}")
    print(f"Bit depth: {image.bit_depth}")

2. PointCloud

Point cloud data structure.

Attribute	Type	Description	Unit
width	int	Point cloud width	points
height	int	Point cloud height	points
fields	list[PointField]	Point cloud fields	list
point_step	int	Point step	bytes
row_step	int	Row step	bytes
is_bigendian	bool	Whether big-endian	boolean
is_dense	bool	Whether dense	boolean
data	numpy.ndarray	Point cloud data	bytes
timestamp_ns	int	Timestamp	nanoseconds

Example:

import agibot_gdk
import time

# Get point cloud data
lidar = agibot_gdk.Lidar()
time.sleep(1.0)
pointcloud = lidar.get_latest_pointcloud(agibot_gdk.LidarType.kLidarFront, 1000.0)

if pointcloud is not None:
    print(f"Point cloud size: {pointcloud.width} x {pointcloud.height}")
    print(f"Timestamp: {pointcloud.timestamp_ns}")
    print(f"Data size: {pointcloud.data_size} bytes")
    print(f"Number of fields: {len(pointcloud.fields)}")
    for field in pointcloud.fields:
        print(f"  Field: {field.name}, offset: {field.offset}, type: {field.datatype}")

3. ImuData

IMU data structure.

Attribute	Type	Description	Unit
angular_velocity	Vector3	Angular velocity	radians/second
linear_acceleration	Vector3	Linear acceleration	meters/second²
timestamp_ns	int	Timestamp	nanoseconds

Example:

import agibot_gdk
import time

# Get IMU data
imu = agibot_gdk.Imu()
time.sleep(1.0)
imu_data = imu.get_latest_imu(agibot_gdk.ImuType.kImuChassis, 1000.0)

if imu_data is not None:
    print(f"Angular velocity: ({imu_data.angular_velocity.x}, {imu_data.angular_velocity.y}, {imu_data.angular_velocity.z})")
    print(f"Linear acceleration: ({imu_data.linear_acceleration.x}, {imu_data.linear_acceleration.y}, {imu_data.linear_acceleration.z})")
    print(f"Timestamp: {imu_data.timestamp_ns}")

4. CameraIntrinsic

Camera intrinsic parameter structure.

Attribute	Type	Description	Unit
intrinsic	list[float]	Intrinsics [fx, fy, cx, cy]	pixels
distortion	list[float]	Distortion parameters [k1, k2, p1, p2, k3, k4, k5, k6]	unitless

Example:

import agibot_gdk
import time

# Get camera intrinsics
camera = agibot_gdk.Camera()
time.sleep(1.0)
intrinsic = camera.get_camera_intrinsic(agibot_gdk.CameraType.kHeadStereoLeft)

print(f"Intrinsics:")
print(f"  fx: {intrinsic.intrinsic[0]}")
print(f"  fy: {intrinsic.intrinsic[1]}")
print(f"  cx: {intrinsic.intrinsic[2]}")
print(f"  cy: {intrinsic.intrinsic[3]}")

print(f"Distortion parameters:")
for i, dist in enumerate(intrinsic.distortion):
    print(f"  k{i+1}: {dist}")

Robot Control Data Types

1. JointState

Joint state structure.

Attribute	Type	Description	Unit
name	str	Joint name	string
mode	int	Joint mode	integer
position	float	Joint position	radians
velocity	float	Joint velocity	radians/second
effort	float	Joint torque	newton-meters
motor_position	float	Motor position	radians
motor_velocity	float	Motor velocity	radians/second
motor_current	float	Motor current	amperes
error_code	int	Error code	integer

Example:

import agibot_gdk
import time

# Get joint states
robot = agibot_gdk.Robot()
time.sleep(1.0)
joint_states = robot.get_joint_states()

print(f"Number of joints: {joint_states['nums']}")
for state in joint_states['states']:
    print(f"Joint: {state['name']}")
    print(f"  Position: {state['position']}")
    print(f"  Velocity: {state['velocity']}")
    print(f"  Torque: {state['effort']}")

2. JointControlReq

Joint control request structure.

Attribute	Type	Description	Unit
joint_names	list[str]	List of joint names	string list
joint_positions	list[float]	List of joint positions	radians
joint_velocities	list[float]	List of joint velocities	radians/second
life_time	float	Lifetime	seconds
detail	str	Detailed information	string

Example:

import agibot_gdk
import time

# Create a joint control request
joint_control_req = agibot_gdk.JointControlReq()
joint_control_req.joint_names = ["idx01_body_joint1", "idx02_body_joint2"]
joint_control_req.joint_positions = [0.0, 0.0]
joint_control_req.joint_velocities = [0.1, 0.1]
joint_control_req.life_time = 5.0

# Execute joint control
robot = agibot_gdk.Robot()
time.sleep(1.0)
result = robot.joint_control_request(joint_control_req)
if result == agibot_gdk.GDKRes.kSuccess:
    print("Joint control succeeded")

3. EndEffectorPose

End effector pose control structure.

Attribute	Type	Description	Unit
group	int	Control group	integer
left_end_effector_pose	Pose	Left end effector pose	pose
right_end_effector_pose	Pose	Right end effector pose	pose
life_time	float	Lifetime	seconds

Example:

Note: end_effector_pose_control() requires the action to be interpolated to respond correctly; this example only illustrates the EndEffectorPose data structure

import agibot_gdk
import time

# Create an end effector pose control request
# This request needs to be interpolated together with the current end effector pose; this example is for illustration only
end_pose = agibot_gdk.EndEffectorPose()
end_pose.group = agibot_gdk.EndEffectorControlGroup.kBothArms
end_pose.left_end_effector_pose.position.x = 0.3
end_pose.left_end_effector_pose.position.y = 0.2
end_pose.left_end_effector_pose.position.z = 0.4
end_pose.left_end_effector_pose.orientation.x = 0.0
end_pose.left_end_effector_pose.orientation.y = 0.0
end_pose.left_end_effector_pose.orientation.z = 0.0
end_pose.left_end_effector_pose.orientation.w = 1.0
end_pose.right_end_effector_pose.position.x = 0.3
end_pose.right_end_effector_pose.position.y = 0.3
end_pose.right_end_effector_pose.position.z = -0.2
end_pose.right_end_effector_pose.orientation.x = 0.0
end_pose.right_end_effector_pose.orientation.y = 0.0
end_pose.right_end_effector_pose.orientation.z = 0.0
end_pose.right_end_effector_pose.orientation.w = 1.0
end_pose.life_time = 5.0

# Execute end effector pose control
robot = agibot_gdk.Robot()
time.sleep(1.0)
result = robot.end_effector_pose_control(end_pose)
if result == agibot_gdk.GDKRes.kSuccess:
    print("End effector pose control succeeded")

Map Data Types

1. MapInfo

Map information structure.

Attribute	Type	Description	Unit
id	int	Map ID	integer
name	str	Map name	string
status	int	Map status	integer
counter	int	Map counter	integer
timestamp_ns	int	Timestamp	nanoseconds
gravity	Vector3	Gravity vector	meters/second²
cloud_map	PointCloud	Point cloud map	point cloud
grid_map	OccupancyGrid	Occupancy grid map	grid
walls	list[list[Point3d]]	Walls	point list
infeasible_areas	list[list[Point3d]]	Infeasible areas	point list
guide_pts	list[GuidePtInfo]	Guide points	guide point list

Example:

import agibot_gdk
import time

# Get map information
map_manager = agibot_gdk.Map()
time.sleep(1.0)

# Before getting map information, first complete mapping
try:
    map_info = map_manager.get_map(1)
except Exception as e:
    print(f"Failed to get map information: {e}")
    exit(1)

print(f"Map name: {map_info.name}")
print(f"Map ID: {map_info.id}")
print(f"Map status: {map_info.status}")
print(f"Gravity vector: ({map_info.gravity.x}, {map_info.gravity.y}, {map_info.gravity.z})")
print(f"Number of walls: {len(map_info.walls)}")
print(f"Number of infeasible areas: {len(map_info.infeasible_areas)}")
print(f"Number of guide points: {len(map_info.guide_pts)}")

2. OccupancyGrid

Occupancy grid map structure.

Attribute	Type	Description	Unit
width	int	Map width	grid cells
height	int	Map height	grid cells
resolution	float	Resolution	meters/grid cell
origin	Pose	Origin pose	pose
data	list[int]	Grid data	integer list
timestamp_ns	int	Timestamp	nanoseconds

Example:

import agibot_gdk
import time

# Get the grid map
map_manager = agibot_gdk.Map()
time.sleep(1.0)
map_info = map_manager.get_map(1)
grid_map = map_info.grid_map

print(f"Grid map size: {grid_map.width} x {grid_map.height}")
print(f"Resolution: {grid_map.resolution} meters/grid cell")
print(f"Origin position: ({grid_map.origin.position.x}, {grid_map.origin.position.y}, {grid_map.origin.position.z})")
print(f"Grid data size: {len(grid_map.data)}")

Coordinate Transformation Data Types

1. Transform

Coordinate transformation structure.

Attribute	Type	Description	Unit
translation	Vector3	Translation vector	meters
rotation	Quaternion	Rotation quaternion	unitless

Example:

import agibot_gdk
import time

# Get a coordinate transform
tf = agibot_gdk.TF()
time.sleep(1.0)
transform = tf.get_tf_from_base_link("arm_l_end_link")

print(f"Translation: ({transform.translation.x}, {transform.translation.y}, {transform.translation.z})")
print(f"Rotation: ({transform.rotation.x}, {transform.rotation.y}, {transform.rotation.z}, {transform.rotation.w})")

2. TransformStamped

Coordinate transformation structure with a timestamp.

Attribute	Type	Description	Unit
frame_id	str	Parent coordinate frame ID	string
child_frame_id	str	Child coordinate frame ID	string
transform	Transform	Transformation information	transform
timestamp_ns	int	Timestamp	nanoseconds

Example:

import agibot_gdk
import time

# Get all coordinate transforms
tf = agibot_gdk.TF()
time.sleep(1.0)
transforms = tf.get_all_tf_from_base_link()

for transform_stamped in transforms:
    print(f"Coordinate frames: {transform_stamped.frame_id} -> {transform_stamped.child_frame_id}")
    print(f"  Translation: ({transform_stamped.transform.translation.x}, {transform_stamped.transform.translation.y}, {transform_stamped.transform.translation.z})")
    print(f"  Timestamp: {transform_stamped.timestamp_ns}")

Usage Notes

1. Data validity: Check whether the returned data is None before use
2. Enum value usage: Use enum values instead of integer values to improve code readability
3. Array access: Use Python list syntax to access array elements
4. String encoding: Strings use UTF-8 encoding

Application Scenarios

• Robot control: Using joint states and control requests for robot motion control
• Sensor data processing: Processing image, point cloud, IMU, and other sensor data
• Map management: Using map information for navigation and path planning
• Coordinate transformation: Handling transformation relationships between different coordinate frames
• Status monitoring: Monitoring the working status of the robot's various components
• Data fusion: Fusing multiple types of sensor data for environmental perception
• Path planning: Planning paths based on map data
• Vision processing: Using camera intrinsic parameters for image rectification and 3D reconstruction