arc.java

GEo 地理操作源代码

/*$************************************************************************************************
 **
 ** $Id: Arc.java,v 1.4 2004/05/06 15:51:51 desruisseaux Exp $
 **
 ** $Source: /cvsroot/geoapi/src/org/opengis/spatialschema/geometry/geometry/Arc.java,v $
 **
 ** Copyright (C) 2003 Open GIS Consortium, Inc. All Rights Reserved. http://www.opengis.org/Legal/
 **
 *************************************************************************************************/
package org.opengis.spatialschema.geometry.geometry;

// OpenGIS direct dependencies
import org.opengis.spatialschema.geometry.DirectPosition;
import org.opengis.spatialschema.geometry.primitive.Bearing;


/**
 * Arc of the circle determined by 3 points, starting at the first, passing through the second
 * and terminating at the third. If the 3 points are co-linear, then the arc shall be a 3-point
 * line string, and will not be able to return values for center, radius, start angle and end
 * angle.
 *
 * <blockquote><font size=2>
 * <strong>NOTE:</strong> In the model, an  <code>Arc</code> is a subclass of {@link ArcString},
 * being a trivial arc string consisting of only one arc. This may be counter-intuitive in the
 * sense that subclasses are often thought of as more complex than their superclass (with
 * additional methods and attributes). An <code>Arc</code> is simpler than a {@linkplain ArcString
 * arc string} in that it has less data, but it is more complex in that it can return geometric
 * information such as "center", "start angle", and "end angle". This additional computational
 * complexity forces the subclassing to be the way it is. In addition the "is type of" semantics
 * works this way and not the other.
 * </font></blockquote>
 *
 * In its simplest representation, the three points in the {@linkplain #getControlPoints control point}
 * sequence for an <code>Arc</code> shall consist of, in order, the initial point on the arc, some
 * point on the arc neither at the start or end, and the end point of the <code>Arc</code>. If
 * additional points are given, then all points must lie on the circle defined by any 3 non-colinear
 * points in the control point array. All points shall lie on the same circle, and shall be given
 * in the {@linkplain #getControlPoints control point} array in the order in which they occur on
 * the arc.
 *
 * <blockquote><font size=2>
 * <strong>NOTE:</strong> The use of the term "midPoint" for the center {@linkplain Position position}
 * of the {@linkplain #getControlPoints control point} sequence is not meant to require that
 * the {@linkplain Position position} be the geometric midpoint of the arc. This is the best
 * choice for this {@linkplain Position position} from a computational stability perspective,
 * but it is not absolutely necessary for the mathematics to work.
 * </font></blockquote>
 *
 * @UML abstract GM_Arc
 * @author ISO/DIS 19107
 * @author <A HREF="http://www.opengis.org">OpenGIS&reg; consortium</A>
 * @version 2.0
 *
 * @see GeometryFactory#createArc(Position,Position,Position)
 * @see GeometryFactory#createArc(Position,Position,double,double[])
 */
public interface Arc extends ArcString {
    /**
     * Calculates the center of the circle of which this arc is a portion as a direct position.
     * The {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system}
     * of the returned {@linkplain DirectPosition direct position} will be the same as that
     * for this <code>Arc</code>. In some extreme cases, the {@linkplain DirectPosition direct
     * position} as calculated may lie outside the domain of validity of the coordinate reference
     * system used by this <code>Arc</code> (especially if the underlying arc has a very large
     * radius). Implementations may choose an appropriate course of action in such cases.
     *
     * @return The center of the circle of which this arc is a portion.
     * @UML operation center
     */
    public DirectPosition getCenter();

    /**
     * Calculates the radius of the circle of which this arc is a portion.
     *
     * @return The radius of the circle of which this arc is a portion.
     * @UML operation radius
     * @unitof Distance
     */
    public double getRadius();

    /**
     * Calculates the bearing of the line from the center of the circle of which this arc is a
     * portion to the start point of the arc. In the 2D case this will be a start angle. In the
     * 3D case, the normal bearing angle implies that the arc is parallel to the reference circle.
     * If this is not the case, then the bearing must include altitude information.
     *
     * @return The bearing from the {@linkplain #getCenter center} of the circle to the
     *         {@link #getStartPoint start point} of this arc.
     * @UML operation startAngle
     *
     * @revisit Inconsistent UML: "startAngle" and "startOfArc" are both used.
     *          Which one is the right one?
     */
    public Bearing getStartAngle();

    /**
     * Calculates the bearing of the line from the center of the circle of which this arc is a
     * portion to the end point of the arc. In the 2D case this will be an end angle. In the 3D
     * case, the normal bearing angle implies that the arc is parallel to the reference circle.
     * If this is not the case, then the bearing must include altitude information.
     *
     * @return The bearing from the {@linkplain #getCenter center} of the circle to the
     *         {@link #getEndPoint end point} of this arc.
     * @UML operation endAngle
     *
     * @revisit Inconsistent UML: "endAngle" and "endOfArc" are both used.
     *          Which one is the right one?
     */
    public Bearing getEndAngle();
}