/*
    * 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.oned;
  
  import java.util.Collections;
  import java.util.List;
  import java.util.Objects;
  
  import org.apache.commons.geometry.core.RegionLocation;
  import org.apache.commons.geometry.core.Transform;
  import org.apache.commons.geometry.core.partitioning.AbstractHyperplane;
  import org.apache.commons.geometry.core.partitioning.Hyperplane;
  import org.apache.commons.geometry.core.partitioning.HyperplaneConvexSubset;
  import org.apache.commons.geometry.core.partitioning.HyperplaneLocation;
  import org.apache.commons.geometry.core.partitioning.Split;
  import org.apache.commons.numbers.core.Precision;
  
  /** Class representing an oriented point in 1-dimensional spherical space,
   * meaning an azimuth angle and a direction (increasing or decreasing angles)
   * along the circle.
   *
   * <p>Hyperplanes split the spaces they are embedded in into three distinct parts:
   * the hyperplane itself, a plus side and a minus side. However, since spherical
   * space wraps around, a single oriented point is not sufficient to partition the space;
   * any point could be classified as being on the plus or minus side of a hyperplane
   * depending on the direction that the circle is traversed. The approach taken in this
   * class to address this issue is to (1) define a second, implicit cut point at {@code 0pi} and
   * (2) define the domain of hyperplane points (for partitioning purposes) to be the
   * range {@code [0, 2pi)}. Each hyperplane then splits the space into the intervals
   * {@code [0, x]} and {@code [x, 2pi)}, where {@code x} is the location of the hyperplane.
   * One way to visualize this is to picture the circle as a cake that has already been
   * cut at {@code 0pi}. Each hyperplane then specifies the location of the second
   * cut of the cake, with the plus and minus sides being the pieces thus cut.
   * </p>
   *
   * <p>Note that with the hyperplane partitioning rules described above, the hyperplane
   * at {@code 0pi} is unique in that it has the entire space on one side (minus the hyperplane
   * itself) and no points whatsoever on the other. This is very different from hyperplanes in
   * Euclidean space, which always have infinitely many points on both sides.</p>
   *
   * <p>Instances of this class are guaranteed to be immutable.</p>
   * @see CutAngles
   */
  public final class CutAngle extends AbstractHyperplane<Point1S> {
      /** Hyperplane location as a point. */
      private final Point1S point;
  
      /** Hyperplane direction. */
      private final boolean positiveFacing;
  
      /** Simple constructor.
       * @param point location of the hyperplane
       * @param positiveFacing if true, the hyperplane will point in a positive angular
       *      direction; otherwise, it will point in a negative direction
       * @param precision precision context used to compare floating point values
       */
      CutAngle(final Point1S point, final boolean positiveFacing,
              final Precision.DoubleEquivalence precision) {
          super(precision);
  
          this.point = point;
          this.positiveFacing = positiveFacing;
      }
  
      /** Get the location of the hyperplane as a point.
       * @return the hyperplane location as a point
       * @see #getAzimuth()
       */
      public Point1S getPoint() {
          return point;
      }
  
      /** Get the location of the hyperplane as a single value. This is
       * equivalent to {@code cutAngle.getPoint().getAzimuth()}.
       * @return the location of the hyperplane as a single value.
       * @see #getPoint()
       * @see Point1S#getAzimuth()
       */
      public double getAzimuth() {
          return point.getAzimuth();
      }
  
      /** Get the location of the hyperplane as a single value, normalized
       * to the range {@code [0, 2pi)}. This is equivalent to
       * {@code cutAngle.getPoint().getNormalizedAzimuth()}.
      * @return the location of the hyperplane, normalized to the range
      *      {@code [0, 2pi)}
      * @see #getPoint()
      * @see Point1S#getNormalizedAzimuth()
      */
     public double getNormalizedAzimuth() {
         return point.getNormalizedAzimuth();
     }
 
     /** Return true if the hyperplane is oriented with its plus
      * side pointing toward increasing angles.
      * @return true if the hyperplane is facing in the direction
      *      of increasing angles
      */
     public boolean isPositiveFacing() {
         return positiveFacing;
     }
 
     /** Return true if this instance should be considered equivalent to the argument, using the
      * given precision context for comparison.
      * <p>The instances are considered equivalent if they
      * <ol>
      *    <li>have equivalent point locations (points separated by multiples of 2pi are
      *      considered equivalent) and
      *    <li>point in the same direction.</li>
      * </ol>
      * @param other point to compare with
      * @param precision precision context to use for the comparison
      * @return true if this instance should be considered equivalent to the argument
      * @see Point1S#eq(Point1S, Precision.DoubleEquivalence)
      */
     public boolean eq(final CutAngle other, final Precision.DoubleEquivalence precision) {
         return point.eq(other.point, precision) &&
                 positiveFacing == other.positiveFacing;
     }
 
     /** {@inheritDoc} */
     @Override
     public double offset(final Point1S pt) {
         final double dist = pt.getNormalizedAzimuth() - this.point.getNormalizedAzimuth();
         return positiveFacing ? +dist : -dist;
     }
 
     /** {@inheritDoc} */
     @Override
     public HyperplaneLocation classify(final Point1S pt) {
         final Precision.DoubleEquivalence precision = getPrecision();
 
         final Point1S compPt = Point1S.ZERO.eq(pt, precision) ?
                 Point1S.ZERO :
                 pt;
 
         final double offsetValue = offset(compPt);
         final double cmp = precision.signum(offsetValue);
 
         if (cmp > 0) {
             return HyperplaneLocation.PLUS;
         } else if (cmp < 0) {
             return HyperplaneLocation.MINUS;
         }
 
         return HyperplaneLocation.ON;
     }
 
     /** {@inheritDoc} */
     @Override
     public Point1S project(final Point1S pt) {
         return this.point;
     }
 
     /** {@inheritDoc} */
     @Override
     public CutAngle reverse() {
         return new CutAngle(point, !positiveFacing, getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public CutAngle transform(final Transform<Point1S> transform) {
         final Point1S tPoint = transform.apply(point);
         final boolean tPositiveFacing = transform.preservesOrientation() == positiveFacing;
 
         return CutAngles.fromPointAndDirection(tPoint, tPositiveFacing, getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public boolean similarOrientation(final Hyperplane<Point1S> other) {
         return positiveFacing == ((CutAngle) other).positiveFacing;
     }
 
     /** {@inheritDoc}
      *
      * <p>Since there are no subspaces in spherical 1D space, this method effectively returns a stub implementation
      * of {@link HyperplaneConvexSubset}, the main purpose of which is to support the proper functioning
      * of the partitioning code.</p>
      */
     @Override
     public HyperplaneConvexSubset<Point1S> span() {
         return new CutAngleConvexSubset(this);
     }
 
     /** {@inheritDoc} */
     @Override
     public int hashCode() {
         return Objects.hash(point, positiveFacing, getPrecision());
     }
 
     /** {@inheritDoc} */
     @Override
     public boolean equals(final Object obj) {
         if (this == obj) {
             return true;
         } else if (!(obj instanceof CutAngle)) {
             return false;
         }
 
         final CutAngle other = (CutAngle) obj;
         return Objects.equals(getPrecision(), other.getPrecision()) &&
                 Objects.equals(point, other.point) &&
                 positiveFacing == other.positiveFacing;
     }
 
     /** {@inheritDoc} */
     @Override
     public String toString() {
         final StringBuilder sb = new StringBuilder();
         sb.append(this.getClass().getSimpleName())
             .append("[point= ")
             .append(point)
             .append(", positiveFacing= ")
             .append(isPositiveFacing())
             .append(']');
 
         return sb.toString();
     }
 
     /** {@link HyperplaneConvexSubset} implementation for spherical 1D space. Since there are no subspaces in 1D,
      * this is effectively a stub implementation, its main use being to allow for the correct functioning of
      * partitioning code.
      */
     private static final class CutAngleConvexSubset implements HyperplaneConvexSubset<Point1S> {
         /** The hyperplane containing for this instance. */
         private final CutAngle hyperplane;
 
         /** Simple constructor.
          * @param hyperplane containing hyperplane instance
          */
         CutAngleConvexSubset(final CutAngle hyperplane) {
             this.hyperplane = hyperplane;
         }
 
         /** {@inheritDoc} */
         @Override
         public CutAngle getHyperplane() {
             return hyperplane;
         }
 
         /** {@inheritDoc}
         *
         * <p>This method always returns {@code false}.</p>
         */
         @Override
         public boolean isFull() {
             return false;
         }
 
         /** {@inheritDoc}
         *
         * <p>This method always returns {@code false}.</p>
         */
         @Override
         public boolean isEmpty() {
             return false;
         }
 
         /** {@inheritDoc}
          *
          * <p>This method always returns {@code false}.</p>
          */
         @Override
         public boolean isInfinite() {
             return false;
         }
 
         /** {@inheritDoc}
         *
         * <p>This method always returns {@code true}.</p>
         */
         @Override
         public boolean isFinite() {
             return true;
         }
 
         /** {@inheritDoc}
          *
          *  <p>This method always returns {@code 0}.</p>
          */
         @Override
         public double getSize() {
             return 0;
         }
 
         /** {@inheritDoc}
          *
          * <p>This method returns the point for the underlying hyperplane.</p>
          */
         @Override
         public Point1S getCentroid() {
             return hyperplane.getPoint();
         }
 
         /** {@inheritDoc}
          *
          * <p>This method returns {@link RegionLocation#BOUNDARY} if the
          * point is on the hyperplane and {@link RegionLocation#OUTSIDE}
          * otherwise.</p>
          */
         @Override
         public RegionLocation classify(final Point1S point) {
             if (hyperplane.contains(point)) {
                 return RegionLocation.BOUNDARY;
             }
 
             return RegionLocation.OUTSIDE;
         }
 
         /** {@inheritDoc} */
         @Override
         public Point1S closest(final Point1S point) {
             return hyperplane.project(point);
         }
 
         /** {@inheritDoc} */
         @Override
         public Split<CutAngleConvexSubset> split(final Hyperplane<Point1S> splitter) {
             final HyperplaneLocation side = splitter.classify(hyperplane.getPoint());
 
             CutAngleConvexSubset minus = null;
             CutAngleConvexSubset plus = null;
 
             if (side == HyperplaneLocation.MINUS) {
                 minus = this;
             } else if (side == HyperplaneLocation.PLUS) {
                 plus = this;
             }
 
             return new Split<>(minus, plus);
         }
 
         /** {@inheritDoc} */
         @Override
         public List<CutAngleConvexSubset> toConvex() {
             return Collections.singletonList(this);
         }
 
         /** {@inheritDoc} */
         @Override
         public CutAngleConvexSubset transform(final Transform<Point1S> transform) {
             return new CutAngleConvexSubset(getHyperplane().transform(transform));
         }
 
         /** {@inheritDoc} */
         @Override
         public CutAngleConvexSubset reverse() {
             return new CutAngleConvexSubset(hyperplane.reverse());
         }
 
         /** {@inheritDoc} */
         @Override
         public String toString() {
             final StringBuilder sb = new StringBuilder();
             sb.append(this.getClass().getSimpleName())
                 .append("[hyperplane= ")
                 .append(hyperplane)
                 .append(']');
 
             return sb.toString();
         }
     }
 }