/*
 * 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;
        }
    }
}