Module org.apache.sis.util

Package org.apache.sis.math

Class Plane

Object

Plane

All Implemented Interfaces:

Serializable, Cloneable, Double­Binary­Operator

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
• Linear­Transform­Builder
• Serialized Form

Constructor Summary

Constructors

Constructor	Description
Plane()	Constructs a new plane with all coefficients initialized to Double.Na­N.
Plane(double sx, double sy, double z0)	Constructs a new plane initialized to the given coefficients.

Method Summary

Modifier and Type	Method	Description
double	apply­As­Double(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 Direct­Position> 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	hash­Code()	Returns a hash code value for this plane.
void	set­Equation(double sx, double sy, double z0)	Sets the equation of this plane to the given coefficients.
void	set­Equation(Number sx, Number sy, Number z0)	Sets this plane from values of arbitrary Number type.
final double	slope­X()	Returns the slope along the x values.
final double	slope­Y()	Returns the slope along the y values.
String	to­String()	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, get­Class, notify, notify­All, wait, wait, wait

Constructor Details

Plane

public Plane()

Constructs a new plane with all coefficients initialized to Double.Na­N.

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:

• set­Equation(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:

apply­As­Double in interface Double­Binary­Operator

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 set­Equation(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.Na­N 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:

Illegal­Argument­Exception - 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.Na­N 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:

Illegal­Argument­Exception - 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:

Illegal­Argument­Exception - if z does not have the expected length or if a z value is Double.Na­N.

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.Na­N 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:

Mismatched­Dimension­Exception - 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:

hash­Code 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:

to­String in class Object