Documentation: layman friendly terminology in cast_ray max_toi

[andrewbaxter]

In https://rapier.rs/docs/user_guides/rust/scene_queries it says the limit is [ray.origin, ray.origin + ray.dir * max_toi] suggesting that max_toi is in unit of ray.dir (i.e. toi 1 == ray.origin + ray.dir).

The code docstring says limits the length of the ray to ray.dir.norm() * max_toi (i.e. toi 1 could be before or after ray.origin + ray.dir).

[sebcrozet]

The ray.dir.norm() refers to the norm of the dir vector (a synonymous for norm is magnitude if that helps). So ray.dir.norm() * max_toi has the same length as ray.dir * max_toi, making this equivalent to saying that it is limited to ray.origin + ray.dir * max_toi.

[andrewbaxter]

Ah thanks... I think I'm still a bit confused.

Bevy uses Vec3 which has a normalize() but no norm() method. I assumed norm() meant normalize, but maybe this is wrong - but this is the bevy_rapier documentation so I'd assume bevy conventions. Do you mean norm() returns the length of the vector, like Vec3::length? Vec3::new(10., 0., 0.).normalize() * 3. and Vec3::new(10., 0., 0.) * 3 have two very different lengths.

If that's the case, I still believe it might help if the documentation is updated to use more easily distinguishable terminology. I'm not familiar with that use of norm there are probably others who are the same.

[andrewbaxter]

And thank you for this library! It's absolutely not something I'd want to write myself.

[sebcrozet]

Yes, norm is the length of the vector. norm, length, magnitude all mean the same thing here. See wikipedia. The word norm is a slightly more general term, here implied to be the euclidean norm. The function normalize (both in bevy/glam and rapier/nalgebra) divide the vector by its norm.