Application: gvSIG desktop

/* gvSIG. Geographic Information System of the Valencian Government

 *

 * Copyright (C) 2007-2008 Infrastructures and Transports Department

 * of the Valencian Government (CIT)

 * 

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 * 

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 

 * MA  02110-1301, USA.

 * 

 */

/*

 * AUTHORS (In addition to CIT):

 * 2009 {Iver T.I.}   {Task}

 */

package org.gvsig.fmap.geom;

import java.awt.Shape;

import java.awt.geom.AffineTransform;

import java.awt.geom.PathIterator;

import java.awt.geom.Rectangle2D;

import java.io.Serializable;

import org.cresques.cts.ICoordTrans;

import org.gvsig.fmap.geom.handler.Handler;

import org.gvsig.fmap.geom.operation.GeometryOperationContext;

import org.gvsig.fmap.geom.operation.GeometryOperationException;

import org.gvsig.fmap.geom.operation.GeometryOperationNotSupportedException;

import org.gvsig.fmap.geom.primitive.Envelope;

import org.gvsig.fmap.geom.primitive.GeneralPathX;

import org.gvsig.fmap.geom.primitive.Point;

import org.gvsig.fmap.geom.type.GeometryType;

/**

 * <p>

 * This interface is equivalent to the GM_Object specified in <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26012"

 * >ISO 19107</a>. It is the root class of the geometric object taxonomy and

 * supports interfaces common to all geographically referenced geometric

 * objects.

 * </p>

 * <p>

 * Geometry instances are sets of direct positions in a particular coordinate

 * reference system. A Geometry can be regarded as an infinite set of points

 * that satisfies the set operation interfaces for a set of direct positions.

 * </p>

 * <p>

 * A geometric object shall be a combination of a coordinate geometry and a

 * coordinate reference system. In all of the operations, all geometric

 * calculations shall be done in the coordinate reference system of the first

 * geometric object accessed, which is normally the object whose operation is

 * being invoked. Returned objects shall be in the coordinate reference system

 * in which the calculations are done unless explicitly stated otherwise.

 * </p>

 * <p>

 * This class extends of the {@link Shape} class by historical reasons but this

 * inheritance will disappear in future versions.

 * </p>

 * @see <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26012"

 *      >ISO 19107< /a>

 */

public interface Geometry extends Shape, Serializable, Comparable {

        /**

         * Predefined geometry types in the model.

         */

        public interface TYPES {

                /**

                 * Any geometry.

                 */

                public final static int GEOMETRY = 0;

                /**

                 * A geometric element that has zero dimensions and a location

                 * determinable by an ordered set of coordinates.

                 */

                public final static int POINT = 1;

                /**

                 * A straight or curved geometric element that is generated by a moving

                 * point and that has extension only along the path of the point.

                 */

                public final static int CURVE = 2;

                /**

                 * A closed plane figure bounded by straight lines.

                 */

                public final static int SURFACE = 3;

                /**

                 * Solids in 3D.

                 */

                public final static int SOLID = 4;

              /**

                 * A set that can contain points, lines and polygons. This is usual in

                 * <i>CAD</i> layers <i>(dxf, dgn, dwg)</i>.

                 */

                public final static int AGGREGATE = 6;

                /**

                 * A set of points.

                 */

                public final static int MULTIPOINT = 7;

                /**

                 * A set of lines.

                 */

                public final static int MULTICURVE = 8;

                /**

                 * A set of polygons.

                 */

                public final static int MULTISURFACE = 9;

                /**

                 * A set of solids.

                 */

                public final static int MULTISOLID = 10;

                /**

                 * A closed plane curve every point of which is equidistant from a fixed

                 * point within the curve.

                 */

                public final static int CIRCLE = 11;

                /**

                 * A continuous portion (as of a circle or ellipse) of a curved line.

                 */

                public final static int ARC = 12;

                /**

                 * A closed plane curve generated by a point moving in such a way that

                 * the sums of its distances from two fixed points is a constant : a

                 * plane section of a right circular cone that is a closed curve.

                 */

                public final static int ELLIPSE = 13;

                public final static int SPLINE = 14;

                public final static int ELLIPTICARC = 15;

                /**

                 * NO DATA geometry.

                 */

                public final static int NULL = 16;

        }

        public interface DIMENSIONS {

                public final static int X = 0;

                public final static int Y = 1;

                public final static int Z = 2;

        }

