Java tutorial
/* * 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.math3.geometry.spherical.twod; import org.apache.commons.math3.geometry.Point; import org.apache.commons.math3.geometry.euclidean.threed.Rotation; import org.apache.commons.math3.geometry.euclidean.threed.Vector3D; import org.apache.commons.math3.geometry.partitioning.Embedding; import org.apache.commons.math3.geometry.partitioning.Hyperplane; import org.apache.commons.math3.geometry.partitioning.SubHyperplane; import org.apache.commons.math3.geometry.partitioning.Transform; import org.apache.commons.math3.geometry.spherical.oned.Arc; import org.apache.commons.math3.geometry.spherical.oned.ArcsSet; import org.apache.commons.math3.geometry.spherical.oned.S1Point; import org.apache.commons.math3.geometry.spherical.oned.Sphere1D; import org.apache.commons.math3.util.FastMath; /** 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 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> * @since 3.3 */ public class Circle implements Hyperplane<Sphere2D>, Embedding<Sphere2D, Sphere1D> { /** 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 */ public Circle(final Vector3D pole, final double 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 \( \pi \).</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 */ public Circle(final S2Point first, final S2Point second, final double 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 */ private Circle(final Vector3D pole, final Vector3D x, final Vector3D y, final double 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} */ 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} */ public Point<Sphere2D> project(Point<Sphere2D> point) { return toSpace(toSubSpace(point)); } /** {@inheritDoc} */ public double getTolerance() { return tolerance; } /** {@inheritDoc} * @see #getPhase(Vector3D) */ public S1Point toSubSpace(final Point<Sphere2D> point) { return new S1Point(getPhase(((S2Point) 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(Point) */ public double getPhase(final Vector3D direction) { return FastMath.PI + FastMath.atan2(-direction.dotProduct(y), -direction.dotProduct(x)); } /** {@inheritDoc} * @see #getPointAt(double) */ public S2Point toSpace(final Point<Sphere1D> point) { return new S2Point(getPointAt(((S1Point) 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(Point) * @see #getXAxis() * @see #getYAxis() */ public Vector3D getPointAt(final double alpha) { return new Vector3D(FastMath.cos(alpha), x, FastMath.sin(alpha), 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(0.5 * FastMath.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); final double halfPi = 0.5 * FastMath.PI; return new Arc(alpha - halfPi, alpha + halfPi, tolerance); } /** {@inheritDoc} */ public SubCircle wholeHyperplane() { return new SubCircle(this, new ArcsSet(tolerance)); } /** Build a region covering the whole space. * @return a region containing the instance (really a {@link * SphericalPolygonsSet SphericalPolygonsSet} instance) */ public SphericalPolygonsSet wholeSpace() { return new SphericalPolygonsSet(tolerance); } /** {@inheritDoc} * @see #getOffset(Vector3D) */ public double getOffset(final Point<Sphere2D> point) { return getOffset(((S2Point) 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(Point) */ public double getOffset(final Vector3D direction) { return Vector3D.angle(pole, direction) - 0.5 * FastMath.PI; } /** {@inheritDoc} */ public boolean sameOrientationAs(final Hyperplane<Sphere2D> other) { final Circle otherC = (Circle) other; return Vector3D.dotProduct(pole, otherC.pole) >= 0.0; } /** Get a {@link org.apache.commons.math3.geometry.partitioning.Transform * Transform} embedding a 3D rotation. * @param rotation rotation to use * @return a new transform that can be applied to either {@link * Point Point}, {@link Circle Line} or {@link * org.apache.commons.math3.geometry.partitioning.SubHyperplane * SubHyperplane} instances */ public static Transform<Sphere2D, Sphere1D> getTransform(final Rotation rotation) { return new CircleTransform(rotation); } /** Class embedding a 3D rotation. */ private static class CircleTransform implements Transform<Sphere2D, Sphere1D> { /** Underlying rotation. */ private final Rotation rotation; /** Build a transform from a {@code Rotation}. * @param rotation rotation to use */ public CircleTransform(final Rotation rotation) { this.rotation = rotation; } /** {@inheritDoc} */ public S2Point apply(final Point<Sphere2D> point) { return new S2Point(rotation.applyTo(((S2Point) point).getVector())); } /** {@inheritDoc} */ public Circle apply(final Hyperplane<Sphere2D> hyperplane) { final Circle circle = (Circle) hyperplane; return new Circle(rotation.applyTo(circle.pole), rotation.applyTo(circle.x), rotation.applyTo(circle.y), circle.tolerance); } /** {@inheritDoc} */ public SubHyperplane<Sphere1D> apply(final SubHyperplane<Sphere1D> sub, final Hyperplane<Sphere2D> original, final Hyperplane<Sphere2D> transformed) { // as the circle is rotated, the limit angles are rotated too return sub; } } }