Improve Segment2d/Segment3d API and docs

[Jondolf]

Objective

#17404 reworked the Segment2d and Segment3d types to be defined by two endpoints rather than a direction and half-length. However, the API is still very minimal and limited, and documentation is inconsistent and outdated.

Solution

Add the following helper methods for Segment2d and Segment3d:

• from_scaled_direction
• from_ray_and_length
• length_squared
• direction
• try_direction
• scaled_direction
• transformed
• reversed

Segment2d has a few 2D-specific methods:

• left_normal
• try_left_normal
• scaled_left_normal
• right_normal
• try_right_normal
• scaled_right_normal

There are now also From implementations for converting [Vec2; 2] and (Vec2, Vec2) to a Segment2d, and similarly for 3D.

I have also updated documentation to be more accurate and consistent, and simplified a few methods.

---

Prior Art

Parry's Segment type has a lot of similar methods, though my implementation is a bit more comprehensive. A lot of these methods can be useful for various geometry algorithms.

[greeble-dev]

Suggested some small changes.

[Jondolf]

@alice-i-cecile Those only changed the 2D methods so 3D is now inconsistent. I can fix it in a sec though

[alice-i-cecile]

Thank you very much @Jondolf :)

[github-actions]

Your PR caused a change in the graphical output of an example or rendering test. This might be intentional, but it could also mean that something broke!
You can review it at https://pixel-eagle.com/project/B04F67C0-C054-4A6F-92EC-F599FEC2FD1D?filter=PR-18206

If it's expected, please add the M-Deliberate-Rendering-Change label.

If this change seems unrelated to your PR, you can consider updating your PR to target the latest main branch, either by rebasing or merging main into it.

[Jondolf]

Also I would prefer if the reversing method memswapped like what I originally had, since that's what I personally need for my use cases (e.g. I have a segment clipping algo where I need to sort features, which includes swapping things around).

We could have both reverse (in-place mutation) and reversed (returns a new segment) to match the existing API of Triangle2d/Triangle3d. I can do that either here or in a follow-up, either is fine for me

[alice-i-cecile]

@Jondolf let's add both here.

[Jondolf]

Done! Also added #[must_use] to reversed to be more explicit about it returning a new segment instead of mutating the original segment

[alice-i-cecile]

Much appreciated: you always do such excellent work.