Line (Apache Commons Math 3.6.1 API)

java.lang.Object
- org.apache.commons.math3.geometry.euclidean.twod.Line

All Implemented Interfaces:

Embedding<Euclidean2D,Euclidean1D>, Hyperplane<Euclidean2D>
```
public class Line
extends Object
implements Hyperplane<Euclidean2D>, Embedding<Euclidean2D,Euclidean1D>
```
This class represents an oriented line in the 2D plane.
An oriented line can be defined either by prolongating a line segment between two points past these points, or by one point and an angular direction (in trigonometric orientation).

Since it is oriented the two half planes at its two sides are unambiguously identified as a left half plane and a right half plane. This can be used to identify the interior and the exterior in a simple way by local properties only when part of a line is used to define part of a polygon boundary.

A line can also be used to completely define a reference frame in the plane. It is sufficient to select one specific point in the line (the orthogonal projection of the original reference frame on the line) and to use the unit vector in the line direction and the orthogonal vector oriented from left half plane to right half plane. We define two coordinates by the process, the abscissa along the line, and the offset across the line. All points of the plane are uniquely identified by these two coordinates. The line is the set of points at zero offset, the left half plane is the set of points with negative offsets and the right half plane is the set of points with positive offsets.

Since:

3.0

Constructor Summary

Constructors
Constructor and Description
`Line(Line line)` Copy constructor.
`Line(Vector2D p, double angle)` Deprecated. as of 3.3, replaced with `Line(Vector2D, double, double)`
`Line(Vector2D p, double angle, double tolerance)` Build a line from a point and an angle.
`Line(Vector2D p1, Vector2D p2)` Deprecated. as of 3.3, replaced with `Line(Vector2D, Vector2D, double)`
`Line(Vector2D p1, Vector2D p2, double tolerance)` Build a line from two points.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`contains(Vector2D p)` Check if the line contains a point.
`Line`	`copySelf()` Copy the instance.
`double`	`distance(Vector2D p)` Compute the distance between the instance and a point.
`double`	`getAngle()` Get the angle of the line.
`double`	`getOffset(Line line)` Get the offset (oriented distance) of a parallel line.
`double`	`getOffset(Point<Euclidean2D> point)` Get the offset (oriented distance) of a point.
`double`	`getOffset(Vector<Euclidean2D> vector)` Get the offset (oriented distance) of a vector.
`double`	`getOriginOffset()` Get the offset of the origin.
`Vector2D`	`getPointAt(Vector1D abscissa, double offset)` Get one point from the plane.
`Line`	`getReverse()` Get the reverse of the instance.
`double`	`getTolerance()` Get the tolerance below which points are considered to belong to the hyperplane.
`static Transform<Euclidean2D,Euclidean1D>`	`getTransform(AffineTransform transform)` Deprecated. as of 3.6, replaced with `getTransform(double, double, double, double, double, double)`
`static Transform<Euclidean2D,Euclidean1D>`	`getTransform(double cXX, double cYX, double cXY, double cYY, double cX1, double cY1)` Get a `Transform` embedding an affine transform.
`Vector2D`	`intersection(Line other)` Get the intersection point of the instance and another line.
`boolean`	`isParallelTo(Line line)` Check the instance is parallel to another line.
`Point<Euclidean2D>`	`project(Point<Euclidean2D> point)` Project a point to the hyperplane.
`void`	`reset(Vector2D p, double alpha)` Reset the instance as if built from a line and an angle.
`void`	`reset(Vector2D p1, Vector2D p2)` Reset the instance as if built from two points.
`void`	`revertSelf()` Revert the instance.
`boolean`	`sameOrientationAs(Hyperplane<Euclidean2D> other)` Check if the instance has the same orientation as another hyperplane.
`void`	`setAngle(double angle)` Set the angle of the line.
`void`	`setOriginOffset(double offset)` Set the offset of the origin.
`Vector2D`	`toSpace(Point<Euclidean1D> point)` Transform a sub-space point into a space point.
`Vector2D`	`toSpace(Vector<Euclidean1D> vector)` Transform a sub-space point into a space point.
`Vector1D`	`toSubSpace(Point<Euclidean2D> point)` Transform a space point into a sub-space point.
`Vector1D`	`toSubSpace(Vector<Euclidean2D> vector)` Transform a space point into a sub-space point.
`void`	`translateToPoint(Vector2D p)` Translate the line to force it passing by a point.
`SubLine`	`wholeHyperplane()` Build a sub-hyperplane covering the whole hyperplane.
`PolygonsSet`	`wholeSpace()` Build a region covering the whole space.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Line
```
public Line(Vector2D p1,
    Vector2D p2,
    double tolerance)
```
    Build a line from two points.
    The line is oriented from p1 to p2
    
    Parameters:
    p1 - first point
    p2 - second point
    tolerance - tolerance below which points are considered identical
    Since:
    
    3.3
  - Line
