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 toDouble.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 arbitraryNumber
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).
-
-
-
Constructor Detail
-
Plane
public Plane()
Constructs a new plane with all coefficients initialized toDouble.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 toz(x,y)
, but subclasses may override with different formulas. This method is provided for interoperability with libraries making use ofjava.util.function
.- Specified by:
applyAsDouble
in interfaceDoubleBinaryOperator
- 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 arbitraryNumber
type. This method is invoked by algorithms that may produce other kind of numbers (for example with different precision) than the usualdouble
primitive type. The default implementation delegates tosetEquation(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 invokingfit(Vector, Vector, Vector)
where all vectors have a length ofnx
×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
- Parameters:
nx
- number of columns.ny
- number of rows.z
- values of a matrix ofnx
columns byny
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 isDouble.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.
-
equals
public boolean equals(Object object)
Compares this plane with the specified object for equality.
-
hashCode
public int hashCode()
Returns a hash code value for this plane.
-
-