首页 / Cesium / API 文档
Quaternion
先看结论
四元数，表示三维旋转。没有万向节锁，插值也平滑， 实体朝向和相机姿态在内部都存成它。
new Cesium.Quaternion(x, y, z, w)
构造参数
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
x | number | 0 | 虚部 x 分量 |
y | number | 0 | 虚部 y 分量 |
z | number | 0 | 虚部 z 分量 |
w | number | 1 | 实部；默认值 (0, 0, 0, 1) 即单位四元数 |
常用静态方法
| 成员 | 返回 | 说明 |
|---|---|---|
Quaternion.IDENTITY | Quaternion | 无旋转 |
fromAxisAngle(axis, angle, result) | Quaternion | 绕单位轴旋转 angle 弧度 |
fromRotationMatrix(matrix, result) | Quaternion | 由 Matrix3 旋转矩阵反解 |
fromHeadingPitchRoll(hpr, result) | Quaternion | 由航向俯仰横滚构造，最常用 |
computeAxis(quaternion, result) | Cartesian3 | 取旋转轴 |
computeAngle(quaternion) | number | 取旋转角，弧度 |
multiply(left, right, result) | Quaternion | 组合旋转，先 right 后 left |
conjugate(q, result) / inverse(q, result) | Quaternion | 共轭与逆；单位四元数两者相同 |
normalize(q, result) | Quaternion | 归一化，消除累积误差 |
slerp(start, end, t, result) | Quaternion | 球面线性插值，t 取 0 到 1 |
clone(q, result) / equals(a, b) | Quaternion / boolean | 拷贝与相等判断 |
示例
var position = Cesium.Cartesian3.fromDegrees(116.391, 39.907, 0);
// 由航向俯仰横滚得到朝向四元数，再给实体
var hpr = new Cesium.HeadingPitchRoll(
Cesium.Math.toRadians(30),
Cesium.Math.toRadians(-5),
0
);
var quaternion = Cesium.Quaternion.fromHeadingPitchRoll(
hpr,
new Cesium.Quaternion()
);
viewer.entities.add({
position: position,
orientation: quaternion,
model: {
uri: '/models/drone.glb',
minimumPixelSize: 24
}
});
// 绕本地 z 轴自转 180°，与原朝向组合
var spin = Cesium.Quaternion.fromAxisAngle(
Cesium.Cartesian3.UNIT_Z,
Cesium.Math.toRadians(180)
);
var turned = Cesium.Quaternion.multiply(quaternion, spin, new Cesium.Quaternion());
// 取旋转轴与角度
var axis = Cesium.Quaternion.computeAxis(turned, new Cesium.Cartesian3());
var angle = Cesium.Quaternion.computeAngle(turned);注意事项
- 四元数乘法不可交换，
multiply(a, b)与multiply(b, a)结果不同。 - 只有单位四元数才表示纯旋转；多次相乘后建议
normalize，避免模型逐渐变形。 q与-q表示同一旋转，直接比较分量判断朝向会出错，要比较旋转效果或角度差。- 实体同时设
orientation和模型自带动画时，朝向以外部设置为准，动画只影响骨骼。
经纬志（2026）。《Quaternion》。https://www.jingweizhi.com/cesium/api/quaternion.html（访问日期 2026-11-03）。