Package org.apache.commons.geometry.euclidean.threed

Class EmbeddingPlane

java.lang.Object
org.apache.commons.geometry.core.partitioning.AbstractHyperplane<Vector3D>
org.apache.commons.geometry.euclidean.threed.Plane
org.apache.commons.geometry.euclidean.threed.EmbeddingPlane
All Implemented Interfaces:
Embedding<Vector3D,Vector2D>, EmbeddingHyperplane<Vector3D,Vector2D>, Hyperplane<Vector3D>
public final class EmbeddingPlane extends Plane implements EmbeddingHyperplane<Vector3D,Vector2D>
Extension of the Plane class that supports embedding of 2D subspaces in the plane. This is accomplished by defining two additional vectors, u and v, that define the x and y axes respectively of the embedded subspace. For completeness, an additional vector getW() is defined, which is simply an alias for the plane normal. Together, the vectors u, v, and w form a right-handed orthonormal basis.

The additional u and v vectors are not required to fulfill the contract of Hyperplane. Therefore, they are not considered when using instances of this type purely as a hyperplane. For example, the eq and similiarOrientation methods do not consider them.

  • Field Details

    • u

      private final Vector3D.Unit u
      First normalized vector of the plane frame (in plane).

    • v

      private final Vector3D.Unit v
      Second normalized vector of the plane frame (in plane).

  • Constructor Details

    • EmbeddingPlane

      EmbeddingPlane(Vector3D.Unit u, Vector3D.Unit v, Vector3D.Unit w, double originOffset, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Construct a new instance from an orthonormal set of basis vectors and an origin offset.
      Parameters:
      u - first vector of the basis (in plane)
      v - second vector of the basis (in plane)
      w - third vector of the basis (plane normal)
      originOffset - offset of the origin with respect to the plane.
      precision - precision context used for floating point comparisons

  • Method Details

    • getU

      public Vector3D.Unit getU()
      Get the plane first canonical vector.

      The frame defined by (u, v, w) is a right-handed orthonormalized frame).

      Returns:
      normalized first canonical vector
      See Also:

    • getV

      public Vector3D.Unit getV()
      Get the plane second canonical vector.

      The frame defined by (u, v, w) is a right-handed orthonormalized frame).

      Returns:
      normalized second canonical vector
      See Also:

    • getW

      public Vector3D.Unit getW()
      Get the plane third canonical vector, ie, the plane normal. This method is simply an alias for Plane.getNormal().

      The frame defined by u, v, w is a right-handed orthonormalized frame.

      Returns:
      normalized normal vector
      See Also:

    • getEmbedding

      public EmbeddingPlane getEmbedding()
      Return the current instance.
      Overrides:
      getEmbedding in class Plane
      Returns:
      a plane instance suitable for embedding 2D subspaces

    • toSubspace

      public Vector2D toSubspace(Vector3D point)
      Transform a 3D space point into an in-plane point.
      Specified by:
      toSubspace in interface Embedding<Vector3D,Vector2D>
      Parameters:
      point - point of the space
      Returns:
      in-plane point
      See Also:

    • toSpace

      public Vector3D toSpace(Vector2D point)
      Transform an in-plane point into a 3D space point.
      Specified by:
      toSpace in interface Embedding<Vector3D,Vector2D>
      Parameters:
      point - in-plane point
      Returns:
      3D space point
      See Also:

    • pointAt

      public Vector3D pointAt(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

    • reverse

      public EmbeddingPlane reverse()
      Build a new reversed version of this 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 Plane.getNormal() method is reversed.

      Specified by:
      reverse in interface Hyperplane<Vector3D>
      Overrides:
      reverse in class Plane
      Returns:
      a new reversed plane

    • transform

      public EmbeddingPlane transform(Transform<Vector3D> transform)
      Transform this instance using the given Transform.

      Instances are transformed by selecting 3 representative points from the plane, transforming them, and constructing a new plane from the transformed points. Since the normal is not transformed directly, but rather is constructed new from the transformed points, the relative orientations of points in the plane are preserved, even for transforms that do not preserve orientation. The example below shows a plane being transformed by a non-orientation-preserving transform. The normal of the transformed plane retains its counterclockwise relationship to the points in the plane, in contrast with the normal that is transformed directly by the transform. 

       // construct a plane from 3 points; the normal will be selected such that the
 // points are ordered counterclockwise when looking down the plane normal.
 Vector3D p1 = Vector3D.of(0, 0, 0);
 Vector3D p2 = Vector3D.of(+1, 0, 0);
 Vector3D p3 = Vector3D.of(0, +1, 0);

 Plane plane = Planes.fromPoints(p1, p2, p3, precision); // normal is (0, 0, +1)

 // create a transform that negates all x-values; this transform does not
 // preserve orientation, i.e. it will convert a right-handed system into a left-handed
 // system and vice versa
 AffineTransformMatrix3D transform = AffineTransformMatrix3D.createScale(-1, 1,  1);

 // transform the plane
 Plane transformedPlane = plane.transform(transform);

 // the plane normal is oriented such that transformed points are still ordered
 // counterclockwise when looking down the plane normal; since the point (1, 0, 0) has
 // now become (-1, 0, 0), the normal has flipped to (0, 0, -1)
 transformedPlane.getNormal();

 // directly transform the original plane normal; the normal is unchanged by the transform
 // since the target space of the transform is left-handed
 AffineTransformMatrix3D normalTransform = transform.normalTransform();
 Vector3D directlyTransformedNormal = normalTransform.apply(plane.getNormal()); // (0, 0, +1)
      Specified by:
      transform in interface Hyperplane<Vector3D>
      Overrides:
      transform in class Plane
      Parameters:
      transform - object to transform this instance with
      Returns:
      a new, transformed hyperplane

    • translate

      public EmbeddingPlane translate(Vector3D translation)
      Translate the plane by the specified amount.
      Overrides:
      translate in class Plane
      Parameters:
      translation - translation to apply
      Returns:
      a new plane

    • rotate

      public EmbeddingPlane rotate(Vector3D center, QuaternionRotation rotation)
      Rotate the plane around the specified point.
      Overrides:
      rotate in class Plane
      Parameters:
      center - rotation center
      rotation - 3-dimensional rotation
      Returns:
      a new rotated plane

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Plane

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Plane

    • toString

      public String toString()
      Overrides:
      toString in class Plane

    • subspaceTransform

      public EmbeddingPlane.SubspaceTransform subspaceTransform(Transform<Vector3D> transform)
      Get an object containing the current plane transformed by the argument along with a 2D transform that can be applied to subspace points. The subspace transform transforms subspace points such that their 3D location in the transformed plane is the same as their 3D location in the original plane after the 3D transform is applied. For example, consider the code below: 
            SubspaceTransform st = plane.subspaceTransform(transform);

      Vector2D subPt = Vector2D.of(1, 1);

      Vector3D a = transform.apply(plane.toSpace(subPt)); // transform in 3D space
      Vector3D b = st.getPlane().toSpace(st.getTransform().apply(subPt)); // transform in 2D space
      At the end of execution, the points a (which was transformed using the original 3D transform) and b (which was transformed in 2D using the subspace transform) are equivalent.
      Parameters:
      transform - the transform to apply to this instance
      Returns:
      an object containing the transformed plane along with a transform that can be applied to subspace points
      See Also: