Geometry class Null safety

A representation of a planar, linear vector geometry.

Binary Predicates

Because it is not clear at this time what semantics for spatial analysis methods involving GeometryCollections would be useful, GeometryCollections are not supported as arguments to binary predicates or the relate method.

Overlay Methods

The overlay methods return the most specific class possible to represent the result. If the result is homogeneous, a Point, LineString, or Polygon will be returned if the result contains a single element; otherwise, a MultiPoint, MultiLineString, or MultiPolygon will be returned. If the result is heterogeneous a GeometryCollection will be returned.

Because it is not clear at this time what semantics for set-theoretic methods involving GeometryCollections would be useful, GeometryCollections are not supported as arguments to the set-theoretic methods.

Representation of Computed Geometries

The SFS states that the result of a set-theoretic method is the "point-set" result of the usual set-theoretic definition of the operation (SFS 3.2.21.1). However, there are sometimes many ways of representing a point set as a Geometry.

The SFS does not specify an unambiguous representation of a given point set returned from a spatial analysis method. One goal of JTS is to make this specification precise and unambiguous. JTS uses a canonical form for Geometrys returned from overlay methods. The canonical form is a Geometry which is simple and noded:

Simple means that the Geometry returned will be simple according to the JTS definition of isSimple.
Noded applies only to overlays involving LineStrings. It means that all intersection points on LineStrings will be present as endpoints of LineStrings in the result.

This definition implies that non-simple geometries which are arguments to spatial analysis methods must be subjected to a line-dissolve process to ensure that the results are simple.

Constructed Points And The Precision Model

The results computed by the set-theoretic methods may contain constructed points which are not present in the input Geometry s. These new points arise from intersections between line segments in the edges of the input Geometrys. In the general case it is not possible to represent constructed points exactly. This is due to the fact that the coordinates of an intersection point may contain twice as many bits of precision as the coordinates of the input line segments. In order to represent these constructed points explicitly, JTS must truncate them to fit the PrecisionModel.

Unfortunately, truncating coordinates moves them slightly. Line segments which would not be coincident in the exact result may become coincident in the truncated representation. This in turn leads to "topology collapses" -- situations where a computed element has a lower dimension than it would in the exact result.

When JTS detects topology collapses during the computation of spatial analysis methods, it will throw an exception. If possible the exception will report the location of the collapse.

Geometry Equality

There are two ways of comparing geometries for equality: structural equality and topological equality.

Structural Equality

