Vectors Package Update

lib/src/main/java/com/titanrobotics2022/geometry/AbstractPoint.java

@@ -0,0 +1,34 @@
+package com.titanrobotics2022.geometry;
+
+/**
+ *  Represents a generic geometric point.
+ *  @param <S> Type of the coordinate system that the point is defined by.
+ */
+public interface AbstractPoint<S extends CoordinateSystem> {
+
+    /**
+     *  Checks if any of the coordinates are NaN; false otherwise.
+     *  @return True if any of the coordinates are NaN; false otherwise.
+     */
+    boolean isNaN();
+
+    /**
+     *  Checks if any of the coordiantes are positive or negative infinity; false otherwise.
+     *  @return True if any of the coordiantes are positive or negative infinity; false otherwise.
+     */
+    boolean isInfinite();
+
+    /**
+     *  Get the space to which the point belongs.
+     *  @return Returns the defining space type.
+     */
+    CoordinateSystem getSpace();
+
+    /**
+     *  Asserts that two coordinates are equal with tolerance.
+     *  @param rhs Coordinate to be compared to implicit coordinate.
+     *  @param tolerance Maximum tolerance difference between coordinates.
+     *  @return True if coordinates are within tolerance of each other; false otherwise.
+     */
+    boolean equals(S rhs, double tolerance);
+}

lib/src/main/java/com/titanrobotics2022/geometry/AbstractVectorOperations.java

@@ -0,0 +1,90 @@
+package com.titanrobotics2022.geometry;
+
+/**
+ *  Represents general operations that can be performed on all geometric vectors.
+ *  @param <S> Type of the coordinate system that the vector is defined by.
+ *  @implNote All operations can be optimized for different vector spaces in implementing classes.
+ */
+public interface AbstractVectorOperations<S extends CoordinateSystem> extends AbstractPoint<S> {
+
+    /** 
+     *  Get the null vector of the vector space or origin point of the affine space.
+     *  @return null vector of the vector space or origin point of the affine space
+     */
+    S getZero();
+
+    /**
+     *  Perform addition on the lhs implicit vector with the rhs explicit vector.
+     *  <p>result = lhs + rhs
+     *  @param rhs The vector addend.
+     *  @return Sum of two vectors.
+     */
+    S plus(S rhs);
+
+    /**
+     *  Perform subtraction on the lhs implicit vector with the rhs explicit vector.
+     *  <p>result = lhs - rhs
+     *  @param rhs The vector subtractend.
+     *  @return Difference of two vectors.
+     */
+    S minus(S rhs);
+
+    /**
+     *  Perform scalar multiplication to the implicit vector.
+     *  <p>result = scalar * vector
+     *  @apiNote This method should be used to divide by scaling the vector by 1 / divisor.
+     *  User will need to check for zero division.
+     *  @param scalar Coefficient to scale vector by.
+     *  @return The scaled vector.
+     */
+    S scalarMultiply(double scalar);
+
+    /**
+     *  Same as scalar multiplication by -1 to the implicit vector.
+     *  <p>result = -1 * vector
+     *  @return A vector pointing in the opposite geometric direction with same magnitude.
+     */
+    S negate();
+
+    /**
+     *  The geometric/euclidean norm of the vector.
+     *  @return The geometric length of the vector.
+     */
+    double magnitude();
+
+    /**
+     *  The geometric/euclidean norm of the vector squared.
+     *  @implNote Should be implemented without squaring the magnitude to optimize execution.
+     *  <p>Ex: Cartesian2D magnitude squared = x * x + y * y.
+     *  @return The geometric length of the vector squared.
+     */
+    double magnitudeSquared();
+
+    /**
+     *  Computes a normalized geometric vector (magnitude 1).
+     *  @return Normalizes a vector.
+     */
+    S unitVector();
+
+    /**
+     *  Computes the dot/scalar product of an implicit and explicit geometric vector.
+     *  <p>result = lhs * rhs
+     *  @param rhs A second vector.
+     *  @return The dot product of lhs implicit and rhs explicit.
+     */
+    double dot(S rhs);
+
+    /**
+     *  The projection of implicit vector onto explicit vector.
+     *  <p>result = proj(implicit) onto explicit
+     *  @param targetVec Vector to project onto.
+     *  @return The resulting projection.
+     */
+    S projectOnto(S targetVec);
+
+    /**
+     *  The signed angle made between the vector and the positive x-axis
+     *  @return Angle in radians
+     */
+    double azimuthalAngle();
+}

lib/src/main/java/com/titanrobotics2022/geometry/CoordinateSystem.java

@@ -0,0 +1,13 @@
+package com.titanrobotics2022.geometry;
+
+/**
+ *  A generic geometric coordinate system that represents a vector space.
+ */
+public interface CoordinateSystem {
+
+    /**
+     *  Gets the number of dimensions in the space.
+     *  @return The number of dimensions in the space.
+     */
+    int getDimension();
+}

lib/src/main/java/com/titanrobotics2022/geometry/Vector2DOperations.java

@@ -0,0 +1,21 @@
+package com.titanrobotics2022.geometry;
+
+/**
+ *  Represents 2-Dimensional general operations that can be performed on all 2-Dimensional geometric vectors.
+ *  @param <S> Type of the 2-Dimensional coordinate system that the vector is defined by.
+ *  @implNote Does not check if the coordinate system contains 2 dimensions.
+ *  @implNote All operations can be optimized for different vector spaces in implementing classes.
+ */
+public interface Vector2DOperations<S extends CoordinateSystem> extends AbstractVectorOperations<S> {
+
+    /**
+     *  The cross product of two vectors.
+     *  In two dimensions such a cross product has no z dimension which means that
+     *  lhs and rhs vectors are coplanar so resulting cross product only contains the z dimension.
+     *  <p>result = lhs X rhs
+     *  @apiNote Useful for computing surface normals found in graphics computation.
+     *  @param rhs The rhs vector of the cross product.
+     *  @return The z component of the cross product (can be negative).
+     */
+    public double cross(S rhs);
+}

lib/src/main/java/com/titanrobotics2022/geometry/Vector3DOperations.java

@@ -0,0 +1,18 @@
+package com.titanrobotics2022.geometry;
+
+/**
+ *  Represents 3-Dimensional general operations that can be performed on all 3-Dimensional geometric vectors.
+ *  @param <S> Type of the 3-Dimensional coordinate system that the vector is defined by.
+ *  @implNote Does not check if the coordinate system contains 3 dimensions.
+ *  @implNote All operations can be optimized for different vector spaces in implementing classes.
+ */
+public interface Vector3DOperations<S extends CoordinateSystem> extends AbstractVectorOperations<S> {
+
+    /**
+     *  The cross product of two vectors.
+     *  <p>result = lhs X rhs
+     *  @param rhs The rhs vector of the cross product.
+     *  @return A 3-Dimensional vector.
+     */
+    public S cross(S rhs);
+}