diff --git a/cocos/core/math/vec3.ts b/cocos/core/math/vec3.ts index fccc854449..c49cce4dc1 100644 --- a/cocos/core/math/vec3.ts +++ b/cocos/core/math/vec3.ts @@ -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, b: Readonly, normal: Readonly): 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 计算向量在指定平面上的投影 diff --git a/tests/core/math/vec3.test.ts b/tests/core/math/vec3.test.ts index b7020520af..fe0674eb07 100644 --- a/tests/core/math/vec3.test.ts +++ b/tests/core/math/vec3.test.ts @@ -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, b: Readonly, normal: Readonly) { + const result = assertsResult_basic(a, b, normal); + expect(result).toBeGreaterThan(0); + } + + function assertsResult_negativeSign(a: Readonly, b: Readonly, normal: Readonly) { + const result = assertsResult_basic(a, b, normal); + expect(result).toBeLessThan(0); + } + + function assertsResult_zero(a: Readonly, b: Readonly, normal: Readonly) { + const result = assertsResult_basic(a, b, normal); + expect(result).toStrictEqual(0); + } + + function assertsResult_basic(a: Readonly, b: Readonly, normal: Readonly) { + const result = Vec3.signedAngle(a, b, normal); + expect(Math.abs(result)).toBeCloseTo(Vec3.angle(a, b), MATCH_NUM_DIGITS); + return result; + } + }); }); \ No newline at end of file diff --git a/tests/value-types/vec3.test.ts b/tests/value-types/vec3.test.ts index 1f0d204ad1..50a87c8617 100644 --- a/tests/value-types/vec3.test.ts +++ b/tests/value-types/vec3.test.ts @@ -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);