Package net.algart.math.geometry

Class StraightLine3D

java.lang.Object
net.algart.math.geometry.StraightLine3D
All Implemented Interfaces:
Cloneable
public final class StraightLine3D extends Object implements Cloneable

Directional infinite straight line in 3D space. It is defined as some start point o=(x0,y0,z0), belonging to this straight, and some direction, represented as a unit vector d=(dx,dy,dz). The line consists of all point p=o+td, −∞<t<+∞.

This class is not thread-safe, but is thread-compatible and can be synchronized manually if multithreading access is necessary.

  • Method Summary

    Modifier and Type
    Method
    Description
    StraightLine3D
    clone()
    Returns an exact copy of this object.
    double
    distanceToStartPoint(double x, double y, double z)
    Returns the distance from the given point (x,y,z) to the start point (x0,y0,z0).
    double
    distanceToStartPointSquare(double x, double y, double z)
    Returns (x−x0)2 + (y−y0)2 + (z−z0)2.
    double
    distanceToStraight(double x, double y, double z)
    Returns the distance from the given point (x,y,z) to this straight.
    static double
    distanceToStraight(double dx, double dy, double dz, double x, double y, double z)
    Returns the distance from the given point (x,y,z) to the straight getInstanceFromOrigin(dx, dy, dz), where d=(dx,dy,dz) is some unit vector.
    double
    distanceToStraightSquare(double x, double y, double z)
    Returns the square of the distance from the given point (x,y,z) to this straight.
    static double
    distanceToStraightSquare(double dx, double dy, double dz, double x, double y, double z)
    Returns the square of the distance from the given point (x,y,z) to the straight getInstanceFromOrigin(dx, dy, dz), where d=(dx,dy,dz) is some unit vector.
    double
    dx()
    Returns x-component of the direction d.
    double
    dy()
    Returns y-component of the direction d.
    double
    dz()
    Returns z-component of the direction d.
    boolean
    equals(Object o)
    Indicates whether some other object is an instance of this class, containing the same straight line (the same o and d).
    int
    hashCode()
    Returns the hash code of this object.
    static StraightLine3D
    newLine()
    Creates some new straight line, passing through the origin (0,0,0).
    static StraightLine3D
    newLine(double x0, double y0, double z0, double dx, double dy, double dz)
    Creates new straight line, passing through the given start point (x0,y0,z0), with the given direction.
    static StraightLine3D
    newLineAlongI(double x0, double y0, double z0, Orthonormal3DBasis basis)
    Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector i of the specified basis.
    static StraightLine3D
    newLineAlongJ(double x0, double y0, double z0, Orthonormal3DBasis basis)
    Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector j of the specified basis.
    static StraightLine3D
    newLineAlongK(double x0, double y0, double z0, Orthonormal3DBasis basis)
    Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector k of the specified basis.
    static StraightLine3D
    newLineThroughOrigin(double dx, double dy, double dz)
    Creates new straight line, passing through the origin (0,0,0), with the given direction.
    double
    pointProjection(double x, double y, double z)
    Returns (x−x0)*dx + (y−y0)*dy + (z−z0)*dz.
    StraightLine3D
    setDirection(double dx, double dy, double dz)
    Sets new direction d.
    StraightLine3D
    setDirectionAlongI(Orthonormal3DBasis basis)
    Sets new direction d equal to the unit vector i of the specified basis.
    StraightLine3D
    setDirectionAlongJ(Orthonormal3DBasis basis)
    Sets new direction d equal to the unit vector j of the specified basis.
    StraightLine3D
    setDirectionAlongK(Orthonormal3DBasis basis)
    Sets new direction d equal to the unit vector k of the specified basis.
    StraightLine3D
    setDirectionAlongX()
    Sets new direction d equal to the unit vector (1,0,0).
    StraightLine3D
    setDirectionAlongY()
    Sets new direction d equal to the unit vector (0,1,0).
    StraightLine3D
    setDirectionAlongZ()
    Sets new direction d equal to the unit vector (0,0,1).
    StraightLine3D
    setRandomDirection(RandomGenerator random)
    Sets new direction randomly with uniform distribution in the space.
    StraightLine3D
    setStart(double x0, double y0, double z0)
    Sets new start point o.
    StraightLine3D
    setTo(StraightLine3D other)
    Sets this straight to be identical to the passed straight.
    StraightLine3D
    shiftAlong(double shift)
    Shift the start point o along the direction d:
    o = o + shift * d.
    Please remember that d vector is unit, so the argument is equal to the actual value of shifting the start point.
    String
    toString()
    Returns a brief string description of this object.
    double
    vectorProjection(double ax, double ay, double az)
    Returns projection of the given vector a to this straight: ax * dx + ay * dy + az * dz.
    double
    x(double t)
    Returns x0 + t * dx.
    double
    x0()
    Returns x-coordinate of the start point o.
    StraightLine3D
    x0(double x0)
    Sets x-coordinate of the start point o.
    double
    y(double t)
    Returns y0 + t * dy.
    double
    y0()
    Returns y-coordinate of the start point o.
    StraightLine3D
    y0(double y0)
    Sets y-coordinate of the start point o.
    double
    z(double t)
    Returns z0 + t * dz.
    double
    z0()
    Returns z-coordinate of the start point o.
    StraightLine3D
    z0(double z0)
    Sets z-coordinate of the start point o.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • newLine

      public static StraightLine3D newLine()
      Creates some new straight line, passing through the origin (0,0,0). The direction of this straight is (1,0,0) (x-axis), but you should not use this fact: in future versions this may change.
      Returns:
      new straight line.

    • newLineThroughOrigin

      public static StraightLine3D newLineThroughOrigin(double dx, double dy, double dz)
      Creates new straight line, passing through the origin (0,0,0), with the given direction.

      If the given d vector is not unit, it is automatically replaced with a unit vector of the same direction: all components are divided by its length. But if the vector is shorter than Orthonormal3DBasis.MIN_ALLOWED_LENGTH, an exception is thrown.

      Parameters:
      dx - x-component of the direction d.
      dy - y-component of the direction d.
      dz - z-component of the direction d.
      Returns:
      new straight line.
      Throws:
      IllegalArgumentException - if the specified vector is zero or extremely short.

    • newLine

      public static StraightLine3D newLine(double x0, double y0, double z0, double dx, double dy, double dz)
      Creates new straight line, passing through the given start point (x0,y0,z0), with the given direction.

      If the given d vector is not unit, it is automatically replaced with a unit vector of the same direction: all components are divided by its length. But if the vector is shorter than Orthonormal3DBasis.MIN_ALLOWED_LENGTH, an exception is thrown.

      Parameters:
      x0 - x-coordinate of the start point o.
      y0 - y-coordinate of the start point o.
      z0 - z-coordinate of the start point o.
      dx - x-component of the direction d.
      dy - y-component of the direction d.
      dz - z-component of the direction d.
      Returns:
      new straight line.
      Throws:
      IllegalArgumentException - if the specified vector is zero or extremely short.

    • newLineAlongI

      public static StraightLine3D newLineAlongI(double x0, double y0, double z0, Orthonormal3DBasis basis)
      Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector i of the specified basis.
      Parameters:
      x0 - x-coordinate of the start point o.
      y0 - y-coordinate of the start point o.
      z0 - z-coordinate of the start point o.
      basis - some orthonormal basis (i, j, k).
      Returns:
      new straight line.
      Throws:
      NullPointerException - if basis is null.

    • newLineAlongJ

      public static StraightLine3D newLineAlongJ(double x0, double y0, double z0, Orthonormal3DBasis basis)
      Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector j of the specified basis.
      Parameters:
      x0 - x-coordinate of the start point o.
      y0 - y-coordinate of the start point o.
      z0 - z-coordinate of the start point o.
      basis - some orthonormal basis (i, j, k).
      Returns:
      new straight line.
      Throws:
      NullPointerException - if basis is null.

    • newLineAlongK

      public static StraightLine3D newLineAlongK(double x0, double y0, double z0, Orthonormal3DBasis basis)
      Creates new straight line, passing through the given start point (x0,y0,z0) and directed along the unit vector k of the specified basis.
      Parameters:
      x0 - x-coordinate of the start point o.
      y0 - y-coordinate of the start point o.
      z0 - z-coordinate of the start point o.
      basis - some orthonormal basis (i, j, k).
      Returns:
      new straight line.
      Throws:
      NullPointerException - if basis is null.

    • x0

      public double x0()
      Returns x-coordinate of the start point o.
      Returns:
      x-coordinate of the start point o.

    • x0

      public StraightLine3D x0(double x0)
      Sets x-coordinate of the start point o.
      Parameters:
      x0 - new x-coordinate of the start point o.
      Returns:
      a reference to this object.

    • y0

      public double y0()
      Returns y-coordinate of the start point o.
      Returns:
      y-coordinate of the start point o.

    • y0

      public StraightLine3D y0(double y0)
      Sets y-coordinate of the start point o.
      Parameters:
      y0 - new y-coordinate of the start point o.
      Returns:
      a reference to this object.

    • z0

      public double z0()
      Returns z-coordinate of the start point o.
      Returns:
      z-coordinate of the start point o.

    • z0

      public StraightLine3D z0(double z0)
      Sets z-coordinate of the start point o.
      Parameters:
      z0 - new z-coordinate of the start point o.
      Returns:
      a reference to this object.

    • setStart

      public StraightLine3D setStart(double x0, double y0, double z0)
      Sets new start point o.
      Parameters:
      x0 - new x-coordinate of the start point o.
      y0 - new y-coordinate of the start point o.
      z0 - new z-coordinate of the start point o.
      Returns:
      a reference to this object.

    • dx

      public double dx()
      Returns x-component of the direction d.
      Returns:
      x-component of the direction d.

    • dy

      public double dy()
      Returns y-component of the direction d.
      Returns:
      y-component of the direction d.

    • dz

      public double dz()
      Returns z-component of the direction d.
      Returns:
      z-component of the direction d.

    • setDirection

      public StraightLine3D setDirection(double dx, double dy, double dz)
      Sets new direction d.

      If the given d vector is not unit, it is automatically replaced with a unit vector of the same direction: all components are divided by its length. But if the vector is shorter than Orthonormal3DBasis.MIN_ALLOWED_LENGTH, an exception is thrown.

      Parameters:
      dx - new x-component of the direction d.
      dy - new y-component of the direction d.
      dz - new z-component of the direction d.
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if the specified vector is zero or extremely short.

    • shiftAlong

      public StraightLine3D shiftAlong(double shift)
      Shift the start point o along the direction d:
      o = o + shift * d.
      Please remember that d vector is unit, so the argument is equal to the actual value of shifting the start point.
      Parameters:
      shift - value of shifting.
      Returns:
      a reference to this object.

    • setDirectionAlongI

      public StraightLine3D setDirectionAlongI(Orthonormal3DBasis basis)
      Sets new direction d equal to the unit vector i of the specified basis.
      Parameters:
      basis - some orthonormal basis (i, j, k).
      Returns:
      a reference to this object.
      Throws:
      NullPointerException - if basis is null.

    • setDirectionAlongJ

      public StraightLine3D setDirectionAlongJ(Orthonormal3DBasis basis)
      Sets new direction d equal to the unit vector j of the specified basis.
      Parameters:
      basis - some orthonormal basis (i, j, k).
      Returns:
      a reference to this object.
      Throws:
      NullPointerException - if basis is null.

    • setDirectionAlongK

      public StraightLine3D setDirectionAlongK(Orthonormal3DBasis basis)
      Sets new direction d equal to the unit vector k of the specified basis.
      Parameters:
      basis - some orthonormal basis (i, j, k).
      Returns:
      a reference to this object.
      Throws:
      NullPointerException - if basis is null.

    • setDirectionAlongX

      public StraightLine3D setDirectionAlongX()
      Sets new direction d equal to the unit vector (1,0,0).
      Returns:
      a reference to this object.

    • setDirectionAlongY

      public StraightLine3D setDirectionAlongY()
      Sets new direction d equal to the unit vector (0,1,0).
      Returns:
      a reference to this object.

    • setDirectionAlongZ

      public StraightLine3D setDirectionAlongZ()
      Sets new direction d equal to the unit vector (0,0,1).
      Returns:
      a reference to this object.

    • setRandomDirection

      public StraightLine3D setRandomDirection(RandomGenerator random)
      Sets new direction randomly with uniform distribution in the space. This is chosen with help of random.nextDouble() method.
      Parameters:
      random - random generator used to create the basis.
      Returns:
      a reference to this object.

    • setTo

      public StraightLine3D setTo(StraightLine3D other)
      Sets this straight to be identical to the passed straight.
      Parameters:
      other - other straight.
      Returns:
      a reference to this object.
      Throws:
      NullPointerException - if the argument is null.

    • x

      public double x(double t)
      Returns x0 + t * dx.
      Parameters:
      t - the shift value from the start point.
      Returns:
      x-coordinate of a point.

    • y

      public double y(double t)
      Returns y0 + t * dy.
      Parameters:
      t - the shift value from the start point.
      Returns:
      y-coordinate of a point.

    • z

      public double z(double t)
      Returns z0 + t * dz.
      Parameters:
      t - the shift value from the start point.
      Returns:
      z-coordinate of a point.

    • vectorProjection

      public double vectorProjection(double ax, double ay, double az)
      Returns projection of the given vector a to this straight: ax * dx + ay * dy + az * dz.

      Equivalent to Orthonormal3DBasis.scalarProduct(ax, ay, ax, dx, dy, dz).

      Parameters:
      ax - x-component of the vector.
      ay - y-component of the vector.
      az - z-component of the vector.
      Returns:
      projection of the given vector to the direction of this straight.

    • pointProjection

      public double pointProjection(double x, double y, double z)
      Returns (x−x0)*dx + (y−y0)*dy + (z−z0)*dz.
      Parameters:
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.
      Returns:
      t value for the projection of the given point to this straight.

    • distanceToStartPointSquare

      public double distanceToStartPointSquare(double x, double y, double z)
      Returns (x−x0)2 + (y−y0)2 + (z−z0)2.
      Parameters:
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.
      Returns:
      square of the distance to the start point o.

    • distanceToStartPoint

      public double distanceToStartPoint(double x, double y, double z)
      Returns the distance from the given point (x,y,z) to the start point (x0,y0,z0).

      Equivalent to Math.sqrt(distanceToStartPointSquare(x, y, z)).

      Parameters:
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.
      Returns:
      square of the distance to the start point o.

    • distanceToStraightSquare

      public double distanceToStraightSquare(double x, double y, double z)
      Returns the square of the distance from the given point (x,y,z) to this straight.

      Equivalent to StraightLine3D.distanceToStraightSquare(dx(), dy(), dz(), x - x0(), y - y0(), z - z0()).

      Parameters:
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.
      Returns:
      square of the distance between the point and this straight.

    • distanceToStraight

      public double distanceToStraight(double x, double y, double z)
      Returns the distance from the given point (x,y,z) to this straight.

      Equivalent to Math.sqrt(distanceToStraightSquare(x, y, z)).

      Parameters:
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.
      Returns:
      distance between the point and this straight.

    • toString

      public String toString()
      Returns a brief string description of this object.

      The result of this method may depend on implementation.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.

    • equals

      public boolean equals(Object o)
      Indicates whether some other object is an instance of this class, containing the same straight line (the same o and d). The corresponding coordinates are compared as in Double.equals method, i.e. they are converted to long values by Double.doubleToLongBits method and the results are compared.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to be compared for equality with this instance.
      Returns:
      true if and only if the specified object is an instance of StraightLine3D, representing the same straight line as this object.

    • hashCode

      public int hashCode()
      Returns the hash code of this object.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this object.

    • clone

      public StraightLine3D clone()
      Returns an exact copy of this object.
      Overrides:
      clone in class Object
      Returns:
      a reference to the clone.

    • distanceToStraightSquare

      public static double distanceToStraightSquare(double dx, double dy, double dz, double x, double y, double z)
      Returns the square of the distance from the given point (x,y,z) to the straight getInstanceFromOrigin(dx, dy, dz), where d=(dx,dy,dz) is some unit vector.

      This method works faster than creating a new instance of this class and calling its distanceToStraightSquare(double, double, double) method. But this method requires that the vector (dx, dy, dz) to be unit: dx * dx + dy * dy+ dz * dz = 1.0, otherwise its result will be incorrect.

      Parameters:
      dx - x-component of the unit direction vector d.
      dy - y-component of the unit direction vector d.
      dz - z-component of the unit direction vector d.
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.

    • distanceToStraight

      public static double distanceToStraight(double dx, double dy, double dz, double x, double y, double z)
      Returns the distance from the given point (x,y,z) to the straight getInstanceFromOrigin(dx, dy, dz), where d=(dx,dy,dz) is some unit vector.

      Equivalent to Math.sqrt(distanceToStraightSquare(dx, dy, dz, x, y, z)).

      Parameters:
      dx - x-component of the unit direction vector d.
      dy - y-component of the unit direction vector d.
      dz - z-component of the unit direction vector d.
      x - x-coordinate of the point.
      y - y-coordinate of the point.
      z - z-coordinate of the point.