Domain Layer - Value Objects

controller.domain.value_objects.dh_param

DHParam dataclass

DHParam()

机械臂 DH 参数配置。

存储运动学和动力学所需的 DH 参数。

属性：

名称	类型	描述
kinematic_dh	array	运动学 DH 参数表。
dynamic_dh	array	动力学 DH 参数表。

初始化默认 DH 参数。

源代码位于： src/controller/controller/domain/value_objects/dh_param.py

def __init__(self):
    """初始化默认 DH 参数。"""
    self.kinematic_dh = np.array([
        [0.0, 0.0, 0.0,  0.0],
        [0.0, -pi/2, 0.0, -pi/2],
        [0.425, pi, 0.0, 0.0],
        [0.401, pi, 0.0856, pi/2],
        [0.0, pi/2, 0.086, 0.0],
        [0.0, -pi/2, 0.231, 0.0]  
    ], dtype=float)

    self.dynamic_dh = np.array([
        [0.0, 0.0, 0.0, 0.0],
        [0.0, -pi/2, 0.0, -pi/2],
        [0.425, pi, 0.0, 0.0],
        [0.401, pi, 0.0856, pi/2],
        [0.0, pi/2, 0.086, 0.0],
        [0.0, -pi/2, 0.0725, 0.0]
    ])

get_kinematic_dh

get_kinematic_dh() -> np.ndarray

获取运动学 DH 参数。

返回：

类型	描述
ndarray	np.ndarray: 运动学 DH 参数矩阵。

源代码位于： src/controller/controller/domain/value_objects/dh_param.py

def get_kinematic_dh(self) -> np.ndarray:
    """获取运动学 DH 参数。

    Returns:
        np.ndarray: 运动学 DH 参数矩阵。
    """
    return self.kinematic_dh

get_dynamic_dh

get_dynamic_dh() -> np.ndarray

获取动力学 DH 参数。

返回：

类型	描述
ndarray	np.ndarray: 动力学 DH 参数矩阵。

源代码位于： src/controller/controller/domain/value_objects/dh_param.py

def get_dynamic_dh(self) -> np.ndarray:
    """获取动力学 DH 参数。

    Returns:
        np.ndarray: 动力学 DH 参数矩阵。
    """
    return self.dynamic_dh

controller.domain.value_objects.hand_eye_calibration_config

手眼标定配置值对象

CameraIntrinsics dataclass

CameraIntrinsics(fx: float, fy: float, cx: float, cy: float)

相机内参。

属性：

名称	类型	描述
fx	float	x 方向焦距。
fy	float	y 方向焦距。
cx	float	光心 x 坐标。
cy	float	光心 y 坐标。

TargetOffset dataclass

TargetOffset(x: float, y: float, z: float)

目标偏移量（米）。

属性：

名称	类型	描述
x	float	x 方向偏移。
y	float	y 方向偏移。
z	float	z 方向偏移。

to_array

to_array() -> np.ndarray

转换为 numpy 数组。

返回：

类型	描述
ndarray	np.ndarray: [x, y, z] 数组。

源代码位于： src/controller/controller/domain/value_objects/hand_eye_calibration_config.py

def to_array(self) -> np.ndarray:
    """转换为 numpy 数组。

    Returns:
        np.ndarray: [x, y, z] 数组。
    """
    return np.array([self.x, self.y, self.z])

EndEffectorAdjustment dataclass

EndEffectorAdjustment(z_rotation: float, y_rotation: float, x_rotation: float)

末端姿态调整（弧度）。

属性：

名称	类型	描述
z_rotation	float	绕 Z 轴旋转角度。
y_rotation	float	绕 Y 轴旋转角度。
x_rotation	float	绕 X 轴旋转角度。

HandEyeCalibrationConfig dataclass

HandEyeCalibrationConfig(hand_eye_matrix: ndarray, camera_intrinsics: CameraIntrinsics, target_offset: TargetOffset, end_effector_adjustment: EndEffectorAdjustment)

手眼标定完整配置。

这是一个值对象（Value Object），不可变且无副作用。

属性：

名称	类型	描述
hand_eye_matrix	ndarray	4x4 齐次变换矩阵。
camera_intrinsics	CameraIntrinsics	相机内参。
target_offset	TargetOffset	目标偏移量。
end_effector_adjustment	EndEffectorAdjustment	末端姿态调整。

__post_init__

__post_init__()

验证数据完整性。

引发：

