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

  Defined in the `sis-utility` module

- - ### 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

    All Methods Instance Methods Concrete Methods
    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.
    `double` | `slopeX()` | Returns the slope along the x values.
    `double` | `slopeY()` | Returns the slope along the y values.
    `String` | `toString()` | Returns a string representation of this plane.
    `double` | `x​(double y, double z)` | Computes the x value for the specified (y,z) point.
    `double` | `y​(double x, double z)` | Computes the y value for the specified (x,z) point.
    `double` | `z​(double x, double y)` | Computes the z value for the specified (x,y) point.
    `double` | `z0()` | Returns the z value at (x,y) = (0,0).

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### 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 Detail

    - #### 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`