feat: 3D ray and line primitives added

Engine.Core/Primitives/Ray3D.cs

@@ -0,0 +1,109 @@
+using System;
+
+namespace Engine.Core;
+
+/// <summary>
+/// Represents an infinite ray in 3D space.
+/// </summary>
+/// <param name="Origin">The <see cref="Vector3D"/> in 3D space where the ray starts from.</param>
+/// <param name="Direction">Normalized <see cref="Vector3D"/> indicating the ray's is direction.</param> 
+public readonly struct Ray3D(Vector3D Origin, Vector3D Direction) : IEquatable<Ray3D>
+{
+    /// <summary>
+    /// The starting point of the <see cref="Ray3D"/>.
+    /// </summary>
+    public readonly Vector3D Origin = Origin;
+
+    /// <summary>
+    /// The direction in which the <see cref="Ray3D"/> points. Should be a normalized vector.
+    /// </summary>
+    public readonly Vector3D Direction = Direction;
+
+    /// <summary>
+    /// Gets a <see cref="Ray3D"/> with the same origin but with the direction reversed.
+    /// </summary>
+    public readonly Ray3D Reversed => new(Origin, -Direction);
+
+    public static bool operator ==(Ray3D left, Ray3D right) => left.Origin == right.Origin && left.Direction == right.Direction;
+    public static bool operator !=(Ray3D left, Ray3D right) => left.Origin != right.Origin || left.Direction != right.Direction;
+    
+    public static implicit operator Ray3D(Line3D line) => new(line.From, line.From.FromTo(line.To).Normalized);
+
+    /// <summary>
+    /// Constructs a <see cref="Line3D"/> from a <see cref="Ray3D"/>, extending from its origin in the <see cref="Ray3D"/>'s direction for a given distance.
+    /// </summary>
+    /// <param name="ray">The source <see cref="Ray3D"/>.</param>
+    /// <param name="distance">The length of the line segment to create from the <see cref="Ray3D"/>.</param>
+    /// <returns>A <see cref="Line3D"/> representing the segment of the <see cref="Ray3D"/>.</returns>
+    public static Line3D GetLine(Ray3D ray, float distance)
+        => new(ray.Origin, ray.Origin + ray.Direction * distance);
+
+    /// <summary>
+    /// Evaluates the point on the <see cref="Ray3D"/> at a specified distance from its origin.
+    /// </summary>
+    /// <param name="ray">The <see cref="Ray3D"/> to evaluate.</param>
+    /// <param name="distanceFromOrigin">The distance from the origin along the <see cref="Ray3D"/>'s direction.</param>
+    /// <returns>A <see cref="Vector3D"/> representing the point at the given distance on the <see cref="Ray3D"/>.</returns>
+    public static Vector3D Evaluate(Ray3D ray, float distanceFromOrigin)
+        => ray.Origin + ray.Direction * distanceFromOrigin;
+
+    /// <summary>
+    /// Calculates the closest point on the <see cref="Ray3D"/> to the specified point.
+    /// </summary>
+    public static Vector3D ClosestPointTo(Ray3D ray, Vector3D point)
+    {
+        Vector3D originToPoint = ray.Origin.FromTo(point);
+
+        float dot = ray.Direction.Dot(originToPoint);
+
+        return ray.Origin + ray.Direction * dot;
+    }
+
+    /// <summary>
+    /// Checks if two <see cref="Ray3D"/>s are approximately equal within a specified epsilon range.
+    /// </summary>
+    /// <param name="left">The first <see cref="Ray3D"/>.</param>
+    /// <param name="right">The second <see cref="Ray3D"/>.</param>
+    /// <param name="epsilon">The epsilon range.</param>
+    /// <returns><see cref="true"/> if the <see cref="Ray3D"/>s are approximately equal; otherwise, <see cref="false"/>.</returns>
+    public static bool ApproximatelyEquals(Ray3D left, Ray3D right, float epsilon = float.Epsilon)
+        => left.Origin.ApproximatelyEquals(right.Origin, epsilon) && left.Direction.ApproximatelyEquals(right.Direction, epsilon);
+
+    /// <summary>
+    /// Determines whether the specified object is equal to the current <see cref="Ray3D"/>.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current <see cref="Ray3D"/>.</param>
+    /// <returns><see cref="true"/> if the specified object is equal to the current <see cref="Ray3D"/>; otherwise, <see cref="false"/>.</returns>
+    public override bool Equals(object? obj) => obj is Ray3D ray3D && this == ray3D;
+    public bool Equals(Ray3D other) => this == other;
+
+    /// <summary>
+    /// Generates a hash code for the <see cref="Ray3D"/>.
+    /// </summary>
+    /// <returns>A hash code for the <see cref="Ray3D"/>.</returns>
+    public override int GetHashCode() => System.HashCode.Combine(Origin, Direction);
+
+    /// <summary>
+    /// Converts the <see cref="Ray3D"/> to its string representation.
+    /// </summary>
+    /// <returns>A string representation of the <see cref="Ray3D"/>.</returns>
+    public override string ToString() => $"{nameof(Ray3D)}({Origin}, {Direction})";
+}
+
+/// <summary>
+/// Provides extension methods for the <see cref="Ray3D"/> struct.
+/// </summary>
+public static class Ray3DExtensions
+{
+    /// <inheritdoc cref="Ray3D.GetLine(Ray3D, float) />
+    public static Line3D ToLine(this Ray3D ray, float distance) => Ray3D.GetLine(ray, distance);
+
+    /// <inheritdoc cref="Ray3D.Evaluate(Ray3D, float) />
+    public static Vector3D Evaluate(this Ray3D ray, float distanceFromOrigin) => Ray3D.Evaluate(ray, distanceFromOrigin);
+
+    /// <inheritdoc cref="Ray3D.ClosestPointTo(Ray3D, Vector3D) />
+    public static Vector3D ClosestPointTo(this Ray3D ray, Vector3D point) => Ray3D.ClosestPointTo(ray, point);
+
+    /// <inheritdoc cref="Ray3D.ApproximatelyEquals(Ray3D, Ray3D, float)" />
+    public static bool ApproximatelyEquals(this Ray3D left, Ray3D right, float epsilon = float.Epsilon) => Ray3D.ApproximatelyEquals(left, right, epsilon);
+}