API基础类型 / Quaternion
Quaternion Class
四元数
用于表示 3D 旋转的单位四元数。
四元数与 Transform 类似，实现了旋转的矩阵表示。与存储旋转、缩放和剪切的 Transform 不同，四元数仅存储旋转。
四元数可以使用轴角对或欧拉角进行参数化。由于它们的紧凑性以及它们在内存中的存储方式，某些操作对于浮点错误的处理更加高效。
Table of contents
Properties
w: number |
|---|
| w 分量。 |
x: number |
| x 分量。 |
y: number |
| y 分量。 |
z: number |
| z 分量。 |
halfToRad: any |
| 获取一个半弧度系数 |
Accessors
conjugated(): Quaternion |
|---|
| 返回当前四元数的共轭四元数，对单位四元数与求逆等价，但更高效 |
inverted(): Quaternion |
| 返回当前四元数的逆 |
length(): number |
| 求四元数长度 |
normalized(): Quaternion |
| 返回一个当前四元数归一后的新四元数 |
sqrLength(): number |
| 求四元数长度平方 |
identity(): Quaternion |
| 获取一个单位四元数 |
Methods
clone(): Quaternion |
|---|
| 克隆当前四元数。 |
equals(a: Quaternion, b: Quaternion, epsilon?: number): boolean |
| 排除浮点数误差的四元数近似等价判断 |
fromRotation(v: Rotation, outer?: Quaternion): Quaternion |
| 读取旋转角数据创建或者写入一个四元数 |
getAxisX(outer?: Vector): Vector |
| 返回定义此四元数的坐标系 X 轴向量 |
getAxisY(outer?: Vector): Vector |
| 返回定义此四元数的坐标系 Y 轴向量 |
getAxisZ(outer?: Vector): Vector |
| 返回定义此四元数的坐标系 Z 轴向量 |
getEuler(outerZ?: boolean, outer?: Vector): Vector |
| 根据四元数计算欧拉角 |
getEulerAngles(): Vector |
| 返回当前四元数转化的欧拉角（x-y-z）。 |
normalize(a: Quaternion, outer?: Quaternion): Quaternion |
| 归一化四元数 |
set(other): Quaternion |
| 设置当前四元数使其与指定四元数相等。 |
setEulerAngles(euler: Vector): void |
| 设置欧拉角 |
strictEquals(a: Quaternion, b: Quaternion): boolean |
| 四元数等价判断 |
toRotation(): Rotation |
| 获取一个当前四元数的旋转数据 |
toString(): string |
| 输出为字符串 |
calculateW(a: Quaternion, outer?: Quaternion): Quaternion |
| 根据 xyz 分量计算 w 分量，默认已归一化 |
conjugate(a: Quaternion, outer?: Quaternion): Quaternion |
| 求共轭四元数，对单位四元数与求逆等价，但更高效 |
dot(a: Quaternion, b: Quaternion): number |
| 四元数点积（数量积） |
equals(a: Quaternion, b: Quaternion, epsilon?: number): boolean |
| 排除浮点数误差的四元数近似等价判断 |
fromAngleZ(z: number, outer?: Quaternion): Quaternion |
| 根据 2D 角度（0, 0, z）计算四元数 |
fromAxes(xAxis: Vector, yAxis: Vector, zAxis: Vector, outer?: Quaternion): Quaternion |
| 根据坐标轴朝向计算四元数，默认三向量都已归一化且相互垂直 |
fromAxisAngle(axis: Vector, rad: number, outer?: Quaternion): Quaternion |
| 根据旋转轴和旋转弧度计算四元数 |
fromMatrix3x3(m: Matrix3x3, outer?: Quaternion): Quaternion |
| 根据三维矩阵信息计算四元数，默认输入矩阵不含有缩放信息 |
fromRotation(v: Rotation, outer?: Quaternion): Quaternion |
| 读取旋转角数据创建或者写入一个四元数 |
fromViewUp(view: Vector, up?: Vector, outer?: Quaternion): Quaternion |
| 根据视口的前方向和上方向计算四元数 |
getAxis(q: Quaternion, outer?: Vector): Vector |
| 获取四元数的旋转轴 |
getAxisAngle(q: Quaternion): number |
| 获取四元数的旋转弧度 |
invert(a: Quaternion, outer?: Quaternion): Quaternion |
| 四元数求逆 |
lerp(a: Quaternion, b: Quaternion, t: number, outer?: Quaternion): Quaternion |
| 逐元素线性插值： A + t * (B - A) |
multiply(a: Quaternion, b: Quaternion, outer?: Quaternion): Quaternion |
| 四元数乘法 |
multiplyVector(a: Vector, q: Quaternion, outer?: Vector): Vector |
| 四元数乘以一个三维向量(通常用于向量通过四元数旋转) |
normalize(a: Quaternion, outer?: Quaternion): Quaternion |
| 归一化四元数 |
rotateAround(rot: Quaternion, axis: Vector, rad: number, outer?: Quaternion): Quaternion |
| 绕世界空间下指定轴旋转四元数 |
rotateAroundLocal(rot: Quaternion, axis: Vector, rad: number, outer?: Quaternion): Quaternion |
| 绕本地空间下指定轴旋转四元数 |
rotateX(a: Quaternion, rad: number, outer?: Quaternion): Quaternion |
| 绕 X 轴旋转指定四元数 |
rotateY(a: Quaternion, rad: number, outer?: Quaternion): Quaternion |
| 绕 Y 轴旋转指定四元数 |
rotateZ(a: Quaternion, rad: number, outer?: Quaternion): Quaternion |
| 绕 Z 轴旋转指定四元数 |
rotationTo(a: Vector, b: Vector, outer?: Quaternion): Quaternion |
| 设置四元数为两向量a和b间的最短路径旋转，默认两向量都已归一化 |
slerp(a: Quaternion, b: Quaternion, t: number, outer?: Quaternion): Quaternion |
| 四元数球面插值 |
sqlerp(a: Quaternion, b: Quaternion, c: Quaternion, d: Quaternion, t: number, outer?: Quaternion): Quaternion |
| 带两个控制点的四元数球面插值 |
strictEquals(a: Quaternion, b: Quaternion): boolean |
| 四元数等价判断 |
toMatrix3x3(q: Quaternion, outer?: Matrix3x3): Matrix3x3 |
| 根据四元数旋转信息计算矩阵 |
• new Quaternion(v)
Parameters
v Quaternion | 四元素 |
|---|
• new Quaternion(x, y, z, w)
Parameters
x number | x 分量 default:0 range: [-1, 1] type: 浮点数 |
|---|---|
y number | y 分量 default:0 range: [-1, 1] type: 浮点数 |
z number | z 分量 default:0 range: [-1, 1] type: 浮点数 |
w number | w 分量 default:1 range: [-1, 1] type: 浮点数 |
Properties
w
• w: number
w 分量。
x
• x: number
x 分量。
y
• y: number
y 分量。
z
• z: number
z 分量。
halfToRad
▪ Static Private halfToRad: any
获取一个半弧度系数
Accessors
conjugated
• | ||
|---|---|---|
返回当前四元数的共轭四元数，对单位四元数与求逆等价，但更高效 Returns
|
inverted
• | ||
|---|---|---|
返回当前四元数的逆 Returns
|
length
• | ||
|---|---|---|
求四元数长度 Returns
|
normalized
• | ||
|---|---|---|
返回一个当前四元数归一后的新四元数 Returns
|
sqrLength
• | ||
|---|---|---|
求四元数长度平方 Returns
|
identity
• |
|---|
获取一个单位四元数 Precautions Quaternion(0,0,0,1)。 Returns |
Quaternion |
|---|
Methods
clone
• clone(): Quaternion
克隆当前四元数。
Returns
Quaternion | 四元数 |
|---|
equals
• equals(other, epsilon?): boolean
判断当前四元数是否在误差范围内与指定向量相等。
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
epsilon? number | 最小误差数 default:1.e-7 range: 建议传入小于 1 的值。 type:浮点数 |
Returns
boolean | 返回是否相等的结果 |
|---|
fromRotation
• fromRotation(v): void
当前四元数读取一个旋转数据
Parameters
v Rotation | 读取的字符串数据 |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
getAxisX
• getAxisX(outer?): Vector
返回定义此四元数的坐标系 X 轴向量
Parameters
outer? Vector | 接收结果的 Vector 对象 default:null |
|---|
Returns
Vector | 此四元数的坐标系 X 轴向量 |
|---|
getAxisY
• getAxisY(outer?): Vector
返回定义此四元数的坐标系 Y 轴向量
Parameters
outer? Vector | 接收结果的 Vector 对象 default:null |
|---|
Returns
Vector | 此四元数的坐标系 Y 轴向量 |
|---|
getAxisZ
• getAxisZ(outer?): Vector
返回定义此四元数的坐标系 Z 轴向量
Parameters
outer? Vector | 接收结果的 Vector 对象 default:null |
|---|
Returns
Vector | 此四元数的坐标系 Z 轴向量 |
|---|
getEuler
• getEuler(outerZ?, outer?): Vector
根据四元数计算欧拉角
Parameters
outerZ? boolean | 将z值范围更改为[-180，-90]U[90，180] default:false |
|---|---|
outer? Vector | 接收结果的 Vector 对象 default:null |
Returns
Vector | 欧拉角。返回角度 x, y 在 [-180, 180] 区间内, z 默认在 [-90, 90] 区间内，旋转顺序为 YZX |
|---|
getEulerAngles
• getEulerAngles(): Vector
返回当前四元数转化的欧拉角（x-y-z）。
Returns
Vector | 欧拉角 |
|---|
normalize
• normalize(): void
将当前四元数归一化
Parameters
a Quaternion | 四元数a |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
set
• set(other): Quaternion
设置当前四元数使其与指定四元数相等。
Parameters
other Quaternion | 四元数数据 |
|---|
Returns
Quaternion | this |
|---|
• set(x?, y?, z?, w?): Quaternion
设置当前四元数指定元素值。
Parameters
x? number | 四元数的 x 分量 default:0 range: [-1, 1] type: 浮点数 |
|---|---|
y? number | 四元数的 y 分量 default:0 range: [-1, 1] type: 浮点数 |
z? number | 四元数的 z 分量 default:0 range: [-1, 1] type: 浮点数 |
w? number | 四元数的 w 分量 default:0 range: [-1, 1] type: 浮点数 |
Returns
Quaternion | 当前四元数 |
|---|
setEulerAngles
• setEulerAngles(euler): void
设置欧拉角
Parameters
euler Vector | 传入的欧拉角 |
|---|
strictEquals
• strictEquals(other): boolean
判断当前四元数是否与指定四元数相等。
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
Returns
boolean | 返回是否相等的结果 |
|---|
toRotation
• toRotation(): Rotation
获取一个当前四元数的旋转数据
Returns
Rotation | 旋转数据 |
|---|
toString
• toString(): string
输出为字符串
Returns
string | 四元数值字符串 |
|---|
calculateW
• Static calculateW(a, outer?): Quaternion
根据 xyz 分量计算 w 分量，默认已归一化
Parameters
a Quaternion | 目标四元数 |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
conjugate
• Static conjugate(a, outer?): Quaternion
求共轭四元数，对单位四元数与求逆等价，但更高效
Parameters
a Quaternion | 四元数a |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
dot
• Static dot(a, b): number
四元数点积（数量积）
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
Returns
number | 返回一个结果数 |
|---|
equals
• Static equals(a, b, epsilon?): boolean
排除浮点数误差的四元数近似等价判断
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
epsilon? number | 最小误差数 default:1.e-7 range: 建议传入小于 1 的值。 type:浮点数 |
Returns
boolean | 返回是否相等的结果 |
|---|
fromAngleZ
• Static fromAngleZ(z, outer?): Quaternion
根据 2D 角度（0, 0, z）计算四元数
Parameters
z number | 绕 z 旋转的角度值。 range: 不限制 type:浮点数 |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
fromAxes
• Static fromAxes(xAxis, yAxis, zAxis, outer?): Quaternion
根据坐标轴朝向计算四元数，默认三向量都已归一化且相互垂直
Parameters
xAxis Vector | x轴的向量值 |
|---|---|
yAxis Vector | y轴的向量值 |
zAxis Vector | z轴的向量值 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
fromAxisAngle
• Static fromAxisAngle(axis, rad, outer?): Quaternion
根据旋转轴和旋转弧度计算四元数
Parameters
axis Vector | 旋转轴 |
|---|---|
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
fromMatrix3x3
• Static fromMatrix3x3(m, outer?): Quaternion
根据三维矩阵信息计算四元数，默认输入矩阵不含有缩放信息
Parameters
m Matrix3x3 | 三维矩阵 |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
fromRotation
• Static fromRotation(v, outer?): Quaternion
读取旋转角数据创建或者写入一个四元数
Parameters
v Rotation | 读取的字符串数据 |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
fromViewUp
• Static fromViewUp(view, up?, outer?): Quaternion
根据视口的前方向和上方向计算四元数
Parameters
view Vector | 视口的前向量 |
|---|---|
up? Vector | 上方向量 default:null |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
getAxis
• Static getAxis(q, outer?): Vector
获取四元数的旋转轴
Parameters
q Quaternion | 目标四元数 |
|---|---|
outer? Vector | 被写入的 Vector 对象 default:null |
Returns
Vector | 返回一个三维向量 |
|---|
getAxisAngle
• Static getAxisAngle(q): number
获取四元数的旋转弧度
Parameters
q Quaternion | 目标四元数 |
|---|
Returns
number | 返回一个弧度值 |
|---|
invert
• Static invert(a, outer?): Quaternion
四元数求逆
Parameters
a Quaternion | 四元数a |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
lerp
• Static lerp(a, b, t, outer?): Quaternion
逐元素线性插值： A + t * (B - A)
Parameters
a Quaternion | 四元数 a |
|---|---|
b Quaternion | 四元数 b |
t number | 插值 range: [0, 1] type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
multiply
• Static multiply(a, b, outer?): Quaternion
四元数乘法
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
multiplyVector
• Static multiplyVector(a, q, outer?): Vector
四元数乘以一个三维向量(通常用于向量通过四元数旋转)
Parameters
a Vector | 目标向量 |
|---|---|
q Quaternion | 四元数 |
outer? Vector | 被写入的 Vector 对象 default:null |
Returns
Vector | 返回一个旋转后的三维向量 |
|---|
normalize
• Static normalize(a, outer?): Quaternion
归一化四元数
Parameters
a Quaternion | 四元数a |
|---|---|
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotateAround
• Static rotateAround(rot, axis, rad, outer?): Quaternion
绕世界空间下指定轴旋转四元数
Parameters
rot Quaternion | 被旋转的四元数 |
|---|---|
axis Vector | 代表旋转轴的三维向量 |
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotateAroundLocal
• Static rotateAroundLocal(rot, axis, rad, outer?): Quaternion
绕本地空间下指定轴旋转四元数
Parameters
rot Quaternion | 需要变换的四元数 |
|---|---|
axis Vector | 代表旋转轴的三维向量 |
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotateX
• Static rotateX(a, rad, outer?): Quaternion
绕 X 轴旋转指定四元数
Parameters
a Quaternion | 四元数 |
|---|---|
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotateY
• Static rotateY(a, rad, outer?): Quaternion
绕 Y 轴旋转指定四元数
Parameters
a Quaternion | 四元数 |
|---|---|
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotateZ
• Static rotateZ(a, rad, outer?): Quaternion
绕 Z 轴旋转指定四元数
Parameters
a Quaternion | 四元数 |
|---|---|
rad number | 弧度值 range: 不限制 type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
rotationTo
• Static rotationTo(a, b, outer?): Quaternion
设置四元数为两向量a和b间的最短路径旋转，默认两向量都已归一化
Parameters
a Vector | 向量 a |
|---|---|
b Vector | 向量 b |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
slerp
• Static slerp(a, b, t, outer?): Quaternion
四元数球面插值
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
t number | 插值 range: [0, 1] type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
sqlerp
• Static sqlerp(a, b, c, d, t, outer?): Quaternion
带两个控制点的四元数球面插值
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
c Quaternion | 四元数c |
d Quaternion | 四元数d |
t number | 插值 range: [0, 1] type:浮点数 |
outer? Quaternion | 接收结果的 Quaternion 对象 default:null |
Returns
Quaternion | 返回一个四元数 |
|---|
strictEquals
• Static strictEquals(a, b): boolean
四元数等价判断
Parameters
a Quaternion | 四元数a |
|---|---|
b Quaternion | 四元数b |
Returns
boolean | 返回是否相等的结果 |
|---|
toMatrix3x3
• Static toMatrix3x3(q, outer?): Matrix3x3
根据四元数旋转信息计算矩阵
Parameters
q Quaternion | 四元数信息 |
|---|---|
outer? Matrix3x3 | 被写入的 Matrix3x3 对象 default:null |
Returns
Matrix3x3 | 返回一个三维矩阵 |
|---|