org.apache.sis.math

## Class Line

- Object
- - Line

- All Implemented Interfaces:
    Serializable, Cloneable

      public class Line
      extends Object
      implements 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 and 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 and Description
    --- | ---
    `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`

- - ### 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 inverse function.
      Returns:
        the y value for the given x value.
      See Also:
        `x(double)`

    - #### 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` - ordinate x of the first point.
        `y1` - ordinate y of the first point.
        `x2` - ordinate x of the second point.
        `y2` - ordinate 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 ordinate values in the (x,y) order. This method assumes that the x values are precise and all uncertainty is in y. `Double​.NaN` ordinate 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.

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