文章目录前言一、欧拉角的万向锁问题1.1 什么是万向锁1.2 四元数的优势二、单轴旋转四元数构造2.1 绕 Y 轴旋转左右2.2 绕 X 轴旋转上下三、四元数乘法合成双轴旋转3.1 四元数乘法公式3.2 项目中的完整合成实现四、乘法顺序对旋转效果的影响4.1 为什么是 qy * qx 而非 qx * qy4.2 上下角度限制的必要性总结前言在 3D 模型查看器中支持手指上下左右任意方向拖拽旋转模型看似简单背后却涉及三维旋转数学中的一个经典问题——万向锁Gimbal Lock。用欧拉角Euler Angles分别存储 X 轴和 Y 轴旋转量在两轴组合时会产生轴向退化导致某些方向无法旋转。解决这一问题的标准方案是使用**四元数Quaternion**表示旋转并通过四元数乘法合成多轴旋转。本文将从数学原理出发结合项目中的真实代码讲解如何在 HarmonyOS 6 的kit.ArkGraphics3D中实现正确的双轴四元数旋转。运行效果如下一、欧拉角的万向锁问题1.1 什么是万向锁欧拉角用三个角度值Pitch/Yaw/Roll描述旋转当其中一个轴旋转 90° 时另外两个轴的旋转面重合导致丢失一个旋转自由度。在模型查看器场景中当用户将模型仰视/俯视到接近 90° 时左右旋转会变得异常——手指向左滑模型可能向右甚至绕错误的轴旋转。1.2 四元数的优势四元数用四个分量(x, y, z, w)描述旋转其中(x, y, z)为旋转轴分量w为旋转角余弦特性欧拉角四元数存储量3 个浮点数4 个浮点数万向锁存在不存在插值非线性有跳变球面线性插值(SLERP)平滑合成矩阵乘法9 次乘法四元数乘法16 次乘法但数值更稳定ArkGraphics3D 支持不直接支持node.rotation 原生接受四元数核心优势node.rotation直接接受{x, y, z, w}格式的四元数无需额外转换四元数合成结果始终是单位四元数数值精度稳定任意角度组合都能正确旋转不存在奇异点二、单轴旋转四元数构造2.1 绕 Y 轴旋转左右绕单位向量轴(ax, ay, az)旋转角度theta的四元数公式q (ax * sin(theta/2), ay * sin(theta/2), az * sin(theta/2), cos(theta/2))绕 Y 轴ax0, ay1, az0// 绕世界 Y 轴旋转四元数左右consthy:numberthis.angleY/2;constqy_x:number0;constqy_y:numberMath.sin(hy);constqy_z:number0;constqy_w:numberMath.cos(hy);2.2 绕 X 轴旋转上下绕 X 轴ax1, ay0, az0// 绕世界 X 轴旋转四元数上下consthx:numberthis.angleX/2;constqx_x:numberMath.sin(hx);constqx_y:number0;constqx_z:number0;constqx_w:numberMath.cos(hx);提示公式中使用的是半角theta / 2这是四元数旋转的基本性质——绕轴旋转theta角对应半角的三角函数。初学者常犯的错误是直接传入整角导致旋转量翻倍。三、四元数乘法合成双轴旋转3.1 四元数乘法公式两个四元数p (px, py, pz, pw)和q (qx, qy, qz, qw)的乘积r p * qrx pw*qx px*qw py*qz - pz*qy ry pw*qy - px*qz py*qw pz*qx rz pw*qz px*qy - py*qx pz*qw rw pw*qw - px*qx - py*qy - pz*qz3.2 项目中的完整合成实现applyRotation():void{consttarget:Node|nullthis.modelNode??(this.scene?.root??null);if(!target){return;}// 绕世界 Y 轴旋转四元数左右consthy:numberthis.angleY/2;constqy_x:number0;constqy_y:numberMath.sin(hy);constqy_z:number0;constqy_w:numberMath.cos(hy);// 绕世界 X 轴旋转四元数上下consthx:numberthis.angleX/2;constqx_x:numberMath.sin(hx);constqx_y:number0;constqx_z:number0;constqx_w:numberMath.cos(hx);// 合成q qy * qx先 X 后 Y让上下旋转跟随当前朝向target.rotation{x:qy_w*qx_xqy_x*qx_wqy_y*qx_z-qy_z*qx_y,y:qy_w*qx_y-qy_x*qx_zqy_y*qx_wqy_z*qx_x,z:qy_w*qx_zqy_x*qx_y-qy_y*qx_xqy_z*qx_w,w:qy_w*qx_w-qy_x*qx_x-qy_y*qx_y-qy_z*qx_z};}由于qy和qx的很多分量为零代入化简后展开的各分量值为x qy_w * qx_x 0 0 - 0 cos(hy/2) * sin(hx/2) y 0 - 0 qy_y * qx_w 0 sin(hy/2) * cos(hx/2) z 0 0 - 0 0 0 w qy_w * qx_w - 0 - qy_y * qx_y - 0 cos(hy/2)*cos(hx/2) - sin(hy/2)*0 cos(hy/2)*cos(hx/2)这正是标准的 YX 欧拉角到四元数转换公式代码中保留完整乘法展开而非化简是为了代码可读性和通用性若将来需要增加 Z 轴旋转Roll只需添加第三个四元数继续乘法合成无需重构。四、乘法顺序对旋转效果的影响4.1 为什么是 qy * qx 而非 qx * qy四元数乘法不满足交换律qy * qx与qx * qy结果不同合成顺序含义旋转行为qy * qx先在局部坐标系绕 X 旋转再绕世界 Y 旋转上下旋转跟随当前面朝方向符合直觉qx * qy先在局部坐标系绕 Y 旋转再绕世界 X 旋转上下旋转始终绕全局 X 轴侧转时上下方向错位// 合成q qy * qx先 X 后 Y让上下旋转跟随当前朝向target.rotation{x:qy_w*qx_xqy_x*qx_wqy_y*qx_z-qy_z*qx_y,y:qy_w*qx_y-qy_x*qx_zqy_y*qx_wqy_z*qx_x,z:qy_w*qx_zqy_x*qx_y-qy_y*qx_xqy_z*qx_w,w:qy_w*qx_w-qy_x*qx_x-qy_y*qx_y-qy_z*qx_z};选择qy * qx的交互逻辑当模型已经被左右旋转了 90°侧面朝向用户此时手指上下滑动模型应该继续绕自身的上下轴翻转即相对于当前面朝方向的 X 轴而非绕世界空间固定的 X 轴旋转。qy * qx正好实现了这种本地坐标系的旋转感。4.2 上下角度限制的必要性constmaxX:number85*Math.PI/180;if(this.angleXmaxX){this.angleXmaxX;}if(this.angleX-maxX){this.angleX-maxX;}虽然四元数本身不会产生万向锁但从用户体验角度俯仰角超过 ±90° 后模型会倒过来显示用户会感到困惑。限制在 ±85° 内保留了充足的上下旋转空间同时避免极点附近的视觉突变。主要特点四元数合成不累积数值误差长时间旋转也不会出现漂移合成结果为单位四元数直接写入node.rotation无需归一化零 Z 轴分量确保模型始终保持直立不产生侧倾总结本文深入讲解了在 HarmonyOS 6kit.ArkGraphics3D中实现双轴四元数旋转的数学原理与工程实践。核心要点是用独立的角度变量angleY左右和angleX上下分别构造单轴旋转四元数再通过四元数乘法qy * qx合成最终旋转每帧写入node.rotation。这种方案彻底规避了欧拉角的万向锁问题代码结构清晰且天然支持扩展第三轴旋转。掌握四元数旋转合成是进入 3D 应用开发的必备基础。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是我持续创作的动力需要源码的记得私聊哦