## org.opengis.geometry
Interface Geometry

All Superinterfaces:
  TransfiniteSet

All Known Subinterfaces:
  Aggregate, Boundary, Complex, ComplexBoundary, Composite, CompositeCurve, CompositePoint, CompositeSolid, CompositeSurface, Curve, CurveBoundary, MultiCurve, MultiPoint, MultiPrimitive, MultiSurface, OrientableCurve, OrientablePrimitive, OrientableSurface, Point, PolyhedralSurface, Primitive, PrimitiveBoundary, Ring, Shell, Solid, SolidBoundary, Surface, SurfaceBoundary, Tin, TriangulatedSurface

    @UML(identifier="GM_Object",
         specification=ISO_19107)
    public interface Geometry

extends TransfiniteSet

Root class of the geometric object taxonomy. `Geometry` supports interfaces common to all geographically referenced geometric objects. `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, `TransfiniteSet<DirectPosition>`.

Since:
  GeoAPI 1.0
Version:
  ISO 19107

Method Summary
`Object` `clone()` Returns a clone of this geometry with deep copy semantic.
`double` `distance(Geometry geometry)` Returns the distance between this `Geometry` and another `Geometry`.
`Boundary` `getBoundary()` Returns a finite set of `Geometry`s containing all of the direct positions on the boundary of this `Geometry`.
`Geometry` `getBuffer(double distance)` Returns a `Geometry` containing all points whose distance from this `Geometry` is less than or equal to the distance passed as a parameter.
`DirectPosition` `getCentroid()` Returns the mathematical centroid for this `Geometry`.
`Complex` `getClosure()` Returns a finite set of `Geometry`s containing all of the points on the boundary of this `Geometry` and this object (the union of the object and its boundary).
`Geometry` `getConvexHull()` Returns a `Geometry` that represents the convex hull of this `Geometry`.
`int` `getCoordinateDimension()` Returns the dimension of the coordinates that define this `Geometry`, which must be the same as the coordinate dimension of the coordinate reference system for this `Geometry`.
`CoordinateReferenceSystem` `getCoordinateReferenceSystem()` Returns the coordinate reference system used in direct position coordinates.
`int` `getDimension(DirectPosition point)` Returns the inherent dimension of this `Geometry`, which shall be less than or equal to the coordinate dimension.
`double` `getDistance(Geometry geometry)` Deprecated. use `distance(org.opengis.geometry.Geometry)`.
`Envelope` `getEnvelope()` Returns the minimum bounding box for this `Geometry`.
`Set` `getMaximalComplex()` Returns the set of maximal complexes within which this `Geometry` is contained.
`Geometry` `getMbRegion()` Returns a region in the coordinate reference system that contains this `Geometry`.
`Precision` `getPrecision()` Returns the precision model used to guide the accuracy of topology operations.
`DirectPosition` `getRepresentativePoint()` Returns a point value that is guaranteed to be on this `Geometry`.
`boolean` `isCycle()` Returns `true` if this `Geometry` has an empty boundary after topological simplification (removal of overlaps between components in non-structured aggregates, such as subclasses of `Aggregate`).
`boolean` `isMutable()` Returns `false` if this geometry is immutable.
`boolean` `isSimple()` Returns `true` if this `Geometry` has no interior point of self-intersection or selftangency.
`Geometry` `toImmutable()` Returns an immutable copy of this geometry.
`Geometry` `transform(CoordinateReferenceSystem newCRS)` Returns a new `Geometry` that is the coordinate transformation of this `Geometry` into the passed coordinate reference system within the accuracy of the transformation.
`Geometry` `transform(CoordinateReferenceSystem newCRS, MathTransform transform)` Returns a new `Geometry` that is the coordinate transformation of this `Geometry` into the passed coordinate reference system, using the specified transform.

Methods inherited from interface TransfiniteSet
`contains, contains, difference, equals, intersection, intersects, symmetricDifference, union`

Method Detail

### getCoordinateReferenceSystem

    @UML(identifier="CRS",
         obligation=MANDATORY,
         specification=ISO_19107)
    CoordinateReferenceSystem getCoordinateReferenceSystem()

  Returns the coordinate reference system used in direct position coordinates. If `null`, then this `Geometry` uses the coordinate reference system from another `Geometry` in which it is contained. The most common example where the coordinate reference system is `null` is the elements and subcomplexes of a maximal complex. The complex can carry the coordinate reference system for all primitive elements and for all `Complex` subcomplexes.

  This association is only navigable from `Geometry` to coordinate reference system. This means that the coordinate reference system objects in a data set do not keep a list of `Geometry`s that use them.

  Returns:
    The coordinate reference system used in direct position coordinates.
  See Also:
    `getCoordinateDimension()`

### getPrecision

    Precision getPrecision()

  Returns the precision model used to guide the accuracy of topology operations.

  Returns:
    the precision model used for topological operations.

### getMbRegion

    @UML(identifier="mbRegion",
         obligation=MANDATORY,
         specification=ISO_19107)
    Geometry getMbRegion()

  Returns a region in the coordinate reference system that contains this `Geometry`. The default shall be to return an instance of an appropriate `Geometry` subclass that represents the same spatial set returned from `getEnvelope()`. The most common use of `mbRegion` will be to support indexing methods that use extents other than minimum bounding rectangles (MBR or envelopes). This does not restrict the returned `Geometry` from being a non-vector geometric representation, although those types are not defined within this specification.

  Returns:
    The minimum bounding region.
  See Also:
    `getEnvelope()`, `getBoundary()`

### getRepresentativePoint

    @UML(identifier="representativePoint",
         obligation=MANDATORY,
         specification=ISO_19107)
    DirectPosition getRepresentativePoint()

  Returns a point value that is guaranteed to be on this `Geometry`. The default logic may be to use the direct position of the point returned by `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.

  Returns:
    The representative point.
  See Also:
    `getCentroid()`

