/*
    * 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.spherical.twod;
  
  import org.apache.commons.geometry.core.Transform;
  import org.apache.commons.geometry.euclidean.threed.AffineTransformMatrix3D;
  import org.apache.commons.geometry.euclidean.threed.Vector3D;
  import org.apache.commons.geometry.euclidean.threed.rotation.QuaternionRotation;
  
  /** Implementation of the {@link Transform} interface for spherical 2D points.
   *
   * <p>This class uses an {@link AffineTransformMatrix3D} to perform spherical point transforms
   * in Euclidean 3D space.</p>
   *
   * <p>Instances of this class are guaranteed to be immutable.</p>
   */
  public final class Transform2S implements Transform<Point2S> {
      /** Static instance representing the identity transform. */
      private static final Transform2S IDENTITY = new Transform2S(AffineTransformMatrix3D.identity());
  
      /** Static transform instance that reflects across the x-y plane. */
      private static final AffineTransformMatrix3D XY_PLANE_REFLECTION = AffineTransformMatrix3D.createScale(1, 1, -1);
  
      /** Euclidean transform matrix underlying the spherical transform. */
      private final AffineTransformMatrix3D euclideanTransform;
  
      /** Construct a new instance from its underlying Euclidean transform.
       * @param euclideanTransform underlying Euclidean transform
       */
      private Transform2S(final AffineTransformMatrix3D euclideanTransform) {
          this.euclideanTransform = euclideanTransform;
      }
  
      /** Get the Euclidean transform matrix underlying the spherical transform.
       * @return the Euclidean transform matrix underlying the spherical transform
       */
      public AffineTransformMatrix3D getEuclideanTransform() {
          return euclideanTransform;
      }
  
      /** {@inheritDoc} */
      @Override
      public Point2S apply(final Point2S pt) {
          final Vector3D vec = pt.getVector();
          return Point2S.from(euclideanTransform.apply(vec));
      }
  
      /** {@inheritDoc} */
      @Override
      public boolean preservesOrientation() {
          return euclideanTransform.preservesOrientation();
      }
  
      /** {@inheritDoc} */
      @Override
      public Transform2S inverse() {
          return new Transform2S(euclideanTransform.inverse());
      }
  
      /** Apply a rotation of {@code angle} radians around the given point to this instance.
       * @param pt point to rotate around
       * @param angle rotation angle in radians
       * @return transform resulting from applying the specified rotation to this instance
       */
      public Transform2S rotate(final Point2S pt, final double angle) {
          return premultiply(createRotation(pt, angle));
      }
  
      /** Apply a rotation of {@code angle} radians around the given 3D axis to this instance.
       * @param axis 3D axis of rotation
       * @param angle rotation angle in radians
       * @return transform resulting from applying the specified rotation to this instance
       */
      public Transform2S rotate(final Vector3D axis, final double angle) {
          return premultiply(createRotation(axis, angle));
      }
  
      /** Apply the given quaternion rotation to this instance.
       * @param quaternion quaternion rotation to apply
       * @return transform resulting from applying the specified rotation to this instance
       */
      public Transform2S rotate(final QuaternionRotation quaternion) {
          return premultiply(createRotation(quaternion));
      }
  
     /** Apply a reflection across the equatorial plane defined by the given pole point
      * to this instance.
      * @param pole pole point defining the equatorial reflection plane
      * @return transform resulting from applying the specified reflection to this instance
      */
     public Transform2S reflect(final Point2S pole) {
         return premultiply(createReflection(pole));
     }
 
     /** Apply a reflection across the equatorial plane defined by the given pole vector
      * to this instance.
      * @param poleVector pole vector defining the equatorial reflection plane
      * @return transform resulting from applying the specified reflection to this instance
      */
     public Transform2S reflect(final Vector3D poleVector) {
         return premultiply(createReflection(poleVector));
     }
 
     /** Multiply the underlying Euclidean transform of this instance by that of the argument, eg,
      * {@code other * this}. The returned transform performs the equivalent of
      * {@code other} followed by {@code this}.
      * @param other transform to multiply with
      * @return a new transform computed by multiplying the matrix of this
      *      instance by that of the argument
      * @see AffineTransformMatrix3D#multiply(AffineTransformMatrix3D)
      */
     public Transform2S multiply(final Transform2S other) {
         return multiply(this, other);
     }
 
     /** Multiply the underlying Euclidean transform matrix of the argument by that of this instance, eg,
      * {@code this * other}. The returned transform performs the equivalent of {@code this}
      * followed by {@code other}.
      * @param other transform to multiply with
      * @return a new transform computed by multiplying the matrix of the
      *      argument by that of this instance
      * @see AffineTransformMatrix3D#premultiply(AffineTransformMatrix3D)
      */
     public Transform2S premultiply(final Transform2S other) {
         return multiply(other, this);
     }
 
     /** {@inheritDoc} */
     @Override
     public int hashCode() {
         return euclideanTransform.hashCode();
     }
 
     /**
      * Return true if the given object is an instance of {@link Transform2S}
      * and the underlying Euclidean transform matrices are exactly equal.
      * @param obj object to test for equality with the current instance
      * @return true if the underlying transform matrices are exactly equal
      */
     @Override
     public boolean equals(final Object obj) {
         if (this == obj) {
             return true;
         }
         if (!(obj instanceof Transform2S)) {
             return false;
         }
         final Transform2S other = (Transform2S) obj;
 
         return euclideanTransform.equals(other.euclideanTransform);
     }
 
     /** {@inheritDoc} */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
 
         sb.append(this.getClass().getSimpleName())
             .append("[euclideanTransform= ")
             .append(getEuclideanTransform())
             .append(']');
 
         return sb.toString();
     }
 
     /** Return an instance representing the identity transform. This transform is guaranteed
      * to return an <em>equivalent</em> (ie, co-located) point for any input point. However, the
      * points are not guaranteed to contain exactly equal coordinates. For example, at the poles, an
      * infinite number of points exist that vary only in the azimuth coordinate. When one of these
      * points is transformed by this identity transform, the returned point may contain a different
      * azimuth value from the input, but it will still represent the same location in space.
      * @return an instance representing the identity transform
      */
     public static Transform2S identity() {
         return IDENTITY;
     }
 
     /** Create a transform that rotates the given angle around {@code pt}.
      * @param pt point to rotate around
      * @param angle angle of rotation in radians
      * @return a transform that rotates the given angle around {@code pt}
      */
     public static Transform2S createRotation(final Point2S pt, final double angle) {
         return createRotation(pt.getVector(), angle);
     }
 
     /** Create a transform that rotates the given angle around {@code axis}.
      * @param axis 3D axis of rotation
      * @param angle angle of rotation in radians
      * @return a transform that rotates the given angle {@code axis}
      */
     public static Transform2S createRotation(final Vector3D axis, final double angle) {
         return createRotation(QuaternionRotation.fromAxisAngle(axis, angle));
     }
 
     /** Create a transform that performs the given 3D rotation.
      * @param quaternion quaternion instance representing the 3D rotation
      * @return a transform that performs the given 3D rotation
      */
     public static Transform2S createRotation(final QuaternionRotation quaternion) {
         return new Transform2S(quaternion.toMatrix());
     }
 
     /** Create a transform that performs a reflection across the equatorial plane
      * defined by the given pole point.
      * @param pole pole point defining the equatorial reflection plane
      * @return a transform that performs a reflection across the equatorial plane
      *      defined by the given pole point
      */
     public static Transform2S createReflection(final Point2S pole) {
         return createReflection(pole.getVector());
     }
 
     /** Create a transform that performs a reflection across the equatorial plane
      * defined by the given pole point.
      * @param poleVector pole vector defining the equatorial reflection plane
      * @return a transform that performs a reflection across the equatorial plane
      *      defined by the given pole point
      */
     public static Transform2S createReflection(final Vector3D poleVector) {
         final QuaternionRotation quat = QuaternionRotation.createVectorRotation(poleVector, Vector3D.Unit.PLUS_Z);
 
         final AffineTransformMatrix3D matrix = quat.toMatrix()
                 .premultiply(XY_PLANE_REFLECTION)
                 .premultiply(quat.inverse().toMatrix());
 
         return new Transform2S(matrix);
     }
 
     /** Multiply the Euclidean transform matrices of the arguments together.
      * @param a first transform
      * @param b second transform
      * @return the transform computed as {@code a x b}
      */
     private static Transform2S multiply(final Transform2S a, final Transform2S b) {
 
         return new Transform2S(a.euclideanTransform.multiply(b.euclideanTransform));
     }
 }