Package jme3utilities.math

Class VectorXZ

java.lang.Object
jme3utilities.math.VectorXZ
All Implemented Interfaces:
com.jme3.export.Savable, Comparable<ReadXZ>, ReadXZ
public class VectorXZ extends Object implements Comparable<ReadXZ>, ReadXZ, com.jme3.export.Savable
Single-precision vector with no 'y' coordinate, used to represent horizontal locations, offsets, orientations, directions, rotations, and extents. Immutable except for read(com.jme3.export.JmeImporter). For viewport coordinates, use Vector2f instead.

By convention, +X is north/forward and +Z is east/right.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final VectorXZ
    backward
    backward direction
    static final VectorXZ
    east
    east direction on map
    static final VectorXZ
    forward
    forward direction
    static final VectorXZ
    left
    left turn/rotation
    static final Logger
    logger
    message logger for this class
    static final VectorXZ
    north
    north direction on map
    static final VectorXZ
    right
    right turn/rotation
    static final VectorXZ
    south
    south direction on map
    static final VectorXZ
    west
    west direction on map
    static final VectorXZ
    zero
    a zero vector

  • Constructor Summary

    Constructors
    Constructor
    Description
    VectorXZ()
    Instantiate a zero vector.
    VectorXZ(float azimuth)
    Instantiate a unit vector from an azimuth value.
    VectorXZ(float x, float z)
    Instantiate a vector from a pair of coordinate values.
    VectorXZ(com.jme3.math.Vector3f vector3D)
    Instantiate a vector by projecting a 3-D vector onto the X-Z plane.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    aboutEquals(ReadXZ otherVector, float absoluteTolerance)
    Test for approximate equality with another vector using a Chebyshev metric.
    ReadXZ
    add(ReadXZ increment)
    Add to (translate) this vector.
    float
    azimuth()
    Determine the azimuth of this vector.
    ReadXZ
    cardinalize()
    Convert this vector to one of the 4 cardinal directions.
    ReadXZ
    clampDirection(float maxAbsAngle)
    Clamp this vector to be within a specified angle of north (the +X axis).
    ReadXZ
    clampElliptical(float maxX, float maxZ)
    Clamp this vector to be within an origin-centered, axis-aligned ellipse.
    ReadXZ
    clampLength(float radius)
    Clamp this vector to be within an origin-centered circle.
    int
    compareTo(float hX, float hZ)
    Compare lexicographically with a hypothetical vector having the specified components, distinguishing 0 and -0 and giving priority to the X components.
    int
    compareTo(ReadXZ otherVector)
    Compare lexicographically with another vector, with the X-component having priority.
    double
    cosineAngleBetween(ReadXZ otherVector)
    Determine the cosine of the angle between this vector and another.
    float
    cross(ReadXZ otherVector)
    Determine the (left-handed) cross product of this vector with another.
    float
    directionError(ReadXZ directionGoal)
    Determine a signed directional error of this vector with respect to a goal.
    ReadXZ
    divide(float scalar)
    Divide this vector by a scalar.
    double
    dot(ReadXZ otherVector)
    Determine the dot (scalar) product of this vector with another.
    boolean
    equals(float hX, float hZ)
    Test for equality with a hypothetical vector having the specified components, distinguishing 0 and -0.
    boolean
    equals(Object otherObject)
    Test for exact equivalence with another Object, distinguishing 0 and -0.
    ReadXZ
    firstQuadrant()
    Mirror (or reflect) this vector to the first quadrant.
    float
    getX()
    Read the X-component of this vector.
    float
    getZ()
    Read the Z-component of this vector.
    int
    hashCode()
    Generate the hash code for this vector.
    ReadXZ
    interpolate(ReadXZ otherVector, float otherFraction)
    Interpolate (blend) this vector with another.
    boolean
    isFirstQuadrant()
    Test whether this vector is in the first quadrant.
    boolean
    isZero()
    Test whether this vector is a zero vector.
    float
    length()
    Determine the length (or magnitude or norm) of this vector.
    double
    lengthSquared()
    Determine the squared length of this vector.
    ReadXZ
    mirrorZ()
    Mirror (or reflect) this vector across the X-axis (complex conjugate or inverse rotation).
    ReadXZ
    mult(float multiplier)
    Scale this vector by a scalar.
    ReadXZ
    mult(ReadXZ multiplier)
    Multiply this vector by another (complex product or rotate-and-scale).
    ReadXZ
    negate()
    Negate this vector (or reverse its direction or reflect it in the origin).
    ReadXZ
    normalize()
    Normalize this vector to a unit vector.
    void
    read(com.jme3.export.JmeImporter importer)
    De-serialize this instance, for example when loading from a J3O file.
    ReadXZ
    rotate(float radians)
    Rotate a vector CLOCKWISE about the +Y axis.
    ReadXZ
    scale(ReadXZ multiplier)
    Scale this vector by another (non-uniform scaling).
    ReadXZ
    subtract(ReadXZ decrement)
    Subtract from (inverse translate) this vector.
    com.jme3.math.Quaternion
    toQuaternion()
    Treating this vector as a rotation (from north), generate an equivalent Quaternion.
    com.jme3.math.Quaternion
    toQuaternion(com.jme3.math.Quaternion storeResult)
    Treating this vector as a rotation (from north), generate an equivalent Quaternion.
    String
    toString()
    Represent this vector as a text string.
    com.jme3.math.Vector3f
    toVector3f()
    Create an equivalent 3-D vector.
    com.jme3.math.Vector3f
    toVector3f(float y)
    Create an equivalent 3-D vector with the specified y value.
    com.jme3.math.Vector3f
    toVector3f(float y, com.jme3.math.Vector3f storeResult)
    Create an equivalent 3-D vector with the specified y value.
    static void
    validateNonZero(ReadXZ vector, String description)
    Validate a non-zero VectorXZ as a method argument.
    void
    write(com.jme3.export.JmeExporter exporter)
    Serialize this instance, for example when saving to a J3O file.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • logger

      public static final Logger logger
      message logger for this class

    • backward

      public static final VectorXZ backward
      backward direction

    • east

      public static final VectorXZ east
      east direction on map
      See Also:
      • Vector3f.UNIT_Z

    • forward

      public static final VectorXZ forward
      forward direction
      See Also:
      • Vector3f.UNIT_X

    • left

      public static final VectorXZ left
      left turn/rotation

    • north

      public static final VectorXZ north
      north direction on map
      See Also:
      • Vector3f.UNIT_X

    • south

      public static final VectorXZ south
      south direction on map

    • west

      public static final VectorXZ west
      west direction on map

    • zero

      public static final VectorXZ zero
      a zero vector
      See Also:
      • Vector3f.ZERO

  • Constructor Details

    • VectorXZ

      public VectorXZ()
      Instantiate a zero vector.
      See Also:

    • VectorXZ

      public VectorXZ(float azimuth)
      Instantiate a unit vector from an azimuth value.
      Parameters:
      azimuth - radians east of north

    • VectorXZ

      public VectorXZ(com.jme3.math.Vector3f vector3D)
      Instantiate a vector by projecting a 3-D vector onto the X-Z plane.
      Parameters:
      vector3D - the 3-D vector (not null, unaffected)

    • VectorXZ

      public VectorXZ(float x, float z)
      Instantiate a vector from a pair of coordinate values.
      Parameters:
      x - northing component or X coordinate or cosine
      z - easting component or Z coordinate or sine

  • Method Details

    • validateNonZero

      public static void validateNonZero(ReadXZ vector, String description)
      Validate a non-zero VectorXZ as a method argument.
      Parameters:
      vector - vector to validate (not null, non-zero)
      description - textual description of the vector
      Throws:
      IllegalArgumentException - if the vector is zero
      See Also:

    • aboutEquals

      public boolean aboutEquals(ReadXZ otherVector, float absoluteTolerance)
      Test for approximate equality with another vector using a Chebyshev metric.
      Specified by:
      aboutEquals in interface ReadXZ
      Parameters:
      otherVector - (not null)
      absoluteTolerance - (≥0)
      Returns:
      true if each component differs by tolerance or less, otherwise false

    • add

      public ReadXZ add(ReadXZ increment)
      Add to (translate) this vector.
      Specified by:
      add in interface ReadXZ
      Parameters:
      increment - vector to be added to this vector (not null)
      Returns:
      a sum vector
      See Also:
      • Vector3f.add(com.jme3.math.Vector3f)

    • azimuth

      public float azimuth()
      Determine the azimuth of this vector. Note: the directional convention is left-handed. If this vector is zero, return zero.
      Specified by:
      azimuth in interface ReadXZ
      Returns:
      angle in radians (>-Pi, ≤Pi), measured CW from north (the +X direction)

    • cardinalize

      public ReadXZ cardinalize()
      Convert this vector to one of the 4 cardinal directions. If this vector is zero, return a zero vector.
      Specified by:
      cardinalize in interface ReadXZ
      Returns:
      a unit vector (4 possible values) or a zero vector

    • clampDirection

      public ReadXZ clampDirection(float maxAbsAngle)
      Clamp this vector to be within a specified angle of north (the +X axis).
      Specified by:
      clampDirection in interface ReadXZ
      Parameters:
      maxAbsAngle - tolerance angle in radians (≥0, ≤Pi)
      Returns:
      clamped vector with same length

    • clampElliptical

      public ReadXZ clampElliptical(float maxX, float maxZ)
      Clamp this vector to be within an origin-centered, axis-aligned ellipse.
      Specified by:
      clampElliptical in interface ReadXZ
      Parameters:
      maxX - radius of the ellipse in the X-direction (≥0)
      maxZ - radius of the ellipse in the Z-direction (≥0)
      Returns:
      clamped vector with the same direction

    • clampLength

      public ReadXZ clampLength(float radius)
      Clamp this vector to be within an origin-centered circle.
      Specified by:
      clampLength in interface ReadXZ
      Parameters:
      radius - radius of the circle (≥0)
      Returns:
      clamped vector with the same direction
      See Also:

    • compareTo

      public int compareTo(float hX, float hZ)
      Compare lexicographically with a hypothetical vector having the specified components, distinguishing 0 and -0 and giving priority to the X components.
      Specified by:
      compareTo in interface ReadXZ
      Parameters:
      hX - X component of the hypothetical vector
      hZ - Z component of the hypothetical vector
      Returns:
      0 if this vector equals the hypothetical; negative if this comes before the hypothetical; positive if this comes after hypothetical

    • cosineAngleBetween

      public double cosineAngleBetween(ReadXZ otherVector)
      Determine the cosine of the angle between this vector and another. This is used to compare the similarity of direction vectors. Returns a double-precision value for precise comparisons.
      Specified by:
      cosineAngleBetween in interface ReadXZ
      Parameters:
      otherVector - the other vector (not null)
      Returns:
      the cosine of the angle (≥-1, ≤1) or 1 if either vector is zero
      See Also:
      • Vector3f.angleBetween(com.jme3.math.Vector3f)

    • cross

      public float cross(ReadXZ otherVector)
      Determine the (left-handed) cross product of this vector with another. For example, north.cross(east) = +1 and east.cross(north) = -1.
      Specified by:
      cross in interface ReadXZ
      Parameters:
      otherVector - the other vector (not null)
      Returns:
      the left-handed cross product
      See Also:
      • Vector3f.cross(com.jme3.math.Vector3f)

    • directionError

      public float directionError(ReadXZ directionGoal)
      Determine a signed directional error of this vector with respect to a goal. The result is positive if the goal is to the right and negative if the goal is to the left.
      Specified by:
      directionError in interface ReadXZ
      Parameters:
      directionGoal - goal direction (not null, not zero)
      Returns:
      the sine of the angle from the goal, or +/-1 if that angle's magnitude exceeds 90 degrees

    • divide

      public ReadXZ divide(float scalar)
      Divide this vector by a scalar.
      Specified by:
      divide in interface ReadXZ
      Parameters:
      scalar - scaling factor (not zero)
      Returns:
      a vector 'scalar' times shorter than this one, with same direction if scalar>0, opposite direction if scalar<0
      See Also:
      • Vector3f.divide(float)

    • dot

      public double dot(ReadXZ otherVector)
      Determine the dot (scalar) product of this vector with another.
      Specified by:
      dot in interface ReadXZ
      Parameters:
      otherVector - other vector (not null)
      Returns:
      the dot product
      See Also:

    • equals

      public boolean equals(float hX, float hZ)
      Test for equality with a hypothetical vector having the specified components, distinguishing 0 and -0.
      Specified by:
      equals in interface ReadXZ
      Parameters:
      hX - X component of the hypothetical vector
      hZ - Z component of the hypothetical vector
      Returns:
      true if equivalent, otherwise false

    • firstQuadrant

      public ReadXZ firstQuadrant()
      Mirror (or reflect) this vector to the first quadrant.
      Specified by:
      firstQuadrant in interface ReadXZ
      Returns:
      a mirrored vector with the same length, both components ≥0

    • getX

      public float getX()
      Read the X-component of this vector.
      Specified by:
      getX in interface ReadXZ
      Returns:
      the X-component
      See Also:
      • Vector3f.getX()

    • getZ

      public float getZ()
      Read the Z-component of this vector.
      Specified by:
      getZ in interface ReadXZ
      Returns:
      the Z-component
      See Also:
      • Vector3f.getZ()

    • interpolate

      public ReadXZ interpolate(ReadXZ otherVector, float otherFraction)
      Interpolate (blend) this vector with another.
      Specified by:
      interpolate in interface ReadXZ
      Parameters:
      otherVector - other vector (not null)
      otherFraction - how much weight to give to the other vector (≥0, ≤1, 0 → purely this, 1 → purely the other)
      Returns:
      a blended vector

    • isFirstQuadrant

      public boolean isFirstQuadrant()
      Test whether this vector is in the first quadrant.
      Specified by:
      isFirstQuadrant in interface ReadXZ
      Returns:
      true if both components are ≥0, false otherwise
      See Also:

    • isZero

      public boolean isZero()
      Test whether this vector is a zero vector.
      Specified by:
      isZero in interface ReadXZ
      Returns:
      true if both components are zero, false otherwise
      See Also:

    • length

      public float length()
      Determine the length (or magnitude or norm) of this vector.
      Specified by:
      length in interface ReadXZ
      Returns:
      the length (≥0)
      See Also:
      • Vector3f.length()

    • lengthSquared

      public double lengthSquared()
      Determine the squared length of this vector. This is used to compare the lengths of vectors. Returns a double-precision value for precise comparisons.
      Specified by:
      lengthSquared in interface ReadXZ
      Returns:
      the squared length (≥0)
      See Also:

    • mirrorZ

      public ReadXZ mirrorZ()
      Mirror (or reflect) this vector across the X-axis (complex conjugate or inverse rotation).
      Specified by:
      mirrorZ in interface ReadXZ
      Returns:
      a mirrored vector with the same length

    • mult

      public ReadXZ mult(float multiplier)
      Scale this vector by a scalar.
      Specified by:
      mult in interface ReadXZ
      Parameters:
      multiplier - scaling factor
      Returns:
      a vector 'scalar' times longer than this one, with same direction if multiplier>0, opposite direction if multiplier<0
      See Also:
      • Vector3f.mult(float)

    • mult

      public ReadXZ mult(ReadXZ multiplier)
      Multiply this vector by another (complex product or rotate-and-scale). This is NOT analogous to Vector3f.mult(Vector3f), which performs non-uniform scaling.
      Specified by:
      mult in interface ReadXZ
      Parameters:
      multiplier - rotated/scaled result for the current north (not null)
      Returns:
      the complex product
      See Also:

    • negate

      public ReadXZ negate()
      Negate this vector (or reverse its direction or reflect it in the origin). This is equivalent to #mult(-1f)
      Specified by:
      negate in interface ReadXZ
      Returns:
      a vector with same magnitude and opposite direction
      See Also:
      • Vector3f.negate()

    • normalize

      public ReadXZ normalize()
      Normalize this vector to a unit vector. If this vector is zero, return a zero vector.
      Specified by:
      normalize in interface ReadXZ
      Returns:
      a unit vector (with the same direction) or a zero vector
      See Also:
      • Vector3f.normalize()

    • rotate

      public ReadXZ rotate(float radians)
      Rotate a vector CLOCKWISE about the +Y axis. Note: This method is used to apply azimuths, which is why its angle convention is left-handed.
      Specified by:
      rotate in interface ReadXZ
      Parameters:
      radians - clockwise (LH) angle of rotation in radians
      Returns:
      a vector with the same length
      See Also:
      • Vector2f.rotateAroundOrigin(float, boolean)

    • scale

      public ReadXZ scale(ReadXZ multiplier)
      Scale this vector by another (non-uniform scaling).
      Specified by:
      scale in interface ReadXZ
      Parameters:
      multiplier - scaled result for the current north (not null)
      Returns:
      a scaled vector
      See Also:
      • Vector3f.mult(com.jme3.math.Vector3f)

    • subtract

      public ReadXZ subtract(ReadXZ decrement)
      Subtract from (inverse translate) this vector.
      Specified by:
      subtract in interface ReadXZ
      Parameters:
      decrement - vector to be subtracted from this vector (not null)
      Returns:
      a vector equal to the difference of the 2 vectors
      See Also:
      • Vector3f.subtract(com.jme3.math.Vector3f)

    • toQuaternion

      public com.jme3.math.Quaternion toQuaternion()
      Treating this vector as a rotation (from north), generate an equivalent Quaternion.
      Specified by:
      toQuaternion in interface ReadXZ
      Returns:
      a new Quaternion

    • toQuaternion

      public com.jme3.math.Quaternion toQuaternion(com.jme3.math.Quaternion storeResult)
      Treating this vector as a rotation (from north), generate an equivalent Quaternion.
      Specified by:
      toQuaternion in interface ReadXZ
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a Quaternion (either storeResult or a new instance, not null)

    • toVector3f

      public com.jme3.math.Vector3f toVector3f()
      Create an equivalent 3-D vector.
      Specified by:
      toVector3f in interface ReadXZ
      Returns:
      a new 3-D vector with y=0

    • toVector3f

      public com.jme3.math.Vector3f toVector3f(float y)
      Create an equivalent 3-D vector with the specified y value.
      Specified by:
      toVector3f in interface ReadXZ
      Parameters:
      y - the y-coordinate
      Returns:
      a new 3-D vector

    • toVector3f

      public com.jme3.math.Vector3f toVector3f(float y, com.jme3.math.Vector3f storeResult)
      Create an equivalent 3-D vector with the specified y value.
      Specified by:
      toVector3f in interface ReadXZ
      Parameters:
      y - the y-coordinate
      storeResult - storage for the result (modified if not null)
      Returns:
      a 3-D vector (either storeResult or a new instance, not null)

    • compareTo

      public int compareTo(ReadXZ otherVector)
      Compare lexicographically with another vector, with the X-component having priority.
      Specified by:
      compareTo in interface Comparable<ReadXZ>
      Parameters:
      otherVector - (not null)
      Returns:
      0 if this vector equals otherVector; negative if this comes before otherVector; positive if this comes after otherVector

    • equals

      public boolean equals(Object otherObject)
      Test for exact equivalence with another Object, distinguishing 0 and -0.
      Overrides:
      equals in class Object
      Parameters:
      otherObject - the object to compare to (may be null, unaffected)
      Returns:
      true if the objects are equivalent, otherwise false
      See Also:

    • hashCode

      public int hashCode()
      Generate the hash code for this vector.
      Overrides:
      hashCode in class Object
      Returns:
      value for use in hashing

    • toString

      public String toString()
      Represent this vector as a text string. The format is: (x=XX.XXX, z=ZZ.ZZZ)
      Overrides:
      toString in class Object
      Returns:
      descriptive string of text (not null)

    • read

      public void read(com.jme3.export.JmeImporter importer) throws IOException
      De-serialize this instance, for example when loading from a J3O file.
      Specified by:
      read in interface com.jme3.export.Savable
      Parameters:
      importer - (not null)
      Throws:
      IOException - from importer

    • write

      public void write(com.jme3.export.JmeExporter exporter) throws IOException
      Serialize this instance, for example when saving to a J3O file.
      Specified by:
      write in interface com.jme3.export.Savable
      Parameters:
      exporter - (not null)
      Throws:
      IOException - from exporter