Package com.j3d.engine.math.matrix

Class Vector3

java.lang.Object
com.j3d.engine.math.matrix.Vector3
All Implemented Interfaces:
MatrixInterface
Direct Known Subclasses:
Point
public class Vector3 extends Object implements MatrixInterface
Represents an immutable 3D vector or a point in 3D space.

This class also implements the MatrixInterface, treating the vector as a 3x1 column matrix. This allows it to be used directly in matrix operations defined in MatrixMath.

All vector operations (e.g., add, sub, mult) return a new Vector3 instance, preserving the immutability of the original.

Author:
Lehlogonolo Poole
See Also:

  • Field Details

    • x

      private final double x

    • y

      private final double y

    • z

      private final double z

    • Y

      public static Vector3 Y
      A static constant representing the unit vector along the positive Y-axis (0, 1, 0).

    • X

      public static Vector3 X
      A static constant representing the unit vector along the positive X-axis (1, 0, 0).

    • Z

      public static Vector3 Z
      A static constant representing the unit vector along the positive Z-axis (0, 0, 1).

    • NY

      public static Vector3 NY
      A static constant representing the unit vector along the negative Y-axis (0, -1, 0).

    • NX

      public static Vector3 NX
      A static constant representing the unit vector along the negative X-axis (-1, 0, 0).

    • NZ

      public static Vector3 NZ
      A static constant representing the unit vector along the negative Z-axis (0, 0, -1).

    • ZERO

      public static Vector3 ZERO
      A static constant representing the zero vector (0, 0, 0).

    • UNIT

      public static Vector3 UNIT
      A static constant representing the unit vector (1, 1, 1).

  • Constructor Details

    • Vector3

      public Vector3(double[][] m)
      Constructs a new vector 3 from a 2d matrix double array
      Parameters:
      m - The 2d matrix double array

    • Vector3

      @ConstructorProperties({"getX","getY","getZ"}) public Vector3(double x, double y, double z)
      Constructs a vector with the specified x, y, and z components.
      Parameters:
      x - The X component.
      y - The Y component.
      z - The Z component.

    • Vector3

      public Vector3()
      Constructs a zero vector (0, 0, 0).

    • Vector3

      public Vector3(boolean empty)

  • Method Details

    • isNotEmpty

      public boolean isNotEmpty()
      Checks if the vector is not set to the special "empty" value.
      Returns:
      true if the vector holds meaningful data, false otherwise.

    • of

      public static Vector3 of(MatrixInterface m)
      Creates a Vector3 from a 3x1 MatrixInterface.
      Parameters:
      m - The matrix to convert. Must have 3 rows and 1 column.
      Returns:
      A new Vector3 instance.
      Throws:
      RuntimeException - if the matrix is not 3x1.

    • getX

      public double getX()
      Returns:
      The X component of the vector.

    • getY

      public double getY()
      Returns:
      The Y component of the vector.

    • getZ

      public double getZ()
      Returns:
      The Z component of the vector.

    • dot

      public double dot(Vector3 v)
      Calculates the dot product of this vector and another.
      Parameters:
      v - The other vector.
      Returns:
      The scalar dot product.

    • normalize

      public Vector3 normalize()
      Normalizes the vector to have a magnitude of 1.
      Returns:
      A new, normalized Vector3.

    • add

      public Vector3 add(Vector3 v)
      Adds another vector to this one.
      Parameters:
      v - The vector to add.
      Returns:
      A new Vector3 representing the sum.

    • magnitude

      public double magnitude()
      Calculates the magnitude (length) of the vector.
      Returns:
      The magnitude of the vector.

    • mult

      public Vector3 mult(double scalar)
      Multiplies the vector by a scalar value.
      Parameters:
      scalar - The scalar value to multiply by.
      Returns:
      A new, scaled Vector3.

    • mult

      public Vector3 mult(Vector3 B)
      Performs component-wise multiplication (Hadamard product) with another vector.
      Parameters:
      B - The vector to multiply by.
      Returns:
      A new Vector3 with the component-wise product.

    • div

      public Vector3 div(double scalar)
      Divides the vector by a scalar value.
      Parameters:
      scalar - The scalar value to divide by.
      Returns:
      A new Vector3 with the divided values.

    • cross

      public Vector3 cross(Vector3 B)
      Calculates the cross product of this vector and another.
      Parameters:
      B - The other vector.
      Returns:
      A new Vector3 representing the cross product, which is orthogonal to both vectors.

    • sub

      public Vector3 sub(Vector3 B)
      Subtracts another vector from this one.
      Parameters:
      B - The vector to subtract.
      Returns:
      A new Vector3 representing the difference.

    • distance

      public double distance(Vector3 B)
      Calculates the Euclidean distance between this vector (as a point) and another.
      Parameters:
      B - The other vector.
      Returns:
      The distance between the two points.

    • random

      public static Vector3 random(Vector3 low, Vector3 high)
      Generates a random Vector3 with components within a specified range.
      Parameters:
      low - The lower bound vector for the range.
      high - The upper bound vector for the range.
      Returns:
      A new random Vector3.

    • copy

      public Vector3 copy()
      Creates a deep copy of this vector.
      Specified by:
      copy in interface MatrixInterface
      Returns:
      A new Vector3 instance with the same X, Y, and Z values.

    • toPoint

      public CartesianPoint toPoint(Camera cam)
      Projects this 3D vector onto a 2D Cartesian plane based on the camera's properties. This method transforms the world-space vector into camera space and then projects it onto the camera's 2D projection plane.
      Parameters:
      cam - The camera defining the viewpoint and projection.
      Returns:
      The resulting 2D CartesianPoint.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • distanceSquaredTo

      public double distanceSquaredTo(CartesianPoint point)
      Calculates the squared 2D distance from this vector's X and Y components to a CartesianPoint. The Z component is ignored. This is useful for fast 2D distance comparisons.
      Parameters:
      point - The 2D point.
      Returns:
      The squared distance in the XY plane.

    • reduceToVector3

      public static Vector3 reduceToVector3(List<Vector3> vectors, BiFunction<Vector3,Vector3,Vector3> reducer)
      Reduces a list of vectors into a single vector using a binary reducer function.
      Parameters:
      vectors - The list of vectors to reduce.
      reducer - A BiFunction that combines two vectors into one.
      Returns:
      The final reduced Vector3.

    • reduce

      public static <K> K reduce(ArrayList<Vector3> vectors, BiFunction<Vector3,K,K> reducer, K initialValue)
      A generic reduction function for a list of vectors.
      Type Parameters:
      K - The type of the accumulated value.
      Parameters:
      vectors - The list of vectors to process.
      reducer - The function to apply to each vector and the accumulated value.
      initialValue - The initial value for the reduction.
      Returns:
      The final accumulated value.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • rotateAroundAxis

      public Vector3 rotateAroundAxis(Vector3 axis, double angleDegrees)
      Rotates this vector around a given axis by a specified angle using Rodrigues' rotation formula.
      Parameters:
      axis - The axis to rotate around (should be a normalized vector).
      angleDegrees - The angle in degrees to rotate.
      Returns:
      A new Vector3 representing the rotated vector.

    • scale

      public Vector3 scale(double d)
      Scales the vector by a scalar value. Alias for mult(double).
      Parameters:
      d - The scalar value to multiply by.
      Returns:
      A new, scaled Vector3.

    • rows

      public int rows()
      Description copied from interface: MatrixInterface
      Returns the number of rows in the matrix.
      Specified by:
      rows in interface MatrixInterface
      Returns:
      The number of rows, which is always 3 for a Vector3.

    • cols

      public int cols()
      Description copied from interface: MatrixInterface
      Returns the number of columns in the matrix.
      Specified by:
      cols in interface MatrixInterface
      Returns:
      The number of columns, which is always 1 for a Vector3.

    • get

      public double get(int row, int col)
      Gets the value at a specific row in this 3x1 column matrix.
      Specified by:
      get in interface MatrixInterface
      Parameters:
      row - The row index (0 for X, 1 for Y, 2 for Z).
      col - The column index (must be 0).
      Returns:
      The value of the corresponding component.

    • get

      public double[][] get()
      Returns the underlying data as a 2D array (3x1).
      Specified by:
      get in interface MatrixInterface
      Returns:
      A new 2D double array {{X}, {Y}, {Z}}.

    • toCommandPaletteString

      public String toCommandPaletteString()
      Converts this Vector3 to command palette syntax
      Returns:
      the string version of this vector3.

    • toObject

      public EngineObject toObject()

    • stream

      public Stream<Double> stream()

    • triple

      public Triple<Double> triple()

    • acrossX

      public static Vector3 acrossX(double x)
      Creates a vector along the X-axis with the specified magnitude.
      Parameters:
      x - The magnitude along the X-axis.
      Returns:
      A new Vector3 (x, 0, 0).

    • acrossY

      public static Vector3 acrossY(double y)
      Creates a vector along the Y-axis with the specified magnitude.
      Parameters:
      y - The magnitude along the Y-axis.
      Returns:
      A new Vector3 (0, y, 0).

    • acrossZ

      public static Vector3 acrossZ(double z)
      Creates a vector along the Z-axis with the specified magnitude.
      Parameters:
      z - The magnitude along the Z-axis.
      Returns:
      A new Vector3 (0, 0, z).

    • setXComponent

      public static Vector3 setXComponent(Vector3 original, double xComp)

    • setYComponent

      public static Vector3 setYComponent(Vector3 original, double yComp)

    • setZComponent

      public static Vector3 setZComponent(Vector3 original, double zComp)

    • fromObject

      public static Vector3 fromObject(GettersPack.CallProperties callProperties, EngineObject obj)