Class Plane

Object
Plane
All Implemented Interfaces:
Serializable, Cloneable, Double­Binary­Operator

public class Plane extends Object implements DoubleBinaryOperator, Cloneable, Serializable
Equation of a plane in a three-dimensional space (x,y,z). The plane equation is expressed by sx, sy and z₀ coefficients as below:
z(x,y) = sxx + syy + z₀
Those coefficients can be set directly, or computed by a linear regression of this plane through a set of three-dimensional points.
Since:
0.5
See Also:

Defined in the sis-utility module

  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a new plane with all coefficients initialized to Double​.Na­N.
    Plane(double sx, double sy, double z0)
    Constructs a new plane initialized to the given coefficients.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    apply­As­Double(double x, double y)
    Evaluates this equation for the given values.
    Returns a clone of this plane.
    boolean
    equals(Object object)
    Compares this plane with the specified object for equality.
    double
    fit(double[] x, double[] y, double[] z)
    Computes the plane's coefficients from the given coordinate values.
    double
    fit(int nx, int ny, Vector z)
    Computes the plane's coefficients from values distributed on a regular grid.
    double
    fit(Iterable<? extends Direct­Position> points)
    Computes the plane's coefficients from the given sequence of points.
    double
    fit(Vector x, Vector y, Vector z)
    Computes the plane's coefficients from the given coordinate values.
    int
    Returns a hash code value for this plane.
    void
    set­Equation(double sx, double sy, double z0)
    Sets the equation of this plane to the given coefficients.
    void
    Sets this plane from values of arbitrary Number type.
    final double
    Returns the slope along the x values.
    final double
    Returns the slope along the y values.
    Returns a string representation of this plane.
    final double
    x(double y, double z)
    Computes the x value for the specified (y,z) point.
    final double
    y(double x, double z)
    Computes the y value for the specified (x,z) point.
    final double
    z(double x, double y)
    Computes the z value for the specified (x,y) point.
    final double
    z0()
    Returns the z value at (x,y) = (0,0).

    Methods inherited from class Object

    finalize, get­Class, notify, notify­All, wait, wait, wait
  • Constructor Details

    • Plane

      public Plane()
      Constructs a new plane with all coefficients initialized to Double​.Na­N.
    • Plane

      public Plane(double sx, double sy, double z0)
      Constructs a new plane initialized to the given coefficients.
      Parameters:
      sx - the slope along the x values.
      sy - the slope along the y values.
      z0 - the z value at (x,y) = (0,0).
      See Also:
  • Method Details

    • slopeX

      public final double slopeX()
      Returns the slope along the x values. This coefficient appears in the plane equation sxx + syy + z₀.
      Returns:
      the sx term.
    • slopeY

      public final double slopeY()
      Returns the slope along the y values. This coefficient appears in the plane equation sxx + syy + z₀.
      Returns:
      the sy term.
    • z0

      public final double z0()
      Returns the z value at (x,y) = (0,0). This coefficient appears in the plane equation sxx + syy + z₀.
      Returns:
      the z₀ term.
      See Also:
    • x

      public final double x(double y, double z)
      Computes the x value for the specified (y,z) point. The x value is computed using the following equation:
      x(y,z) = (z - (z₀ + sy⋅y)) / sx
      Parameters:
      y - the y value where to compute x.
      z - the z value where to compute x.
      Returns:
      the x value.
    • y

      public final double y(double x, double z)
      Computes the y value for the specified (x,z) point. The y value is computed using the following equation:
      y(x,z) = (z - (z₀ + sx⋅x)) / sy
      Parameters:
      x - the x value where to compute y.
      z - the z value where to compute y.
      Returns:
      the y value.
    • z

      public final double z(double x, double y)
      Computes the z value for the specified (x,y) point. The z value is computed using the following equation:
      z(x,y) = sx⋅x + sy⋅y + z₀
      Parameters:
      x - the x value where to compute z.
      y - the y value where to compute z.
      Returns:
      the z value.
      See Also:
    • applyAsDouble

      public double applyAsDouble(double x, double y)
      Evaluates this equation for the given values. The default implementation delegates to z(x,y), but subclasses may override with different formulas. This method is provided for interoperability with libraries making use of java​.util​.function.
      Specified by:
      apply­As­Double in interface Double­Binary­Operator
      Parameters:
      x - the first operand where to evaluate the function.
      y - the second operand where to evaluate the function.
      Returns:
      the function value for the given operands.
      Since:
      1.0
    • setEquation

      public void setEquation(double sx, double sy, double z0)
      Sets the equation of this plane to the given coefficients.
      Parameters:
      sx - the slope along the x values.
      sy - the slope along the y values.
      z0 - the z value at (x,y) = (0,0).
    • setEquation

      public void setEquation(Number sx, Number sy, Number z0)
      Sets this plane from values of arbitrary Number type. This method is invoked by algorithms that may produce other kind of numbers (for example with different precision) than the usual double primitive type. The default implementation delegates to set­Equation(double, double, double), but subclasses can override this method if they want to process other kind of numbers in a special way.
      Parameters:
      sx - the slope along the x values.
      sy - the slope along the y values.
      z0 - the z value at (x,y) = (0,0).
      Since:
      0.8
    • fit

      public double fit(double[] x, double[] y, double[] z)
      Computes the plane's coefficients from the given coordinate values. This method uses a linear regression in the least-square sense, with the assumption that the (x,y) values are precise and all uncertainty is in z. Double​.Na­N values are ignored. The result is undetermined if all points are colinear.

      The default implementation delegates to fit(Vector, Vector, Vector).

      Parameters:
      x - vector of x coordinates.
      y - vector of y coordinates.
      z - vector of z values.
      Returns:
      an estimation of the Pearson correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
      Throws:
      Illegal­Argument­Exception - if x, y and z do not have the same length.
    • fit

      public double fit(Vector x, Vector y, Vector z)
      Computes the plane's coefficients from the given coordinate values. This method uses a linear regression in the least-square sense, with the assumption that the (x,y) values are precise and all uncertainty is in z. Double​.Na­N values are ignored. The result is undetermined if all points are colinear.

      The default implementation delegates to fit(Iterable).

      Parameters:
      x - vector of x coordinates.
      y - vector of y coordinates.
      z - vector of z values.
      Returns:
      an estimation of the Pearson correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
      Throws:
      Illegal­Argument­Exception - if x, y and z do not have the same length.
      Since:
      0.8
    • fit

      public double fit(int nx, int ny, Vector z)
      Computes the plane's coefficients from values distributed on a regular grid. Invoking this method is equivalent (except for NaN handling) to invoking fit(Vector, Vector, Vector) where all vectors have a length of nx × ny and the x and y vectors have the following content:
      x and y vectors content
      x vector y vector
      0 1 2 3 4 5 … nx-1
      0 1 2 3 4 5 … nx-1
      0 1 2 3 4 5 … nx-1

      0 1 2 3 4 5 … nx-1
      0 0 0 0 0 0 … 0
      1 1 1 1 1 1 … 1
      2 2 2 2 2 2 … 2

      ny-1 ny-1 ny-1 … ny-1
      This method uses a linear regression in the least-square sense, with the assumption that the (x,y) values are precise and all uncertainty is in z. The result is undetermined if all points are colinear.
      Parameters:
      nx - number of columns.
      ny - number of rows.
      z - values of a matrix of nx columns by ny rows organized in a row-major fashion.
      Returns:
      an estimation of the Pearson correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
      Throws:
      Illegal­Argument­Exception - if z does not have the expected length or if a z value is Double​.Na­N.
      Since:
      0.8
    • fit

      public double fit(Iterable<? extends DirectPosition> points)
      Computes the plane's coefficients from the given sequence of points. This method uses a linear regression in the least-square sense, with the assumption that the (x,y) values are precise and all uncertainty is in z. Points shall be three dimensional with coordinate values in the (x,y,z) order. Double​.Na­N values are ignored. The result is undetermined if all points are colinear.
      Parameters:
      points - the three-dimensional points.
      Returns:
      an estimation of the Pearson correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
      Throws:
      Mismatched­Dimension­Exception - if a point is not three-dimensional.
    • clone

      public Plane clone()
      Returns a clone of this plane.
      Overrides:
      clone in class Object
      Returns:
      a clone of this plane.
    • equals

      public boolean equals(Object object)
      Compares this plane with the specified object for equality.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with this plane for equality.
      Returns:
      true if both objects are equal.
    • hashCode

      public int hashCode()
      Returns a hash code value for this plane.
      Overrides:
      hash­Code in class Object
    • toString

      public String toString()
      Returns a string representation of this plane. The string will contain the plane's equation, as below:
      z(x,y) = sxx + syy + z₀
      Overrides:
      to­String in class Object