001    //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/model/spatialschema/Geometry.java $
002    /*----------------------------------------------------------------------------
003     This file is part of deegree, http://deegree.org/
004     Copyright (C) 2001-2009 by:
005       Department of Geography, University of Bonn
006     and
007       lat/lon GmbH
008    
009     This library is free software; you can redistribute it and/or modify it under
010     the terms of the GNU Lesser General Public License as published by the Free
011     Software Foundation; either version 2.1 of the License, or (at your option)
012     any later version.
013     This library is distributed in the hope that it will be useful, but WITHOUT
014     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
015     FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
016     details.
017     You should have received a copy of the GNU Lesser General Public License
018     along with this library; if not, write to the Free Software Foundation, Inc.,
019     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020    
021     Contact information:
022    
023     lat/lon GmbH
024     Aennchenstr. 19, 53177 Bonn
025     Germany
026     http://lat-lon.de/
027    
028     Department of Geography, University of Bonn
029     Prof. Dr. Klaus Greve
030     Postfach 1147, 53001 Bonn
031     Germany
032     http://www.geographie.uni-bonn.de/deegree/
033    
034     e-mail: info@deegree.org
035    ----------------------------------------------------------------------------*/
036    package org.deegree.model.spatialschema;
037    
038    import java.io.Serializable;
039    
040    import org.deegree.model.crs.CoordinateSystem;
041    
042    import com.vividsolutions.jts.operation.buffer.BufferOp;
043    
044    /**
045     *
046     * The basic interface for all geometries. it declares the methods that are common to all geometries. this doesn't means
047     * for example that all geometries defines a valid boundary but is there asked for they should be able to answer (with
048     * null).
049     *
050     * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
051     *
052     * @author last edited by: $Author: mschneider $
053     *
054     * @version $Revision: 18195 $, $Date: 2009-06-18 17:55:39 +0200 (Do, 18 Jun 2009) $
055     *
056     */
057    public interface Geometry extends Serializable {
058    
059        /**
060         * (default) a semi-circle
061         */
062        int BUFFER_CAP_ROUND = BufferOp.CAP_ROUND;
063    
064        /**
065         * a straight line perpendicular to the end segment
066         */
067        int BUFFER_CAP_BUTT = BufferOp.CAP_BUTT;
068    
069        /**
070         * a half-square
071         */
072        int BUFFER_CAP_SQUARE = BufferOp.CAP_SQUARE;
073    
074        /**
075         * @return the bounding box of a geometry
076         */
077        Envelope getEnvelope();
078    
079        /**
080         * @return the boundary of a geometry
081         */
082        Boundary getBoundary();
083    
084        /**
085         * The operation "dimension" shall return the inherent dimension of this Geometry, which shall be less than or equal
086         * to the coordinate dimension. The dimension of a collection of geometric objects shall be the largest dimension of
087         * any of its pieces. Points are 0-dimensional, curves are 1-dimensional, surfaces are 2-dimensional, and solids are
088         * 3-dimensional.
089         *
090         * @return the for this geometry defined dimension.
091         */
092        int getDimension();
093    
094        /**
095         * The operation "coordinateDimension" shall return the dimension of the coordinates that define this Geometry,
096         * which must be the same as the coordinate dimension of the coordinate reference system for this Geometry.
097         *
098         * @return the actual dimension
099         */
100        int getCoordinateDimension();
101    
102        /**
103         * @return the spatial reference system of a geometry
104         */
105        CoordinateSystem getCoordinateSystem();
106    
107        /**
108         * @return true if no geometry values resp. points stored within the geometry.
109         */
110        boolean isEmpty();
111    
112        /**
113         * The operation "distance" shall return the distance between this Geometry and another Geometry. This distance is
114         * defined to be the greatest lower bound of the set of distances between all pairs of points that include one each
115         * from each of the two Geometries. A "distance" value shall be a positive number associated to distance units such
116         * as meters or standard foot. If necessary, the second geometric object shall be transformed into the same
117         * coordinate reference system as the first before the distance is calculated.
118         * <p>
119         * </p>
120         * If the geometric objects overlap, or touch, then their distance apart shall be zero. Some current implementations
121         * use a "negative" distance for such cases, but the approach is neither consistent between implementations, nor
122         * theoretically viable.
123         *
124         * @param other
125         * @return the distance between this Geometry and another Geometry
126         */
127        double distance( Geometry other );
128    
129        /**
130         * translate a geometry by the submitted values. if the length of <tt>d</tt> is smaller then the dimension of the
131         * geometry only the first d.length'th coordinates will be translated. If the length of <tt>d</tt> is larger then
132         * the dimension of the geometry an ArrayIndexOutOfBoundExceptions raises.
133         *
134         * @param d
135         *            vector to translate the geometry with
136         */
137        void translate( double[] d );
138    
139        /**
140         * The operation "centroid" shall return the mathematical centroid for this Geometry. The result is not guaranteed
141         * to be on the object. For heterogeneous collections of primitives, the centroid only takes into account those of
142         * the largest dimension. For example, when calculating the centroid of surfaces, an average is taken weighted by
143         * area. Since curves have no area they do not contribute to the average.
144         *
145         * @return the centroid
146         */
147        Point getCentroid();
148    
149        /**
150         * The operation "convexHull" shall return a Geometry that represents the convex hull of this Geometry.
151         *
152         * @return the convexHull
153         */
154        Geometry getConvexHull();
155    
156        /**
157         * The operation "buffer" shall return a Geometry containing all points whose distance from this Geometry is less
158         * than or equal to the "distance" passed as a parameter. The Geometry returned is in the same reference system as
159         * this original Geometry. The dimension of the returned Geometry is normally the same as the coordinate dimension -
160         * a collection of Surfaces in 2D space and a collection of Solids in 3D space, but this may be application defined.
161         *
162         * @param distance
163         * @return a Geometry containing all points whose distance from this Geometry is less than or equal to the
164         *         "distance" passed as a parameter
165         */
166        Geometry getBuffer( double distance );
167    
168        /**
169         * The operation "buffer" shall return a Geometry containing all points whose distance from this Geometry is less
170         * than or equal to the "distance" passed as a parameter. The Geometry returned is in the same reference system as
171         * this original Geometry. The dimension of the returned Geometry is normally the same as the coordinate dimension -
172         * a collection of Surfaces in 2D space and a collection of Solids in 3D space, but this may be application defined.
173         *
174         * @param distance
175         * @param segments
176         * @param capStyle
177         * @return a Geometry containing all points whose distance from this Geometry is less than or equal to the
178         *         "distance" passed as a parameter
179         */
180        Geometry getBuffer( double distance, int segments, int capStyle );
181    
182        /**
183         * The Boolean valued operation "contains" shall return TRUE if this Geometry contains another Geometry.
184         *
185         * @param other
186         * @return true if the other is conatained.
187         */
188        boolean contains( Geometry other );
189    
190        /**
191         * The Boolean valued operation "contains" shall return TRUE if this Geometry contains a single point given by a
192         * coordinate.
193         *
194         * @param position
195         * @return true if this contains the position.
196         */
197        boolean contains( Position position );
198    
199        /**
200         * The Boolean valued operation "intersects" shall return TRUE if this Geometry intersects another Geometry. Within
201         * a Complex, the Primitives do not intersect one another. In general, topologically structured data uses shared
202         * geometric objects to capture intersection information.
203         *
204         * @param other
205         * @return true if this Geometry intersects another Geometry
206         */
207        boolean intersects( Geometry other );
208    
209        /**
210         * The "union" operation shall return the set theoretic union of this Geometry and the passed Geometry.
211         *
212         * @param other
213         * @return the union of this and the other.
214         */
215        Geometry union( Geometry other );
216    
217        /**
218         * The "intersection" operation shall return the set theoretic intersection of this Geometry and the passed
219         * Geometry.
220         *
221         * @param other
222         * @return the intersection of this Geometry and the other Geometry.
223         * @throws GeometryException
224         */
225        Geometry intersection( Geometry other )
226                                throws GeometryException;
227    
228        /**
229         * The "difference" operation shall return the set theoretic difference of this Geometry and the passed Geometry.
230         *
231         * @param other
232         * @return the difference between this and the other.
233         */
234        Geometry difference( Geometry other );
235    
236        /**
237         * provide optimized proximity queries within for a distance . calvin added on 10/21/2003
238         *
239         * @param other
240         * @param distance
241         * @return true if the geometry is in distance of this geometry
242         */
243        boolean isWithinDistance( Geometry other, double distance );
244    
245        /**
246         * sets tolerance value use for topological operations
247         *
248         * @param tolerance
249         */
250        void setTolerance( double tolerance );
251    
252        /**
253         * @return the tolerance value use for topological operations
254         *
255         */
256        double getTolerance();
257    
258    }