Module org.dyn4j

Class Rotation


  • public class Rotation
    extends java.lang.Object
    This class represents a rotation (in 2D space). The aim of this class is to reduce as much as possible the use of trigonometric function calls (like Math.sin/cos or Math.atan2) because the majority of those are very slow to compute. This can be achieved by pre-computing the sin and cos of the angle of the rotation. A Rotation object is essentially a vector with norm 1. This class encapsulates the above so the user need not directly use and compute those trigonometric values. This also provides implicit validation as the user cannot create a Rotation with invalid values (values not derived from cos/sin of some angle). The receiver of a Rotation object can be sure it always represents a valid rotation.
    Since:
    3.4.0
    Version:
    3.4.0
    Author:
    Manolis Tsamis
    • Field Detail

      • cost

        protected double cost
        The cosine of the angle described by this Rotation
      • sint

        protected double sint
        The sine of the angle described by this Rotation
    • Constructor Detail

      • Rotation

        protected Rotation​(double cost,
                           double sint)
        Internal constructor that directly sets the cost and sint fields of the Rotation without additional validation.
        Parameters:
        cost - The cosine of some angle
        sint - The sine of the same angle
      • Rotation

        public Rotation()
        Default constructor. Creates an identity Rotation.
      • Rotation

        public Rotation​(Rotation rotation)
        Copy constructor.
        Parameters:
        rotation - the Rotation to copy from
      • Rotation

        public Rotation​(double angle)
        Creates a Rotation from the given angle.
        Parameters:
        angle - the angle in radians
    • Method Detail

      • of

        public static Rotation of​(double angle)
        Alternative way to create a new Rotation from a given angle.
        Parameters:
        angle - in radians
        Returns:
        A Rotation for that angle
      • ofDegrees

        public static Rotation ofDegrees​(double angle)
        Alternative way to create a new Rotation from a given angle, in degrees.
        Parameters:
        angle - in degrees
        Returns:
        A Rotation for that angle
      • of

        public static Rotation of​(Vector2 direction)
        Static method to create a Rotation object from the direction of a given Vector2.
        Parameters:
        direction - The Vector2 describing a direction
        Returns:
        A Rotation with the same direction
      • of

        public static Rotation of​(double cost,
                                  double sint)
        Static method to create a Rotation from a pair of values that lie on the unit circle; That is a pair of values (x, y) such that x = cos(θ), y = sin(θ) for some value θ This method is provided for the case where the cos and sin values are already computed and the overhead can be avoided. This method will check whether those values are indeed on the unit circle and otherwise throw an IllegalArgumentException.
        Parameters:
        cost - The x value = cos(θ)
        sint - The y value = sin(θ)
        Returns:
        A Rotation defined by (cost, sint)
        Throws:
        java.lang.IllegalArgumentException - if (cost, sint) is not on the unit circle
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • equals

        public boolean equals​(Rotation rotation)
        Returns true if the cos and sin components of this Rotation are the same as the given Rotation.
        Parameters:
        rotation - the Rotation to compare to
        Returns:
        boolean
      • equals

        public boolean equals​(Rotation rotation,
                              double error)
        Returns true if the cos and sin components of this Rotation are the same as the given Rotation given the specified error.
        Parameters:
        rotation - the Rotation to compare to
        error - the error
        Returns:
        boolean
      • equals

        public boolean equals​(double angle)
        Returns true if the cos and sin components of this Rotation are the same as the given angle
        Parameters:
        angle - the angle in radians
        Returns:
        boolean
      • equals

        public boolean equals​(double angle,
                              double error)
        Returns true if the cos and sin components of this Rotation are the same as the given angle given the specified error.
        Parameters:
        angle - the angle in radians
        error - the error
        Returns:
        boolean
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • set

        public Rotation set​(double angle)
        Sets this Rotation to the given angle.
        Parameters:
        angle - the angle in radians
        Returns:
        Rotation this rotation
      • getCost

        public double getCost()
        Returns the value of cos(θ) for this Rotation.
        Returns:
        double
      • getSint

        public double getSint()
        Returns the value of sin(θ) for this Rotation.
        Returns:
        double
      • toRadians

        public double toRadians()
        Returns the angle in radians for this Rotation.
        Returns:
        double
      • toDegrees

        public double toDegrees()
        Returns the angle in degrees for this Rotation.
        Returns:
        double
      • toVector

        public Vector2 toVector()
        Returns this Rotation as a unit length direction vector.
        Returns:
        Vector2
      • toVector

        public Vector2 toVector​(double magnitude)
        Returns this Rotation as a direction vector with the given magnitude.
        Parameters:
        magnitude - the magnitude
        Returns:
        Vector2
      • rotate45Helper

        Rotation rotate45Helper​(double cost,
                                double sint)
        Internal helper method to perform rotations consisting of a 45 degree.
        Parameters:
        cost - the cos of the angle
        sint - the sin of the angle
        Returns:
        This Rotation after being set to (cost, sint) and rotated 45 degrees
      • getRotated45Helper

        Rotation getRotated45Helper​(double cost,
                                    double sint)
        Internal helper method to perform rotations consisting of a 45 degree. Returns a new Rotation object.
        Parameters:
        cost - the cos of the angle
        sint - the sin of the angle
        Returns:
        A new Rotation with initial values (cost, sint) and then rotated 45 degrees
      • rotate45

        public Rotation rotate45()
        Rotates this rotation 45 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated45

        public Rotation getRotated45()
        Rotates this rotation 45 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate90

        public Rotation rotate90()
        Rotates this rotation 90 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated90

        public Rotation getRotated90()
        Rotates this rotation 90 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate135

        public Rotation rotate135()
        Rotates this rotation 135 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated135

        public Rotation getRotated135()
        Rotates this rotation 135 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate180

        public Rotation rotate180()
        Rotates this rotation 180 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated180

        public Rotation getRotated180()
        Rotates this rotation 180 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate225

        public Rotation rotate225()
        Rotates this rotation 225 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated225

        public Rotation getRotated225()
        Rotates this rotation 225 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate270

        public Rotation rotate270()
        Rotates this rotation 270 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated270

        public Rotation getRotated270()
        Rotates this rotation 270 degrees and returns a new rotation.
        Returns:
        Rotation
      • rotate315

        public Rotation rotate315()
        Rotates this rotation 315 degrees and returns this rotation.
        Returns:
        Rotation
      • getRotated315

        public Rotation getRotated315()
        Rotates this rotation 315 degrees and returns a new rotation.
        Returns:
        Rotation
      • inverse

        public Rotation inverse()
        Negates this rotation and returns this rotation.

        Let θ be the rotation, then -θ is the inverse rotation.

        Returns:
        Rotation
      • getInversed

        public Rotation getInversed()
        Negates this rotation and returns a new rotation.

        Let θ be the rotation, then -θ is the inverse rotation.

        Returns:
        Rotation
      • rotate

        Rotation rotate​(double c,
                        double s)
        Internal method that rotates this Rotation by an angle θ and returns this rotation.
        Parameters:
        c - cos(θ)
        s - sin(θ)
        Returns:
        Rotation
      • getRotated

        public Rotation getRotated​(double c,
                                   double s)
        Internal method that return a new Rotation representing this Rotation after being rotated by an angle θ.
        Parameters:
        c - cos(θ)
        s - sin(θ)
        Returns:
        Rotation
      • rotate

        public Rotation rotate​(Rotation rotation)
        Rotates this rotation by the given rotation and returns this rotation.
        Parameters:
        rotation - the Rotation
        Returns:
        Rotation
      • getRotated

        public Rotation getRotated​(Rotation rotation)
        Rotates this rotation by the given rotation and returns a new rotation.
        Parameters:
        rotation - the Rotation
        Returns:
        Rotation
      • rotate

        public Rotation rotate​(double angle)
        Rotates this rotation by the given angle and returns this rotation.
        Parameters:
        angle - the rotation in radians
        Returns:
        Rotation
      • getRotated

        public Rotation getRotated​(double angle)
        Rotates this rotation by the given angle and returns a new rotation.
        Parameters:
        angle - the rotation in radians
        Returns:
        Rotation
      • isIdentity

        public boolean isIdentity()
        Returns true if this rotation is an identity rotation.
        Returns:
        boolean
      • isIdentity

        public boolean isIdentity​(double error)
        Returns true if this rotation is an identity rotation within the given error.
        Parameters:
        error - the error
        Returns:
        boolean
      • dot

        public double dot​(Rotation rotation)
        Returns the dot product of the this Rotation and the given Rotation which is essentially the sine of the angle between those rotations.
        Parameters:
        rotation - the Rotation
        Returns:
        double
      • cross

        public double cross​(Rotation rotation)
        Returns the cross product of the this Rotation and the given Rotation which is essentially the sine of the angle between those rotations.
        Parameters:
        rotation - the Rotation
        Returns:
        double
      • dot

        double dot​(Vector2 vector)
        Returns the dot product of the this Rotation and the given Vector2. For internal use.
        Parameters:
        vector - the Vector2
        Returns:
        double
      • cross

        double cross​(Vector2 vector)
        Returns the cross product of the this Rotation and the given Vector2. For internal use.
        Parameters:
        vector - the Vector2
        Returns:
        double
      • compare

        public int compare​(Rotation other)
        Compares this Rotation with another one, based on the angle between them (The one with -π ≤ θ ≤ π) Returns 1 if θ > 0, -1 if θ < 0 and 0 otherwise
        Parameters:
        other - the Rotation to compare to
        Returns:
        int
      • compare

        public int compare​(Vector2 other)
        Compares this Rotation with a Vector2, based on the angle between them (The one with -π ≤ θ ≤ π) Returns 1 if θ > 0, -1 if θ < 0 and 0 otherwise
        Parameters:
        other - the Vector2 to compare to
        Returns:
        int