Plane (Apache Commons Math 3.3 API)

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

## Class Plane

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

- All Implemented Interfaces:
    Embedding<Euclidean3D,Euclidean2D>, Hyperplane<Euclidean3D>

      public class Plane
      extends Object
      implements Hyperplane<Euclidean3D>, Embedding<Euclidean3D,Euclidean2D>

  The class represent planes in a three dimensional space.
  Since:
    3.0
  Version:
    $Id: Plane.java 1560115 2014-01-21 17:49:13Z luc $

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Plane(Plane plane)` Copy constructor.
    `Plane(Vector3D normal)` Deprecated. as of 3.3, replaced with `Plane(Vector3D, double)`
    `Plane(Vector3D normal, double tolerance)` Build a plane normal to a given direction and containing the origin.
    `Plane(Vector3D p, Vector3D normal)` Deprecated. as of 3.3, replaced with `Plane(Vector3D, Vector3D, double)`
    `Plane(Vector3D p, Vector3D normal, double tolerance)` Build a plane from a point and a normal.
    `Plane(Vector3D p1, Vector3D p2, Vector3D p3)` Deprecated. as of 3.3, replaced with `Plane(Vector3D, Vector3D, Vector3D, double)`
    `Plane(Vector3D p1, Vector3D p2, Vector3D p3, double tolerance)` Build a plane from three points.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `contains(Vector3D p)` Check if the instance contains a point.
    `Plane` | `copySelf()` Copy the instance.
    `Vector3D` | `getNormal()` Get the normalized normal vector.
    `double` | `getOffset(Plane plane)` Get the offset (oriented distance) of a parallel plane.
    `double` | `getOffset(Point<Euclidean3D> point)` Get the offset (oriented distance) of a point.
    `double` | `getOffset(Vector<Euclidean3D> vector)` Get the offset (oriented distance) of a vector.
    `Vector3D` | `getOrigin()` Get the origin point of the plane frame.
    `Vector3D` | `getPointAt(Vector2D inPlane, double offset)` Get one point from the 3D-space.
    `double` | `getTolerance()` Get the tolerance below which points are considered to belong to the hyperplane.
    `Vector3D` | `getU()` Get the plane first canonical vector.
    `Vector3D` | `getV()` Get the plane second canonical vector.
    `Vector3D` | `intersection(Line line)` Get the intersection of a line with the instance.
    `Line` | `intersection(Plane other)` Build the line shared by the instance and another plane.
    `static Vector3D` | `intersection(Plane plane1, Plane plane2, Plane plane3)` Get the intersection point of three planes.
    `boolean` | `isSimilarTo(Plane plane)` Check if the instance is similar to another plane.
    `Point<Euclidean3D>` | `project(Point<Euclidean3D> point)` Project a point to the hyperplane.
    `void` | `reset(Plane original)` Reset the instance from another one.
    `void` | `reset(Vector3D p, Vector3D normal)` Reset the instance as if built from a point and a normal.
    `void` | `revertSelf()` Revert the plane.
    `Plane` | `rotate(Vector3D center, Rotation rotation)` Rotate the plane around the specified point.
    `boolean` | `sameOrientationAs(Hyperplane<Euclidean3D> other)` Check if the instance has the same orientation as another hyperplane.
    `Vector3D` | `toSpace(Point<Euclidean2D> point)` Transform an in-plane point into a 3D space point.
    `Vector3D` | `toSpace(Vector<Euclidean2D> vector)` Transform a sub-space point into a space point.
    `Vector2D` | `toSubSpace(Point<Euclidean3D> point)` Transform a 3D space point into an in-plane point.
    `Vector2D` | `toSubSpace(Vector<Euclidean3D> vector)` Transform a space point into a sub-space point.
    `Plane` | `translate(Vector3D translation)` Translate the plane by the specified amount.
    `SubPlane` | `wholeHyperplane()` Build a region covering the whole hyperplane.
    `PolyhedronsSet` | `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

    - #### Plane

          public Plane(Vector3D normal,
               double tolerance)
                throws MathArithmeticException

      Build a plane normal to a given direction and containing the origin.
      Parameters:
        `normal` - normal direction to the plane
        `tolerance` - tolerance below which points are considered identical
      Throws:
        `MathArithmeticException` - if the normal norm is too small
      Since:
        3.3

    - #### Plane

          public Plane(Vector3D p,
               Vector3D normal,
               double tolerance)
                throws MathArithmeticException

      Build a plane from a point and a normal.
      Parameters:
        `p` - point belonging to the plane
        `normal` - normal direction to the plane
        `tolerance` - tolerance below which points are considered identical
      Throws:
        `MathArithmeticException` - if the normal norm is too small
      Since:
        3.3

    - #### Plane

          public Plane(Vector3D p1,
               Vector3D p2,
               Vector3D p3,
               double tolerance)
                throws MathArithmeticException

      Build a plane from three points.

      The plane is oriented in the direction of `(p2-p1) ^ (p3-p1)`

      Parameters:
        `p1` - first point belonging to the plane
        `p2` - second point belonging to the plane
        `p3` - third point belonging to the plane
        `tolerance` - tolerance below which points are considered identical
      Throws:
        `MathArithmeticException` - if the points do not constitute a plane
      Since:
        3.3

    - #### Plane

          @Deprecated
          public Plane(Vector3D normal)
                throws MathArithmeticException

      Deprecated. as of 3.3, replaced with `Plane(Vector3D, double)`
      Build a plane normal to a given direction and containing the origin.
      Parameters:
        `normal` - normal direction to the plane
      Throws:
        `MathArithmeticException` - if the normal norm is too small

    - #### Plane

          @Deprecated
          public Plane(Vector3D p,
                          Vector3D normal)
                throws MathArithmeticException

      Deprecated. as of 3.3, replaced with `Plane(Vector3D, Vector3D, double)`
      Build a plane from a point and a normal.
      Parameters:
        `p` - point belonging to the plane
        `normal` - normal direction to the plane
      Throws:
        `MathArithmeticException` - if the normal norm is too small

    - #### Plane

          @Deprecated
          public Plane(Vector3D p1,
                          Vector3D p2,
                          Vector3D p3)
                throws MathArithmeticException

      Deprecated. as of 3.3, replaced with `Plane(Vector3D, Vector3D, Vector3D, double)`
      Build a plane from three points.

      The plane is oriented in the direction of `(p2-p1) ^ (p3-p1)`

      Parameters:
        `p1` - first point belonging to the plane
        `p2` - second point belonging to the plane
        `p3` - third point belonging to the plane
      Throws:
        `MathArithmeticException` - if the points do not constitute a plane

    - #### Plane

          public Plane(Plane plane)

      Copy constructor.

      The instance created is completely independant of the original one. A deep copy is used, none of the underlying object are shared.

      Parameters:
        `plane` - plane to copy

  - ### Method Detail

    - #### copySelf

          public Plane 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<Euclidean3D>`
      Returns:
        a new hyperplane, copy of the instance

    - #### reset

          public void reset(Vector3D p,
                   Vector3D normal)
                     throws MathArithmeticException

      Reset the instance as if built from a point and a normal.
      Parameters:
        `p` - point belonging to the plane
        `normal` - normal direction to the plane
      Throws:
        `MathArithmeticException` - if the normal norm is too small

    - #### reset

          public void reset(Plane original)

      Reset the instance from another one.

      The updated instance is completely independant of the original one. A deep reset is used none of the underlying object is shared.

      Parameters:
        `original` - plane to reset from

    - #### getOrigin

          public Vector3D getOrigin()

      Get the origin point of the plane frame.

      The point returned is the orthogonal projection of the 3D-space origin in the plane.

      Returns:
        the origin point of the plane frame (point closest to the 3D-space origin)

    - #### getNormal

          public Vector3D getNormal()

      Get the normalized normal vector.

      The frame defined by (`getU`, `getV`, `getNormal`) is a rigth-handed orthonormalized frame).

      Returns:
        normalized normal vector
      See Also:
        `getU()`, `getV()`

    - #### getU

          public Vector3D getU()

      Get the plane first canonical vector.

      The frame defined by (`getU`, `getV`, `getNormal`) is a rigth-handed orthonormalized frame).

      Returns:
        normalized first canonical vector
      See Also:
        `getV()`, `getNormal()`

    - #### getV

          public Vector3D getV()

      Get the plane second canonical vector.

      The frame defined by (`getU`, `getV`, `getNormal`) is a rigth-handed orthonormalized frame).

      Returns:
        normalized second canonical vector
      See Also:
        `getU()`, `getNormal()`

    - #### project

          public Point<Euclidean3D> project(Point<Euclidean3D> point)

      Project a point to the hyperplane.
      Specified by:
        `project` in interface `Hyperplane<Euclidean3D>`
      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<Euclidean3D>`
      Returns:
        tolerance below which points are considered to belong to the hyperplane
      Since:
        3.3

    - #### revertSelf

          public void revertSelf()

      Revert the plane.

      Replace the instance by a similar plane with opposite orientation.

      The new plane frame is chosen in such a way that a 3D point that had `(x, y)` in-plane coordinates and `z` offset with respect to the plane and is unaffected by the change will have `(y, x)` in-plane coordinates and `-z` offset with respect to the new plane. This means that the `u` and `v` vectors returned by the `getU()` and `getV()` methods are exchanged, and the `w` vector returned by the `getNormal()` method is reversed.

    - #### toSubSpace

          public Vector2D toSubSpace(Vector<Euclidean3D> 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 Vector3D toSpace(Vector<Euclidean2D> 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 Vector2D toSubSpace(Point<Euclidean3D> point)

      Transform a 3D space point into an in-plane point.
      Specified by:
        `toSubSpace` in interface `Embedding<Euclidean3D,Euclidean2D>`
      Parameters:
        `point` - point of the space (must be a `Vector3D` instance)
      Returns:
        in-plane point (really a `Vector2D` instance)
      See Also:
        `toSpace(org.apache.commons.math3.geometry.Vector<org.apache.commons.math3.geometry.euclidean.twod.Euclidean2D>)`

    - #### toSpace

          public Vector3D toSpace(Point<Euclidean2D> point)

      Transform an in-plane point into a 3D space point.
      Specified by:
        `toSpace` in interface `Embedding<Euclidean3D,Euclidean2D>`
      Parameters:
        `point` - in-plane point (must be a `Vector2D` instance)
      Returns:
        3D space point (really a `Vector3D` instance)
      See Also:
        `toSubSpace(org.apache.commons.math3.geometry.Vector<org.apache.commons.math3.geometry.euclidean.threed.Euclidean3D>)`

    - #### getPointAt

          public Vector3D getPointAt(Vector2D inPlane,
                            double offset)

      Get one point from the 3D-space.
      Parameters:
        `inPlane` - desired in-plane coordinates for the point in the plane
        `offset` - desired offset for the point
      Returns:
        one point in the 3D-space, with given coordinates and offset relative to the plane

    - #### isSimilarTo

          public boolean isSimilarTo(Plane plane)

      Check if the instance is similar to another plane.

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

      Parameters:
        `plane` - plane to which the instance is compared
      Returns:
        true if the planes are similar

    - #### rotate

          public Plane rotate(Vector3D center,
                     Rotation rotation)

      Rotate the plane around the specified point.

      The instance is not modified, a new instance is created.

      Parameters:
        `center` - rotation center
        `rotation` - vectorial rotation operator
      Returns:
        a new plane

    - #### translate

          public Plane translate(Vector3D translation)

      Translate the plane by the specified amount.

      The instance is not modified, a new instance is created.

      Parameters:
        `translation` - translation to apply
      Returns:
        a new plane

    - #### intersection

          public Vector3D intersection(Line line)

      Get the intersection of a line with the instance.
      Parameters:
        `line` - line intersecting the instance
      Returns:
        intersection point between between the line and the instance (null if the line is parallel to the instance)

    - #### intersection

          public Line intersection(Plane other)

      Build the line shared by the instance and another plane.
      Parameters:
        `other` - other plane
      Returns:
        line at the intersection of the instance and the other plane (really a `Line` instance)

    - #### intersection

          public static Vector3D intersection(Plane plane1,
                              Plane plane2,
                              Plane plane3)

      Get the intersection point of three planes.
      Parameters:
        `plane1` - first plane1
        `plane2` - second plane2
        `plane3` - third plane2
      Returns:
        intersection point of three planes, null if some planes are parallel

    - #### wholeHyperplane

          public SubPlane wholeHyperplane()

      Build a region covering the whole hyperplane.
      Specified by:
        `wholeHyperplane` in interface `Hyperplane<Euclidean3D>`
      Returns:
        a region covering the whole hyperplane

    - #### wholeSpace

          public PolyhedronsSet wholeSpace()

      Build a region covering the whole space.
      Specified by:
        `wholeSpace` in interface `Hyperplane<Euclidean3D>`
      Returns:
        a region containing the instance (really a `PolyhedronsSet` instance)

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

    - #### getOffset

          public double getOffset(Plane plane)

      Get the offset (oriented distance) of a parallel plane.

      This method should be called only for parallel planes otherwise the result is not meaningful.

      The offset is 0 if both planes are the same, it is positive if the plane is on the plus side of the instance and negative if it is on the minus side, according to its natural orientation.

      Parameters:
        `plane` - plane to check
      Returns:
        offset of the plane

    - #### getOffset

          public double getOffset(Vector<Euclidean3D> vector)

      Get the offset (oriented distance) of a vector.
      Parameters:
        `vector` - vector to check
      Returns:
        offset of the vector

    - #### getOffset

          public double getOffset(Point<Euclidean3D> 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<Euclidean3D>`
      Parameters:
        `point` - point to check
      Returns:
        offset of the point

    - #### sameOrientationAs

          public boolean sameOrientationAs(Hyperplane<Euclidean3D> other)

      Check if the instance has the same orientation as another hyperplane.
      Specified by:
        `sameOrientationAs` in interface `Hyperplane<Euclidean3D>`
      Parameters:
        `other` - other hyperplane to check against the instance
      Returns:
        true if the instance and the other hyperplane have the same orientation

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.