在RealityKit/ARKit中无法绕Z轴旋转3D元素的技术求助

针对你遇到的眼睑模型（半球体）无法通过代码绕Z轴旋转，但X/Y轴正常、Reality Composer中操作有效的问题，以下是几个核心排查方向：

1. 模型局部坐标系与世界坐标系不匹配 #

很多3D模型在导出或编辑时，局部坐标系的轴指向可能和你预期的世界/父节点坐标系不一致。比如你代码中指定的[0,0,1]是世界Z轴，但模型自身的局部Z轴可能被旋转过，导致该方向的旋转无法直观体现。

• 验证方式：在Reality Composer中选中眼睑模型，开启局部坐标系显示，确认Z轴的指向是否和你代码中预期的旋转方向一致。
• 解决方法：如果局部Z轴指向不符，代码中应使用模型自身局部坐标系的Z轴（可通过robot.topLidL?.transform.localTransform.columns.2获取）来创建旋转四元数，而非直接用[0,0,1]。

2. 父节点的变换干扰 #

如果topLidL是某个父节点的子节点，父节点的非均匀缩放、旋转会扭曲子节点的局部坐标系，导致Z轴旋转效果被抵消或变形。

• 排查点：检查父节点的scale属性，确保三个分量数值相等（无拉伸）；查看父节点的orientation是否存在意外旋转。
• 解决方法：若父节点必须保留非均匀缩放，可尝试将眼睑模型从父节点中独立出来，或使用relativeTransform设置相对于父节点的旋转，而非直接修改orientation。

3. 四元数乘法顺序错误 #

RealityKit中simd_mul的四元数乘法是右乘优先，即先应用右侧的旋转，再叠加左侧的旋转。你当前的代码是先应用Z轴旋转，再叠加X轴旋转，若顺序逻辑错误，可能导致Z轴旋转被X轴旋转覆盖。

• 调整顺序尝试：

  robot.topLidL?.orientation = simd_mul(
      simd_quatf(angle: deg2rad((130 * browLeft) - (60 * browInnerUp)), axis: [0, 0, 1]),
      simd_quatf(angle: deg2rad(-80 + (130 * eyeBlinkLeft)), axis: [1, 0, 0])
  )
  

• 也可尝试使用addRotation方法明确指定局部坐标系旋转：

  // 先重置原有旋转，再添加Z轴旋转（示例）
  robot.topLidL?.orientation = simd_quatf(angle: deg2rad(-80 + (130 * eyeBlinkLeft)), axis: [1, 0, 0])
  robot.topLidL?.addRotation(
      simd_quatf(angle: deg2rad((130 * browLeft) - (60 * browInnerUp)), axis: [0, 0, 1]),
      relativeTo: .local
  )
  

4. 模型的物理约束或锁定设置 #

检查模型是否被添加了物理约束或在Reality Composer中设置了旋转锁定：

• 在Reality Composer中查看模型的物理属性，确认未勾选“锁定Z轴旋转”选项；
• 代码中检查是否为模型添加了PhysicsBody并设置了固定旋转（如mode = .static或allowsRotation = false）。

5. 对象引用与值验证 #

即使你确认了browLeft等数值有效，仍需验证：

• robot.topLidL是否确实指向目标模型实例（可打印robot.topLidL?.name确认）；
• 修改orientation后，打印robot.topLidL?.orientation确认数值是否已更新。

附你提供的代码片段 #

原始组合旋转代码：

robot.topLidL?.orientation = simd_mul(
    simd_quatf(angle: deg2rad(-80 + (130 * eyeBlinkLeft)), axis: [1, 0, 0]), // 眨眼动作正常
    simd_quatf(angle: deg2rad((130 * browLeft) - (60 * browInnerUp)), axis: [0, 0, 1])) // Z轴旋转无反应

单独Z轴旋转测试代码：

robot.topLidL?.orientation = simd_quatf(angle: deg2rad((130 * browLeft) - (60 * browInnerUp)), axis: [0, 0, 1])
// 硬编码测试
robot.topLidL?.orientation = simd_quatf(angle: deg2rad(50), axis: [0, 0, 1])

角度转换函数：

private func deg2rad(_ value: Float) -> Float {
    value * .pi / 180
}

内容的提问来源于stack exchange，提问作者Alan Scarpa