| /* |
| * 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.Comparator; |
| import java.util.Objects; |
| |
| import org.apache.commons.geometry.core.Geometry; |
| import org.apache.commons.geometry.core.Point; |
| import org.apache.commons.geometry.core.exception.GeometryValueException; |
| import org.apache.commons.geometry.core.internal.SimpleTupleFormat; |
| import org.apache.commons.geometry.core.precision.DoublePrecisionContext; |
| import org.apache.commons.geometry.euclidean.twod.PolarCoordinates; |
| import org.apache.commons.geometry.euclidean.twod.Vector2D; |
| import org.apache.commons.numbers.angle.PlaneAngle; |
| import org.apache.commons.numbers.angle.PlaneAngleRadians; |
| |
| /** This class represents a point on the 1-sphere, or in other words, an |
| * azimuth angle on a circle. The value of the azimuth angle is not normalized |
| * by default, meaning that instances can be constructed representing negative |
| * values or values greater than {@code 2pi}. However, instances separated by a |
| * multiple of {@code 2pi} are considered equivalent for most methods, with the |
| * exceptions being {@link #equals(Object)} and {@link #hashCode()}, where the |
| * azimuth values must match exactly in order for instances to be considered |
| * equal. |
| * |
| * <p>Instances of this class are guaranteed to be immutable.</p> |
| */ |
| public final class Point1S implements Point<Point1S> { |
| |
| /** A point with coordinates set to {@code 0*pi}. */ |
| public static final Point1S ZERO = Point1S.of(Geometry.ZERO_PI); |
| |
| /** A point with coordinates set to {@code pi}. */ |
| public static final Point1S PI = Point1S.of(Geometry.PI); |
| |
| // CHECKSTYLE: stop ConstantName |
| /** A point with all coordinates set to NaN. */ |
| public static final Point1S NaN = Point1S.of(Double.NaN); |
| // CHECKSTYLE: resume ConstantName |
| |
| /** Comparator that sorts points by normalized azimuth in ascending order. |
| * Points are only considered equal if their normalized azimuths match exactly. |
| * Null arguments are evaluated as being greater than non-null arguments. |
| * @see #getNormalizedAzimuth() |
| */ |
| public static final Comparator<Point1S> NORMALIZED_AZIMUTH_ASCENDING_ORDER = (a, b) -> { |
| int cmp = 0; |
| |
| if (a != null && b != null) { |
| cmp = Double.compare(a.getNormalizedAzimuth(), b.getNormalizedAzimuth()); |
| } else if (a != null) { |
| cmp = -1; |
| } else if (b != null) { |
| cmp = 1; |
| } |
| |
| return cmp; |
| }; |
| |
| /** Azimuthal angle in radians. */ |
| private final double azimuth; |
| |
| /** Normalized azimuth value in the range {@code [0, 2pi)}. */ |
| private final double normalizedAzimuth; |
| |
| /** Build a point from its internal components. |
| * @param azimuth azimuth angle |
| * @param normalizedAzimuth azimuth angle normalized to the range {@code [0, 2pi)} |
| */ |
| private Point1S(final double azimuth, final double normalizedAzimuth) { |
| this.azimuth = azimuth; |
| this.normalizedAzimuth = normalizedAzimuth; |
| } |
| |
| /** Get the azimuth angle in radians. This value is not normalized and |
| * can be any floating point number. |
| * @return azimuth angle |
| * @see Point1S#of(double) |
| */ |
| public double getAzimuth() { |
| return azimuth; |
| } |
| |
| /** Get the azimuth angle normalized to the range {@code [0, 2pi)}. |
| * @return the azimuth angle normalized to the range {@code [0, 2pi)}. |
| */ |
| public double getNormalizedAzimuth() { |
| return normalizedAzimuth; |
| } |
| |
| /** Get the normalized vector corresponding to this azimuth angle in 2D Euclidean space. |
| * @return normalized vector |
| */ |
| public Vector2D getVector() { |
| if (isFinite()) { |
| return PolarCoordinates.toCartesian(1, azimuth); |
| } |
| |
| return null; |
| } |
| |
| /** {@inheritDoc} */ |
| @Override |
| public int getDimension() { |
| return 1; |
| } |
| |
| /** {@inheritDoc} */ |
| @Override |
| public boolean isNaN() { |
| return Double.isNaN(azimuth); |
| } |
| |
| /** {@inheritDoc} */ |
| @Override |
| public boolean isInfinite() { |
| return !isNaN() && Double.isInfinite(azimuth); |
| } |
| |
| /** {@inheritDoc} */ |
| @Override |
| public boolean isFinite() { |
| return Double.isFinite(azimuth); |
| } |
| |
| /** {@inheritDoc} |
| * |
| * <p>The returned value is the shortest angular distance between |
| * the two points, in the range {@code [0, pi]}.</p> |
| */ |
| @Override |
| public double distance(final Point1S point) { |
| return distance(this, point); |
| } |
| |
| /** Return the signed distance (angular separation) between this instance and the |
| * given point in the range {@code [-pi, pi)}. If {@code p1} is the current instance, |
| * {@code p2} the given point, and {@code d} the signed distance, then |
| * {@code p1.getAzimuth() + d} is an angle equivalent to {@code p2.getAzimuth()}. |
| * @param point point to compute the signed distance to |
| * @return the signed distance between this instance and the given point in the range |
| * {@code [-pi, pi)} |
| */ |
| public double signedDistance(final Point1S point) { |
| return signedDistance(this, point); |
| } |
| |
| /** Return an equivalent point with an azimuth value at or above the given base. |
| * The returned point has an azimuth value in the range {@code [base, base + 2pi)}. |
| * @param base point to place this instance's azimuth value above |
| * @return a point equivalent to the current instance but with an azimuth |
| * value in the range {@code [base, base + 2pi)} |
| * @throws GeometryValueException if the azimuth value is NaN or infinite and |
| * cannot be normalized |
| */ |
| public Point1S above(final Point1S base) { |
| return normalize(base.getAzimuth() + Geometry.PI); |
| } |
| |
| /** Return an equivalent point with an azimuth value strictly below the given base. |
| * The returned point has an azimuth value in the range {@code [base - 2pi, base)}. |
| * @param base point to place this instance's azimuth value below |
| * @return a point equivalent to the current instance but with an azimuth |
| * value in the range {@code [base - 2pi, base)} |
| * @throws GeometryValueException if the azimuth value is NaN or infinite and |
| * cannot be normalized |
| */ |
| public Point1S below(final Point1S base) { |
| return normalize(base.getAzimuth() - Geometry.PI); |
| } |
| |
| /** Normalize this point around the given center point. The azimuth value of |
| * the returned point is in the range {@code [center - pi, center + pi)}. |
| * @param center point to center this instance around |
| * @return a point equivalent to this instance but with an azimuth value |
| * in the range {@code [center - pi, center + pi)}. |
| * @throws GeometryValueException if the azimuth value is NaN or infinite and |
| * cannot be normalized |
| */ |
| public Point1S normalize(final Point1S center) { |
| return normalize(center.getAzimuth()); |
| } |
| |
| /** Return an equivalent point with an azimuth value normalized around the given center |
| * angle. The azimuth value of the returned point is in the range |
| * {@code [center - pi, center + pi)}. |
| * @param center angle to center this instance around |
| * @return a point equivalent to this instance but with an azimuth value |
| * in the range {@code [center - pi, center + pi)}. |
| * @throws GeometryValueException if the azimuth value is NaN or infinite and |
| * cannot be normalized |
| */ |
| public Point1S normalize(final double center) { |
| if (isFinite()) { |
| final double az = PlaneAngleRadians.normalize(azimuth, center); |
| return new Point1S(az, normalizedAzimuth); |
| } |
| throw new GeometryValueException("Cannot normalize azimuth value: " + azimuth); |
| } |
| |
| /** Get the point exactly opposite this point on the circle, {@code pi} distance away. |
| * The azimuth of the antipodal point is in the range {@code [0, 2pi)}. |
| * @return the point exactly opposite this point on the circle |
| */ |
| public Point1S antipodal() { |
| double az = normalizedAzimuth + Geometry.PI; |
| if (az >= Geometry.TWO_PI) { |
| az -= Geometry.TWO_PI; |
| } |
| |
| return Point1S.of(az); |
| } |
| |
| /** Return true if this instance is equivalent to the argument. The points are |
| * considered equivalent if the shortest angular distance between them is equal to |
| * zero as evaluated by the given precision context. This means that points that differ |
| * in azimuth by multiples of {@code 2pi} are considered equivalent. |
| * @param other point to compare with |
| * @param precision precision context used for floating point comparisons |
| * @return true if this instance is equivalent to the argument |
| */ |
| public boolean eq(final Point1S other, final DoublePrecisionContext precision) { |
| final double dist = signedDistance(other); |
| return precision.eqZero(dist); |
| } |
| |
| /** |
| * Get a hashCode for the point. Points normally must have exactly the |
| * same azimuth angles in order to have the same hash code. Points |
| * will angles that differ by multiples of {@code 2pi} will not |
| * necessarily have the same hash code. |
| * |
| * <p>All NaN values have the same hash code.</p> |
| * |
| * @return a hash code value for this object |
| */ |
| @Override |
| public int hashCode() { |
| if (isNaN()) { |
| return 542; |
| } |
| return 1759 * Objects.hash(azimuth, normalizedAzimuth); |
| } |
| |
| /** Test for the exact equality of two points on the 1-sphere. |
| * |
| * <p>If all coordinates of the given points are exactly the same, and none are |
| * <code>Double.NaN</code>, the points are considered to be equal. Points with |
| * azimuth values separated by multiples of {@code 2pi} are <em>not</em> considered |
| * equal.</p> |
| * |
| * <p><code>NaN</code> coordinates are considered to affect globally the vector |
| * and be equals to each other - i.e, if either (or all) coordinates of the |
| * point are equal to <code>Double.NaN</code>, the point is equal to |
| * {@link #NaN}.</p> |
| * |
| * @param other Object to test for equality to this |
| * @return true if two points on the 1-sphere objects are exactly equal, false if |
| * object is null, not an instance of Point1S, or |
| * not equal to this Point1S instance |
| * |
| */ |
| @Override |
| public boolean equals(final Object other) { |
| if (this == other) { |
| return true; |
| } |
| |
| if (other instanceof Point1S) { |
| final Point1S rhs = (Point1S) other; |
| |
| if (rhs.isNaN()) { |
| return this.isNaN(); |
| } |
| |
| return Double.compare(azimuth, rhs.azimuth) == 0 && |
| Double.compare(normalizedAzimuth, rhs.normalizedAzimuth) == 0; |
| } |
| |
| return false; |
| } |
| |
| /** {@inheritDoc} */ |
| @Override |
| public String toString() { |
| return SimpleTupleFormat.getDefault().format(getAzimuth()); |
| } |
| |
| /** Create a new point instance from the given azimuth angle. |
| * @param azimuth azimuth angle in radians |
| * @return point instance with the given azimuth angle |
| * @see #getAzimuth() |
| */ |
| public static Point1S of(final double azimuth) { |
| final double normalizedAzimuth = PolarCoordinates.normalizeAzimuth(azimuth); |
| |
| return new Point1S(azimuth, normalizedAzimuth); |
| } |
| |
| /** Create a new point instance from the given azimuth angle. |
| * @param azimuth azimuth azimuth angle in radians |
| * @return point instance with the given azimuth angle |
| * @see #getAzimuth() |
| */ |
| public static Point1S of(final PlaneAngle azimuth) { |
| return of(azimuth.toRadians()); |
| } |
| |
| /** Create a new point instance from the given Euclidean 2D vector. The returned point |
| * will have an azimuth value equal to the angle between the positive x-axis and the |
| * given vector, measured in a counter-clockwise direction. |
| * @param vector 3D vector to create the point from |
| * @return a new point instance with an azimuth value equal to the angle between the given |
| * vector and the positive x-axis, measured in a counter-clockwise direction |
| */ |
| public static Point1S from(final Vector2D vector) { |
| final PolarCoordinates polar = PolarCoordinates.fromCartesian(vector); |
| final double az = polar.getAzimuth(); |
| |
| return new Point1S(az, az); |
| } |
| |
| /** Create a new point instance containing an azimuth value equal to that of the |
| * given set of polar coordinates. |
| * @param polar polar coordinates to convert to a point |
| * @return a new point instance containing an azimuth value equal to that of |
| * the given set of polar coordinates. |
| */ |
| public static Point1S from(final PolarCoordinates polar) { |
| final double az = polar.getAzimuth(); |
| |
| return new Point1S(az, az); |
| } |
| |
| /** Parse the given string and returns a new point instance. The expected string |
| * format is the same as that returned by {@link #toString()}. |
| * @param str the string to parse |
| * @return point instance represented by the string |
| * @throws IllegalArgumentException if the given string has an invalid format |
| */ |
| public static Point1S parse(final String str) { |
| return SimpleTupleFormat.getDefault().parse(str, az -> Point1S.of(az)); |
| } |
| |
| /** Compute the signed shortest distance (angular separation) between two points. The return |
| * value is in the range {@code [-pi, pi)} and is such that {@code p1.getAzimuth() + d} |
| * (where {@code d} is the signed distance) is an angle equivalent to {@code p2.getAzimuth()}. |
| * @param p1 first point |
| * @param p2 second point |
| * @return the signed angular separation between p1 and p2, in the range {@code [-pi, pi)}. |
| */ |
| public static double signedDistance(final Point1S p1, final Point1S p2) { |
| double dist = p2.normalizedAzimuth - p1.normalizedAzimuth; |
| if (dist < -Geometry.PI) { |
| dist += Geometry.TWO_PI; |
| } |
| if (dist >= Geometry.PI) { |
| dist -= Geometry.TWO_PI; |
| } |
| return dist; |
| } |
| |
| /** Compute the shortest distance (angular separation) between two points. The returned |
| * value is in the range {@code [0, pi]}. This method is equal to the absolute value of |
| * the {@link #signedDistance(Point1S, Point1S) signed distance}. |
| * @param p1 first point |
| * @param p2 second point |
| * @return the angular separation between p1 and p2, in the range {@code [0, pi]}. |
| * @see #signedDistance(Point1S, Point1S) |
| */ |
| public static double distance(final Point1S p1, final Point1S p2) { |
| return Math.abs(signedDistance(p1, p2)); |
| } |
| } |
