oss/luanti
oss/luanti
1
0
Fork 0
mirror of https://github.com/luanti-org/luanti.git synced 2025-08-06 17:41:04 +00:00
Code Wiki Activity

Document & extend testing for rotation conventions (#16200)

Browse source 
* Document Luanti rotation conventions
* Add test for setPitchYawRollRad (entity) rotation conventions
* Test and document that `vector.rotate` uses (extrinsic) Z-X-Y rotation order
This commit is contained in:
Lars Müller 2025-07-13 17:11:12 +02:00 • committed by GitHub
parent 33940021a1
commit 23bf50a07c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 123 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/script/lua_api/l_object.cpp
View file

@ -1158,6 +1158,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;
}

84
src/unittest/test_irr_matrix4.cpp
View file

@ -6,6 +6,8 @@
#include "irrMath.h"
#include "matrix4.h"
#include "irr_v3d.h"
#include "util/numeric.h"
#include <functional>
using matrix4 = core::matrix4;
@ -17,10 +19,60 @@ 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<void(core::matrix4 &m, const v3f &rot_rad)> &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 Y*X*Z (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)") {
SECTION("rotation order is Z*Y*X (matrix notation)") {
v3f rot{1, 2, 3};
matrix4 X, Y, Z, ZYX;
X.setRotationRadians({rot.X, 0, 0});
@ -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") {

2
src/unittest/test_irr_rotation.cpp
View file

@ -5,8 +5,6 @@
#include "catch_amalgamated.hpp"
#include "irrMath.h"
#include "matrix4.h"
#include "irrMath.h"
#include "matrix4.h"
#include "irr_v3d.h"
#include "quaternion.h"
#include <functional>

3
src/util/numeric.h
View file

@ -478,6 +478,8 @@ inline void wrappedApproachShortest(T &current, const T target, const T stepsize
}
}
/// @note Uses (extrinsic) Z-X-Y rotation order, left-handed rotation
/// @note This is not consistent with matrix4::setRotationRadians
void setPitchYawRollRad(core::matrix4 &m, v3f rot);
inline void setPitchYawRoll(core::matrix4 &m, v3f rot)
@ -485,6 +487,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)