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