Module org.apache.sis.util
Package org.apache.sis.math

# Class Plane

Object
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) = sx⋅x + sy⋅y + 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:
  - `Line`
  - `LinearTransformBuilder`
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Plane()`
  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.
  `Plane`
  `clone()`
  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 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`
  `hashCode()`
  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`
  `setEquation(Number sx, Number sy, Number z0)`
  Sets this plane from values of arbitrary `Number` type.
  `final double`
  `slopeX()`
  Returns the slope along the x values.
  `final double`
  `slopeY()`
  Returns the slope along the y values.
  `String`
  `toString()`
  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, getClass, notify, notifyAll, wait, wait, wait`

- ## 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:
      - `setEquation(double, double, double)`

- ## Method Details

  - ### slopeX

    public final double slopeX()
    Returns the slope along the x values. This coefficient appears in the plane equation sx⋅x + sy⋅y + z₀.
    Returns:
      the sx term.

  - ### slopeY

    public final double slopeY()
    Returns the slope along the y values. This coefficient appears in the plane equation sx⋅x + sy⋅y + 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 sx⋅x + sy⋅y + z₀.
    Returns:
      the z₀ term.
    See Also:
      - `z(double, double)`

  - ### 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:
      - `z0()`

  - ### 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 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:
      `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) = sx⋅x + sy⋅y + z₀

    Overrides:
      `toString` in class `Object`