```
public Line(Vector2D p,
    double angle,
    double tolerance)
```
    Build a line from a point and an angle.
    
    Parameters:
    p - point belonging to the line
    angle - angle of the line with respect to abscissa axis
    tolerance - tolerance below which points are considered identical
    Since:
    
    3.3
  - Line
```
@Deprecated
public Line(Vector2D p1,
               Vector2D p2)
```
    Deprecated. as of 3.3, replaced with Line(Vector2D, Vector2D, double)
    
    Build a line from two points.
    The line is oriented from p1 to p2
    
    Parameters:
    p1 - first point
    p2 - second point
  - Line
```
@Deprecated
public Line(Vector2D p,
               double angle)
```
    Deprecated. as of 3.3, replaced with Line(Vector2D, double, double)
    
    Build a line from a point and an angle.
    
    Parameters:
    p - point belonging to the line
    angle - angle of the line with respect to abscissa axis
  - Line
```
public Line(Line line)
```
    Copy constructor.
    The created instance is completely independent from the original instance, it is a deep copy.
    
    Parameters:
    line - line to copy
- Method Detail
  - copySelf
```
public Line copySelf()
```
    Copy the instance.
    The instance created is completely independant of the original one. A deep copy is used, none of the underlying objects are shared (except for immutable objects).
    
    Specified by:
    
    copySelf in interface Hyperplane<Euclidean2D>
    
    Returns:
    a new hyperplane, copy of the instance
  - reset
```
public void reset(Vector2D p1,
         Vector2D p2)
```
    Reset the instance as if built from two points.
    The line is oriented from p1 to p2
    
    Parameters:
    p1 - first point
    p2 - second point
  - reset
```
public void reset(Vector2D p,
         double alpha)
```
    Reset the instance as if built from a line and an angle.
    
    Parameters:
    p - point belonging to the line
    alpha - angle of the line with respect to abscissa axis
  - revertSelf
```
public void revertSelf()
```
    Revert the instance.
  - getReverse
```
public Line getReverse()
```
    Get the reverse of the instance.
    Get a line with reversed orientation with respect to the instance.
    
    As long as neither the instance nor its reverse are modified (i.e. as long as none of the reset(Vector2D, Vector2D), reset(Vector2D, double), revertSelf(), setAngle(double) or setOriginOffset(double) methods are called), then the line and its reverse remain linked together so that line.getReverse().getReverse() == line. When one of the line is modified, the link is deleted as both instance becomes independent.
    
    Returns:
    a new line, with orientation opposite to the instance orientation
  - toSubSpace
```
public Vector1D toSubSpace(Vector<Euclidean2D> vector)
```
    Transform a space point into a sub-space point.
    
    Parameters:
    vector - n-dimension point of the space
    
    Returns:
    (n-1)-dimension point of the sub-space corresponding to the specified space point
  - toSpace
```
public Vector2D toSpace(Vector<Euclidean1D> vector)
```
    Transform a sub-space point into a space point.
    
    Parameters:
    vector - (n-1)-dimension point of the sub-space
    
    Returns:
    n-dimension point of the space corresponding to the specified sub-space point
  - toSubSpace
