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.primitive;
033
034 import java.util.List;
035 import org.opengis.geometry.Envelope;
036 import org.opengis.geometry.coordinate.Position;
037 import org.opengis.geometry.MismatchedDimensionException;
038 import org.opengis.geometry.MismatchedReferenceSystemException;
039 import org.opengis.referencing.crs.CoordinateReferenceSystem;
040 import org.opengis.annotation.UML;
041 import org.opengis.annotation.Extension;
042
043 import static org.opengis.annotation.Obligation.*;
044 import static org.opengis.annotation.Specification.*;
045
046
047 /**
048 * A factory of {@linkplain Primitive primitive} geometric objects.
049 * All primitives created through this interface will use the
050 * {@linkplain #getCoordinateReferenceSystem factory's coordinate reference system}.
051 * Creating primitives in a different CRS may requires a different instance of
052 * {@code PrimitiveFactory}.
053 *
054 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
055 * @author Martin Desruisseaux (IRD)
056 * @since GeoAPI 1.0
057 */
058 public interface PrimitiveFactory {
059 /**
060 * Returns the coordinate reference system in use for all {@linkplain Primitive primitive}
061 * geometric objects to be created through this interface.
062 */
063 CoordinateReferenceSystem getCoordinateReferenceSystem();
064
065 /**
066 * Returns an envelope as a primitive. An {@linkplain Envelope envelope} will often be
067 * used in query operations, and therefore must have a cast operation that returns a
068 * {@linkplain org.opengis.geometry.Geometry geometry}. The actual return of the operation depends
069 * upon the dimension of the {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate
070 * reference system} and the extent of the {@linkplain Envelope envelope}. In a 2D system,
071 * the primitive returned will be a {@linkplain Surface surface} (if the envelope does not
072 * collapse to a point or line). In 3D systems, the usual return is a {@linkplain Solid solid}.
073 * <p>
074 * <strong>EXAMPLE:</strong> In the case where the {@linkplain Envelope envelope} is totally
075 * contained in the domain of validity of its {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem
076 * coordinate reference system} object, its associated {@linkplain Primitive primitive} is the convex
077 * hull of the various permutations of the coordinates in the corners. For example, suppose
078 * that a particular envelope in 2D is defined as:
079 *
080 * <blockquote><pre>
081 * lowerCorner = (x1, y1)
082 * upperCorner = (x2, y2)</pre></blockquote>
083 *
084 * (we ignore the CRS below, assuming that it is a global variable), then we can take the
085 * various permutations of the ordinate values to create a list of polygon corners:
086 *
087 * <blockquote><pre>
088 * {@link org.opengis.geometry.aggregate.MultiPoint} = { (x1, y1), (x1, y2), (x2, y1), (x2, y2) }</pre></blockquote>
089 *
090 * If we then apply the {@linkplain org.opengis.geometry.Geometry#getConvexHull convex hull}
091 * function to the multi point, we get a polygon as a {@linkplain Surface surface}.
092 * The extent of a polygon in 2D is totally defined by its
093 * {@linkplain org.opengis.geometry.Geometry#getBoundary boundary} (internal surface
094 * patches are planar and do not need interior control points) which gives
095 * us a data type to represent {@linkplain Surface surface} in 2D:
096 *
097 * <blockquote><pre>
098 * {@link org.opengis.geometry.primitive.Ring} = {
099 * {@link org.opengis.geometry.coordinate.LineString} = { (x1, y1), (x1, y2), (x2, y2), (x2, y1), (x1, y1)}
100 * }</pre></blockquote>
101 *
102 * So that the {@linkplain SurfaceBoundary surface boundary} record contains the above-cited
103 * exterior ring, and an empty set of interior rings (convex sets have no "interior" holes).
104 *
105 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
106 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
107 * @throws MismatchedDimensionException If geometric objects given in argument don't have
108 * the expected dimension.
109 */
110 @UML(identifier="GM_Primitive(GM_Envelope)", obligation=MANDATORY, specification=ISO_19107)
111 Primitive createPrimitive(Envelope envelope)
112 throws MismatchedReferenceSystemException, MismatchedDimensionException;
113
114 /**
115 * Creates a point at the specified location specified by coordinates.
116 *
117 * @throws MismatchedDimensionException If geometric objects given in argument don't have
118 * the expected dimension.
119 */
120 @Extension
121 Point createPoint(double[] coordinates)
122 throws MismatchedDimensionException;
123
124 /**
125 * Creates a point at the specified position.
126 *
127 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
128 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
129 * @throws MismatchedDimensionException If geometric objects given in argument don't have
130 * the expected dimension.
131 */
132 @UML(identifier="GM_Point(GM_Position)", obligation=MANDATORY, specification=ISO_19107)
133 Point createPoint(Position position)
134 throws MismatchedReferenceSystemException, MismatchedDimensionException;
135
136 /**
137 * Takes a list of {@linkplain CurveSegment curve segments} with the appropriate
138 * end-to-start relationships and creates a {@linkplain Curve curve}.
139 *
140 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
141 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
142 * @throws MismatchedDimensionException If geometric objects given in argument don't have
143 * the expected dimension.
144 */
145 @UML(identifier="GM_Curve(GM_CurveSegment[1..n])", obligation=MANDATORY, specification=ISO_19107)
146 Curve createCurve(List<CurveSegment> segments)
147 throws MismatchedReferenceSystemException, MismatchedDimensionException;
148
149 /**
150 * Takes a list of {@linkplain SurfacePatch surface patches} with the appropriate
151 * side-toside relationships and creates a {@linkplain Surface surface}.
152 *
153 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
154 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
155 * @throws MismatchedDimensionException If geometric objects given in argument don't have
156 * the expected dimension.
157 */
158 @UML(identifier="GM_Surface(GM_SurfacePatch[1..n])", obligation=MANDATORY, specification=ISO_19107)
159 Surface createSurface(List<SurfacePatch> surfaces)
160 throws MismatchedReferenceSystemException, MismatchedDimensionException;
161
162 /**
163 * Constructs a {@linkplain Surface surface} by indicating its boundary as a collection
164 * of {@linkplain Curve curves} organized into the specified {@linkplain SurfaceBoundary
165 * surface boundary}. This method is guaranteed to work always in 2D coordinate spaces,
166 * In 3D coordinate spaces, this method shall require all of the defining boundary
167 * {@linkplain Curve curve} instances to be coplanar (lie in a single plane) which will
168 * define the surface interior.
169 *
170 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
171 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
172 * @throws MismatchedDimensionException If geometric objects given in argument don't have
173 * the expected dimension.
174 */
175 @UML(identifier="GM_Surface(GM_SurfaceBoundary)", obligation=MANDATORY, specification=ISO_19107)
176 Surface createSurface(SurfaceBoundary boundary)
177 throws MismatchedReferenceSystemException, MismatchedDimensionException;
178
179 /**
180 * Constructs a new {@linkplain SurfaceBoundary surface boundary} object
181 * representing the boundary of a two-dimensional surface.
182 *
183 * @param exterior In the normal 2D case, this identifies the curve that is
184 * the exterior curve of the surface. In cases where an exterior
185 * cannot be unambiguously chosen (a bounded cylinder, for example),
186 * this parameter may be null.
187 * @param interiors All of the curve components of the boundary that are not
188 * the exterior.
189 * @throws MismatchedReferenceSystemException If geometric objects given in
190 * argument don't use a {@linkplain CoordinateReferenceSystem
191 * coordinate reference system} compatible with the one held by this
192 * factory.
193 * @throws MismatchedDimensionException If geometric objects given in argument don't have
194 * the expected dimension.
195 */
196 @Extension
197 SurfaceBoundary createSurfaceBoundary(Ring exterior, List<Ring> interiors)
198 throws MismatchedReferenceSystemException, MismatchedDimensionException;
199
200 /**
201 * Constructs a {@linkplain Solid solid} by indicating its boundary as a collection of
202 * {@linkplain Shell shells} organized into a {@linkplain SolidBoundary solid boundary}.
203 * Since this specification is limited to 3-dimensional coordinate reference systems,
204 * any solid is definable by its boundary.
205 *
206 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
207 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
208 * @throws MismatchedDimensionException If geometric objects given in argument don't have
209 * the expected dimension.
210 */
211 @UML(identifier="GM_Solid(GM_SolidBoundary)", obligation=MANDATORY, specification=ISO_19107)
212 Solid createSolid(SolidBoundary boundary)
213 throws MismatchedReferenceSystemException, MismatchedDimensionException;
214
215 /**
216 * Constructs a {@linkplain Ring ring} out of its component curves.
217 *
218 * @param curves The list of curves that comprise the newly created Ring.
219 * These curves must connect to form a continuous curve whose start
220 * point is the same as its end point.
221 *
222 * @throws MismatchedReferenceSystemException If geometric objects given in argument don't
223 * use compatible {@linkplain CoordinateReferenceSystem coordinate reference system}.
224 * @throws MismatchedDimensionException If geometric objects given in argument don't have
225 * the expected dimension.
226 */
227 @Extension
228 Ring createRing(List<OrientableCurve> curves)
229 throws MismatchedReferenceSystemException, MismatchedDimensionException;
230 }