Circle.java
/*
* 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
*
* https://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.
*/
/*
* This is not the original file distributed by the Apache Software Foundation
* It has been modified by the Hipparchus project
*/
package org.hipparchus.geometry.spherical.twod;
import org.hipparchus.exception.MathIllegalArgumentException;
import org.hipparchus.geometry.euclidean.threed.Rotation;
import org.hipparchus.geometry.euclidean.threed.Vector3D;
import org.hipparchus.geometry.partitioning.Embedding;
import org.hipparchus.geometry.partitioning.Hyperplane;
import org.hipparchus.geometry.partitioning.RegionFactory;
import org.hipparchus.geometry.partitioning.Transform;
import org.hipparchus.geometry.spherical.oned.Arc;
import org.hipparchus.geometry.spherical.oned.ArcsSet;
import org.hipparchus.geometry.spherical.oned.LimitAngle;
import org.hipparchus.geometry.spherical.oned.S1Point;
import org.hipparchus.geometry.spherical.oned.Sphere1D;
import org.hipparchus.geometry.spherical.oned.SubLimitAngle;
import org.hipparchus.util.FastMath;
import org.hipparchus.util.MathUtils;
import org.hipparchus.util.SinCos;
/** This class represents an oriented great circle on the 2-sphere.
* <p>An oriented circle can be defined by a center point. The circle
* is the set of points that are in the normal plan the center.</p>
* <p>Since it is oriented the two spherical caps at its two sides are
* unambiguously identified as a left cap and a right cap. This can be
* used to identify the interior and the exterior in a simple way by
* local properties only when part of a line is used to define part of
* a spherical polygon boundary.</p>
*/
public class Circle
implements Hyperplane<Sphere2D, S2Point, Circle, SubCircle>,
Embedding<Sphere2D, S2Point, Sphere1D, S1Point> {
/** Pole or circle center. */
private Vector3D pole;
/** First axis in the equator plane, origin of the phase angles. */
private Vector3D x;
/** Second axis in the equator plane, in quadrature with respect to x. */
private Vector3D y;
/** Tolerance below which close sub-arcs are merged together. */
private final double tolerance;
/** Build a great circle from its pole.
* <p>The circle is oriented in the trigonometric direction around pole.</p>
* @param pole circle pole
* @param tolerance tolerance below which close sub-arcs are merged together
* @exception MathIllegalArgumentException if tolerance is smaller than {@link Sphere1D#SMALLEST_TOLERANCE}
*/
public Circle(final Vector3D pole, final double tolerance)
throws MathIllegalArgumentException {
Sphere2D.checkTolerance(tolerance);
reset(pole);
this.tolerance = tolerance;
}
/** Build a great circle from two non-aligned points.
* <p>The circle is oriented from first to second point using the path smaller than π.</p>
* @param first first point contained in the great circle
* @param second second point contained in the great circle
* @param tolerance tolerance below which close sub-arcs are merged together
* @exception MathIllegalArgumentException if tolerance is smaller than {@link Sphere1D#SMALLEST_TOLERANCE}
*/
public Circle(final S2Point first, final S2Point second, final double tolerance)
throws MathIllegalArgumentException {
Sphere2D.checkTolerance(tolerance);
reset(first.getVector().crossProduct(second.getVector()));
this.tolerance = tolerance;
}
/** Build a circle from its internal components.
* <p>The circle is oriented in the trigonometric direction around center.</p>
* @param pole circle pole
* @param x first axis in the equator plane
* @param y second axis in the equator plane
* @param tolerance tolerance below which close sub-arcs are merged together
* @exception MathIllegalArgumentException if tolerance is smaller than {@link Sphere1D#SMALLEST_TOLERANCE}
*/
private Circle(final Vector3D pole, final Vector3D x, final Vector3D y, final double tolerance)
throws MathIllegalArgumentException {
Sphere2D.checkTolerance(tolerance);
this.pole = pole;
this.x = x;
this.y = y;
this.tolerance = tolerance;
}
/** Copy constructor.
* <p>The created instance is completely independent from the
* original instance, it is a deep copy.</p>
* @param circle circle to copy
*/
public Circle(final Circle circle) {
this(circle.pole, circle.x, circle.y, circle.tolerance);
}
/** {@inheritDoc} */
@Override
public Circle copySelf() {
return new Circle(this);
}
/** Reset the instance as if built from a pole.
* <p>The circle is oriented in the trigonometric direction around pole.</p>
* @param newPole circle pole
*/
public void reset(final Vector3D newPole) {
this.pole = newPole.normalize();
this.x = newPole.orthogonal();
this.y = Vector3D.crossProduct(newPole, x).normalize();
}
/** Revert the instance.
*/
public void revertSelf() {
// x remains the same
y = y.negate();
pole = pole.negate();
}
/** Get the reverse of the instance.
* <p>Get a circle with reversed orientation with respect to the
* instance. A new object is built, the instance is untouched.</p>
* @return a new circle, with orientation opposite to the instance orientation
*/
public Circle getReverse() {
return new Circle(pole.negate(), x, y.negate(), tolerance);
}
/** {@inheritDoc} */
@Override
public S2Point project(S2Point point) {
return toSpace(toSubSpace(point));
}
/** {@inheritDoc} */
@Override
public double getTolerance() {
return tolerance;
}
/** {@inheritDoc}
* @see #getPhase(Vector3D)
*/
@Override
public S1Point toSubSpace(final S2Point point) {
return new S1Point(getPhase(point.getVector()));
}
/** Get the phase angle of a direction.
* <p>
* The direction may not belong to the circle as the
* phase is computed for the meridian plane between the circle
* pole and the direction.
* </p>
* @param direction direction for which phase is requested
* @return phase angle of the direction around the circle
* @see #toSubSpace(S2Point)
*/
public double getPhase(final Vector3D direction) {
return FastMath.PI + FastMath.atan2(-direction.dotProduct(y), -direction.dotProduct(x));
}
/** {@inheritDoc}
* @see #getPointAt(double)
*/
@Override
public S2Point toSpace(final S1Point point) {
return new S2Point(getPointAt(point.getAlpha()));
}
/** Get a circle point from its phase around the circle.
* @param alpha phase around the circle
* @return circle point on the sphere
* @see #toSpace(S1Point)
* @see #getXAxis()
* @see #getYAxis()
*/
public Vector3D getPointAt(final double alpha) {
final SinCos sc = FastMath.sinCos(alpha);
return new Vector3D(sc.cos(), x, sc.sin(), y);
}
/** Get the X axis of the circle.
* <p>
* This method returns the same value as {@link #getPointAt(double)
* getPointAt(0.0)} but it does not do any computation and always
* return the same instance.
* </p>
* @return an arbitrary x axis on the circle
* @see #getPointAt(double)
* @see #getYAxis()
* @see #getPole()
*/
public Vector3D getXAxis() {
return x;
}
/** Get the Y axis of the circle.
* <p>
* This method returns the same value as {@link #getPointAt(double)
* getPointAt(MathUtils.SEMI_PI)} but it does not do any computation and always
* return the same instance.
* </p>
* @return an arbitrary y axis point on the circle
* @see #getPointAt(double)
* @see #getXAxis()
* @see #getPole()
*/
public Vector3D getYAxis() {
return y;
}
/** Get the pole of the circle.
* <p>
* As the circle is a great circle, the pole does <em>not</em>
* belong to it.
* </p>
* @return pole of the circle
* @see #getXAxis()
* @see #getYAxis()
*/
public Vector3D getPole() {
return pole;
}
/** Get the arc of the instance that lies inside the other circle.
* @param other other circle
* @return arc of the instance that lies inside the other circle
*/
public Arc getInsideArc(final Circle other) {
final double alpha = getPhase(other.pole);
return new Arc(alpha - MathUtils.SEMI_PI, alpha + MathUtils.SEMI_PI, tolerance);
}
/** {@inheritDoc} */
@Override
public SubCircle wholeHyperplane() {
return new SubCircle(this, new ArcsSet(tolerance));
}
/** {@inheritDoc} */
@Override
public SubCircle emptyHyperplane() {
final RegionFactory<Sphere1D, S1Point, LimitAngle, SubLimitAngle> factory = new RegionFactory<>();
return new SubCircle(this, factory.getComplement(new ArcsSet(tolerance)));
}
/** Build a region covering the whole space.
* @return a region containing the instance (really a {@link
* SphericalPolygonsSet SphericalPolygonsSet} instance)
*/
@Override
public SphericalPolygonsSet wholeSpace() {
return new SphericalPolygonsSet(tolerance);
}
/** {@inheritDoc}
* @see #getOffset(Vector3D)
*/
@Override
public double getOffset(final S2Point point) {
return getOffset(point.getVector());
}
/** Get the offset (oriented distance) of a direction.
* <p>The offset is defined as the angular distance between the
* circle center and the direction minus the circle radius. It
* is therefore 0 on the circle, positive for directions outside of
* the cone delimited by the circle, and negative inside the cone.</p>
* @param direction direction to check
* @return offset of the direction
* @see #getOffset(S2Point)
*/
public double getOffset(final Vector3D direction) {
return Vector3D.angle(pole, direction) - MathUtils.SEMI_PI;
}
/** {@inheritDoc} */
@Override
public S2Point moveToOffset(final S2Point point, final double offset) {
final SinCos scOld = FastMath.sinCos(getOffset(point));
final SinCos scNew = FastMath.sinCos(offset);
final double ratio = scNew.cos() / scOld.cos();
return new S2Point(new Vector3D(ratio * scOld.sin() - scNew.sin(), pole,
ratio, point.getVector()));
}
/** {@inheritDoc} */
@Override
public S2Point arbitraryPoint() {
return new S2Point(pole.orthogonal());
}
/** {@inheritDoc} */
@Override
public boolean sameOrientationAs(final Circle other) {
return Vector3D.dotProduct(pole, other.pole) >= 0.0;
}
/**
* Get the arc on this circle between two defining points. Only the point's projection
* on the circle matters, which is computed using {@link #getPhase(Vector3D)}.
*
* @param a first point.
* @param b second point.
* @return an arc of the circle.
*/
public Arc getArc(final S2Point a, final S2Point b) {
final double phaseA = getPhase(a.getVector());
double phaseB = getPhase(b.getVector());
if (phaseB < phaseA) {
phaseB += 2 * FastMath.PI;
}
return new Arc(phaseA, phaseB, tolerance);
}
/** Get a {@link org.hipparchus.geometry.partitioning.Transform
* Transform} embedding a 3D rotation.
* @param rotation rotation to use
* @return a new transform that can be applied to either {@link
* org.hipparchus.geometry.Point Point}, {@link Circle Line} or {@link
* org.hipparchus.geometry.partitioning.SubHyperplane
* SubHyperplane} instances
*/
public static Transform<Sphere2D, S2Point, Circle, SubCircle, Sphere1D, S1Point, LimitAngle, SubLimitAngle>
getTransform(final Rotation rotation) {
return new CircleTransform(rotation);
}
/** Class embedding a 3D rotation. */
private static class CircleTransform
implements Transform<Sphere2D, S2Point, Circle, SubCircle, Sphere1D, S1Point, LimitAngle, SubLimitAngle> {
/** Underlying rotation. */
private final Rotation rotation;
/** Build a transform from a {@code Rotation}.
* @param rotation rotation to use
*/
CircleTransform(final Rotation rotation) {
this.rotation = rotation;
}
/** {@inheritDoc} */
@Override
public S2Point apply(final S2Point point) {
return new S2Point(rotation.applyTo(point.getVector()));
}
/** {@inheritDoc} */
@Override
public Circle apply(final Circle circle) {
return new Circle(rotation.applyTo(circle.pole),
rotation.applyTo(circle.x),
rotation.applyTo(circle.y),
circle.tolerance);
}
/** {@inheritDoc} */
@Override
public SubLimitAngle apply(final SubLimitAngle sub, final Circle original, final Circle transformed) {
// as the circle is rotated, the limit angles are rotated too
return sub;
}
}
}