        /**

         * The subtype of a geometry is related with the dimension of the geometry,

         * that is a combination between the spatial dimension (2D, 2ZD, 3D) and the

         * M coordinate or "measure".

         * 

         * @author <a href="mailto:jpiera@gvsig.org">Jorge Piera</a>

         */

        public interface SUBTYPES {

                /**

                 * Geometries with two dimensions.

                 */

                public final static int GEOM2D = 0;

                /**

                 * Geometries with three dimensions.

                 */

                public final static int GEOM3D = 1;

                /**

                 * Geometries with two dimensions and with the M coordinate.

                 */

                public final static int GEOM2DM = 2;

                /**

                 * Geometries with three dimensions and with the M coordinate.

                 */

                public final static int GEOM3DM = 3;

                /**

                 * The subtype us unknown.

                 */

                public final static int UNKNOWN = 4;

        }

        /**

         * Initial value for new geometry types (it must not overlap with the basic

         * ones defined in TYPES).

         */

        public static final int EXTENDED_GEOMTYPE_OFFSET = 17;

        /**

         * Initial value for new geometry subtypes (it must not overlap with the

         * basic ones defined in SUBTYPES).

         */

        public static final int EXTENDED_GEOMSUBTYPE_OFFSET = 6;

        public interface OPERATIONS {

                public final static String CONVERTTOWKT = "toWKT";

                public final static String CONVERTTOWKB = "toWKB";

                public final static String BUFFER = "buffer";

                public final static String DISTANCE = "Distance";

                public final static String CONTAINS = "Contains";

                public final static String OVERLAPS = "OVERLAPS";

                public final static String CONVEXHULL = "ConvexHull";

                public final static String COVERS = "Covers";

                public final static String CROSSES = "Crosses";

                public final static String DIFFERENCE = "Difference";

                public final static String DISJOIN = "Disjoin";

                public final static String INTERSECTION = "Intersaction";

                public final static String INTERSECTS = "Intersects";

                public final static String TOUCHES = "Touches";

                public final static String UNION = "Union";

                public final static String WITHIN = "Within";

                public final static String COVEREDBY = "CoveredBy";

        }

        public static int BEST = 0;

        /**

         * North.

         */

        public static int N = 1;

        /**

         * North - East.

         */

        public static int NE = 2;

        /**

         * East.

         */

        public static int E = 3;

        /**

         * South - East.

         */

        public static int SE = 4;

        /**

         * South.

         */

        public static int S = 5;

        /**

         * South - West.

         */

        public static int SW = 6;

        /**

         * West.

         */

        public static int W = 7;

        /**

         * North - West.

         */

        public static int NW = 8;

        public static int SELECTHANDLER = 0;

        public static int STRETCHINGHANDLER = 1;

        /**

         * If this geometry is a predefined interface then this method returns one

         * of {@link Geometry.TYPES} contants.<br>

         * If this geometry is an extended type then this method returns a runtime

         * constant that identifies its type. By convention this value is stored in

         * a constant called .CODE within the geometry class, for instance:

         * Point2D.CODE.

         * 

         * @return If this geometry is a predefined interface then one of

         *         {@link Geometry.TYPES} or a runtime constant if it is an extended

         *         type.

         */

        public int getType();

        /**

         * Creates a clone of this geometry.

         * 

         * @return A clone of this geometry.

         */

        public Geometry cloneGeometry();

        /**

         * Returns true if this geometry intersects the rectangle passed as

         * parameter.

         * 

         * @param r

         *            Rectangle.

         * 

         * @return True, if <code>this</code> intersects <code>r</code>.

         */

        public boolean intersects(Rectangle2D r);

        /**

         * Used by the drawing strategies to quickly test whether this geometry

         * intersects with the visible rectangle.

         * 

         * @param x

         *            The minimum X coordinate.

         * @param y

         *            The minimum Y coordinate.

         * @param w

         *            The width of the envelope.

         * @param h

         *            The height of the envelope.

         * @return true if <code>this</code> intersects the rectangle defined by the

         *         parameters.

         */

        public boolean fastIntersects(double x, double y, double w, double h);

        /**

         * <p>

         * Returns the minimum bounding box for this Geometry. This shall be the

         * coordinate region spanning the minimum and maximum value for each

         * ordinate taken on by DirectPositions in this Geometry. The simplest

         * representation for an envelope consists of two DirectPositions, the first

         * one containing all the minimums for each ordinate, and second one

         * containing all the maximums.

         * </p>

         * 

         * @return The minimum bounding box for this Geometry.

         */

