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 * A variant of the arc that stores the parameters of the second constructor of
045 * the component {@linkplain Arc arcs} and recalculates the other attributes of
046 * the standard arc. The {@linkplain ArcString#getControlPoints control point} sequence
047 * is similar to that in {@linkplain ArcString arc string}, but the midPoint
048 * {@linkplain Position position} is not needed since it is to be calculated.
049 * The control point sequence shall consist of the start and end points of each arc.
050 *
051 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
052 * @author Martin Desruisseaux (IRD)
053 * @since GeoAPI 1.0
054 *
055 * @see GeometryFactory#createArcStringByBulge
056 */
057 @UML(identifier="GM_ArcStringByBulge", specification=ISO_19107)
058 public interface ArcStringByBulge extends CurveSegment {
059 /**
060 * Returns the offset of each arc's midpoint. The attribute "bulge" is the real number
061 * multiplier for the normal that determines the offset direction of the midpoint of each
062 * arc. The length of the bulge sequence is exactly 1 less than the length of the control
063 * point array, since a bulge is needed for each pair of adjacent points in the control point
064 * array.
065 * <p>
066 * The bulge is not given by a distance, since it is simply a multiplier for the normal,
067 * the unit of the offset distance is determined by the length function for vectors in
068 * the coordinate reference system. In the examples in this specification, the normal is
069 * often given as a Euclidean unit vector, which may or may not fix its length to one
070 * depending of the distance formulae used for the coordinate reference system.
071 * <p>
072 * The midpoint of the resulting arc is given by:
073 *
074 * <blockquote><code>
075 * midPoint = (({@link #getStartPoint startPoint} +
076 * {@link #getEndPoint endPoint})/2.0)
077 * + bulge×{@link #getNormals normal}
078 * </code></blockquote>
079 *
080 * @return The offset of each arc's midpoint.
081 */
082 @UML(identifier="bulge", obligation=MANDATORY, specification=ISO_19107)
083 double[] getBulges();
084
085 /**
086 * Returns the number of circular arcs in the string. Since the interpolation method
087 * requires overlapping sets of 2 positions, the number of arcs determines the number
088 * of {@linkplain ArcString#getControlPoints control points}.
089 *
090 * <blockquote>
091 * <pre>numArc = {@link ArcString#getControlPoints controlPoints}.length - 1</pre>
092 * </blockquote>
093 *
094 * @return The number of circular arcs.
095 */
096 @UML(identifier="numArc", obligation=MANDATORY, specification=ISO_19107)
097 int getNumArc();
098
099 /**
100 * Returns a vector normal (perpendicular) to the chord of the arc, the line joining the
101 * first and last point of the arc. In a 2D coordinate system, there are only two possible
102 * directions for the normal, and it is often given as a signed real, indicating its length,
103 * with a positive sign indicating a left turn angle from the chord line, and a negative sign
104 * indicating a right turn from the chord. In 3D, the normal determines the plane of the arc,
105 * along with the {@linkplain #getStartPoint start} and {@linkplain #getEndPoint end point}
106 * of the arc.
107 * <p>
108 * The normal is usually a unit vector, but this is not absolutely necessary. If the normal
109 * is a zero vector, the geometric object becomes equivalent to the straight line between
110 * the two end points. The length of the normal sequence is exactly the same as for the
111 * {@linkplain #getBulges bulge} sequence, 1 less than the control point sequence length.
112 *
113 * @return The sequence of normal vectors.
114 */
115 @UML(identifier="normal", obligation=MANDATORY, specification=ISO_19107)
116 List<double[]> getNormals();
117
118 /**
119 * The interpolation for a {@code ArcStringByBulge} is
120 * "{@linkplain CurveInterpolation#CIRCULAR_ARC_2_POINTS_WITH_BULGE
121 * Circular arc by 2 points and bulge factor}".
122 *
123 * @return Always {@link CurveInterpolation#CIRCULAR_ARC_2_POINTS_WITH_BULGE}.
124 */
125 @UML(identifier="interpolation", obligation=MANDATORY, specification=ISO_19107)
126 CurveInterpolation getInterpolation();
127
128 /**
129 * Recast as a base {@linkplain ArcString arc string}.
130 *
131 * @return This arc string by bulge as a base {@linkplain ArcString arc string}.
132 */
133 @UML(identifier="asGM_ArcString", obligation=MANDATORY, specification=ISO_19107)
134 ArcString asArcString();
135 }