org.apache.commons.math3.geometry.euclidean.threed

## Class Line

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

- All Implemented Interfaces:
    Embedding<Euclidean3D,Euclidean1D>

      public class Line
      extends java.lang.Object
      implements Embedding<Euclidean3D,Euclidean1D>

  The class represent lines in a three dimensional space.

  Each oriented line is intrinsically associated with an abscissa which is a coordinate on the line. The point at abscissa 0 is the orthogonal projection of the origin on the line, another equivalent way to express this is to say that it is the point of the line which is closest to the origin. Abscissa increases in the line direction.

  Since:
    3.0
  Version:
    $Id: Line.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private Vector3D` | `direction` Line direction.
    `private Vector3D` | `zero` Line point closest to the origin.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Line(Line line)` Copy constructor.
    `Line(Vector3D p1, Vector3D p2)` Build a line from two points.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Vector3D` | `closestPoint(Line line)` Compute the point of the instance closest to another line.
    `boolean` | `contains(Vector3D p)` Check if the instance contains a point.
    `double` | `distance(Line line)` Compute the shortest distance between the instance and another line.
    `double` | `distance(Vector3D p)` Compute the distance between the instance and a point.
    `double` | `getAbscissa(Vector3D point)` Get the abscissa of a point with respect to the line.
    `Vector3D` | `getDirection()` Get the normalized direction vector.
    `Vector3D` | `getOrigin()` Get the line point closest to the origin.
    `Vector3D` | `intersection(Line line)` Get the intersection point of the instance and another line.
    `boolean` | `isSimilarTo(Line line)` Check if the instance is similar to another line.
    `Vector3D` | `pointAt(double abscissa)` Get one point from the line.
    `void` | `reset(Vector3D p1, Vector3D p2)` Reset the instance as if built from two points.
    `Line` | `revert()` Get a line with reversed direction.
    `Vector3D` | `toSpace(Vector<Euclidean1D> point)` Transform a sub-space point into a space point.
    `Vector1D` | `toSubSpace(Vector<Euclidean3D> point)` Transform a space point into a sub-space point.
    `SubLine` | `wholeLine()` Build a sub-line covering the whole line.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### direction

          private Vector3D direction

      Line direction.

    - #### zero

          private Vector3D zero

      Line point closest to the origin.

  - ### Constructor Detail

    - #### Line

          public Line(Vector3D p1,
              Vector3D p2)
               throws MathIllegalArgumentException

      Build a line from two points.
      Parameters:
        `p1` - first point belonging to the line (this can be any point)
        `p2` - second point belonging to the line (this can be any point, different from p1)
      Throws:
        `MathIllegalArgumentException` - if the points are equal

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

    - #### reset

          public void reset(Vector3D p1,
                   Vector3D p2)
                     throws MathIllegalArgumentException

      Reset the instance as if built from two points.
      Parameters:
        `p1` - first point belonging to the line (this can be any point)
        `p2` - second point belonging to the line (this can be any point, different from p1)
      Throws:
        `MathIllegalArgumentException` - if the points are equal

    - #### revert

          public Line revert()

      Get a line with reversed direction.
      Returns:
        a new instance, with reversed direction

    - #### getDirection

          public Vector3D getDirection()

      Get the normalized direction vector.
      Returns:
        normalized direction vector

    - #### getOrigin

          public Vector3D getOrigin()

      Get the line point closest to the origin.
      Returns:
        line point closest to the origin

    - #### getAbscissa

          public double getAbscissa(Vector3D point)

      Get the abscissa of a point with respect to the line.

      The abscissa is 0 if the projection of the point and the projection of the frame origin on the line are the same point.

      Parameters:
        `point` - point to check
      Returns:
        abscissa of the point

    - #### pointAt

          public Vector3D pointAt(double abscissa)

      Get one point from the line.
      Parameters:
        `abscissa` - desired abscissa for the point
      Returns:
        one point belonging to the line, at specified abscissa

    - #### toSubSpace

          public Vector1D toSubSpace(Vector<Euclidean3D> point)

      Transform a space point into a sub-space point.
      Specified by:
        `toSubSpace` in interface `Embedding<Euclidean3D,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:
        `getAbscissa(Vector3D)`

    - #### toSpace

          public Vector3D toSpace(Vector<Euclidean1D> point)

      Transform a sub-space point into a space point.
      Specified by:
        `toSpace` in interface `Embedding<Euclidean3D,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:
        `pointAt(double)`

    - #### isSimilarTo

          public boolean isSimilarTo(Line line)

      Check if the instance is similar to another line.

      Lines are considered similar if they contain the same points. This does not mean they are equal since they can have opposite directions.

      Parameters:
        `line` - line to which instance should be compared
      Returns:
        true if the lines are similar

    - #### contains

          public boolean contains(Vector3D p)

      Check if the instance contains a point.
      Parameters:
        `p` - point to check
      Returns:
        true if p belongs to the line

    - #### distance

          public double distance(Vector3D p)

      Compute the distance between the instance and a point.
      Parameters:
        `p` - to check
      Returns:
        distance between the instance and the point

    - #### distance

          public double distance(Line line)

      Compute the shortest distance between the instance and another line.
      Parameters:
        `line` - line to check against the instance
      Returns:
        shortest distance between the instance and the line

    - #### closestPoint

          public Vector3D closestPoint(Line line)

      Compute the point of the instance closest to another line.
      Parameters:
        `line` - line to check against the instance
      Returns:
        point of the instance closest to another line

    - #### intersection

          public Vector3D intersection(Line line)

      Get the intersection point of the instance and another line.
      Parameters:
        `line` - other line
      Returns:
        intersection point of the instance and the other line or null if there are no intersection points

    - #### wholeLine

          public SubLine wholeLine()

      Build a sub-line covering the whole line.
      Returns:
        a sub-line covering the whole line

Copyright (c) 2003-2013 Apache Software Foundation