001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.geometry.coordinate;
033
034 import java.util.List;
035 import org.opengis.geometry.primitive.CurveInterpolation;
036 import org.opengis.geometry.primitive.CurveSegment;
037 import org.opengis.annotation.UML;
038
039 import static org.opengis.annotation.Obligation.*;
040 import static org.opengis.annotation.Specification.*;
041
042
043 /**
044 * Similar to a {@linkplain LineString line string} except that the interpolation is
045 * by circular arcs. Since it requires 3 points to determine a circular arc, the
046 * {@linkplain #getControlPoints control points} are treated as a sequence of overlapping
047 * sets of 3 {@linkplain Position positions}, the start of each arc, some point between the
048 * start and end, and the end of each arc. Since the end of each arc is the start of the next,
049 * this {@linkplain Position position} is not repeated in the {@linkplain #getControlPoints
050 * control points} sequence.
051 *
052 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
053 * @author Martin Desruisseaux (IRD)
054 * @since GeoAPI 1.0
055 *
056 * @see GeometryFactory#createArcString
057 * @see ArcStringByBulge#asArcString
058 */
059 @UML(identifier="GM_ArcString", specification=ISO_19107)
060 public interface ArcString extends CurveSegment {
061 /**
062 * Returns the number of circular arcs in the string. Since the interpolation method
063 * requires overlapping sets of 3 positions, the number of arcs determines the number
064 * of {@linkplain #getControlPoints control points}:
065 *
066 * <blockquote>
067 * <pre>numArc = ({@link #getControlPoints controlPoints}.length - 1)/2</pre>
068 * </blockquote>
069 *
070 * @return The number of circular arcs.
071 */
072 @UML(identifier="numArc", obligation=MANDATORY, specification=ISO_19107)
073 int getNumArc();
074
075 /**
076 * Returns the sequence of points used to control the arcs in this string. The first three
077 * {@linkplain Position positions} in the sequence determines the first arc. Any three
078 * consecutive {@linkplain Position positions} beginning with an odd offset, determine
079 * another arc in the string.
080 *
081 * @return The control points. The array size is <code>2*{@link #getNumArc numArc} +1</code>.
082 */
083 @UML(identifier="controlPoints", obligation=MANDATORY, specification=ISO_19107)
084 PointArray getControlPoints();
085
086 /**
087 * The interpolation for a {@code ArcString} is
088 * "{@linkplain CurveInterpolation#CIRCULAR_ARC_3_POINTS circular arc by 3 points}".
089 *
090 * @return Always {@link CurveInterpolation#CIRCULAR_ARC_3_POINTS}.
091 */
092 @UML(identifier="interpolation", obligation=MANDATORY, specification=ISO_19107)
093 CurveInterpolation getInterpolation();
094
095 /**
096 * Constructs a sequence of arcs that is the geometric equivalent of this arc string.
097 *
098 * @return The sequence of arcs.
099 */
100 @UML(identifier="asGM_Arc", obligation=MANDATORY, specification=ISO_19107)
101 List<Arc> asArcs();
102 }