### getBoundary

    @UML(identifier="boundary",
         obligation=MANDATORY,
         specification=ISO_19107)
    Boundary getBoundary()

  Returns a finite set of `Geometry`s containing all of the direct positions on the boundary of this `Geometry`. These object collections shall have further internal structure where appropriate. The finite set of `Geometry`s returned shall be in the same coordinate reference system as this `Geometry`. If the `Geometry` is in a complex, then the boundary `Geometry`s returned shall be in the same complex. If the `Geometry` is not in any complex, then the boundary `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.

  Returns:
    The sets of positions on the boundary.
  See Also:
    `getMbRegion()`, `getClosure()`, `getBuffer(double)`, `getDistance(org.opengis.geometry.Geometry)`

### getClosure

    @UML(identifier="closure",
         obligation=MANDATORY,
         specification=ISO_19107)
    Complex getClosure()

  Returns a finite set of `Geometry`s containing all of the points on the boundary of this `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 `Geometry`s returned shall be in the same coordinate reference system as this `Geometry`. If the `Geometry` is in a complex, then the boundary `Geometry`s returned shall be in the same complex. If the `Geometry` is not in any complex, then the boundary `Geometry`s returned may have been constructed in response to the operation.

  Returns:
    The sets of points on the union of this object and its boundary.
  See Also:
    `getBoundary()`

### isSimple

    @UML(identifier="isSimple",
         obligation=MANDATORY,
         specification=ISO_19107)
    boolean isSimple()

  Returns `true` if this `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 `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 `isCycle()` returns `true`).

  Returns:
    `true` if this object has no interior point of self-intersection or selftangency.
  See Also:
    `isCycle()`

