Document why Basis axis vectors are exposed transposed

[TyTYct]

Godot version:

3.1 beta 9

OS/device including version:

Windows 10

Issue description:

print spatial.transform.basis is wrong

I tested some case and this happen when spartial angle between 0 and 180 degree. it is ok at angle 180 degree or 0 degree

Steps to reproduce:

Minimal reproduction project:

test transform.zip

[PapaFl]

Basis is not transposed when converted to String. (or the other way around maybe?)
This results in different output. Not sure if this is an issue/bug.

[akien-mga]

It's not a bug a priori, Basis exposes its axis vectors transposed indeed. This should be better documented.

[Zylann]

Wait, so with this into account, is -z forward, x right and y up? If not, that's yet another piece of info coders have to know to get them, and another reason to support shortcuts #26371

[Calinou]

Wait, so with this into account, is -z forward, x right and y up?

According to Vector3.FORWARD, Vector3.RIGHT and Vector3.UP, yes 😃

[Zylann]

@Calinou those are constants, I mean taking any basis, rotated randomly, are x, y and z vectors still going to represent the same axes we see in the editor?
Edit: they do, ignore me :p

[PapaFl]

Just to clear any confusion:
Transform.basis basically is a 3x3 matrix used for rotation (and scale). Multiplying Basis * Vector3 rotates the Vector3, So multiplying the forward axis vector with a Transform.basis results in a vector pointing "forward" for that transformation.
If we look at how Matrix * Vector multiplication works:

[a  b  c]   [ j ]   [j*a + k*b + l*c]
[d  e  f] * [ k ] = [j*d + k*e + l*f]
[g  h  i]   [ l ]   [j*g + k*h + l*i]

we can see that if the Vector is Vector3(0, 0, -1) This basically results in:

[ -c ]
[ -f ]
[ -i ]

which is equal to -Basis.z exactly because Basis is exposed transposed.

[TyTYct]

I confuse why transform.basis is different from transform.basis.x, transform.basis.y, transform.basis.z.
I think that transform.basis.x is a part of transform.basis.

[PapaFl]

You're right that Basis.X (and Y, Z) represent a part of Basis. As i mentioned above, Basis is a 3x3 Matrix.
Basis.X basically gives you one column of the matrix:

        [a  b  c] 
Basis = [d  e  f], Basis.X = [a, d, g]
        [g  h  i]

However print(Basis) prints the Basis row by row.
I've tried to make this clear in this image:

[TyTYct]

thanks, @PapaFl . I understood that. It is not a bug.

[akien-mga]

I still think it needs better documentation though.

[Calinou]

Should we leave the "full" Basis print handler as-is? I haven't followed the issue closely.

[Chlorobyte-but-real]

For whoever got notified for that message, I am dumb. GLSL works with columns in the matrix as well, but accessing the individual elements is done by supplying the column then the row first, and I got confused (I do my coordinates in x, y usually). There is no inconsistency between GDScript and C#.

[Mickeon]

Just for a bit of clarification and revival of this issue.

In Godot 4 the way both Transform3D and Basis are converted to String (and by extension printed out) has changed:

var my_basis = Basis(Vector3(1, 2, 3), Vector3(4, 5, 6), Vector3(7, 8, 9))
print(my_basis)  # [X: (1, 2, 3), Y: (4, 5, 6), Z: (7, 8, 9)]
	
var transform = Transform3D(my_basis, Vector3.ZERO)
print(transform) # [X: (1, 2, 3), Y: (4, 5, 6), Z: (7, 8, 9), O: (0, 0, 0)]

This should mean that the original issue no longer exists. What could be documented now?