类型	描述
ValueError	如果手眼标定矩阵形状不是 4x4。

源代码位于： src/controller/controller/domain/value_objects/hand_eye_calibration_config.py

def __post_init__(self):
    """验证数据完整性。

    Raises:
        ValueError: 如果手眼标定矩阵形状不是 4x4。
    """
    if self.hand_eye_matrix.shape != (4, 4):
        raise ValueError("手眼标定矩阵必须是 4x4 矩阵")

controller.domain.value_objects.motion_operation_mode

运动操作模式 - Domain Value Object

MotionOperationMode

Bases: Enum

运动操作模式枚举。

属性：

名称	类型	描述
NONE		无操作（仅获取位置）。
EXECUTE		执行运动。
SAVE		保存轨迹。
PREVIEW		预览轨迹（显示曲线）。

controller.domain.value_objects.robot_state_snapshot

机械臂状态快照 - Domain层值对象 不可变的状态数据载体

RobotStateSnapshot dataclass

RobotStateSnapshot(init_status: int, control: int, mode: int, joint_positions: Tuple[int, ...], joint_angles: Tuple[float, ...], joint_speeds: Tuple[int, ...], joint_torques: Tuple[int, ...], joint_status: Tuple[int, ...], double_encoder_interpolations: Tuple[int, ...], errors: Tuple[int, ...], effector_data: Any, timestamp: float)

机械臂状态快照 - 不可变数据载体。

特点： - frozen=True: 不可变，线程安全 - 包含完整的机械臂状态 - 可以保存历史快照序列

属性：

名称	类型	描述
init_status	int	初始化状态。
control	int	当前命令 0x06/0x07...。
mode	int	运行模式 0x08/0x0A...。
joint_positions	Tuple[int, ...]	编码器位置（原始值，6个关节）。
joint_angles	Tuple[float, ...]	关节角度（弧度，6个关节）。
joint_speeds	Tuple[int, ...]	关节速度。
joint_torques	Tuple[int, ...]	关节力矩。
joint_status	Tuple[int, ...]	关节状态码。
double_encoder_interpolations	Tuple[int, ...]	双编码器插值。
errors	Tuple[int, ...]	错误码。
effector_data	Any	夹爪数据。
timestamp	float	接收时间戳。

from_decoded_message classmethod

from_decoded_message(decoded_msg: Any) -> RobotStateSnapshot

从解码消息创建快照。

参数：

名称	类型	描述	默认
decoded_msg	Any	解码后的消息对象，应包含 positions(弧度), speeds, torques 等字段。	必需

返回：

名称	类型	描述
RobotStateSnapshot	RobotStateSnapshot	创建的状态快照实例。

Note

decoded_msg.positions 已经通过 position2radian 转换为弧度值， 所以 joint_angles 直接使用该值。 joint_positions 会通过反向计算还原为原始编码器值。

源代码位于： src/controller/controller/domain/value_objects/robot_state_snapshot.py

@classmethod
def from_decoded_message(cls, decoded_msg: Any) -> 'RobotStateSnapshot':
    """从解码消息创建快照。

    Args:
        decoded_msg (Any): 解码后的消息对象，应包含 positions(弧度), speeds, torques 等字段。

    Returns:
        RobotStateSnapshot: 创建的状态快照实例。

    Note:
        decoded_msg.positions 已经通过 position2radian 转换为弧度值，
        所以 joint_angles 直接使用该值。
        joint_positions 会通过反向计算还原为原始编码器值。
    """        
    robot_utils = RobotUtils()

    # decoded_msg.positions 已经是弧度值（由MessageDecoder的transform完成）
    # 所以直接使用，不需要再次转换
    angles = decoded_msg.positions  # 已经是弧度值

    # 反向计算原始编码器位置值（用于保存完整状态）
    positions = robot_utils.radian2position(angles)

    return cls(
        init_status=decoded_msg.init_status,
        control=decoded_msg.control,
        mode=decoded_msg.mode,
        joint_positions=tuple(positions),  # 反向计算的编码器值
        joint_angles=tuple(angles),        # 直接使用解码后的弧度值
        joint_speeds=tuple(decoded_msg.speeds),
        joint_torques=tuple(decoded_msg.torques),
        joint_status=tuple(decoded_msg.status),
        double_encoder_interpolations=tuple(decoded_msg.double_encoder_interpolations),
        errors=tuple(decoded_msg.errors),
        effector_data=decoded_msg.effector_data,
        timestamp=time.time()
    )