Matrix2d type name

[michaelmera]

What is the rational for the name Matrix2d?

I find it misleading. When I first saw it in code, I interpreted it as the linear part of a transform, then I saw calls to trans().
The doc for this type is: "The type used for matrices." which is not particularly helpful.

IMHO Transform2d would be a more appropriate name. Are there contexts where this is not used as a transform?

[dobkeratops]

/// The type used for matrices.
pub type Matrix2d<T=Scalar> = vecmath::Matrix2x3;

randomly dropping by to comment.. I haven't followed in detail for a while.

But this seems ok, 'Matrix2x3' might be more explicit but a 2x3 is the most general '2d transformation matrix'; a pure 2x2 isn't a complete transformation.

But maybe '2d' really suggests 2x2 to you ?

I've seen conventions where people just assume 'Vector' and 'Matrix' mean the most common cases (vector4 and 4x4 matrix), then increasing amounts of information in postfixes say whats different

I guess you can only resolve this sort of thing by polling a large number of people.

[michaelmera]

Yes, this is exactly my point, names like Matrix2d can be interpreted the way you want. Maybe it is a 2x2 matrix, maybe it is a 2x3 matrix, maybe it is a 42x17 matrix. This gives me almost no info.

On the other hand, Transform2d makes it clear that it represents a transform in a 2d space.
You can implement a 2d transform the way you want (2x3 matrix, struct{scale,trans,rot...}, whatever...), the user don't care, he just knows when to use it.

[mitchmindtree]

The crate itself is called piston2d-graphics, so perhaps there's no need to append the 2d suffix to the type name here either way?

[michaelmera]

Well, I fear most users will need to transform both 2d and 3d objects, so I'd prefer to be explicit and avoid forcing them to write use ... as Transform2d.

[bvssvni]

The name Matrix is likely to be used by some other math library, so to avoid name collision it is named Matrix2d.

The word Matrix2d is meant as:

• a linear map
• algebraic properties (addition and multiplication)
• used for 2D graphics

There are also non-linear transforms for 2D that does not use matrices. Naming it Transform2d will not make it more explicit, it will make it more generic.

[bvssvni]

That said, the docs could be improved.

[michaelmera]

I am not sure I understand your arguments in favor of the name Matrix2d:

• Matrix2d is NOT a linear map in 2d space so if the purpose is to convey this feeling, it is misleading.
• I, as a user, don't really care about algebraic properties if my purpose is to apply a transform to a set of points. I want to do translations, rotations, ...

I get your point that the word 'transform' can raise more general expectations than what the underlying matrix is capable of.
Indeed there are transforms for 2D that cannot be represented by matrices, but I feel that this capture most of what a user can expect in this context. A more accurate name would be Homography2d or ProjectiveGeometryTransform2d, but this seems an overkill and may scare new users.

Additionally I have seen the Matrix2d type used exclusively as a function argument named 'transform', or return type of functions called something like 'transform', or through the trait Transformed. So I think the choice has already been made to say that this is the standard transform supported by this library.

I really mean that Transform2d would be more explicit, as in 'explicit the purpose of the type instead of the underlying implementation'.

[dobkeratops]

Transform could mean SRT values; a Matrix is known as an efficient way to do a transformation.. something you can readily pass around , whilst 'transform' is something you might store in data structures (e.g. current states, animation paths..). Personally I've ended up with the term 'SRT' in my head from some 3d packages I've encountered as a handy acronym for 'transform' and by analogy SQT for Scale-Quaternion-Translation...but those terms might seem obscure ). Of course, transforms could include shearing, as such you might really want a matrix.

does github allow polls?

[michaelmera]

I prefer 'SRT' over 'Matrix' as it says what is the purpose of the type, but I am not a big fan of acronyms in general (except widely understood ones).
Since we do support shearing, I guess it is not sufficient anyway.

Never seen any pool feature on github but I haven't used it a lot, so...

[echochamber]

Again, I'm not super familiar with the terminology used here (been a while since I took linear algebra and only used it occasionally since.). Would it make sense to have a Transform2D trait and just have the Matrix2D implement it? Then depend upon the Tranform2D type when a matrix is being used as a transform? That way you still have the generic data structure but your type signatures are clearer when its being used as a transform?

Also it would allow type signatures like this to take a transform: Transform2D as an arugment (which could then just be implemented for a 2 element tuple of scalars: impl<T> Transform2D (T, T) where T: Scalar