From 5bc191dd8f8b9cb6e260e24e12133b2b2e9f460e Mon Sep 17 00:00:00 2001 From: Lars Mueller Date: Wed, 28 May 2025 19:11:35 +0200 Subject: [PATCH 1/2] Add test for setPitchYawRollRad rotation conventions --- src/unittest/test_irr_matrix4.cpp | 82 +++++++++++++++++++++---------- src/util/numeric.h | 2 + 2 files changed, 57 insertions(+), 27 deletions(-) diff --git a/src/unittest/test_irr_matrix4.cpp b/src/unittest/test_irr_matrix4.cpp index be6c6aa08..5a9a0041d 100644 --- a/src/unittest/test_irr_matrix4.cpp +++ b/src/unittest/test_irr_matrix4.cpp @@ -6,6 +6,8 @@ #include "irrMath.h" #include "matrix4.h" #include "irr_v3d.h" +#include "util/numeric.h" +#include using matrix4 = core::matrix4; @@ -17,8 +19,58 @@ constexpr v3f x{1, 0, 0}; constexpr v3f y{0, 1, 0}; constexpr v3f z{0, 0, 1}; +constexpr f32 QUARTER_TURN = core::PI / 2; + +static void LEFT_HANDED(const std::function &f) { + SECTION("rotation is left-handed") { + SECTION("around the X-axis") { + matrix4 X; + f(X, {QUARTER_TURN, 0 , 0}); + CHECK(X.transformVect(x).equals(x)); + CHECK(X.transformVect(y).equals(z)); + CHECK(X.transformVect(z).equals(-y)); + } + + SECTION("around the Y-axis") { + matrix4 Y; + f(Y, {0, QUARTER_TURN, 0}); + CHECK(Y.transformVect(y).equals(y)); + CHECK(Y.transformVect(x).equals(-z)); + CHECK(Y.transformVect(z).equals(x)); + } + + SECTION("around the Z-axis") { + matrix4 Z; + f(Z, {0, 0, QUARTER_TURN}); + CHECK(Z.transformVect(z).equals(z)); + CHECK(Z.transformVect(x).equals(y)); + CHECK(Z.transformVect(y).equals(-x)); + } + } +} + TEST_CASE("matrix4") { +// This is in numeric.h rather than matrix4.h, but is conceptually a matrix4 method as well +SECTION("setPitchYawRollRad") { + SECTION("rotation order is YXZ (matrix notation)") { + v3f rot{1, 2, 3}; + matrix4 X, Y, Z, YXZ; + setPitchYawRollRad(X, {rot.X, 0, 0}); + setPitchYawRollRad(Y, {0, rot.Y, 0}); + setPitchYawRollRad(Z, {0, 0, rot.Z}); + setPitchYawRollRad(YXZ, rot); + CHECK(!matrix_equals(X * Y * Z, YXZ)); + CHECK(!matrix_equals(X * Z * Y, YXZ)); + CHECK(matrix_equals(Y * X * Z, YXZ)); + CHECK(!matrix_equals(Y * Z * X, YXZ)); + CHECK(!matrix_equals(Z * X * Y, YXZ)); + CHECK(!matrix_equals(Z * Y * X, YXZ)); + } + + LEFT_HANDED(setPitchYawRollRad); +} + SECTION("setRotationRadians") { SECTION("rotation order is ZYX (matrix notation)") { v3f rot{1, 2, 3}; @@ -35,36 +87,12 @@ SECTION("setRotationRadians") { CHECK(matrix_equals(Z * Y * X, ZYX)); } - const f32 quarter_turn = core::PI / 2; - // See https://en.wikipedia.org/wiki/Right-hand_rule#/media/File:Cartesian_coordinate_system_handedness.svg // for a visualization of what handedness means for rotations - SECTION("rotation is right-handed") { - SECTION("rotation around the X-axis is Z-up, counter-clockwise") { - matrix4 X; - X.setRotationRadians({quarter_turn, 0, 0}); - CHECK(X.transformVect(x).equals(x)); - CHECK(X.transformVect(y).equals(z)); - CHECK(X.transformVect(z).equals(-y)); - } - - SECTION("rotation around the Y-axis is Z-up, clockwise") { - matrix4 Y; - Y.setRotationRadians({0, quarter_turn, 0}); - CHECK(Y.transformVect(y).equals(y)); - CHECK(Y.transformVect(x).equals(-z)); - CHECK(Y.transformVect(z).equals(x)); - } - - SECTION("rotation around the Z-axis is Y-up, counter-clockwise") { - matrix4 Z; - Z.setRotationRadians({0, 0, quarter_turn}); - CHECK(Z.transformVect(z).equals(z)); - CHECK(Z.transformVect(x).equals(y)); - CHECK(Z.transformVect(y).equals(-x)); - } - } + LEFT_HANDED([](core::matrix4 &m, const v3f &rot_rad) { + m.setRotationRadians(rot_rad); + }); } SECTION("getScale") { diff --git a/src/util/numeric.h b/src/util/numeric.h index b79ef2aef..ac387f4b8 100644 --- a/src/util/numeric.h +++ b/src/util/numeric.h @@ -478,6 +478,7 @@ inline void wrappedApproachShortest(T ¤t, const T target, const T stepsize } } +/// @note Uses YXZ (matrix notation) rotation order, left-handed rotation void setPitchYawRollRad(core::matrix4 &m, v3f rot); inline void setPitchYawRoll(core::matrix4 &m, v3f rot) @@ -485,6 +486,7 @@ inline void setPitchYawRoll(core::matrix4 &m, v3f rot) setPitchYawRollRad(m, rot * core::DEGTORAD); } +/// @see setPitchYawRollRad v3f getPitchYawRollRad(const core::matrix4 &m); inline v3f getPitchYawRoll(const core::matrix4 &m) From 99c4823af34564c07fffbbebab80996d62bc0b81 Mon Sep 17 00:00:00 2001 From: Lars Mueller Date: Wed, 28 May 2025 20:06:48 +0200 Subject: [PATCH 2/2] Document Luanti rotation conventions --- doc/lua_api.md | 33 ++++++++++++++++++++++++++++----- src/script/lua_api/l_object.cpp | 2 ++ 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/doc/lua_api.md b/doc/lua_api.md index b604b317c..9fa495888 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -3928,6 +3928,28 @@ The following functions provide escape sequences: * Removes all color escape sequences. +Coordinate System +================= + +Luanti uses a **left-handed** coordinate system: Y is "up", X is "right", Z is "forward". +This is the convention used by Unity, DirectX and Irrlicht. +It means that when you're pointing in +Z direction in-game ("forward"), +X is to your right; +Y is up. + +Consistently, rotation is **left-handed** as well: +When your thumb points in the direction of the rotation axis, +your curled fingers point in the direction the rotation goes. +The rotation order is XYZ: First rotation around the X-axis is applied, then Y, then Z. +(Note: As a product of rotation matrices, this will be written in reverse, so ZYX.) + +Attachment and bone override rotations both use these conventions. + +There is an exception, however: Object rotation (`ObjectRef:set_rotation`, `ObjectRef:get_rotation`, `automatic_rotate`) +**does not** use left-handed XYZ rotations. Instead, it uses **right-handed ZXY** rotations: +First roll (Z) is applied, then pitch (X); yaw (Y) is applied last. + +See [Scratchapixel](https://www.scratchapixel.com/lessons/mathematics-physics-for-computer-graphics/geometry/coordinate-systems.html) +or [Wikipedia](https://en.wikipedia.org/wiki/Cartesian_coordinate_system#Orientation_and_handedness) +for a more detailed and pictorial explanation of these terms. Spatial Vectors @@ -8461,9 +8483,9 @@ child will follow movement and rotation of that bone. * `interpolation`: The old and new overrides are interpolated over this timeframe (in seconds). * `absolute`: If set to `false` (which is the default), the override will be relative to the animated property: - * Translation in the case of `position`; - * Composition in the case of `rotation`; - * Per-axis multiplication in the case of `scale` + * Translation in the case of `position`; + * Composition in the case of `rotation`; + * Per-axis multiplication in the case of `scale` * `property = nil` is equivalent to no override on that property * **Note:** Unlike `set_bone_position`, the rotation is in radians, not degrees. * Compatibility note: Clients prior to 5.9.0 only support absolute position and rotation. @@ -8536,9 +8558,10 @@ child will follow movement and rotation of that bone. * `acc` is a vector * `get_acceleration()`: returns the acceleration, a vector * `set_rotation(rot)` - * Sets the rotation * `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading) and Z is roll (bank). + * Sets the **right-handed ZXY** rotation: + First roll (Z) is applied, then pitch (X); yaw (Y) is applied last. * Does not reset rotation incurred through `automatic_rotate`. Remove & re-add your objects to force a certain rotation. * `get_rotation()`: returns the rotation, a vector (radians) @@ -9440,7 +9463,7 @@ Player properties need to be saved manually. -- (see node sound definition for details). automatic_rotate = 0, - -- Set constant rotation in radians per second, positive or negative. + -- Set constant right-handed rotation in radians per second, positive or negative. -- Object rotates along the local Y-axis, and works with set_rotation. -- Set to 0 to disable constant rotation. diff --git a/src/script/lua_api/l_object.cpp b/src/script/lua_api/l_object.cpp index 19c513dd3..4c71fb43f 100644 --- a/src/script/lua_api/l_object.cpp +++ b/src/script/lua_api/l_object.cpp @@ -1144,6 +1144,8 @@ int ObjectRef::l_set_rotation(lua_State *L) v3f rotation = check_v3f(L, 2) * core::RADTODEG; + // Note: These angles are inverted before being applied using setPitchYawRoll, + // hence we end up with a right-handed rotation entitysao->setRotation(rotation); return 0; }