首页 / Cesium / API 文档

HeadingPitchRoll

先看结论

用航向、俯仰、横滚三个角描述朝向。比四元数直观，常见于车辆、飞机、相机的姿态设置。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-28 · 引用本文

new Cesium.HeadingPitchRoll(heading, pitch, roll)

构造参数

参数	类型	说明
`heading`	number	绕本地 z 轴，弧度；0 为正北，顺时针增大
`pitch`	number	绕本地 y 轴，弧度；抬低机头用
`roll`	number	绕本地 x 轴，弧度；机身左右翻滚

三个角都是弧度，直接写度数会得到极端姿态。用 Cesium.Math.toRadians(45) 或 HeadingPitchRoll.fromDegrees 转换。

常用成员与方法

成员	类型 / 返回	说明
`heading` / `pitch` / `roll`	number	三个角，单位弧度，可读可写
`HeadingPitchRoll.fromDegrees(h, p, r, result)`	HeadingPitchRoll	用度数构造，内部自动转弧度
`HeadingPitchRoll.fromQuaternion(q, result)`	HeadingPitchRoll	由四元数反解三个角
`clone(result)`	HeadingPitchRoll	拷贝
`equals(other)` / `equalsEpsilon(other, eps)`	boolean	相等与带容差比较

示例

var position = Cesium.Cartesian3.fromDegrees(116.391, 39.907, 20);

// 三种等价写法
var a = new Cesium.HeadingPitchRoll(0, 0, 0);
var b = Cesium.HeadingPitchRoll.fromDegrees(30, -5, 0);
var c = new Cesium.HeadingPitchRoll(
  Cesium.Math.toRadians(30),
  Cesium.Math.toRadians(-5),
  0
);

// 与位置配对成朝向四元数
var orientation = Cesium.Transforms.headingPitchRollQuaternion(
  position,
  b
);

viewer.entities.add({
  position: position,
  orientation: orientation,
  model: {
    uri: '/models/plane.glb',
    minimumPixelSize: 32
  }
});

// 想直接控制相机时，用 setView 的 orientation 传三个角
viewer.camera.setView({
  destination: position,
  orientation: {
    heading: b.heading,
    pitch: b.pitch,
    roll: b.roll
  }
});

注意事项

构造顺序固定为 heading → pitch → roll，交换位置会得到完全不同的姿态。
Transforms.headingPitchRollQuaternion 需要位置参数，它按该点的东-北-天坐标系解释三个角；换到别处也有效。
模型本身的前向轴不是 +x 时（例如 glTF 约定 +z 向前），朝向会偏 90°，要用 Model.fromGltf 的 forwardAxis 修正。
roll 只在飞机、车辆这类有明确前向的模型上有意义；球体、立方体看不出差别。

引用本文

经纬志（2026）。《HeadingPitchRoll》。https://www.jingweizhi.com/cesium/api/heading-pitch-roll.html（访问日期 2026-11-03）。