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

Class 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 Detail

      • 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 Detail

      • 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 Detail

      • 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(), getW(), Plane.getNormal()

      • 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:
        getU(), getW(), Plane.getNormal()

      • getEmbedding

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

      • 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​(java.lang.Object obj)
        Overrides:
        equals in class Plane

      • toString

        public java.lang.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:
        transform(Transform)