状态读取与触觉图像
了解如何在 ApexHand 中读取关节、电机状态和触觉传感图像。
本节介绍 ApexHand SDK 中与状态感知相关的接口，包括：
- 关节状态：
get_joint_states、关节状态回调 - 电机状态：
get_motor_states、电机状态回调 - 触觉图像：
get_hand_sensor_image、传感图像回调 - 相关数据结构：
HandSensorImage及其子结构
关节状态 JointStates
一次性读取
read_joint_states.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# 省略 connect() ...
states = bot.get_joint_states()
print("timestamp:", states.timestamp)
for js in states.joint_states:
print(js.joint_id, js.position, js.velocity, js.acceleration)
- 返回类型：
JointStates - 成员：
timestamp：时间戳joint_states: List[JointState]
持续回调
joint_states_callback.py
from dexcelbot_apexhand_sdk import DexcelBot, JointStates, ErrorCode
bot = DexcelBot()
# 省略 connect() ...
def on_joint_states(states: JointStates):
# 示例：只打印前几个关节
js_list = states.joint_states[:3]
for js in js_list:
print("[Joint]", js.joint_id, "pos =", js.position)
result = bot.register_joint_states_callback(on_joint_states, freq_hz=100)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError("注册关节状态回调失败")
# ... 运行一段时间后取消注册 ...
bot.unregister_joint_states_callback()
freq_hz：回调频率，单位 Hz。- 传入回调的
states与get_joint_states()返回结构一致。
电机状态 MotorStates
一次性读取
read_motor_states.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# 省略 connect() ...
motors = bot.get_motor_states()
print("timestamp:", motors.timestamp)
for ms in motors.motors:
print("[Motor]", ms.motor_id, "T =", ms.temperature, "I =", ms.current)
- 返回类型：
MotorStates - 成员：
timestampmotors: List[MotorState]
持续回调
motor_states_callback.py
from dexcelbot_apexhand_sdk import DexcelBot, MotorStates, ErrorCode
bot = DexcelBot()
# 省略 connect() ...
def on_motor_states(states: MotorStates):
overheat = [m for m in states.motors if m.temperature > 60.0]
if overheat:
print("警告：发现电机过热：", [m.motor_id for m in overheat])
result = bot.register_motor_states_callback(on_motor_states, freq_hz=50)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError("注册电机状态回调失败")
# ... 运行 ...
bot.unregister_motor_states_callback()
通过电机状态回调，可以实现简单的过温/过流监控，并在必要时触发停机或减速逻辑。
触觉传感图像 HandSensorImage
底层 SDK 暴露了一套结构体，表示整个手的触觉图像：
TactileImage：单块触觉图像width、heightgray_image: List[int]tangential_forces: TangentialForce
CommonFingerSensorImage/ThumbFingerSensorImage：- 对应不同手指的多块表面图像（如
pip_image、dip_image、tip_image等）
- 对应不同手指的多块表面图像（如
HandSensorImage：timestampindex_image、middle_image、ring_image、pinky_imagethumb_imagepalm_image
一次性读取
read_tactile.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# 省略 connect() ...
img = bot.get_hand_sensor_image()
print("timestamp:", img.timestamp)
print("Index PIP image size:", img.index_image.pip_image.width, "x", img.index_image.pip_image.height)
print("Palm image size:", img.palm_image.width, "x", img.palm_image.height)
你可以将
gray_image转换为 NumPy 数组，再使用 Matplotlib 或 OpenCV 进行可视化或处理。
持续回调
tactile_callback.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
# 省略 connect() ...
def on_hand_image(img):
# 示例：输出拇指指尖的平均灰度
tip = img.thumb_image.tip_image
if tip.width * tip.height == 0:
return
avg_gray = sum(tip.gray_image) / (tip.width * tip.height)
print("Thumb tip avg gray:", avg_gray)
result = bot.register_hand_sensor_image_callback(on_hand_image, freq_hz=30)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError("注册手传感图像回调失败")
# ... 一段时间后 ...
bot.unregister_hand_sensor_image_callback()
典型监控任务组合
在实际任务中，你可以组合使用多种回调实现「感知 + 控制」闭环，例如：
- 使用 关节状态回调 做轨迹跟踪误差统计。
- 使用 电机状态回调 做实时过温报警。
- 使用 触觉图像回调 做接触检测或抓取质量评估。
monitor_all.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
JointStates,
MotorStates,
ErrorCode,
)
bot = DexcelBot()
# 省略 connect() ...
def on_joint_states(states: JointStates):
# 只示意：输出少量信息
if states.joint_states:
js = states.joint_states[0]
print("[Joint]", js.joint_id, "pos =", js.position)
def on_motor_states(states: MotorStates):
for m in states.motors:
if m.temperature > 65.0:
print("!!! Motor overheat:", m.motor_id, m.temperature)
def on_hand_image(img):
# 简单接触检测示例：判断手掌区域灰度是否有显著变化
palm = img.palm_image
if palm.width * palm.height == 0:
return
avg_gray = sum(palm.gray_image) / (palm.width * palm.height)
if avg_gray > 10: # 阈值示意
print("Palm contact detected, avg gray =", avg_gray)
bot.register_joint_states_callback(on_joint_states, freq_hz=100)
bot.register_motor_states_callback(on_motor_states, freq_hz=20)
bot.register_hand_sensor_image_callback(on_hand_image, freq_hz=15)
# ... 运行任务 ...
bot.unregister_joint_states_callback()
bot.unregister_motor_states_callback()
bot.unregister_hand_sensor_image_callback()
通过本节内容，你可以在任务执行中完整地感知 ApexHand 的运动状态和触觉信息。下一节将介绍 错误处理与事件回调，包括硬件错误码检测与 register_hardware_error_event_callback 的使用方式。