```
public Vector1D toSubSpace(Point<Euclidean2D> point)
```
    Transform a space point into a sub-space point.
    
    Specified by:
    
    toSubSpace in interface Embedding<Euclidean2D,Euclidean1D>
    
    Parameters:
    point - n-dimension point of the space
    
    Returns:
    (n-1)-dimension point of the sub-space corresponding to the specified space point
    See Also:
    Embedding.toSpace(org.apache.commons.math3.geometry.Point<T>)
  - toSpace
```
public Vector2D toSpace(Point<Euclidean1D> point)
```
    Transform a sub-space point into a space point.
    
    Specified by:
    
    toSpace in interface Embedding<Euclidean2D,Euclidean1D>
    
    Parameters:
    point - (n-1)-dimension point of the sub-space
    
    Returns:
    n-dimension point of the space corresponding to the specified sub-space point
    See Also:
    Embedding.toSubSpace(org.apache.commons.math3.geometry.Point<S>)
  - intersection
```
public Vector2D intersection(Line other)
```
    Get the intersection point of the instance and another line.
    
    Parameters:
    other - other line
    
    Returns:
    intersection point of the instance and the other line or null if there are no intersection points
  - project
```
public Point<Euclidean2D> project(Point<Euclidean2D> point)
```
    Project a point to the hyperplane.
    
    Specified by:
    
    project in interface Hyperplane<Euclidean2D>
    
    Parameters:
    point - point to project
    
    Returns:
    projected point
    Since:
    
    3.3
  - getTolerance
```
public double getTolerance()
```
    Get the tolerance below which points are considered to belong to the hyperplane.
    
    Specified by:
    
    getTolerance in interface Hyperplane<Euclidean2D>
    
    Returns:
    tolerance below which points are considered to belong to the hyperplane
    Since:
    
    3.3
  - wholeHyperplane
```
public SubLine wholeHyperplane()
```
    Build a sub-hyperplane covering the whole hyperplane.
    
    Specified by:
    
    wholeHyperplane in interface Hyperplane<Euclidean2D>
    
    Returns:
    a sub-hyperplane covering the whole hyperplane
  - wholeSpace
```
public PolygonsSet wholeSpace()
```
    Build a region covering the whole space.
    
    Specified by:
    
    wholeSpace in interface Hyperplane<Euclidean2D>
    
    Returns:
    a region containing the instance (really a PolygonsSet instance)
  - getOffset
```
public double getOffset(Line line)
```
    Get the offset (oriented distance) of a parallel line.
    This method should be called only for parallel lines otherwise the result is not meaningful.
    
    The offset is 0 if both lines are the same, it is positive if the line is on the right side of the instance and negative if it is on the left side, according to its natural orientation.
    
    Parameters:
    line - line to check
    
    Returns:
    offset of the line
  - getOffset
```
public double getOffset(Vector<Euclidean2D> vector)
```
    Get the offset (oriented distance) of a vector.
    
    Parameters:
    vector - vector to check
    
    Returns:
    offset of the vector
  - getOffset
```
public double getOffset(Point<Euclidean2D> point)
```
    Get the offset (oriented distance) of a point.
    The offset is 0 if the point is on the underlying hyperplane, it is positive if the point is on one particular side of the hyperplane, and it is negative if the point is on the other side, according to the hyperplane natural orientation.
    
    Specified by:
    
    getOffset in interface Hyperplane<Euclidean2D>
    
    Parameters:
    point - point to check
    
    Returns:
    offset of the point
  - sameOrientationAs
```
public boolean sameOrientationAs(Hyperplane<Euclidean2D> other)
```
    Check if the instance has the same orientation as another hyperplane.
    This method is expected to be called on parallel hyperplanes. The method should not re-check for parallelism, only for orientation, typically by testing something like the sign of the dot-products of normals.
    
    Specified by:
    
    sameOrientationAs in interface Hyperplane<Euclidean2D>
    
    Parameters:
    other - other hyperplane to check against the instance
    
    Returns:
    true if the instance and the other hyperplane have the same orientation
  - getPointAt
