Class Plane

java.lang.Object
org.apache.sis.math.Plane
All Implemented Interfaces:
Serializable, Cloneable, DoubleBinaryOperator

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
Version:
1.0
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    Computes the plane coefficients.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    Number of dimensions.
    private static final long
    Serial number for compatibility with different versions.
    private double
    The slope along the x values.
    private double
    The slope along the y values.
    private double
    The z value at (x,y) = (0,0).
    private static final double
    Threshold value relative to 1 ULP of other terms in the z = sx⋅x + sy⋅y + z₀ equation.
  • Constructor Summary

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

    Modifier and Type
    Method
    Description
    double
    applyAsDouble(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 org.opengis.geometry.DirectPosition> 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
    setEquation(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 java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for compatibility with different versions.
      See Also:
    • DIMENSION

      private static final int DIMENSION
      Number of dimensions.
      See Also:
    • ZERO_THRESHOLD

      private static final double ZERO_THRESHOLD
      Threshold value relative to 1 ULP of other terms in the z = sx⋅x + sy⋅y + z₀ equation. A value of 1 would be theoretically sufficient since adding a value smaller to 1 ULP to a double has no effect. Nevertheless we use a smaller value as a safety because:
      • We perform our checks using the points given by the user, but we don't know how representative those points are.
      • We perform our checks using an approximation which may result in slightly different decisions (false positives) than what we would got by a more robust check.
      This arbitrary threshold value may change in any future SIS version according experience gained.
      Note: A similar constant exists in org.apache.sis.referencing.operation.matrix.GeneralMatrix.
      See Also:
    • sx

      private double sx
      The slope along the x values. This coefficient appears in the plane equation sxx + syy + z₀.
    • sy

      private double sy
      The slope along the y values. This coefficient appears in the plane equation sxx + syy + z₀.
    • z0

      private double z0
      The z value at (x,y) = (0,0). This coefficient appears in the plane equation sxx + syy + z₀.
  • Constructor Details

    • Plane

      public Plane()
      Constructs a new plane with all coefficients initialized to Double.NaN.
    • 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:
      applyAsDouble in interface DoubleBinaryOperator
      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 setEquation(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.NaN 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:
      IllegalArgumentException - 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.NaN 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:
      IllegalArgumentException - 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:
      IllegalArgumentException - if z does not have the expected length or if a z value is Double.NaN.
      Since:
      0.8
    • fit

      public double fit(Iterable<? extends org.opengis.geometry.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.NaN 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:
      org.opengis.geometry.MismatchedDimensionException - 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:
      hashCode 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:
      toString in class Object