        public Envelope getEnvelope();

        /**

         * Reprojects this geometry by the coordinate transformer passed as

         * parameter.

         * 

         * @param ct

         *            Coordinate Transformer.

         */

        public void reProject(ICoordTrans ct);

        /**

         * It applies an affine transformation to the geometry.

         * If parameter value is null, it will be considered an

         * empty transformation, therefore equivalent to the identity

         * transformation.

         * 

         * @param at

         *            The transformation to apply.

         */

        public void transform(AffineTransform at);

        /**

         * Returns the largest number n such that each direct position in a

         * geometric set can be associated with a subset that has the direct

         * position in its interior and is similar (isomorphic) to Rn, Euclidean

         * n-space.

         * 

         * @return The dimension.

         */

        public int getDimension();

        /**

         * Returns <code>true</code> if this Geometry has no interior point of

         * self-intersection or self-tangency. In mathematical formalisms, this

         * means that every point in the interior of the object must have a metric

         * neighborhood whose intersection with the object is isomorphic to an

         * n-sphere, where n is the dimension of this Geometry.

         * 

         * @return If the geometry is simple.

         */

        public boolean isSimple();

        /**

         * Invokes a geometry operation given its index and context.

         * 

         * @param index

         *            Unique index of the operation. Operation code.

         * @param ctx

         *            The context of the geometry operation.

         * @return Object returned by the operation.

         * @throws GeometryOperationNotSupportedException

         *             It is thrown when the operation has been not registered for

         *             this geometry.

         * @throws GeometryOperationException

         *             It is thrown when there is an error executing the operation.

         */

        public Object invokeOperation(int index, GeometryOperationContext ctx)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Invokes a geometry operation given its name and context.

         * 

         * @param opName

         *            Operation name.

         * @param ctx

         *            The context of the geometry operation.

         * @return Object returned by the operation.

         * @throws GeometryOperationNotSupportedException

         *             It is thrown when the operation has been not registered for

         *             this geometry.

         * @throws GeometryOperationException

         *             It is thrown when there is an error executing the operation.

         */

        public Object invokeOperation(String opName, GeometryOperationContext ctx)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Instance of the GeometryType associated to this geometry.

         * 

         * @return The geometry type.

         */

        public GeometryType getGeometryType();

        /**

         * Return a byte array with the equivalent in WKB format of the Geometry.

         * 

         * Utility method to wrap the invocation to the operation

         * {@link OPERATIONS#CONVERTTOWKB}.

         * 

         * @return the WKB version of the geometry

         */

        public byte[] convertToWKB() throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Return a string with the equivalent in WKT format of the Geometry.

         * 

         * This is a utility method to wrap the invocation to the operation

