    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_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    }