### isCycle

    @UML(identifier="isCycle",
         obligation=MANDATORY,
         specification=ISO_19107)
    boolean isCycle()

  Returns `true` if this `Geometry` has an empty boundary after topological simplification (removal of overlaps between components in non-structured aggregates, such as subclasses of `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.

  Returns:
    `true` if this `Geometry` has an empty boundary after topological simplification.
  See Also:
    `isSimple()`

### distance

    @UML(identifier="distance",
         obligation=MANDATORY,
         specification=ISO_19107)
    double distance(Geometry geometry)

  Returns the distance between this `Geometry` and another `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 `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.

  - Map distance is the distance between the points as defined by their positions in a coordinate projection (such as on a map when scale is taken into account). Map distance is usually accurate for small areas where scale functions have well-behaved derivatives.
  - Geodesic distance is the length of the shortest curve between those two points along the surface of the earth model being used by the coordinate reference system. Geodesic distance behaves well for wide areas of coverage, and takes the earth's curvature into account. It is especially handy for air and sea navigation, although care should be taken to distinguish between rhumb line (curves of constant bearing) and geodesic curve distance.
  - Terrain distance takes into account the local vertical displacements (hypsography). Terrain distance can be based either on a geodesic distance or a map distance.

  Parameters:
    `geometry` - The other object.
  Returns:
    The distance between the two objects.
  Since:
    GeoAPI 2.1
  See Also:
    `getBoundary()`, `getBuffer(double)`, `CoordinateSystem.getAxis(int)`
  Unit:
    Distance

### getDistance

    double getDistance(Geometry geometry)

  Deprecated. use `distance(org.opengis.geometry.Geometry)`.

  Returns the distance between this `Geometry` and another `Geometry`.

  Parameters:
    `geometry` - The other object.
  Returns:
    The distance between the two objects.

### getDimension

    @UML(identifier="dimension",
         obligation=MANDATORY,
         specification=ISO_19107)
    int getDimension(DirectPosition point)

  Returns the inherent dimension of this `Geometry`, which shall be less than or equal to the 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 direct positions interior to this `Geometry`. If the passed direct position is `null`, then the operation shall return the largest possible dimension for any direct position in this `Geometry`.

  Parameters:
    `point` - The point where to evaluate the dimension, or `null`.
  Returns:
    The inherent dimension.
  See Also:
    `getCoordinateDimension()`

### getCoordinateDimension

    @UML(identifier="coordinateDimension",
         obligation=MANDATORY,
         specification=ISO_19107)
    int getCoordinateDimension()

  Returns the dimension of the coordinates that define this `Geometry`, which must be the same as the coordinate dimension of the coordinate reference system for this `Geometry`.

  Returns:
    The coordinate dimension.
  See Also:
    `getDimension(org.opengis.geometry.DirectPosition)`, `getCoordinateReferenceSystem()`

### getMaximalComplex

    @UML(identifier="maximalComplex",
         obligation=MANDATORY,
         specification=ISO_19107)
    Set getMaximalComplex()

  Returns the set of maximal complexes within which this `Geometry` is contained. As a set of primitives, a complex may be contained as a set in another larger complex, referred to as a "super complex" of the original. A complex is maximal if there is no such larger super complex.

  Returns:
    The set of maximal complexes within which this `Geometry` is contained.

### transform

    @UML(identifier="transform",
         obligation=MANDATORY,
         specification=ISO_19107)
    Geometry transform(CoordinateReferenceSystem newCRS)
                       throws TransformException

  Returns a new `Geometry` that is the coordinate transformation of this `Geometry` into the passed coordinate reference system within the accuracy of the transformation.

  Parameters:
    `newCRS` - The new coordinate reference system.
  Returns:
    The transformed `Geometry`.
  Throws:
    `TransformException` - if the transformation failed.

### transform

    @Extension
    Geometry transform(CoordinateReferenceSystem newCRS,
                                 MathTransform transform)
                       throws TransformException

  Returns a new `Geometry` that is the coordinate transformation of this `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.

  Parameters:
    `newCRS` - The new coordinate reference system.
    `transform` - The transform from the existing coordinate reference system to the new coordinate reference system.
  Returns:
    The transformed `Geometry`.
  Throws:
    `TransformException` - if the transformation failed.

### getEnvelope

    @UML(identifier="envelope",
         obligation=MANDATORY,
         specification=ISO_19107)
    Envelope getEnvelope()

  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 direct positions in this `Geometry`. The simplest representation for an envelope consists of two 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.

  Returns:
    The envelope.
  See Also:
    `getMbRegion()`

### getCentroid

    @UML(identifier="centroid",
         obligation=MANDATORY,
         specification=ISO_19107)
    DirectPosition getCentroid()

  Returns the mathematical centroid for this `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.

  Returns:
    The centroid.
  See Also:
    `getRepresentativePoint()`

### getConvexHull

    @UML(identifier="convexHull",
         obligation=MANDATORY,
         specification=ISO_19107)
    Geometry getConvexHull()

  Returns a `Geometry` that represents the convex hull of this `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.

  Returns:
    The convex hull.

### getBuffer

    @UML(identifier="buffer",
         obligation=MANDATORY,
         specification=ISO_19107)
    Geometry getBuffer(double distance)

  Returns a `Geometry` containing all points whose distance from this `Geometry` is less than or equal to the distance passed as a parameter. The `Geometry` returned is in the same reference system as this original `Geometry`. The dimension of the returned `Geometry` is normally the same as the coordinate dimension - a collection of surfaces in 2D space and a collection of solids in 3D space, but this may be application defined.

  Parameters:
    `distance` - The distance.
  Returns:
    A geometry containing all points whose distance from this `Geometry` is less than or equal to the specified distance.
  See Also:
    `getBoundary()`, `getDistance(org.opengis.geometry.Geometry)`, `CoordinateSystem.getAxis(int)`
  Unit:
    Distance (for the argument)

### isMutable

    @Extension
    boolean isMutable()

  Returns `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 cloning them. More specifically:

  - If `false`, then this geometry is immutable. It is guarantee that a call to any `setFoo(...)` method will throws an `UnmodifiableGeometryException` (that said, immutable geometries are necessarily unmodifiable. The converse is not true, see next point below). This geometry will never change its state, and there is no need for cloning it.

  - If `true`, then this geometry is mutable. Note that mutable geometry is not synonymous of modifiable geometry. The nuance lays in whatever the geometry may changes its state directly (as of user request) or indirectly:

  - This geometry may be modifiable, in which case invoking `setFoo(...)` methods is legal and will not throws exception.

  - This geometry may still unmodifiable. User is not allowed to modify it himself and invoking any `setFoo(...)` method will throws an `UnmodifiableGeometryException`. However, the implementation may change the geometry itself (for example a time-varying geometry).

### toImmutable

    @Extension
    Geometry toImmutable()

  Returns an immutable copy of this geometry. The returned Geometry is guaranteed to have an `isMutable()` value of false. Moreover, as per the contract of `isMutable()`, its values will never change. Any attempts to change the values of the returned object will result in a `UnmodifiableGeometryException`.

  Implementors are free to return `this` if this object is already immutable.

### clone

    Object clone()
                 throws CloneNotSupportedException

  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:

  - If this geometry is immutable (`isMutable() == false`), then there is no need for cloning this object. This method may return `this` or returns a modifiable copy of this object, at implementation choice.

  - If a deep copy semantic is not possible at a reasonable cost (for example for some database backend), then this method throws a `CloneNotSupportedException`.

  - If a deep cloning is possible for all case (i.e. if this method never throws `CloneNotSupportedException`), then the implementation should implements the `Cloneable` interface.

  Throws:
    `CloneNotSupportedException` - if this object do not support clone. This exception is never throws if this object implements `Cloneable`.
  See Also:
    `Cloneable`, `isMutable()`

Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.