         * {@link OPERATIONS#CONVERTTOWKT}.

         * 

         * @return the WKT version of the geometry.

         * 

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public String convertToWKT() throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Computes a buffer area around this geometry having the given width

         * 

         * This is a utility method to wrap the invocation to the operation

         * {@link OPERATIONS#BUFFER}.

         * 

         * @param distance

         *            the width of the buffer

         * 

         * @return a new Geometry with the computed buffer.

         * 

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public Geometry buffer(double distance)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Tests whether this geometry contains the specified geometry.

         * 

         * This is a utility method to wrap the invocation to the operation

         * {@link OPERATIONS#CONTAINS}.

         * 

         * @param geometry

         *            the Geometry with which to compare this Geometry

         * 

         * @return if this Geometry contains the specified geometry

         * 

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public boolean contains(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Returns the minimum distance between this Geometry and the specified

         * geometry.

         * 

         * This is a utility method to wrap the invocation to the operation

         * {@link OPERATIONS#DISTANCE}.

         * 

         * @param geometry

         *            the Geometry from which to compute the distance

         * 

         * @return the distance between the geometries

         * 

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public double distance(Geometry other)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry[] closestPoints(Geometry other)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        boolean isWithinDistance(Geometry other, double distance) 

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        /**

         * Tests whether this geometry overlaps the specified geometry.

         * 

         * This is a utility method to wrap the invocation to the operation

         * {@link OPERATIONS#OVERLAPS}.

         * 

         * @param geometry

         *            the Geometry with which to compare this Geometry

         * 

         * @return true if the two geometries overlap.

         * 

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public boolean overlaps(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry convexHull() throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean coveredBy(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean crosses(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry difference(Geometry other)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean disjoint(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry intersection(Geometry other)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean intersects(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry snapTo(Geometry other, double snapTolerance)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean touches(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Geometry union(Geometry other)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public boolean within(Geometry geometry)

                        throws GeometryOperationNotSupportedException,

                        GeometryOperationException;

        public Point centroid() throws GeometryOperationNotSupportedException, GeometryOperationException;

        /**

         * This method returns a point which is inside the geometry.

         * This is useful for mathematical purposes but it is very unlikely

         * to be a suitable place for a label, for example.

         * 

         * 

         * @return an interior point

         * @throws GeometryOperationNotSupportedException

         * @throws GeometryOperationException

         */

        public Point getInteriorPoint() throws GeometryOperationNotSupportedException, GeometryOperationException;

        public double area() throws GeometryOperationNotSupportedException, GeometryOperationException;

        public double perimeter() throws GeometryOperationNotSupportedException, GeometryOperationException;

        /**

         * Rotates the geometry by radAngle radians using the given

         * coordinates as center of rotation. Rotating with a positive

         * angle rotates points on the positive x axis toward the

         * positive y axis. In most cases, we assume x increases

         * rightwards and y increases upwards, so in most cases,

         * a positive angle will mean counter-clockwise rotation.

         * 

         * @param radAngle the amount of rotation, in radians

         * @param basex x coordinate of center of rotation

         * @param basey y coordinate of center of rotation

         */

        public void rotate(double radAngle, double basex, double basey);

        /**

         * Shifts geometry by given amount in x and y axes

         * 

         * @param dx 

         * @param dy

         */

        public void move(double dx, double dy);

        /**

         * Scales geometry in x and y axes by given scale factors

         * using the given point as center of projection.

         *  

         * @param basePoint

         * @param sx scale factor in x axis

         * @param sy scale factor in y axis

         */

        public void scale(Point basePoint, double sx, double sy);

        //

        // ===============================================

        //

        /**

     * @return  the awt shape used to display the geometry. It 

     * applies a tranformation before to return the coordinates

     * of the shape

     * @deprecated this class inherits of {@link Shape} by historical

     * reasons. This method has been added just to control the usage of

     * the {@link Shape} class but it will removed in a future.

     */

        public Shape getShape(AffineTransform affineTransform);

        /**

     * @return  the awt shape used to display the geometry. 

     * @deprecated this class inherits of {@link Shape} by historical

     * reasons. This method has been added just to control the usage of

     * the {@link Shape} class but it will removed in a future.

     */

        public Shape getShape();

        /**

         * Returns this geometry's boundary rectangle.

         * 

         * @deprecated use getEnvelope.

         * @return Boundary rectangle.

         */

        public Rectangle2D getBounds2D();

        /**

         * If applies an affine transformation and returns the GeneralPathXIterator

         * with this geometry's information.

         * 

         * @param at

         *            The transformation to apply.

         * @return The GeneralPathXIterator with this geometry's information.

         * @deprecated don't use PathIterator over geometries, use instead specific API for each operation. If not has API for that operation let the project team.

         * 

         */

        public PathIterator getPathIterator(AffineTransform at);

        /**

         * It returns the handlers of the geometry, these they can be of two types

         * is straightening and of selection.

         * 

         * @param type

         *            Type of handlers.

         * 

         * @deprecated don't use Handlers over geometries, use instead specific API for each operation. If not has API for that operation let the project team.

         * @return The handlers.

         */

        public Handler[] getHandlers(int type);

        /**

         * If applies an affine transformation and returns the GeneralPathXIterator

         * with this geometry's information.

         * 

         * @param at

         *            The affine transformation.

         * @param flatness

         * 

         * @return The GeneralPathXIterator with this geometry's information.

         * @deprecated don't use PathIterator over geometries, use instead specific API for each operation. If not has API for that operation let the project team.

         */

        PathIterator getPathIterator(AffineTransform at, double flatness);

        /**

         * Useful to have the real shape behind the scenes. May be uses to edit it

         * knowing it it is a Circle, Ellipse, etc.

         * 

         * @return The awt shape

         * @deprecated

         */

        public Shape getInternalShape();

        /**

         * Get GeneralPathIterator, to do registered operations to it.

         * 

         * @return The GeneralPathX.

         * @deprecated don't use GeneralPathX over geometries, use instead specific API for each operation. If not has API for that operation let the project team.

         */

        public GeneralPathX getGeneralPath();

}