Structural Equality is provided by the {@link #equalsExact(Geometry)} method. This implements a comparison based on exact, structural pointwise equality. The {@link #equals(Object)} is a synonym for this method, to provide structural equality semantics for use in Java collections. It is important to note that structural pointwise equality is easily affected by things like ring order and component order. In many situations it will be desirable to normalize geometries before comparing them (using the {@link #norm()} or {@link #normalize()} methods). {@link #equalsNorm(Geometry)} is provided as a convenience method to compute equality over normalized geometries, but it is expensive to use. Finally, {@link #equalsExact(Geometry, double)} allows using a tolerance value for point comparison.

Topological Equality

Topological Equality is provided by the {@link #equalsTopo(Geometry)} method. It implements the SFS definition of point-set equality defined in terms of the DE-9IM matrix. To support the SFS naming convention, the method {@link #equals(Geometry)} is also provided as a synonym. However, due to the potential for confusion with {@link #equals(Object)} its use is discouraged.

Since {@link #equals(Object)} and {@link #hashCode()} are overridden, Geometries can be used effectively in Java collections.

@version 1.7

Implemented types

Comparable

Implementers

Constructors

Geometry(GeometryFactory geomFactory): Creates a new Geometry via the specified GeometryFactory.

Properties

envelope ↔ Envelope?: The bounding box of this Geometry.
read / write
geomFactory ↔ GeometryFactory: The {@link GeometryFactory} used to create this Geometry
latefinal
hashCode → int: Gets a hash code for the Geometry.
read-onlyoverride
runtimeType → Type: A representation of the runtime type of the object.
read-onlyinherited
SRID ↔ int: The ID of the Spatial Reference System used by this Geometry
read / write
userData ↔ Object?: An object reference which can be used to carry ancillary data defined by the client.
read / write

Methods

applyCF(CoordinateFilter filter) → void: Performs an operation with or on this Geometry's coordinates. If this method modifies any coordinate values, {@link #geometryChanged} must be called to update the geometry state. Note that you cannot use this method to modify this Geometry if its underlying CoordinateSequence's #get method returns a copy of the Coordinate, rather than the actual Coordinate stored (if it even stores Coordinate objects at all).
applyCSF(CoordinateSequenceFilter filter) → void: Performs an operation on the coordinates in this Geometry's {@link CoordinateSequence}s. If the filter reports that a coordinate value has been changed, {@link #geometryChanged} will be called automatically.
applyGCF(GeometryComponentFilter filter) → void: Performs an operation with or on this Geometry and its component Geometry's. Only GeometryCollections and Polygons have component Geometry's; for Polygons they are the LinearRings of the shell and holes.
applyGF(GeometryFilter filter) → void: Performs an operation with or on this Geometry and its subelement Geometrys (if any). Only GeometryCollections and subclasses have subelement Geometry's.
buffer(double distance) → Geometry: Computes a buffer area around this geometry having the given width. The buffer of a Geometry is the Minkowski sum or difference of the geometry with a disc of radius abs(distance).
buffer2(double distance, int quadrantSegments) → Geometry: Computes a buffer area around this geometry having the given width and with a specified accuracy of approximation for circular arcs.
buffer3(double distance, int quadrantSegments, int endCapStyle) → Geometry: Computes a buffer area around this geometry having the given width and with a specified accuracy of approximation for circular arcs, and using a specified end cap style.
clone() → Object?: Creates and returns a full copy of this {@link Geometry} object (including all coordinates contained by it). Subclasses are responsible for overriding this method and copying their internal data. Overrides should call this method first.
compare(List a, List b) → int: Returns the first non-zero result of compareTo encountered as the two Collections are iterated over. If, by the time one of the iterations is complete, no non-zero result has been encountered, returns 0 if the other iteration is also complete. If b completes before a, a positive number is returned; if a before b, a negative number.
override
compareTo(dynamic o) → int: Returns whether this Geometry is greater than, equal to, or less than another Geometry.
override
compareToSameClass(Object o) → int: Returns whether this Geometry is greater than, equal to, or less than another Geometry having the same class.
compareToSameClassWithComparator(Object o, Comparator<CoordinateSequence> comp) → int: Returns whether this Geometry is greater than, equal to, or less than another Geometry of the same class. using the given {@link CoordinateSequenceComparator}.
compareToWithComparator(Object o, Comparator<CoordinateSequence> comp) → int: Returns whether this Geometry is greater than, equal to, or less than another Geometry, using the given {@link CoordinateSequenceComparator}.
computeEnvelopeInternal() → Envelope: Returns the minimum and maximum x and y values in this Geometry , or a null Envelope if this Geometry is empty. Unlike getEnvelopeInternal, this method calculates the Envelope each time it is called; getEnvelopeInternal caches the result of this method.
contains(Geometry g) → bool: Tests whether this geometry contains the argument geometry.
convexHull() → Geometry: Computes the smallest convex Polygon that contains all the points in the Geometry. This obviously applies only to Geometry s which contain 3 or more points; the results for degenerate cases are specified as follows:
copy() → Geometry: Creates a deep copy of this {@link Geometry} object. Coordinate sequences contained in it are copied. All instance fields are copied (i.e. the SRID and userData).
copyInternal() → Geometry: An internal method to copy subclass-specific geometry data.
coveredBy(Geometry g) → bool: Tests whether this geometry is covered by the argument geometry.
covers(Geometry g) → bool: Tests whether this geometry covers the argument geometry.
createPointFromInternalCoord(Coordinate coord, Geometry exemplar) → Point
crosses(Geometry g) → bool: Tests whether this geometry crosses the argument geometry.
difference(Geometry other) → Geometry: Computes a Geometry representing the closure of the point-set of the points contained in this Geometry that are not contained in the other Geometry.
disjoint(Geometry g) → bool: Tests whether this geometry is disjoint from the argument geometry.
distance(Geometry g) → double: Returns the minimum distance between this Geometry and another Geometry.
equal(Coordinate a, Coordinate b, double tolerance) → bool
equals(Geometry? g) → bool: Tests whether this geometry is topologically equal to the argument geometry.
equalsExactGeom(Geometry other) → bool: Returns true if the two Geometrys are exactly equal. Two Geometries are exactly equal iff:
equalsExactWithTol(Geometry other, double tolerance) → bool: Returns true if the two Geometrys are exactly equal, up to a specified distance tolerance. Two Geometries are exactly equal within a distance tolerance if and only if:
equalsNorm(Geometry g) → bool: Tests whether two geometries are exactly equal in their normalized forms. This is a convenience method which creates normalized versions of both geometries before computing {@link #equalsExact(Geometry)}.
equalsObj(Object o) → bool: Tests whether this geometry is structurally and numerically equal to a given Object. If the argument Object is not a Geometry, the result is false. Otherwise, the result is computed using {@link #equalsExact(Geometry)}.
equalsTopo(Geometry g) → bool: Tests whether this geometry is topologically equal to the argument geometry as defined by the SFS equals predicate.
geometryChanged() → void: Notifies this geometry that its coordinates have been changed by an external party (for example, via a {@link CoordinateFilter}). When this method is called the geometry will flush and/or update any derived information it has cached (such as its {@link Envelope} ). The operation is applied to all component Geometries.
geometryChangedAction() → void: Notifies this Geometry that its Coordinates have been changed by an external party. When #geometryChanged is called, this method will be called for this Geometry and its component Geometries.
getArea() → double: Returns the area of this Geometry. Areal Geometries have a non-zero area. They override this function to compute the area. Others return 0.0
getBoundary() → Geometry: Returns the boundary, or an empty geometry of appropriate dimension if this Geometry is empty. (In the case of zero-dimensional geometries, ' an empty GeometryCollection is returned.) For a discussion of this function, see the OpenGIS Simple Features Specification. As stated in SFS Section 2.1.13.1, "the boundary of a Geometry is a set of Geometries of the next lower dimension."
getBoundaryDimension() → int: Returns the dimension of this Geometrys inherent boundary.
getCentroid() → Point: Computes the centroid of this Geometry. The centroid is equal to the centroid of the set of component Geometries of highest dimension (since the lower-dimension geometries contribute zero "weight" to the centroid).
getCoordinate() → Coordinate?: Returns a vertex of this Geometry (usually, but not necessarily, the first one). The returned coordinate should not be assumed to be an actual Coordinate object used in the internal representation.
getCoordinates() → List<Coordinate>: Returns an array containing the values of all the vertices for this geometry. If the geometry is a composite, the array will contain all the vertices for the components, in the order in which the components occur in the geometry.
getDimension() → int: Returns the dimension of this geometry. The dimension of a geometry is is the topological dimension of its embedding in the 2-D Euclidean plane. In the JTS spatial model, dimension values are in the set {0,1,2}.
getEnvelope() → Geometry: Gets a Geometry representing the envelope (bounding box) of this Geometry.
getEnvelopeInternal() → Envelope: Gets an {@link Envelope} containing the minimum and maximum x and y values in this Geometry. If the geometry is empty, an empty Envelope is returned.
getFactory() → GeometryFactory: Gets the factory which contains the context in which this geometry was created.
getGeometryN(int n) → Geometry: Returns an element {@link Geometry} from a {@link GeometryCollection} (or this, if the geometry is not a collection).
getGeometryType() → String: Returns the name of this Geometry's actual class.
getInteriorPoint() → Point: Computes an interior point of this Geometry. An interior point is guaranteed to lie in the interior of the Geometry, if it possible to calculate such a point exactly. Otherwise, the point may lie on the boundary of the geometry.
getLength() → double: Returns the length of this Geometry. Linear geometries return their length. Areal geometries return their perimeter. They override this function to compute the area. Others return 0.0
getNumGeometries() → int: Returns the number of {@link Geometry}s in a {@link GeometryCollection} (or 1, if the geometry is not a collection).
getNumPoints() → int: Returns the count of this Geometrys vertices. The Geometry s contained by composite Geometrys must be Geometry's; that is, they must implement getNumPoints
getPrecisionModel() → PrecisionModel: Returns the PrecisionModel used by the Geometry.
getSortIndex() → int
getSRID() → int: Returns the ID of the Spatial Reference System used by the Geometry.
getUserData() → Object?: Gets the user data object for this geometry, if any.
intersection(Geometry other) → Geometry: Computes a Geometry representing the point-set which is common to both this Geometry and the other Geometry.
intersects(Geometry g) → bool: Tests whether this geometry intersects the argument geometry.
isEmpty() → bool: Tests whether the set of points covered by this Geometry is empty.
isEquivalentClass(Geometry other) → bool: Returns whether the two Geometrys are equal, from the point of view of the equalsExact method. Called by equalsExact . In general, two Geometry classes are considered to be "equivalent" only if they are the same class. An exception is LineString , which is considered to be equivalent to its subclasses.
isGeometryCollection() → bool: Tests whether this is an instance of a general {@link GeometryCollection}, rather than a homogeneous subclass.
isRectangle() → bool: Tests whether this is a rectangular {@link Polygon}.
isSimple() → bool: Tests whether this {@link Geometry} is simple. The SFS definition of simplicity follows the general rule that a Geometry is simple if it has no points of self-tangency, self-intersection or other anomalous points.
isValid() → bool: Tests whether this Geometry is topologically valid, according to the OGC SFS specification.
isWithinDistance(Geometry geom, double distance) → bool: Tests whether the distance from this Geometry to another is less than or equal to a specified value.
norm() → Geometry: Creates a new Geometry which is a normalized copy of this Geometry.
normalize() → void: Converts this Geometry to normal form (or canonical form ). Normal form is a unique representation for Geometry s. It can be used to test whether two Geometrys are equal in a way that is independent of the ordering of the coordinates within them. Normal form equality is a stronger condition than topological equality, but weaker than pointwise equality. The definitions for normal form use the standard lexicographical ordering for coordinates. "Sorted in order of coordinates" means the obvious extension of this ordering to sequences of coordinates.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent method or property is accessed.
inherited
overlaps(Geometry g) → bool: Tests whether this geometry overlaps the specified geometry.
relate(Geometry g) → IntersectionMatrix: Returns the DE-9IM {@link IntersectionMatrix} for the two Geometrys.
relateWithPattern(Geometry g, String intersectionPattern) → bool: Tests whether the elements in the DE-9IM {@link IntersectionMatrix} for the two Geometrys match the elements in intersectionPattern. The pattern is a 9-character string, with symbols drawn from the following set:
reverse() → Geometry: Computes a new geometry which has all component coordinate sequences in reverse order (opposite orientation) to this one.
setSRID(int SRID) → void: Sets the ID of the Spatial Reference System used by the Geometry.
setUserData(Object? userData) → void: A simple scheme for applications to add their own custom data to a Geometry. An example use might be to add an object representing a Coordinate Reference System.
symDifference(Geometry other) → Geometry: Computes a Geometry representing the closure of the point-set which is the union of the points in this Geometry which are not contained in the other Geometry, with the points in the other Geometry not contained in this Geometry. If the result is empty, it is an atomic geometry with the dimension of the highest input dimension.
toString() → String: A string representation of this object.
override
toText() → String: Returns the Well-known Text representation of this Geometry. For a definition of the Well-known Text format, see the OpenGIS Simple Features Specification.
touches(Geometry g) → bool: Tests whether this geometry touches the argument geometry.
union() → Geometry: Computes the union of all the elements of this geometry.
unionGeom(Geometry other) → Geometry: Computes a Geometry representing the point-set which is contained in both this Geometry and the other Geometry.
within(Geometry g) → bool: Tests whether this geometry is within the specified geometry.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

geometryChangedFilter → GeometryComponentFilter: final
SORTINDEX_GEOMETRYCOLLECTION → int: final
SORTINDEX_LINEARRING → int: final
SORTINDEX_LINESTRING → int: final
SORTINDEX_MULTILINESTRING → int: final
SORTINDEX_MULTIPOINT → int: final
SORTINDEX_MULTIPOLYGON → int: final
SORTINDEX_POINT → int: final
SORTINDEX_POLYGON → int: final

Static Methods

checkNotGeometryCollection(Geometry g) → void: Throws an exception if g's type is a GeometryCollection. (Its subclasses do not trigger an exception).
hasNonEmptyElements(List<Geometry> geometries) → bool: Returns true if the array contains any non-empty Geometrys.
hasNullElements(List<Object?> array) → bool: Returns true if the array contains any null elements.