org.apache.sis.math

## Class Plane

- Object
- - Plane

- All Implemented Interfaces:
    Serializable, Cloneable

      public class Plane
      extends Object
      implements 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 and 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 and Description
    --- | ---
    `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 ordinate 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 ordinate 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()`

    - #### 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 ordinate 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.
      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 ordinate 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.
      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 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.
      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 ordinate 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.
      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 contains the plane's equation, as below:

      > z(x,y) = sx⋅x + sy⋅y + z₀

      Overrides:
        `toString` in class `Object`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.