/*$************************************************************************************************
 **
 ** $Id: Geometry.java 831 2006-05-01 00:27:23Z Desruisseaux $
 **
 ** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/spatialschema/geometry/Geometry.java $
 **
 ** Copyright (C) 2003-2005 Open GIS Consortium, Inc.
 ** All Rights Reserved. http://www.opengis.org/legal/
 **
 *************************************************************************************************/
package org.opengis.spatialschema.geometry;

// J2SE direct dependencies
import java.util.Set;

// OpenGIS direct dependencies
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.referencing.operation.MathTransform;
import org.opengis.referencing.operation.TransformException;
import org.opengis.spatialschema.geometry.complex.Complex;
import org.opengis.util.Cloneable; // For javadoc

// Annotations
import org.opengis.annotation.UML;
import org.opengis.annotation.Extension;
import static org.opengis.annotation.Obligation.*;
import static org.opengis.annotation.Specification.*;


/**
 * Root class of the geometric object taxonomy. {@code Geometry} supports interfaces common
 * to all geographically referenced geometric objects. {@code Geometry} instances are sets
 * of direct positions in a particular coordinate reference system. A {@code Geometry} can
 * be regarded as an infinite set of points that satisfies the set operation interfaces for a set
 * of direct positions, {@link TransfiniteSet TransfiniteSet<DirectPosition>}.
 *
 * @version Abstract specification 5
 * @author Martin Desruisseaux (IRD)
 * @since GeoAPI 1.0
 */
