| gvSIG desktop 1

/* 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.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> 

 * @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 {

                /**

                 * NO DATA geometry.

                 */

                public final static int NULL = -1;

                /**

                 * 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 = 4;

                /**

                 * Solids in 3D.

                 */

                public final static int SOLID = 8;

                /**

                 * Words, symbols and form of a written or printed work.

                 */

                public final static int TEXT = 16;

                /**

                 * 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 = 32;

                /**

                 * A set of points.

                 */

                public final static int MULTIPOINT = 64;

                /**

                 * A set of lines.

                 */

                public final static int MULTICURVE = 128;

                /**

                 * A set of polygons.

                 */

                public final static int MULTISURFACE = 256;

                /**

                 * A set of solids.

                 */

                public final static int MULTISOLID = 512;

                /**

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

                 */

                public final static int CIRCLE = 1024;

                /**

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

                 */

                public final static int ARC = 2048;

                /**

                 *  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=4096;

                public final static int SPLINE = 8192;

                public final static int ELLIPTICARC = 16384;

        }

        /**

         * 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{

                /**

                 * The subtype us unknown.

                 */

                public final static int UNKNOWN = 0;

                /**

                 * Geometries with two dimensions.

                 */

                public final static int GEOM2D = 1;

                /**

                 * Geometries with two dimensions and with a value

                 * for the elevation.

                 */

                public final static int GEOM2DZ = 2;

                /**

                 * Geometries with three dimensions.

                 */

                public final static int GEOM3D = 3;

                /**

                 * Geometries with two dimensions and with the 

                 * M coordinate.

                 */

                public final static int GEOM2DM = 4;

                /**

                 * Geometries with three dimensions and with the

                 * M coordinate.

                 */

                public final static int GEOM3DM = 5;

        }

        /** Initial value for new geometry types (it must not overlap with the basic ones defined in TYPES). */

        public static final int EXTENDED_GEOMTYPE_OFFSET = 65536; //2^16;

        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);

        /**

         * Returns this geometry's boundary rectangle.

         * @deprecated use getEnvelope.

         * @return Boundary rectangle.

         */

        public Rectangle2D getBounds2D();

        /**

         * <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);

        /**

         * 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.

         */

        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.

         *

         * @return 

         * The handlers.

         */

        public Handler[] getHandlers(int type);

        /**

         * It applies an affine transformation to the geometry.

         * 

         * @param at

         * The transformation to apply.

         */

        public void transform(AffineTransform at);

        /**

         * 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.

         */

        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

         */

        public Shape getInternalShape();

        /**

         * 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();

        /**

         * Get GeneralPathIterator, to do registered operations to it.

         * @return 

         * The GeneralPathX.

         */

        public GeneralPathX getGeneralPath();

}