Add Vec3.signedAngle (#16013)

* Signed angle

* Update cocos/core/math/vec3.ts

---------

Co-authored-by: Leslie Leigh <leslieleigh@outlook.com>
This commit is contained in:
Leslie Leigh (李的序)
2023-12-19 11:46:29 +08:00
committed by GitHub
parent 6872cf4792
commit da9c103ad3
3 changed files with 132 additions and 2 deletions
+34
View File
@@ -748,6 +748,40 @@ export class Vec3 extends ValueType {
return Math.acos(cosine);
}
/**
* @zh 计算 `a`、`b` 两向量之间的有符号夹角。
*
* 不妨假设 `a`、`b` 是钟表上的两根指针,其中 `a` 指向 12 点整,`normal` 是任何从钟表正面指出的向量。
* 当 `b` **逆时针** 从 12 点走到 6 点的过程中,它们的角度变化范围为 (0°, 180°);
* 当 `b` **顺时针** 从 12 点走到 6 点的过程中,它们的角度变化范围为 (0°, -180°)。
*
* 反之,如果 `normal` 是任何从钟表反面指出的向量,两种范围将对调。
*
* @en Calculates the signed angle between the two vectors `a`, `b`.
*
* Suppose that `a` and `b` are two hands on a clock, where pointing at 12 o'clock,
* and `normal` is arbitrary vector pointing out from the dial side of the clock.
* As `b` goes counterclockwise from 12 o'clock to 6 o'clock, their angle varies in the range (0°, 180°);
* As `b` goes clockwise from 12 o'clock to 6 o'clock, their angle varies in the range (0°, -180°).
*
* Instead, if `normal` is arbitrary vector pointing out from the opposite side of the clock,
* the two ranges would swap.
*
* @param a @zh 向量 `a`。 @en The vector `a`.
* @param b @zh 向量 `b`。 @en The vector `b`.
* @param normal @zh 参考向量。 @en The reference vector.
* @returns @zh 向量 `a` 和 `b` 之间的有符号夹角。 @en The signed angle between `a`, `b`.
*/
public static signedAngle = (() => {
const cacheCross = new Vec3();
return (a: Readonly<IVec3Like>, b: Readonly<IVec3Like>, normal: Readonly<IVec3Like>): number => {
const angle = Vec3.angle(a, b);
const cross = Vec3.cross(cacheCross, a, b);
const dot = Vec3.dot(cross, normal);
return dot < 0 ? -angle : angle;
};
})();
/**
* @en Calculates the projection vector on the specified plane
* @zh 计算向量在指定平面上的投影
+96 -1
View File
@@ -1,5 +1,5 @@
import { log } from '../../test.log';
import { Vec3 } from '../../../cocos/core/math/vec3';
import { v3, Vec3 } from '../../../cocos/core/math/vec3';
import { Mat3 } from '../../../cocos/core/math/mat3';
import { Mat4 } from '../../../cocos/core/math/mat4';
import { Quat } from '../../../cocos/core/math/quat';
@@ -235,4 +235,99 @@ describe('Test Vec3', () => {
return result;
};
});
test(`Signed angle`, () => {
const MATCH_NUM_DIGITS = 6;
// If either of the input vector is zero,
// the result is equal to `Vec3.angle()`(ie. 0),
// in despite of what "normal" is.
assertsResult_zero(Vec3.ZERO, Vec3.ZERO, Vec3.ZERO);
assertsResult_zero(Vec3.ZERO, Vec3.ZERO, v3(4., 5., 6.));
assertsResult_zero(Vec3.ZERO, v3(1., 2., -3.), Vec3.ZERO);
assertsResult_zero(v3(1., 2., -3.), Vec3.ZERO, Vec3.ZERO);
assertsResult_zero(v3(1., 2., -3.), Vec3.ZERO, v3(4., 5., 6.));
// If the input vectors are co-linear,
// the result has positive sign.
// in despite of what "normal" is.
{
const a = v3(1, 2, 3);
const normal = v3(7, -1, 0.618);
{ // b is in same dir.
const b = Vec3.multiplyScalar(v3(), a, 3);
assertsResult_zero(a, b, Vec3.ZERO);
assertsResult_zero(a, b, normal);
assertsResult_zero(a, b, Vec3.negate(v3(), normal));
assertsResult_zero(a, b, Vec3.multiplyScalar(v3(), a, -1.0086));
assertsResult_zero(a, b, Vec3.multiplyScalar(v3(), a, 1.0086));
}
{ // b is in opposite dir.
const b = Vec3.multiplyScalar(v3(), a, -4);
assertsResult_positiveSign(a, b, Vec3.ZERO);
assertsResult_positiveSign(a, b, normal);
assertsResult_positiveSign(a, b, Vec3.negate(v3(), normal));
assertsResult_positiveSign(a, b, Vec3.multiplyScalar(v3(), a, -1.0086));
assertsResult_positiveSign(a, b, Vec3.multiplyScalar(v3(), a, 1.0086));
}
}
// If normal is zero, the result has positive sign.
assertsResult_positiveSign(v3(1., 2., -3.), v3(7, -1, 0.618), Vec3.ZERO);
// If normal is co-linear with either input vector,
// the result is **indeterminate**, but it is equal to either ±`Vec3.angle()`.
{
const a = v3(1, 2, 3);
const b = v3(7, -1, 0.618);
// Theses result positive.
assertsResult_positiveSign(a, b, Vec3.multiplyScalar(v3(), a, -1.5));
assertsResult_positiveSign(a, b, Vec3.multiplyScalar(v3(), a, 1.5));
assertsResult_positiveSign(a, b, Vec3.multiplyScalar(v3(), b, -1.5));
// This results negative.
assertsResult_negativeSign(a, b, Vec3.multiplyScalar(v3(), b, 1.5));
}
/**
* Otherwise, asserts neither two of them are co-linear and neither of them is zero vector.
*
* Let $N$ to be normal of plane decided by $a$ and $b$,
* where $N$ is at the side so that it has the minimal angle between the input normal.
* Let $angle$ be the unsigned angle between $a$ and $b$.
* Around $N$, following the right hand rule, if $a$ can rotate to $b$ in positive $angle$ angle, then the result is $angle$.
* Otherwise, the result is $-angle$.
*/
const _SPEC = undefined;
{
const a = v3(1, 2, 3);
const b = v3(7, -1, 0.618);
const c = v3(-9, -3, -9);
assertsResult_positiveSign(a, b, c);
assertsResult_negativeSign(a, b, Vec3.negate(v3(), c));
}
function assertsResult_positiveSign(a: Readonly<Vec3>, b: Readonly<Vec3>, normal: Readonly<Vec3>) {
const result = assertsResult_basic(a, b, normal);
expect(result).toBeGreaterThan(0);
}
function assertsResult_negativeSign(a: Readonly<Vec3>, b: Readonly<Vec3>, normal: Readonly<Vec3>) {
const result = assertsResult_basic(a, b, normal);
expect(result).toBeLessThan(0);
}
function assertsResult_zero(a: Readonly<Vec3>, b: Readonly<Vec3>, normal: Readonly<Vec3>) {
const result = assertsResult_basic(a, b, normal);
expect(result).toStrictEqual(0);
}
function assertsResult_basic(a: Readonly<Vec3>, b: Readonly<Vec3>, normal: Readonly<Vec3>) {
const result = Vec3.signedAngle(a, b, normal);
expect(Math.abs(result)).toBeCloseTo(Vec3.angle(a, b), MATCH_NUM_DIGITS);
return result;
}
});
});
+2 -1
View File
@@ -1,6 +1,7 @@
import { lerp, toRadian } from '../../cocos/core/math/utils';
import { Vec3 } from '../../cocos/core/math/vec3';
import { v3, Vec3 } from '../../cocos/core/math/vec3';
import { clampf } from '../../cocos/core/utils/misc';
import '../utils/matchers/value-type-asymmetric-matchers';
test('basic test', function () {
const vec3 = new Vec3(1, 2, 3);