@UML(identifier="GM_Object", specification=ISO_19107)
public interface Geometry extends TransfiniteSet {
    /**
     * Returns the coordinate reference system used in {@linkplain DirectPosition direct position}
     * coordinates. If {@code null}, then this {@code Geometry} uses the coordinate reference
     * system from another {@code Geometry} in which it is contained.
     *
     * The most common example where the coordinate reference system is {@code null} is the elements
     * and subcomplexes of a maximal {@linkplain Complex complex}. The {@linkplain Complex complex} can
     * carry the {@linkplain CoordinateReferenceSystem coordinate reference system} for all
     * {@linkplain org.opengis.spatialschema.geometry.primitive.Primitive primitive} elements
     * and for all {@link Complex} subcomplexes.
     * 

* This association is only navigable from {@code Geometry} to {@linkplain CoordinateReferenceSystem * coordinate reference system}. This means that the coordinate reference system objects in a data set do * not keep a list of {@code Geometry}s that use them. * * @return The coordinate reference system used in {@linkplain DirectPosition direct position} * coordinates. * * @see #getCoordinateDimension */ @UML(identifier="CRS", obligation=MANDATORY, specification=ISO_19107) CoordinateReferenceSystem getCoordinateReferenceSystem(); /** * Returns a region in the coordinate reference system that contains this {@code Geometry}. * The default shall be to return an instance of an appropriate {@code Geometry} subclass * that represents the same spatial set returned from {@link #getEnvelope}. The most common * use of {@code mbRegion} will be to support indexing methods that use extents other * than minimum bounding rectangles (MBR or envelopes). This does not restrict the returned * {@code Geometry} from being a non-vector geometric representation, although those * types are not defined within this specification. * * @return The minimum bounding region. * * @see #getEnvelope * @see #getBoundary */ @UML(identifier="mbRegion", obligation=MANDATORY, specification=ISO_19107) Geometry getMbRegion(); /** * Returns a point value that is guaranteed to be on this {@code Geometry}. The default * logic may be to use the {@linkplain DirectPosition direct position} of the point returned by * {@link #getCentroid} if that point is on the object. Another use of representative point may * be for the placement of labels in systems based on graphic presentation. * * @return The representative point. * * @see #getCentroid */ @UML(identifier="representativePoint", obligation=MANDATORY, specification=ISO_19107) DirectPosition getRepresentativePoint(); /** * Returns a finite set of {@code Geometry}s containing all of the direct positions on the * boundary of this {@code Geometry}. These object collections shall have further internal * structure where appropriate. The finite set of {@code Geometry}s returned shall be in * the same coordinate reference system as this {@code Geometry}. If the {@code Geometry} * is in a {@linkplain Complex complex}, then the boundary {@code Geometry}s returned shall be * in the same {@linkplain Complex complex}. If the {@code Geometry} is not in any * {@linkplain Complex complex}, then the boundary {@code Geometry}s returned may have been * constructed in response to the operation. The elements of a boundary shall be smaller in * dimension than the original element. * * @return The sets of positions on the boundary. * * @see #getMbRegion * @see #getClosure * @see #getBuffer * @see #getDistance */ @UML(identifier="boundary", obligation=MANDATORY, specification=ISO_19107) Boundary getBoundary(); /** * Returns a finite set of {@code Geometry}s containing all of the points on the boundary of * this {@code Geometry} and this object (the union of the object and its boundary). These * object collections shall have further internal structure where appropriate. The finite set * of {@code Geometry}s returned shall be in the same coordinate reference system as this * {@code Geometry}. If the {@code Geometry} is in a {@linkplain Complex complex}, then the boundary * {@code Geometry}s returned shall be in the same {@linkplain Complex complex}. If the * {@code Geometry} is not in any {@linkplain Complex complex}, then the boundary * {@code Geometry}s returned may have been constructed in response to the operation. * * @return The sets of points on the union of this object and its boundary. * * @see #getBoundary */ @UML(identifier="closure", obligation=MANDATORY, specification=ISO_19107) Complex getClosure(); /** * Returns {@code true} if this {@code Geometry} has no interior point of * self-intersection or selftangency. 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 {@code Geometry}. *

* Since most coordinate geometries are represented, either directly or indirectly by functions * from regions in Euclidean space of their topological dimension, the easiest test for * simplicity to require that a function exist that is one-to-one and bicontinuous * (continuous in both directions). Such a function is a topological isomorphism. This test * does not work for "closed" objects (that is, objects for which {@link #isCycle} returns * {@code true}). * * @return {@code true} if this object has no interior point of self-intersection or * selftangency. * * @see #isCycle */ @UML(identifier="isSimple", obligation=MANDATORY, specification=ISO_19107) boolean isSimple(); /** * Returns {@code true} if this {@code Geometry} has an empty boundary after topological * simplification (removal of overlaps between components in non-structured aggregates, such as * subclasses of {@link org.opengis.spatialschema.geometry.aggregate.Aggregate}). This condition is alternatively * referred to as being "closed" as in a "closed curve." This creates some confusion since there * are two distinct and incompatible definitions for the word "closed". The use of the word cycle * is rarer (generally restricted to the field of algebraic topology), but leads to less confusion. * Essentially, an object is a cycle if it is isomorphic to a geometric object that is the * boundary of a region in some Euclidean space. Thus a curve is a cycle if it is isomorphic * to a circle (has the same start and end point). A surface is a cycle if it isomorphic to the * surface of a sphere, or some torus. A solid, with finite size, in a space of dimension 3 is * never a cycle. * * @return {@code true} if this {@code Geometry} has an empty boundary after * topological simplification. * * @see #isSimple */ @UML(identifier="isCycle", obligation=MANDATORY, specification=ISO_19107) boolean isCycle(); /** * Returns the distance between this {@code Geometry} and another {@code Geometry}. * This distance is defined to be the greatest lower bound of the set of distances between * all pairs of points that include one each from each of the two {@code Geometry}s. A * "distance" value shall be a positive number associated to a distance unit such as meter * or standard foot. If necessary, the second geometric object shall be transformed into * the same coordinate reference system as the first before the distance is calculated. *

* If the geometric objects overlap, or touch, then their distance apart shall be zero. * Some current implementations use a "negative" distance for such cases, but the approach * is neither consistent between implementations, nor theoretically viable. *

* NOTE: The role of the reference system in distance calculations is * important. Generally, there are at least three types of distances that may be defined * between points (and therefore between geometric objects): map distance, geodesic distance, * and terrain distance. *

* * @param geometry The other object. * @return The distance between the two objects. * @unitof Distance * * @see #getBoundary * @see #getBuffer * @see org.opengis.referencing.cs.CoordinateSystem#getAxis */ @UML(identifier="distance", obligation=MANDATORY, specification=ISO_19107) double getDistance(Geometry geometry); /** * Returns the inherent dimension of this {@code Geometry}, which shall be less than or * equal to the {@linkplain #getCoordinateDimension coordinate dimension}. The dimension of * a collection of geometric objects shall be the largest dimension of any of its pieces. * Points are 0-dimensional, curves are 1-dimensional, surfaces are 2-dimensional, and solids * are 3-dimensional. Locally, the dimension of a geometric object at a point is the dimension * of a local neighborhood of the point - that is the dimension of any coordinate neighborhood * of the point. Dimension is unambiguously defined only for {@linkplain DirectPosition direct * positions} interior to this {@code Geometry}. If the passed {@linkplain DirectPosition * direct position} is {@code null}, then the operation shall return the largest possible * dimension for any {@linkplain DirectPosition direct position} in this {@code Geometry}. * * @param point The point where to evaluate the dimension, or {@code null}. * @return The inherent dimension. * * @see #getCoordinateDimension */ @UML(identifier="dimension", obligation=MANDATORY, specification=ISO_19107) int getDimension(DirectPosition point); /** * Returns the dimension of the coordinates that define this {@code Geometry}, which must * be the same as the coordinate dimension of the coordinate reference system for this * {@code Geometry}. * * @return The coordinate dimension. * * @see #getDimension * @see #getCoordinateReferenceSystem */ @UML(identifier="coordinateDimension", obligation=MANDATORY, specification=ISO_19107) int getCoordinateDimension(); /** * Returns the set of maximal complexes within which this {@code Geometry} is contained. * As a set of primitives, a {@linkplain Complex complex} may be contained as a set in another * larger {@linkplain Complex complex}, referred to as a "super complex" of the original. * A {@linkplain Complex complex} is maximal if there is no such larger super complex. * * @return The set of maximal complexes within which this {@code Geometry} is contained. */ @UML(identifier="maximalComplex", obligation=MANDATORY, specification=ISO_19107) Set getMaximalComplex(); /** * Returns a new {@code Geometry} that is the coordinate transformation of this * {@code Geometry} into the passed coordinate reference system within the accuracy * of the transformation. * * @param newCRS The new coordinate reference system. * @return The transformed {@code Geometry}. * @throws TransformException if the transformation failed. */ @UML(identifier="transform", obligation=MANDATORY, specification=ISO_19107) Geometry transform(CoordinateReferenceSystem newCRS) throws TransformException; /** * Returns a new {@code Geometry} that is the coordinate transformation of this * {@code Geometry} into the passed coordinate reference system, using the * specified transform. It is the user responsability to ensure that the supplied * transform is appropriate for this geometry. * * @param newCRS The new coordinate reference system. * @param transform The transform from the existing coordinate reference system * to the new coordinate reference system. * @throws TransformException if the transformation failed. * @return The transformed {@code Geometry}. */ @Extension Geometry transform(CoordinateReferenceSystem newCRS, MathTransform transform) throws TransformException; /** * Returns the minimum bounding box for this {@code Geometry}. This shall be the * coordinate region spanning the minimum and maximum value for each ordinate taken on by * {@linkplain DirectPosition direct positions} in this {@code Geometry}. The simplest * representation for an envelope consists of two {@linkplain DirectPosition direct positions}, * the first one containing all the minimums for each ordinate, and second one containing all * the maximums. However, there are cases for which these two positions would be outside the * domain of validity of the object's coordinate reference system. * * @return The envelope. * * @see #getMbRegion */ @UML(identifier="envelope", obligation=MANDATORY, specification=ISO_19107) Envelope getEnvelope(); /** * Returns the mathematical centroid for this {@code Geometry}. The result is not guaranteed * to be on the object. For heterogeneous collections of primitives, the centroid only takes * into account those of the largest dimension. For example, when calculating the centroid of * surfaces, an average is taken weighted by area. Since curves have no area they do not * contribute to the average. * * @return The centroid. * * @see #getRepresentativePoint */ @UML(identifier="centroid", obligation=MANDATORY, specification=ISO_19107) DirectPosition getCentroid(); /** * Returns a {@code Geometry} that represents the convex hull of this {@code Geometry}. * Convexity requires the use of "lines" or "curves of shortest length" and the use of different * coordinate systems may result in different versions of the convex hull of an object. Each * implementation shall decide on an appropriate solution to this ambiguity. For two reasonable * coordinate systems, a convex hull of an object in one will be very closely approximated by * the transformed image of the convex hull of the same object in the other. * * @return The convex hull. */ @UML(identifier="convexHull", obligation=MANDATORY, specification=ISO_19107) Geometry getConvexHull(); /** * Returns a {@code Geometry} containing all points whose distance from this * {@code Geometry} is less than or equal to the distance passed as a parameter. * The {@code Geometry} returned is in the same reference system as this original * {@code Geometry}. The dimension of the returned {@code Geometry} is normally * the same as the coordinate dimension - a collection of * {@linkplain org.opengis.spatialschema.geometry.primitive.Surface surfaces} in 2D space and a collection of * {@linkplain org.opengis.spatialschema.geometry.primitive.Solid solids} in 3D space, but this may be application * defined. * * @param distance The distance. * @return A geometry containing all points whose distance from this {@code Geometry} * is less than or equal to the specified distance. * @unitof Distance (for the argument) * * @see #getBoundary * @see #getDistance * @see org.opengis.referencing.cs.CoordinateSystem#getAxis */ @UML(identifier="buffer", obligation=MANDATORY, specification=ISO_19107) Geometry getBuffer(double distance); /** * Returns {@code false} if this geometry is immutable. Immutable geometries are * guarantee to never change their state, neither directly (through a change in this object) * or indirectly (through a change in an other object this geometry depends upon). Immutable * geometries avoid the need for {@linkplain #clone cloning them}. More specifically: * * */ @Extension boolean isMutable(); /** * Returns an immutable copy of this geometry. The returned Geometry is * guaranteed to have an {@code isMutable()} value of false. Moreover, * as per the contract of {@code isMutable()}, its values will never * change. Any attempts to change the values of the returned object will * result in a {@code UnmodifiableGeometryException}. *

* Implementors are free to return {@code this} if this object is * already immutable. */ @Extension Geometry toImmutable(); /** * Returns a clone of this geometry with deep copy semantic. Any change on this object * will have no impact on the returned clone, and conversely. For big geometries, implementations * are encouraged to share as much internal data as possible (as opposed to performing a real * copy of the data), while preserving the deep copy semantic. * *

Special cases:

* * * * @throws CloneNotSupportedException if this object do not support clone. This exception is * never throws if this object implements {@link Cloneable}. * * @see Cloneable * @see #isMutable */ /*{Geometry}*/ Object clone() throws CloneNotSupportedException; }

Ads help maintain this website.