Package com.irurueta.geometry

Class Plane

java.lang.Object
com.irurueta.geometry.Plane
All Implemented Interfaces:
Serializable
public class Plane extends Object implements Serializable
Class defining a plane. Planes can be expressed using the following expression: A * x + B * y + C * z + D = 0
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private double
    a
    Parameter A of a plane.
    private double
    b
    Parameter B of a plane.
    private double
    c
    Parameter C of a plane.
    private double
    d
    Parameter D of a plane.
    static final double
    DEFAULT_COMPARISON_THRESHOLD
    Defines the threshold used when comparing two values.
    private static final double
    DEFAULT_ERROR_THRESHOLD
    Constant defining error threshold, which is a small value close to machine precision.
    static final double
    DEFAULT_LOCUS_THRESHOLD
    Constant defining the distance threshold to determine whether a point lays inside (is locus) this plane or not.
    private static final int
    INHOM_VECTOR_SIZE
    Constant defining the size of vector that define the direction of a plane.
    static final double
    MIN_THRESHOLD
    Minimum allowed threshold.
    private boolean
    normalized
    Defines whether the plane is already normalized or not.
    static final int
    PLANE_NUMBER_PARAMS
    Constant defining the size of the vector that contains plane parameters.
    private static final double
    PRECISION
    Machine precision.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Plane()
    Default constructor of this class.
    Plane(double[] array)
    Constructor.
    Plane(double a, double b, double c, double d)
    Constructor.
    Plane(Point3D point, double[] vector)
    Constructor of a plane from one point and its director vector.
    Plane(Point3D point, double[] vectorA, double[] vectorB)
    Constructor.
    Plane(Point3D pointA, Point3D pointB, Point3D pointC)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    areColinearPoints(Point3D pointA, Point3D pointB, Point3D pointC)
    Determines if provided points are co-linear or have a degenerate configuration.
    double[]
    asArray()
    Returns parameters of this plane as an array containing [a, b, c, d].
    void
    asArray(double[] array)
    Stores the parameters of this plane in provided array as [a, b, c, d].
    void
    closestPoint(Point3D point, Point3D result)
    Computes the point belonging to this plane closest to provided point, which will be located at signedDistance(Point3D) from this plane.
    void
    closestPoint(Point3D point, Point3D result, double threshold)
    Computes the point belonging to this plane closest to provided point, which will be located at signedDistance(Point3D) from this plane.
    static Plane
    createCanonicalPlaneAtInfinity()
    Creates a new instance of a plane located the canonical infinity.
    void
    directorVector(double[] directorVector)
    Computes director vector of this plane and stores the result in provided array.
    double
    dotProduct(Plane plane)
    Computes the dot product between the parameters A, B, C, D of this plane and the ones of provided plane.
    boolean
    equals(Plane plane)
    Checks if the plane described by this instance equals provided plane up to default comparison threshold.
    boolean
    equals(Plane plane, double threshold)
    Checks if the plane described by this instance equals provided plane up to provided threshold.
    boolean
    equals(Object obj)
    Checks if provided object equals current plane.
    double
    getA()
    Returns parameter A of this plane.
    double
    getB()
    Returns parameter B of this plane.
    double
    getC()
    Returns parameter C of this plane.
    Point3D
    getClosestPoint(Point3D point)
    Returns the point belonging to this line closest to provided point, which will be located at signedDistance(Point2D) from this line.
    Point3D
    getClosestPoint(Point3D point, double threshold)
    Returns the point belonging to this line closest to provided point, which will be located at signedDistance(Point2D) from this line.
    double
    getD()
    Returns parameter D of this plane.
    double[]
    getDirectorVector()
    Returns director vector of this plane.
    Point3D
    getIntersection(Plane otherPlane1, Plane otherPlane2)
    Computes and returns the intersection point between this plane and the other 2 provided planes.
    int
    hashCode()
    Returns hash code value.
    void
    intersection(Plane otherPlane1, Plane otherPlane2, Point3D result)
    Computes the intersection point between this plane and the other 2 provided planes.
    boolean
    isLocus(Point3D point)
    Check if provided point is locus (lays into) of the plane.
    boolean
    isLocus(Point3D point, double threshold)
    Check if provided point is locus (lays into) of the plane.
    boolean
    isNormalized()
    Returns boolean indicating whether this plane has already been normalized.
    void
    normalize()
    Normalizes the parameters of this line to increase the accuracy of some computations.
    void
    setA(double a)
    Sets parameter A of this plane.
    static void
    setAsCanonicalPlaneAtInfinity(Plane plane)
    Sets provided plane into the canonical infinity.
    void
    setB(double b)
    Sets parameter B of this plane.
    void
    setC(double c)
    Sets parameter C of this plane.
    void
    setD(double d)
    Sets parameter D of this plane.
    final void
    setParameters(double[] array)
    Sets parameters of this plane.
    final void
    setParameters(double a, double b, double c, double d)
    Sets parameters of this plane.
    final void
    setParametersFrom1PointAnd2Vectors(Point3D point, double[] vectorA, double[] vectorB)
    Sets the parameters of a plane from one point and two vectors.
    final void
    setParametersFromPointAndDirectorVector(Point3D point, double[] vector)
    Sets parameters of a plane from one point and its director vector.
    final void
    setParametersFromThreePoints(Point3D pointA, Point3D pointB, Point3D pointC)
    Computes and sets plane parameters using provided 3D points.
    double
    signedDistance(Point3D point)
    Distance between a plane and a 3D point.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • PLANE_NUMBER_PARAMS

      public static final int PLANE_NUMBER_PARAMS
      Constant defining the size of the vector that contains plane parameters.
      See Also:

    • DEFAULT_LOCUS_THRESHOLD

      public static final double DEFAULT_LOCUS_THRESHOLD
      Constant defining the distance threshold to determine whether a point lays inside (is locus) this plane or not.
      See Also:

    • MIN_THRESHOLD

      public static final double MIN_THRESHOLD
      Minimum allowed threshold.
      See Also:

    • DEFAULT_COMPARISON_THRESHOLD

      public static final double DEFAULT_COMPARISON_THRESHOLD
      Defines the threshold used when comparing two values.
      See Also:

    • PRECISION

      private static final double PRECISION
      Machine precision.
      See Also:

    • DEFAULT_ERROR_THRESHOLD

      private static final double DEFAULT_ERROR_THRESHOLD
      Constant defining error threshold, which is a small value close to machine precision.
      See Also:

    • INHOM_VECTOR_SIZE

      private static final int INHOM_VECTOR_SIZE
      Constant defining the size of vector that define the direction of a plane.
      See Also:

    • a

      private double a
      Parameter A of a plane.

    • b

      private double b
      Parameter B of a plane.

    • c

      private double c
      Parameter C of a plane.

    • d

      private double d
      Parameter D of a plane.

    • normalized

      private boolean normalized
      Defines whether the plane is already normalized or not.

  • Constructor Details

    • Plane

      public Plane()
      Default constructor of this class.

    • Plane

      public Plane(double a, double b, double c, double d)
      Constructor. This constructor accepts every parameter describing a plane in its homogeneous form: Ax + By + Cz + D = 0
      Parameters:
      a - Parameter A of this plane.
      b - Parameter B of this plane.
      c - Parameter C of this plane.
      d - Parameter D of this plane.

    • Plane

      public Plane(double[] array)
      Constructor. This constructor accepts an array containing all the parameters (a, b, c, d) describing a plane.
      Parameters:
      array - Array containing plane parameters.
      Throws:
      IllegalArgumentException - Raised if length of array is not 4.

    • Plane

      public Plane(Point3D pointA, Point3D pointB, Point3D pointC) throws ColinearPointsException
      Constructor. This constructor accepts three 3D points and computes the plane parameters so that the plane passes through provided points (they are locus).
      Parameters:
      pointA - First 3D point to compute the plane.
      pointB - Second 3D point to compute the plane.
      pointC - Third 3D point to compute the plane.
      Throws:
      ColinearPointsException - Raised if provided points lay in a line preventing a single plane to be estimated. This happens in degenerate configurations where points are co-linear and an infinite set of planes pass through them.

    • Plane

      public Plane(Point3D point, double[] vectorA, double[] vectorB) throws ParallelVectorsException
      Constructor.
      Parameters:
      point - Point laying inside the plane.
      vectorA - First vector laying in the plane.
      vectorB - Second vector laying in the plane.
      Throws:
      IllegalArgumentException - Raised if vectors length is not 3.
      ParallelVectorsException - Raised if provided vectors are parallel.

    • Plane

      public Plane(Point3D point, double[] vector)
      Constructor of a plane from one point and its director vector.
      Parameters:
      point - Point laying inside the plane.
      vector - Director vector.
      Throws:
      IllegalArgumentException - Raised if vector length is not 3.

  • Method Details

    • getA

      public double getA()
      Returns parameter A of this plane.
      Returns:
      Parameter A of this plane.

    • getB

      public double getB()
      Returns parameter B of this plane.
      Returns:
      Parameter B of this plane.

    • getC

      public double getC()
      Returns parameter C of this plane.
      Returns:
      Parameter C of this plane.

    • getD

      public double getD()
      Returns parameter D of this plane.
      Returns:
      Parameter D of this plane.

    • setParameters

      public final void setParameters(double a, double b, double c, double d)
      Sets parameters of this plane.
      Parameters:
      a - Parameter A of this plane.
      b - Parameter B of this plane.
      c - Parameter C of this plane.
      d - Parameter D of this plane.

    • setParameters

      public final void setParameters(double[] array)
      Sets parameters of this plane.
      Parameters:
      array - Array containing parameters of this plane.
      Throws:
      IllegalArgumentException - Raised if provided array does not have length equal to 4.

    • setParametersFromThreePoints

      public final void setParametersFromThreePoints(Point3D pointA, Point3D pointB, Point3D pointC) throws ColinearPointsException
      Computes and sets plane parameters using provided 3D points. A plane can be defined from just 3 points.
      Parameters:
      pointA - 1st point.
      pointB - 2nd point.
      pointC - 3rd point.
      Throws:
      ColinearPointsException - if provided points are in a co-linear or degenerate configuration.

    • areColinearPoints

      public static boolean areColinearPoints(Point3D pointA, Point3D pointB, Point3D pointC)
      Determines if provided points are co-linear or have a degenerate configuration. If returned value is true, then such points cannot be used to estimate a plane.
      Parameters:
      pointA - 1st plane.
      pointB - 2nd plane.
      pointC - 3rd plane.
      Returns:
      true if provided points co-linear, false otherwise.

    • setA

      public void setA(double a)
      Sets parameter A of this plane.
      Parameters:
      a - Parameter A.

    • setB

      public void setB(double b)
      Sets parameter B of this plane.
      Parameters:
      b - Parameter B.

    • setC

      public void setC(double c)
      Sets parameter C of this plane.
      Parameters:
      c - Parameter C.

    • setD

      public void setD(double d)
      Sets parameter D of this plane.
      Parameters:
      d - Parameter D.

    • setParametersFrom1PointAnd2Vectors

      public final void setParametersFrom1PointAnd2Vectors(Point3D point, double[] vectorA, double[] vectorB) throws ParallelVectorsException
      Sets the parameters of a plane from one point and two vectors.
      Parameters:
      point - Point laying inside the plane.
      vectorA - First vector laying in the plane.
      vectorB - Second vector laying in the plane.
      Throws:
      IllegalArgumentException - Raised if vectors length is not 3.
      ParallelVectorsException - Raised if provided vectors are parallel.

    • setParametersFromPointAndDirectorVector

      public final void setParametersFromPointAndDirectorVector(Point3D point, double[] vector)
      Sets parameters of a plane from one point and its director vector.
      Parameters:
      point - Point laying inside the plane.
      vector - Director vector.
      Throws:
      IllegalArgumentException - Raised if vector length is not 3.

    • isLocus

      public boolean isLocus(Point3D point)
      Check if provided point is locus (lays into) of the plane.
      Parameters:
      point - Point to be checked.
      Returns:
      True if point is locus of this plane, false otherwise.

    • isLocus

      public boolean isLocus(Point3D point, double threshold)
      Check if provided point is locus (lays into) of the plane.
      Parameters:
      point - Point to be checked.
      threshold - Threshold (non-negative small value) to decide if a point is locus of this plane.
      Returns:
      True if point is locus of this plane, false otherwise.
      Throws:
      IllegalArgumentException - Raised if threshold is negative.

    • signedDistance

      public double signedDistance(Point3D point)
      Distance between a plane and a 3D point. Returned distance equals to the Euclidean distance between this plane and provided point but having sign. Sign indicates whether point is at one side or the other of the plane.
      Parameters:
      point - Point whose distance to this line will be computed.
      Returns:
      Distance between this line and provided point.

    • getClosestPoint

      public Point3D getClosestPoint(Point3D point)
      Returns the point belonging to this line closest to provided point, which will be located at signedDistance(Point2D) from this line. If provided point belong to this line, then the same point will be returned as a result.
      Parameters:
      point - Point to be checked.
      Returns:
      Closest point.

    • getClosestPoint

      public Point3D getClosestPoint(Point3D point, double threshold)
      Returns the point belonging to this line closest to provided point, which will be located at signedDistance(Point2D) from this line. If provided point belong to this line, then the same point will be returned as a result.
      Parameters:
      point - Point to be checked.
      threshold - Threshold to determine whether point is locus of line or not.
      Returns:
      Closest point.
      Throws:
      IllegalArgumentException - Raised if threshold is negative.

    • closestPoint

      public void closestPoint(Point3D point, Point3D result)
      Computes the point belonging to this plane closest to provided point, which will be located at signedDistance(Point3D) from this plane. If provided point belongs to this plane, then the same point will be returned as a result.
      Parameters:
      point - Point to be checked.
      result - Instance where the closest point will be stored.

    • closestPoint

      public void closestPoint(Point3D point, Point3D result, double threshold)
      Computes the point belonging to this plane closest to provided point, which will be located at signedDistance(Point3D) from this plane. If provided point belongs to this plane, then the same point will be returned as a result.
      Parameters:
      point - Point to be checked.
      result - Instance where the closest point will be stored.
      threshold - threshold to determine whether a point is locus of this plane.
      Throws:
      IllegalArgumentException - Raised if threshold is negative.

    • asArray

      public double[] asArray()
      Returns parameters of this plane as an array containing [a, b, c, d].
      Returns:
      Array containing all the parameters that describe this plane.

    • asArray

      public void asArray(double[] array)
      Stores the parameters of this plane in provided array as [a, b, c, d].
      Parameters:
      array - Array where parameters of this plane will be stored.
      Throws:
      IllegalArgumentException - Raised if provided array doesn't have length 4.

    • normalize

      public void normalize()
      Normalizes the parameters of this line to increase the accuracy of some computations.

    • isNormalized

      public boolean isNormalized()
      Returns boolean indicating whether this plane has already been normalized.
      Returns:
      True if this plane is normalized, false otherwise.

    • getDirectorVector

      public double[] getDirectorVector()
      Returns director vector of this plane.
      Returns:
      Director vector of this plane.

    • directorVector

      public void directorVector(double[] directorVector)
      Computes director vector of this plane and stores the result in provided array.
      Parameters:
      directorVector - Array containing director vector.
      Throws:
      IllegalArgumentException - Raised if provided array does not have length 3.

    • getIntersection

      public Point3D getIntersection(Plane otherPlane1, Plane otherPlane2) throws NoIntersectionException
      Computes and returns the intersection point between this plane and the other 2 provided planes.
      Parameters:
      otherPlane1 - other plane 1.
      otherPlane2 - other plane 2.
      Returns:
      point where the three planes intersect.
      Throws:
      NoIntersectionException - if the three planes do not intersect in a single point.

    • intersection

      public void intersection(Plane otherPlane1, Plane otherPlane2, Point3D result) throws NoIntersectionException
      Computes the intersection point between this plane and the other 2 provided planes.
      Parameters:
      otherPlane1 - other plane 1.
      otherPlane2 - other plane 2.
      result - point where the intersection will be stored.
      Throws:
      NoIntersectionException - if the three planes do not intersect in a single point.

    • dotProduct

      public double dotProduct(Plane plane)
      Computes the dot product between the parameters A, B, C, D of this plane and the ones of provided plane. This method normalizes both planes to compute dot product.
      Parameters:
      plane - plane to compute dot product with.
      Returns:
      dot product value.

    • equals

      public boolean equals(Plane plane, double threshold)
      Checks if the plane described by this instance equals provided plane up to provided threshold.
      Parameters:
      plane - plane to be compared to.
      threshold - threshold grade of tolerance to determine whether the planes are equal or not. It is used because due to machine precision, the values might not be exactly equal (if not provided DEFAULT_COMPARISON_THRESHOLD is used).
      Returns:
      true if current plane and provided one are the same, false otherwise.
      Throws:
      IllegalArgumentException - if threshold is negative.

    • equals

      public boolean equals(Plane plane)
      Checks if the plane described by this instance equals provided plane up to default comparison threshold.
      Parameters:
      plane - plane to be compared to.
      Returns:
      true if current plane and provided one are the same, false otherwise.

    • equals

      public boolean equals(Object obj)
      Checks if provided object equals current plane.
      Overrides:
      equals in class Object
      Parameters:
      obj - object to compare.
      Returns:
      true if both objects are considered to be equal, false otherwise.

    • hashCode

      public int hashCode()
      Returns hash code value. This is only defined to keep the compiler happy. This method must be overridden in subclasses of this class.
      Overrides:
      hashCode in class Object
      Returns:
      Hash code.

    • createCanonicalPlaneAtInfinity

      public static Plane createCanonicalPlaneAtInfinity()
      Creates a new instance of a plane located the canonical infinity. The canonical infinity corresponds to all 3D points located at infinity (i.e. M = (X,Y,Z,W = 0), hence P = (A = 0,B = 0,C = 0, W = 1))
      Returns:
      a new instance of a plane located at the canonical infinity.

    • setAsCanonicalPlaneAtInfinity

      public static void setAsCanonicalPlaneAtInfinity(Plane plane)
      Sets provided plane into the canonical infinity. The canonical infinity corresponds to all 3D points located at infinity (i.e. M = (X,Y,Z,W = 0), hence P = (A = 0,B = 0,C = 0, W = 1))
      Parameters:
      plane - plane to be set at infinity.