Explicitly documented that Transform.basis is not necessarily an orthogonal matrix.

Also added a check that in axis-angle rotations, axis is a normalized vector, and modified the docs accordingly.

Fixes #8113.

core/math/matrix3.cpp

@@ -575,6 +575,8 @@ Basis::Basis(const Quat &p_quat) {
 Basis::Basis(const Vector3 &p_axis, real_t p_phi) {
 	// Rotation matrix from axis and angle, see https://en.wikipedia.org/wiki/Rotation_matrix#Rotation_matrix_from_axis_and_angle
 
+	ERR_FAIL_COND(p_axis.is_normalized() == false);
+
 	Vector3 axis_sq(p_axis.x * p_axis.x, p_axis.y * p_axis.y, p_axis.z * p_axis.z);
 
 	real_t cosine = Math::cos(p_phi);

core/math/vector3.h

@@ -75,6 +75,7 @@ struct Vector3 {
 
 	_FORCE_INLINE_ void normalize();
 	_FORCE_INLINE_ Vector3 normalized() const;
+	_FORCE_INLINE_ bool is_normalized() const;
 	_FORCE_INLINE_ Vector3 inverse() const;
 
 	_FORCE_INLINE_ void zero();
@@ -385,6 +386,10 @@ Vector3 Vector3::normalized() const {
 	return v;
 }
 
+bool Vector3::is_normalized() const {
+	return Math::isequal_approx(length(), (real_t)1.0);
+}
+
 Vector3 Vector3::inverse() const {
 
 	return Vector3(1.0 / x, 1.0 / y, 1.0 / z);

doc/base/classes.xml

@@ -20704,7 +20704,7 @@
 		3x3 matrix datatype.
 	</brief_description>
 	<description>
-		3x3 matrix used for 3D rotation and scale. Contains 3 vector fields x,y and z as its columns, which can be interpreted as the local basis vectors of a transformation. Can also be accessed as array of 3D vectors. Almost always used as orthogonal basis for a [Transform].
+		3x3 matrix used for 3D rotation and scale. Contains 3 vector fields x,y and z as its columns, which can be interpreted as the local basis vectors of a transformation. Can also be accessed as array of 3D vectors. These vectors are orthogonal to each other, but are not necessarily normalized. Almost always used as orthogonal basis for a [Transform].
 		For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S).
 	</description>
 	<methods>
@@ -20725,7 +20725,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Create a rotation matrix which rotates around the given axis by the specified angle.
+				Create a rotation matrix which rotates around the given axis by the specified angle. The axis must be a normalized vector.
 			</description>
 		</method>
 		<method name="Matrix3">
@@ -20792,7 +20792,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Introduce an additional rotation around the given axis by phi. Only relevant when the matrix is being used as a part of [Transform].
+				Introduce an additional rotation around the given axis by phi. Only relevant when the matrix is being used as a part of [Transform]. The axis must be a normalized vector.
 			</description>
                 </method>
 		<method name="scaled">
@@ -31548,7 +31548,7 @@
 			<argument index="1" name="angle" type="float">
 			</argument>
 			<description>
-                Returns a quaternion that will rotate around the given axis by the specified angle.
+		                Returns a quaternion that will rotate around the given axis by the specified angle. The axis must be a normalized vector.
 			</description>
 		</method>
 		<method name="Quat">
@@ -43200,7 +43200,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Rotate the transform around given axis by phi.
+				Rotate the transform around given axis by phi. The axis must be a normalized vector.
 			</description>
 		</method>
 		<method name="scaled">
@@ -45402,7 +45402,7 @@ do_property].
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Rotates the vector around some axis by phi radians.
+				Rotates the vector around some axis by phi radians. The axis must be a normalized vector.
 			</description>
 		</method>
 		<method name="slide">