```
public Vector2D getPointAt(Vector1D abscissa,
                  double offset)
```
    Get one point from the plane.
    
    Parameters:
    abscissa - desired abscissa for the point
    offset - desired offset for the point
    
    Returns:
    one point in the plane, with given abscissa and offset relative to the line
  - contains
```
public boolean contains(Vector2D p)
```
    Check if the line contains a point.
    
    Parameters:
    p - point to check
    
    Returns:
    true if p belongs to the line
  - distance
```
public double distance(Vector2D p)
```
    Compute the distance between the instance and a point.
    This is a shortcut for invoking FastMath.abs(getOffset(p)), and provides consistency with what is in the org.apache.commons.math3.geometry.euclidean.threed.Line class.
    
    Parameters:
    p - to check
    
    Returns:
    distance between the instance and the point
    Since:
    
    3.1
  - isParallelTo
```
public boolean isParallelTo(Line line)
```
    Check the instance is parallel to another line.
    
    Parameters:
    line - other line to check
    
    Returns:
    true if the instance is parallel to the other line (they can have either the same or opposite orientations)
  - translateToPoint
```
public void translateToPoint(Vector2D p)
```
    Translate the line to force it passing by a point.
    
    Parameters:
    p - point by which the line should pass
  - getAngle
```
public double getAngle()
```
    Get the angle of the line.
    
    Returns:
    the angle of the line with respect to the abscissa axis
  - setAngle
```
public void setAngle(double angle)
```
    Set the angle of the line.
    
    Parameters:
    angle - new angle of the line with respect to the abscissa axis
  - getOriginOffset
```
public double getOriginOffset()
```
    Get the offset of the origin.
    
    Returns:
    the offset of the origin
  - setOriginOffset
```
public void setOriginOffset(double offset)
```
    Set the offset of the origin.
    
    Parameters:
    offset - offset of the origin
  - getTransform
```
@Deprecated
public static Transform<Euclidean2D,Euclidean1D> getTransform(AffineTransform transform)
                                                       throws MathIllegalArgumentException
```
    Deprecated. as of 3.6, replaced with getTransform(double, double, double, double, double, double)
    
    Get a Transform embedding an affine transform.
    
    Parameters:
    transform - affine transform to embed (must be inversible otherwise the apply(Hyperplane) method would work only for some lines, and fail for other ones)
    
    Returns:
    a new transform that can be applied to either Vector2D, Line or SubHyperplane instances
    
    Throws:
    
    MathIllegalArgumentException - if the transform is non invertible
  - getTransform
```
public static Transform<Euclidean2D,Euclidean1D> getTransform(double cXX,
                                              double cYX,
                                              double cXY,
                                              double cYY,
                                              double cX1,
                                              double cY1)
                                                       throws MathIllegalArgumentException
```
    Get a Transform embedding an affine transform.
    
    Parameters:
    cXX - transform factor between input abscissa and output abscissa
    cYX - transform factor between input abscissa and output ordinate
    cXY - transform factor between input ordinate and output abscissa
    cYY - transform factor between input ordinate and output ordinate
    cX1 - transform addendum for output abscissa
    cY1 - transform addendum for output ordinate
    
    Returns:
    a new transform that can be applied to either Vector2D, Line or SubHyperplane instances
    
    Throws:
    
    MathIllegalArgumentException - if the transform is non invertible
    Since:
    
    3.6

Class Line

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Line

Line

Line

Line

Line

Method Detail

copySelf

reset

reset

revertSelf

getReverse

toSubSpace

toSpace

toSubSpace

toSpace

intersection

project

getTolerance

wholeHyperplane

wholeSpace

getOffset

getOffset

getOffset

sameOrientationAs

getPointAt

contains

distance

isParallelTo

translateToPoint

getAngle

setAngle

getOriginOffset

setOriginOffset

getTransform

getTransform