Package org.apache.sis.math

# Class Line

Object
Line

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `DoubleUnaryOperator`

public class Line extends Object implements DoubleUnaryOperator, Cloneable, Serializable
Equation of a line in a two dimensional space (x,y). A line can be expressed by the y = slope⋅x + y₀ equation where y₀ is the value of y at x = 0.

The equation parameters for a `Line` object can be set at construction time or using one of the `setLine(…)` methods. The y value can be computed for a given x value using the `y(double)` method. Method `x(double)` computes the converse and should work even if the line is vertical.

Comparison with Java2D geometries: At the difference of `Line2D` which is bounded by (x₁,y₁) and (x₂,y₂) points, `Line` objects extend toward infinity.

Since:
  0.5
See Also:
  - `Plane`
  - `LinearTransformBuilder`
  - Serialized Form

Defined in the `sis-utility` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Line()`
  Constructs an uninitialized line.
  `Line(double slope, double y0)`
  Constructs a line with the specified slope and offset.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `double`
  `applyAsDouble(double x)`
  Evaluates this equation for the given value.
  `Line`
  `clone()`
  Returns a clone of this line.
  `boolean`
  `equals(Object object)`
  Compares this line with the specified object for equality.
  `double`
  `fit(double[] x, double[] y)`
  Given a set of data points x[0 … n-1], y[0 … n-1], fits them to a straight line y = slope⋅x + y₀ in a least-squares senses.
  `double`
  `fit(Iterable<? extends DirectPosition> points)`
  Given a sequence of points, fits them to a straight line y = slope⋅x + y₀ in a least-squares senses.
  `double`
  `fit(Vector x, Vector y)`
  Given a set of data points x[0 … n-1], y[0 … n-1], fits them to a straight line y = slope⋅x + y₀ in a least-squares senses.
  `int`
  `hashCode()`
  Returns a hash code value for this line.
  `void`
  `setEquation(double slope, double y0)`
  Sets this line to the specified slope and offset.
  `void`
  `setEquation(Number slope, Number y0)`
  Sets this line from values of arbitrary `Number` type.
  `void`
  `setFromPoints(double x1, double y1, double x2, double y2)`
  Sets a line through the specified points.
  `final double`
  `slope()`
  Returns the slope.
  `String`
  `toString()`
  Returns a string representation of this line.
  `void`
  `translate(double dx, double dy)`
  Translates the line.
  `final double`
  `x(double y)`
  Computes x = f⁻¹(y).
  `final double`
  `x0()`
  Returns the x value for y = 0.
  `final double`
  `y(double x)`
  Computes y = f(x).
  `final double`
  `y0()`
  Returns the y value for x = 0.

  ### Methods inherited from class Object

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

  ### Methods inherited from interface DoubleUnaryOperator

  `andThen, compose`

- ## Constructor Details

  - ### Line

    public Line()
    Constructs an uninitialized line. All methods will return `Double​.NaN`.

  - ### Line

    public Line(double slope, double y0)
    Constructs a line with the specified slope and offset. The linear equation will be y = slope⋅x + y₀.
    Parameters:
      `slope` - the slope.
      `y0` - the y value at x = 0.
    See Also:
      - `setEquation(double, double)`

- ## Method Details

  - ### slope

    public final double slope()
    Returns the slope.
    Returns:
      the slope.
    See Also:
      - `x0()`
      - `y0()`

  - ### x0

    public final double x0()
    Returns the x value for y = 0. Coordinate (x₀, 0) is the intersection point with the x axis.
    Returns:
      the x value for y = 0.
    See Also:
      - `y0()`
      - `slope()`

  - ### x

    public final double x(double y)
    Computes x = f⁻¹(y). If the line is horizontal, then this method returns an infinite value.
    Parameters:
      `y` - the y value where to evaluate the inverse function.
    Returns:
      the x value for the given y value.
    See Also:
      - `y(double)`

  - ### y0

    public final double y0()
    Returns the y value for x = 0. Coordinate (0, y₀) is the intersection point with the y axis.
    Returns:
      the y value for x = 0.
    See Also:
      - `x0()`
      - `slope()`

  - ### y

    public final double y(double x)
    Computes y = f(x). If the line is vertical, then this method returns an infinite value.
    Parameters:
      `x` - the x value where to evaluate the function.
    Returns:
      the y value for the given x value.
    See Also:
      - `x(double)`

  - ### applyAsDouble

    public double applyAsDouble(double x)
    Evaluates this equation for the given value. The default implementation delegates to `y(x)`, 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 `DoubleUnaryOperator`
    Parameters:
      `x` - the value where to evaluate the function.
    Returns:
      the function value for the given operand.
    Since:
      1.0

  - ### translate

    public void translate(double dx, double dy)
    Translates the line. The slope stay unchanged.
    Parameters:
      `dx` - the horizontal translation.
      `dy` - the vertical translation.

  - ### setEquation

    public void setEquation(double slope, double y0)
    Sets this line to the specified slope and offset. The linear equation will be y = slope⋅x + y₀.
    Parameters:
      `slope` - the slope.
      `y0` - the y value at x = 0.
    See Also:
      - `setFromPoints(double, double, double, double)`
      - `fit(double[], double[])`

  - ### setEquation

    public void setEquation(Number slope, Number y0)
    Sets this line 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)`, but subclasses can override this method if they want to process other kind of numbers in a special way.
    Parameters:
      `slope` - the slope.
      `y0` - the y value at x = 0.
    Since:
      0.8

  - ### setFromPoints

    public void setFromPoints(double x1, double y1, double x2, double y2)
    Sets a line through the specified points. The line will continue toward infinity after the points.
    Parameters:
      `x1` - coordinate x of the first point.
      `y1` - coordinate y of the first point.
      `x2` - coordinate x of the second point.
      `y2` - coordinate y of the second point.

  - ### fit

    public double fit(double[] x, double[] y)
    Given a set of data points x[0 … n-1], y[0 … n-1], fits them to a straight line y = slope⋅x + y₀ in a least-squares senses. This method assumes that the x values are precise and all uncertainty is in y.

    The default implementation delegates to `fit(Vector, Vector)`.

    Parameters:
      `x` - vector of x values (independent variable).
      `y` - vector of y values (dependent variable).
    Returns:
      estimation of the correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
    Throws:
      `IllegalArgumentException` - if x and y do not have the same length.

  - ### fit

    public double fit(Vector x, Vector y)
    Given a set of data points x[0 … n-1], y[0 … n-1], fits them to a straight line y = slope⋅x + y₀ in a least-squares senses. This method assumes that the x values are precise and all uncertainty is in y.

    The default implementation delegates to `fit(Iterable)`.

    Parameters:
      `x` - vector of x values (independent variable).
      `y` - vector of y values (dependent variable).
    Returns:
      estimation of the correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
    Throws:
      `IllegalArgumentException` - if x and y do not have the same length.
    Since:
      0.8

  - ### fit

    public double fit(Iterable<? extends DirectPosition> points)
    Given a sequence of points, fits them to a straight line y = slope⋅x + y₀ in a least-squares senses. Points shall be two dimensional with coordinate values in the (x,y) order. This method assumes that the x values are precise and all uncertainty is in y. `Double​.NaN` coordinate values are ignored.
    Parameters:
      `points` - the two-dimensional points.
    Returns:
      estimation of the correlation coefficient. The closer this coefficient is to +1 or -1, the better the fit.
    Throws:
      `MismatchedDimensionException` - if a point is not two-dimensional.

  - ### clone

    public Line clone()
    Returns a clone of this line.
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this line.

  - ### equals

    public boolean equals(Object object)
    Compares this line with the specified object for equality.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with this line for equality.
    Returns:
      `true` if both objects are equal.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this line.
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Returns a string representation of this line. This method returns the linear equation in the form y = slope⋅x + y₀.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this line.