/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.geometry.euclidean.threed;
  
  import java.util.Objects;
  
  import org.apache.commons.geometry.core.Transform;
  import org.apache.commons.geometry.core.partitioning.EmbeddingHyperplane;
  import org.apache.commons.geometry.euclidean.threed.rotation.QuaternionRotation;
  import org.apache.commons.geometry.euclidean.twod.AffineTransformMatrix2D;
  import org.apache.commons.geometry.euclidean.twod.Vector2D;
  import org.apache.commons.numbers.core.Precision;
  
  /** Extension of the {@link Plane} class that supports embedding of 2D subspaces in the plane.
   * This is accomplished by defining two additional vectors, {@link #getU() u} and {@link #getV() v},
   * that define the {@code x} and {@code y} axes respectively of the embedded subspace. For completeness,
   * an additional vector {@link #getW()} is defined, which is simply an alias for the plane normal.
   * Together, the vectors {@code u}, {@code v}, and {@code w} form a right-handed orthonormal basis.
   *
   * <p>The additional {@code u} and {@code v} vectors are not required to fulfill the contract of
   * {@link org.apache.commons.geometry.core.partitioning.Hyperplane Hyperplane}. Therefore, they
   * are not considered when using instances of this type purely as a hyperplane. For example, the
   * {@link Plane#eq(Plane, Precision.DoubleEquivalence) eq} and
   * {@link Plane#similarOrientation(org.apache.commons.geometry.core.partitioning.Hyperplane) similiarOrientation}
   * methods do not consider them.</p>
   */
  public final class EmbeddingPlane extends Plane implements EmbeddingHyperplane<Vector3D, Vector2D> {
      /** First normalized vector of the plane frame (in plane). */
      private final Vector3D.Unit u;
  
      /** Second normalized vector of the plane frame (in plane). */
      private final Vector3D.Unit v;
  
      /** Construct a new instance from an orthonormal set of basis vectors and an origin offset.
       * @param u first vector of the basis (in plane)
       * @param v second vector of the basis (in plane)
       * @param w third vector of the basis (plane normal)
       * @param originOffset offset of the origin with respect to the plane.
       * @param precision precision context used for floating point comparisons
       */
      EmbeddingPlane(final Vector3D.Unit u, final Vector3D.Unit v, final Vector3D.Unit w, final double originOffset,
                     final Precision.DoubleEquivalence precision) {
          super(w, originOffset, precision);
  
          this.u = u;
          this.v = v;
      }
  
      /** Get the plane first canonical vector.
       * <p>
       * The frame defined by ({@link #getU u}, {@link #getV v},
       * {@link #getW w}) is a right-handed orthonormalized frame).
       * </p>
       * @return normalized first canonical vector
       * @see #getV
       * @see #getW
       * @see #getNormal
       */
      public Vector3D.Unit getU() {
          return u;
      }
  
      /** Get the plane second canonical vector.
       * <p>
       * The frame defined by ({@link #getU u}, {@link #getV v},
       * {@link #getW w}) is a right-handed orthonormalized frame).
       * </p>
       * @return normalized second canonical vector
       * @see #getU
       * @see #getW
       * @see #getNormal
       */
      public Vector3D.Unit getV() {
          return v;
      }
  
      /** Get the plane third canonical vector, ie, the plane normal. This
       * method is simply an alias for {@link #getNormal()}.
       * <p>
       * The frame defined by {@link #getU() u}, {@link #getV() v},
       * {@link #getW() w} is a right-handed orthonormalized frame.
       * </p>
       * @return normalized normal vector
       * @see #getU()
       * @see #getV()
      * @see #getNormal()
      */
     public Vector3D.Unit getW() {
         return getNormal();
     }
 
     /** Return the current instance.
      */
     @Override
     public EmbeddingPlane getEmbedding() {
         return this;
     }
 
     /** Transform a 3D space point into an in-plane point.
      * @param point point of the space
      * @return in-plane point
      * @see #toSpace
      */
     @Override
     public Vector2D toSubspace(final Vector3D point) {
         return Vector2D.of(point.dot(u), point.dot(v));
     }
 
     /** Transform an in-plane point into a 3D space point.
      * @param point in-plane point
      * @return 3D space point
      * @see #toSubspace(Vector3D)
      */
     @Override
     public Vector3D toSpace(final Vector2D point) {
         return Vector3D.Sum.create()
                 .addScaled(point.getX(), u)
                 .addScaled(point.getY(), v)
                 .addScaled(-getOriginOffset(), getNormal()).get();
     }
 
     /** Get one point from the 3D-space.
      * @param inPlane desired in-plane coordinates for the point in the plane
      * @param offset  desired offset for the point
      * @return one point in the 3D-space, with given coordinates and offset relative
      *         to the plane
      */
     public Vector3D pointAt(final Vector2D inPlane, final double offset) {
         return Vector3D.Sum.create()
                 .addScaled(inPlane.getX(), u)
                 .addScaled(inPlane.getY(), v)
                 .addScaled(offset - getOriginOffset(), getNormal()).get();
     }
 
     /** Build a new reversed version of this plane, with opposite orientation.
      * <p>
      * The new plane frame is chosen in such a way that a 3D point that had
      * {@code (x, y)} in-plane coordinates and {@code z} offset with respect to the
      * plane and is unaffected by the change will have {@code (y, x)} in-plane
      * coordinates and {@code -z} offset with respect to the new plane. This means
      * that the {@code u} and {@code v} vectors returned by the {@link #getU} and
      * {@link #getV} methods are exchanged, and the {@code w} vector returned by the
      * {@link #getNormal} method is reversed.
      * </p>
      * @return a new reversed plane
      */
     @Override
     public EmbeddingPlane reverse() {
         return new EmbeddingPlane(v, u, getNormal().negate(), -getOriginOffset(), getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public EmbeddingPlane transform(final Transform<Vector3D> transform) {
         final Vector3D origin = getOrigin();
         final Vector3D plusU = origin.add(u);
         final Vector3D plusV = origin.add(v);
 
         final Vector3D tOrigin = transform.apply(origin);
         final Vector3D tPlusU = transform.apply(plusU);
         final Vector3D tPlusV = transform.apply(plusV);
 
         final Vector3D.Unit tU = tOrigin.directionTo(tPlusU);
         final Vector3D.Unit tV = tOrigin.directionTo(tPlusV);
         final Vector3D.Unit tW = tU.cross(tV).normalize();
 
         final double tOriginOffset = -tOrigin.dot(tW);
 
         return new EmbeddingPlane(tU, tV, tW, tOriginOffset, getPrecision());
     }
 
     /** Translate the plane by the specified amount.
      * @param translation translation to apply
      * @return a new plane
      */
     @Override
     public EmbeddingPlane translate(final Vector3D translation) {
         final Vector3D tOrigin = getOrigin().add(translation);
 
         return Planes.fromPointAndPlaneVectors(tOrigin, u, v, getPrecision());
     }
 
     /** Rotate the plane around the specified point.
      * @param center rotation center
      * @param rotation 3-dimensional rotation
      * @return a new rotated plane
      */
     @Override
     public EmbeddingPlane rotate(final Vector3D center, final QuaternionRotation rotation) {
         final Vector3D delta = getOrigin().subtract(center);
         final Vector3D tOrigin = center.add(rotation.apply(delta));
         final Vector3D.Unit tU = rotation.apply(u).normalize();
         final Vector3D.Unit tV = rotation.apply(v).normalize();
 
         return Planes.fromPointAndPlaneVectors(tOrigin, tU, tV, getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public int hashCode() {
         return Objects.hash(getNormal(), getOriginOffset(), u, v, getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public boolean equals(final Object obj) {
         if (this == obj) {
             return true;
         } else if (obj == null || obj.getClass() != EmbeddingPlane.class) {
             return false;
         }
 
         final EmbeddingPlane other = (EmbeddingPlane) obj;
 
         return Objects.equals(this.getNormal(), other.getNormal()) &&
                 Double.compare(this.getOriginOffset(), other.getOriginOffset()) == 0 &&
                 Objects.equals(this.u, other.u) &&
                 Objects.equals(this.v, other.v) &&
                 Objects.equals(this.getPrecision(), other.getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
         sb.append(getClass().getSimpleName())
             .append("[origin= ")
             .append(getOrigin())
             .append(", u= ")
             .append(u)
             .append(", v= ")
             .append(v)
             .append(", w= ")
             .append(getNormal())
             .append(']');
 
         return sb.toString();
     }
 
     /** 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:
      * <pre>
      *      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
      * </pre>
      * At the end of execution, the points {@code a} (which was transformed using the original
      * 3D transform) and {@code b} (which was transformed in 2D using the subspace transform)
      * are equivalent.
      *
      * @param transform the transform to apply to this instance
      * @return an object containing the transformed plane along with a transform that can be applied
      *      to subspace points
      * @see #transform(Transform)
      */
     public SubspaceTransform subspaceTransform(final Transform<Vector3D> transform) {
         final Vector3D origin = getOrigin();
 
         final Vector3D tOrigin = transform.apply(origin);
         final Vector3D tPlusU = transform.apply(origin.add(u));
         final Vector3D tPlusV = transform.apply(origin.add(v));
 
         final EmbeddingPlane tPlane = Planes.fromPointAndPlaneVectors(
                 tOrigin,
                 tOrigin.vectorTo(tPlusU),
                 tOrigin.vectorTo(tPlusV),
                 getPrecision());
 
         final Vector2D tSubspaceOrigin = tPlane.toSubspace(tOrigin);
         final Vector2D tSubspaceU = tSubspaceOrigin.vectorTo(tPlane.toSubspace(tPlusU));
         final Vector2D tSubspaceV = tSubspaceOrigin.vectorTo(tPlane.toSubspace(tPlusV));
 
         final AffineTransformMatrix2D subspaceTransform =
                 AffineTransformMatrix2D.fromColumnVectors(tSubspaceU, tSubspaceV, tSubspaceOrigin);
 
         return new SubspaceTransform(tPlane, subspaceTransform);
     }
 
     /** Class containing a transformed plane instance along with a subspace (2D) transform. The subspace
      * transform produces the equivalent of the 3D transform in 2D.
      */
     public static final class SubspaceTransform {
         /** The transformed plane. */
         private final EmbeddingPlane plane;
 
         /** The subspace transform instance. */
         private final AffineTransformMatrix2D transform;
 
         /** Simple constructor.
          * @param plane the transformed plane
          * @param transform 2D transform that can be applied to subspace points
          */
         public SubspaceTransform(final EmbeddingPlane plane, final AffineTransformMatrix2D transform) {
             this.plane = plane;
             this.transform = transform;
         }
 
         /** Get the transformed plane instance.
          * @return the transformed plane instance
          */
         public EmbeddingPlane getPlane() {
             return plane;
         }
 
         /** Get the 2D transform that can be applied to subspace points. This transform can be used
          * to perform the equivalent of the 3D transform in 2D space.
          * @return the subspace transform instance
          */
         public AffineTransformMatrix2D getTransform() {
             return transform;
         }
     }
 }