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

    All Methods Instance Methods Concrete Methods
    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.
    `double` | `slope()` | Returns the slope.
    `String` | `toString()` | Returns a string representation of this line.
    `void` | `translate​(double dx, double dy)` | Translates the line.
    `double` | `x​(double y)` | Computes x = f⁻¹(y).
    `double` | `x0()` | Returns the x value for y = 0.
    `double` | `y​(double x)` | Computes y = f(x).
    `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 Detail

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

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