Class Geometry
- java.lang.Object
-
- org.locationtech.jts.geom.Geometry
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
,java.lang.Comparable
- Direct Known Subclasses:
GeometryCollection
,LineString
,Point
,Polygon
public abstract class Geometry extends java.lang.Object implements java.lang.Cloneable, java.lang.Comparable, java.io.Serializable
A representation of a planar, linear vector geometry.Binary Predicates
Because it is not clear at this time what semantics for spatial analysis methods involvingGeometryCollection
s would be useful,GeometryCollection
s are not supported as arguments to binary predicates or therelate
method.Overlay Methods
The overlay methods return the most specific class possible to represent the result. If the result is homogeneous, aPoint
,LineString
, orPolygon
will be returned if the result contains a single element; otherwise, aMultiPoint
,MultiLineString
, orMultiPolygon
will be returned. If the result is heterogeneous aGeometryCollection
will be returned.Because it is not clear at this time what semantics for set-theoretic methods involving
GeometryCollection
s 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 aGeometry
.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
Geometry
s returned from overlay methods. The canonical form is aGeometry
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
LineString
s. It means that all intersection points onLineString
s will be present as endpoints ofLineString
s in the result.
Constructed Points And The Precision Model
The results computed by the set-theoretic methods may contain constructed points which are not present in the inputGeometry
s. These new points arise from intersections between line segments in the edges of the inputGeometry
s. 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 thePrecisionModel
.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 theequalsExact(Geometry)
method. This implements a comparison based on exact, structural pointwise equality. Theequals(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 thenorm()
ornormalize()
methods).equalsNorm(Geometry)
is provided as a convenience method to compute equality over normalized geometries, but it is expensive to use. Finally,equalsExact(Geometry, double)
allows using a tolerance value for point comparison.Topological Equality
Topological Equality is provided by theequalsTopo(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 methodequals(Geometry)
is also provided as a synonym. However, due to the potential for confusion withequals(Object)
its use is discouraged.Since
equals(Object)
andhashCode()
are overridden, Geometries can be used effectively in Java collections.- Version:
- 1.7
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
TYPENAME_GEOMETRYCOLLECTION
static java.lang.String
TYPENAME_LINEARRING
static java.lang.String
TYPENAME_LINESTRING
static java.lang.String
TYPENAME_MULTILINESTRING
static java.lang.String
TYPENAME_MULTIPOINT
static java.lang.String
TYPENAME_MULTIPOLYGON
static java.lang.String
TYPENAME_POINT
static java.lang.String
TYPENAME_POLYGON
-
Constructor Summary
Constructors Constructor Description Geometry(GeometryFactory factory)
Creates a newGeometry
via the specified GeometryFactory.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description abstract void
apply(CoordinateFilter filter)
Performs an operation with or on thisGeometry
's coordinates.abstract void
apply(CoordinateSequenceFilter filter)
Performs an operation on the coordinates in thisGeometry
'sCoordinateSequence
s.abstract void
apply(GeometryComponentFilter filter)
Performs an operation with or on this Geometry and its component Geometry's.abstract void
apply(GeometryFilter filter)
Performs an operation with or on thisGeometry
and its subelementGeometry
s (if any).Geometry
buffer(double distance)
Computes a buffer area around this geometry having the given width.Geometry
buffer(double distance, int quadrantSegments)
Computes a buffer area around this geometry having the given width and with a specified accuracy of approximation for circular arcs.Geometry
buffer(double distance, int quadrantSegments, int endCapStyle)
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.java.lang.Object
clone()
Deprecated.int
compareTo(java.lang.Object o)
Returns whether thisGeometry
is greater than, equal to, or less than anotherGeometry
.int
compareTo(java.lang.Object o, CoordinateSequenceComparator comp)
Returns whether thisGeometry
is greater than, equal to, or less than anotherGeometry
, using the givenCoordinateSequenceComparator
.boolean
contains(Geometry g)
Tests whether this geometry contains the argument geometry.Geometry
convexHull()
Computes the smallest convexPolygon
that contains all the points in theGeometry
.Geometry
copy()
Creates a deep copy of thisGeometry
object.boolean
coveredBy(Geometry g)
Tests whether this geometry is covered by the argument geometry.boolean
covers(Geometry g)
Tests whether this geometry covers the argument geometry.boolean
crosses(Geometry g)
Tests whether this geometry crosses the argument geometry.Geometry
difference(Geometry other)
Computes aGeometry
representing the closure of the point-set of the points contained in thisGeometry
that are not contained in theother
Geometry.boolean
disjoint(Geometry g)
Tests whether this geometry is disjoint from the argument geometry.double
distance(Geometry g)
Returns the minimum distance between thisGeometry
and anotherGeometry
.boolean
equals(java.lang.Object o)
Tests whether this geometry is structurally and numerically equal to a givenObject
.boolean
equals(Geometry g)
Tests whether this geometry is topologically equal to the argument geometry.boolean
equalsExact(Geometry other)
Returns true if the twoGeometry
s are exactly equal.abstract boolean
equalsExact(Geometry other, double tolerance)
Returns true if the twoGeometry
s are exactly equal, up to a specified distance tolerance.boolean
equalsNorm(Geometry g)
Tests whether two geometries are exactly equal in their normalized forms.boolean
equalsTopo(Geometry g)
Tests whether this geometry is topologically equal to the argument geometry as defined by the SFSequals
predicate.void
geometryChanged()
Notifies this geometry that its coordinates have been changed by an external party (for example, via aCoordinateFilter
).double
getArea()
Returns the area of thisGeometry
.abstract Geometry
getBoundary()
Returns the boundary, or an empty geometry of appropriate dimension if thisGeometry
is empty.abstract int
getBoundaryDimension()
Returns the dimension of thisGeometry
s inherent boundary.Point
getCentroid()
Computes the centroid of thisGeometry
.abstract Coordinate
getCoordinate()
Returns a vertex of thisGeometry
(usually, but not necessarily, the first one).abstract Coordinate[]
getCoordinates()
Returns an array containing the values of all the vertices for this geometry.abstract int
getDimension()
Returns the dimension of this geometry.Geometry
getEnvelope()
Gets a Geometry representing the envelope (bounding box) of thisGeometry
.Envelope
getEnvelopeInternal()
Gets anEnvelope
containing the minimum and maximum x and y values in thisGeometry
.GeometryFactory
getFactory()
Gets the factory which contains the context in which this geometry was created.Geometry
getGeometryN(int n)
Returns an elementGeometry
from aGeometryCollection
(orthis
, if the geometry is not a collection).abstract java.lang.String
getGeometryType()
Returns the name of this Geometry's actual class.Point
getInteriorPoint()
Computes an interior point of thisGeometry
.double
getLength()
Returns the length of thisGeometry
.int
getNumGeometries()
Returns the number ofGeometry
s in aGeometryCollection
(or 1, if the geometry is not a collection).abstract int
getNumPoints()
Returns the count of thisGeometry
s vertices.PrecisionModel
getPrecisionModel()
Returns thePrecisionModel
used by theGeometry
.int
getSRID()
Returns the ID of the Spatial Reference System used by theGeometry
.java.lang.Object
getUserData()
Gets the user data object for this geometry, if any.int
hashCode()
Gets a hash code for the Geometry.Geometry
intersection(Geometry other)
Computes aGeometry
representing the point-set which is common to both thisGeometry
and theother
Geometry.boolean
intersects(Geometry g)
Tests whether this geometry intersects the argument geometry.abstract boolean
isEmpty()
Tests whether the set of points covered by thisGeometry
is empty.boolean
isRectangle()
Tests whether this is a rectangularPolygon
.boolean
isSimple()
Tests whether thisGeometry
is simple.boolean
isValid()
Tests whether thisGeometry
is topologically valid, according to the OGC SFS specification.boolean
isWithinDistance(Geometry geom, double distance)
Tests whether the distance from thisGeometry
to another is less than or equal to a specified value.Geometry
norm()
Creates a new Geometry which is a normalized copy of this Geometry.abstract void
normalize()
Converts thisGeometry
to normal form (or canonical form ).boolean
overlaps(Geometry g)
Tests whether this geometry overlaps the specified geometry.IntersectionMatrix
relate(Geometry g)
Returns the DE-9IMIntersectionMatrix
for the twoGeometry
s.boolean
relate(Geometry g, java.lang.String intersectionPattern)
Tests whether the elements in the DE-9IMIntersectionMatrix
for the twoGeometry
s match the elements inintersectionPattern
.Geometry
reverse()
Computes a new geometry which has all component coordinate sequences in reverse order (opposite orientation) to this one.void
setSRID(int SRID)
Sets the ID of the Spatial Reference System used by theGeometry
.void
setUserData(java.lang.Object userData)
A simple scheme for applications to add their own custom data to a Geometry.Geometry
symDifference(Geometry other)
Computes aGeometry
representing the closure of the point-set which is the union of the points in thisGeometry
which are not contained in theother
Geometry, with the points in theother
Geometry not contained in thisGeometry
.java.lang.String
toString()
java.lang.String
toText()
Returns the Well-known Text representation of thisGeometry
.boolean
touches(Geometry g)
Tests whether this geometry touches the argument geometry.Geometry
union()
Computes the union of all the elements of this geometry.Geometry
union(Geometry other)
Computes aGeometry
representing the point-set which is contained in both thisGeometry
and theother
Geometry.boolean
within(Geometry g)
Tests whether this geometry is within the specified geometry.
-
-
-
Field Detail
-
TYPENAME_POINT
public static final java.lang.String TYPENAME_POINT
- See Also:
- Constant Field Values
-
TYPENAME_MULTIPOINT
public static final java.lang.String TYPENAME_MULTIPOINT
- See Also:
- Constant Field Values
-
TYPENAME_LINESTRING
public static final java.lang.String TYPENAME_LINESTRING
- See Also:
- Constant Field Values
-
TYPENAME_LINEARRING
public static final java.lang.String TYPENAME_LINEARRING
- See Also:
- Constant Field Values
-
TYPENAME_MULTILINESTRING
public static final java.lang.String TYPENAME_MULTILINESTRING
- See Also:
- Constant Field Values
-
TYPENAME_POLYGON
public static final java.lang.String TYPENAME_POLYGON
- See Also:
- Constant Field Values
-
TYPENAME_MULTIPOLYGON
public static final java.lang.String TYPENAME_MULTIPOLYGON
- See Also:
- Constant Field Values
-
TYPENAME_GEOMETRYCOLLECTION
public static final java.lang.String TYPENAME_GEOMETRYCOLLECTION
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Geometry
public Geometry(GeometryFactory factory)
Creates a newGeometry
via the specified GeometryFactory.- Parameters:
factory
-
-
-
Method Detail
-
getGeometryType
public abstract java.lang.String getGeometryType()
Returns the name of this Geometry's actual class.- Returns:
- the name of this
Geometry
s actual class
-
getSRID
public int getSRID()
Returns the ID of the Spatial Reference System used by theGeometry
.JTS supports Spatial Reference System information in the simple way defined in the SFS. A Spatial Reference System ID (SRID) is present in each
Geometry
object.Geometry
provides basic accessor operations for this field, but no others. The SRID is represented as an integer.- Returns:
- the ID of the coordinate space in which the
Geometry
is defined.
-
setSRID
public void setSRID(int SRID)
Sets the ID of the Spatial Reference System used by theGeometry
.NOTE: This method should only be used for exceptional circumstances or for backwards compatibility. Normally the SRID should be set on the
GeometryFactory
used to create the geometry. SRIDs set using this method will not be propagated to geometries returned by constructive methods.- See Also:
GeometryFactory
-
getFactory
public GeometryFactory getFactory()
Gets the factory which contains the context in which this geometry was created.- Returns:
- the factory for this geometry
-
getUserData
public java.lang.Object getUserData()
Gets the user data object for this geometry, if any.- Returns:
- the user data object, or
null
if none set
-
getNumGeometries
public int getNumGeometries()
Returns the number ofGeometry
s in aGeometryCollection
(or 1, if the geometry is not a collection).- Returns:
- the number of geometries contained in this geometry
-
getGeometryN
public Geometry getGeometryN(int n)
Returns an elementGeometry
from aGeometryCollection
(orthis
, if the geometry is not a collection).- Parameters:
n
- the index of the geometry element- Returns:
- the n'th geometry contained in this geometry
-
setUserData
public void setUserData(java.lang.Object userData)
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.Note that user data objects are not present in geometries created by construction methods.
- Parameters:
userData
- an object, the semantics for which are defined by the application using this Geometry
-
getPrecisionModel
public PrecisionModel getPrecisionModel()
Returns thePrecisionModel
used by theGeometry
.- Returns:
- the specification of the grid of allowable points, for this
Geometry
and all otherGeometry
s
-
getCoordinate
public abstract Coordinate getCoordinate()
Returns a vertex of thisGeometry
(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.- Returns:
- a
Coordinate
which is a vertex of thisGeometry
.
-
getCoordinates
public abstract Coordinate[] getCoordinates()
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.In general, the array cannot be assumed to be the actual internal storage for the vertices. Thus modifying the array may not modify the geometry itself. Use the
CoordinateSequence.setOrdinate(int, int, double)
method (possibly on the components) to modify the underlying data. If the coordinates are modified,geometryChanged()
must be called afterwards.- Returns:
- the vertices of this
Geometry
- See Also:
geometryChanged()
,CoordinateSequence.setOrdinate(int, int, double)
-
getNumPoints
public abstract int getNumPoints()
Returns the count of thisGeometry
s vertices. TheGeometry
s contained by compositeGeometry
s must be Geometry's; that is, they must implementgetNumPoints
- Returns:
- the number of vertices in this
Geometry
-
isSimple
public boolean isSimple()
Tests whether thisGeometry
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.Simplicity is defined for each
Geometry
subclass as follows:- Valid polygonal geometries are simple, since their rings
must not self-intersect.
isSimple
tests for this condition and reportsfalse
if it is not met. (This is a looser test than checking for validity). - Linear rings have the same semantics.
- Linear geometries are simple if they do not self-intersect at points other than boundary points.
- Zero-dimensional geometries (points) are simple if they have no repeated points.
- Empty
Geometry
s are always simple.
- Returns:
true
if thisGeometry
is simple- See Also:
isValid()
- Valid polygonal geometries are simple, since their rings
must not self-intersect.
-
isValid
public boolean isValid()
Tests whether thisGeometry
is topologically valid, according to the OGC SFS specification.For validity rules see the Javadoc for the specific Geometry subclass.
- Returns:
true
if thisGeometry
is valid- See Also:
IsValidOp
-
isEmpty
public abstract boolean isEmpty()
Tests whether the set of points covered by thisGeometry
is empty.Note this test is for topological emptiness, not structural emptiness. A collection containing only empty elements is reported as empty. To check structural emptiness use
getNumGeometries()
.- Returns:
true
if thisGeometry
does not cover any points
-
distance
public double distance(Geometry g)
Returns the minimum distance between thisGeometry
and anotherGeometry
.- Parameters:
g
- theGeometry
from which to compute the distance- Returns:
- the distance between the geometries
- Throws:
java.lang.IllegalArgumentException
- if g is null
-
isWithinDistance
public boolean isWithinDistance(Geometry geom, double distance)
Tests whether the distance from thisGeometry
to another is less than or equal to a specified value.- Parameters:
geom
- the Geometry to check the distance todistance
- the distance value to compare- Returns:
true
if the geometries are less thandistance
apart.
-
isRectangle
public boolean isRectangle()
Tests whether this is a rectangularPolygon
.- Returns:
- true if the geometry is a rectangle.
-
getArea
public double getArea()
Returns the area of thisGeometry
. Areal Geometries have a non-zero area. They override this function to compute the area. Others return 0.0- Returns:
- the area of the Geometry
-
getLength
public double getLength()
Returns the length of thisGeometry
. Linear geometries return their length. Areal geometries return their perimeter. They override this function to compute the area. Others return 0.0- Returns:
- the length of the Geometry
-
getCentroid
public Point getCentroid()
Computes the centroid of thisGeometry
. 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).The centroid of an empty geometry is
POINT EMPTY
.- Returns:
- a
Point
which is the centroid of this Geometry
-
getInteriorPoint
public Point getInteriorPoint()
Computes an interior point of thisGeometry
. 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.The interior point of an empty geometry is
POINT EMPTY
.- Returns:
- a
Point
which is in the interior of this Geometry
-
getDimension
public abstract int getDimension()
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}.Note that this is a different concept to the dimension of the vertex
Coordinate
s. The geometry dimension can never be greater than the coordinate dimension. For example, a 0-dimensional geometry (e.g. a Point) may have a coordinate dimension of 3 (X,Y,Z).- Returns:
- the topological dimension of this geometry.
-
getBoundary
public abstract Geometry getBoundary()
Returns the boundary, or an empty geometry of appropriate dimension if thisGeometry
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."- Returns:
- the closure of the combinatorial boundary of this
Geometry
-
getBoundaryDimension
public abstract int getBoundaryDimension()
Returns the dimension of thisGeometry
s inherent boundary.- Returns:
- the dimension of the boundary of the class implementing this
interface, whether or not this object is the empty geometry. Returns
Dimension.FALSE
if the boundary is the empty geometry.
-
getEnvelope
public Geometry getEnvelope()
Gets a Geometry representing the envelope (bounding box) of thisGeometry
.If this
Geometry
is:- empty, returns an empty
Point
. - a point, returns a
Point
. - a line parallel to an axis, a two-vertex
LineString
- otherwise, returns a
Polygon
whose vertices are (minx miny, minx maxy, maxx maxy, maxx miny, minx miny).
- Returns:
- a Geometry representing the envelope of this Geometry
- See Also:
GeometryFactory.toGeometry(Envelope)
- empty, returns an empty
-
getEnvelopeInternal
public Envelope getEnvelopeInternal()
Gets anEnvelope
containing the minimum and maximum x and y values in thisGeometry
. If the geometry is empty, an emptyEnvelope
is returned.The returned object is a copy of the one maintained internally, to avoid aliasing issues. For best performance, clients which access this envelope frequently should cache the return value.
- Returns:
- the envelope of this
Geometry
.
-
geometryChanged
public void geometryChanged()
Notifies this geometry that its coordinates have been changed by an external party (for example, via aCoordinateFilter
). When this method is called the geometry will flush and/or update any derived information it has cached (such as itsEnvelope
). The operation is applied to all component Geometries.
-
disjoint
public boolean disjoint(Geometry g)
Tests whether this geometry is disjoint from the argument geometry.The
disjoint
predicate has the following equivalent definitions:- The two geometries have no point in common
- The DE-9IM Intersection Matrix for the two geometries matches
[FF*FF****]
! g.intersects(this) = true
(disjoint
is the inverse ofintersects
)
- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s are disjoint- See Also:
intersects(org.locationtech.jts.geom.Geometry)
-
touches
public boolean touches(Geometry g)
Tests whether this geometry touches the argument geometry.The
touches
predicate has the following equivalent definitions:- The geometries have at least one point in common, but their interiors do not intersect.
- The DE-9IM Intersection Matrix for the two geometries matches
at least one of the following patterns
[FT*******]
[F**T*****]
[F***T****]
false
, since points have only interiors. This predicate is symmetric.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s touch; Returnsfalse
if bothGeometry
s are points
-
intersects
public boolean intersects(Geometry g)
Tests whether this geometry intersects the argument geometry.The
intersects
predicate has the following equivalent definitions:- The two geometries have at least one point in common
- The DE-9IM Intersection Matrix for the two geometries matches
at least one of the patterns
[T********]
[*T*******]
[***T*****]
[****T****]
! g.disjoint(this) = true
(intersects
is the inverse ofdisjoint
)
- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s intersect- See Also:
disjoint(org.locationtech.jts.geom.Geometry)
-
crosses
public boolean crosses(Geometry g)
Tests whether this geometry crosses the argument geometry.The
crosses
predicate has the following equivalent definitions:- The geometries have some but not all interior points in common.
- The DE-9IM Intersection Matrix for the two geometries matches
one of the following patterns:
[T*T******]
(for P/L, P/A, and L/A situations)[T*****T**]
(for L/P, A/P, and A/L situations)[0********]
(for L/L situations)
false
.The SFS defined this predicate only for P/L, P/A, L/L, and L/A situations. To make the relation symmetric JTS extends the definition to apply to L/P, A/P and A/L situations as well.
- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s cross.
-
within
public boolean within(Geometry g)
Tests whether this geometry is within the specified geometry.The
within
predicate has the following equivalent definitions:- Every point of this geometry is a point of the other geometry, and the interiors of the two geometries have at least one point in common.
- The DE-9IM Intersection Matrix for the two geometries matches
[T*F**F***]
g.contains(this) = true
(within
is the converse ofcontains(org.locationtech.jts.geom.Geometry)
)
A.within(B) = false
(As a concrete example, take A to be a LineString which lies in the boundary of a Polygon B.) For a predicate with similar behaviour but avoiding this subtle limitation, seecoveredBy(org.locationtech.jts.geom.Geometry)
.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if thisGeometry
is withing
- See Also:
contains(org.locationtech.jts.geom.Geometry)
,coveredBy(org.locationtech.jts.geom.Geometry)
-
contains
public boolean contains(Geometry g)
Tests whether this geometry contains the argument geometry.The
contains
predicate has the following equivalent definitions:- Every point of the other geometry is a point of this geometry, and the interiors of the two geometries have at least one point in common.
- The DE-9IM Intersection Matrix for the two geometries matches
the pattern
[T*****FF*]
g.within(this) = true
(contains
is the converse ofwithin(org.locationtech.jts.geom.Geometry)
)
B.contains(A) = false
. (As a concrete example, take A to be a LineString which lies in the boundary of a Polygon B.) For a predicate with similar behaviour but avoiding this subtle limitation, seecovers(org.locationtech.jts.geom.Geometry)
.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if thisGeometry
containsg
- See Also:
within(org.locationtech.jts.geom.Geometry)
,covers(org.locationtech.jts.geom.Geometry)
-
overlaps
public boolean overlaps(Geometry g)
Tests whether this geometry overlaps the specified geometry.The
overlaps
predicate has the following equivalent definitions:- The geometries have at least one point each not shared by the other (or equivalently neither covers the other), they have the same dimension, and the intersection of the interiors of the two geometries has the same dimension as the geometries themselves.
- The DE-9IM Intersection Matrix for the two geometries matches
[T*T***T**]
(for two points or two surfaces) or[1*T***T**]
(for two curves)
false
. This predicate is symmetric.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s overlap.
-
covers
public boolean covers(Geometry g)
Tests whether this geometry covers the argument geometry.The
covers
predicate has the following equivalent definitions:- Every point of the other geometry is a point of this geometry.
- The DE-9IM Intersection Matrix for the two geometries matches
at least one of the following patterns:
[T*****FF*]
[*T****FF*]
[***T**FF*]
[****T*FF*]
g.coveredBy(this) = true
(covers
is the converse ofcoveredBy(org.locationtech.jts.geom.Geometry)
)
false
.This predicate is similar to
contains(org.locationtech.jts.geom.Geometry)
, but is more inclusive (i.e. returnstrue
for more cases). In particular, unlikecontains
it does not distinguish between points in the boundary and in the interior of geometries. For most situations,covers
should be used in preference tocontains
. As an added benefit,covers
is more amenable to optimization, and hence should be more performant.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if thisGeometry
coversg
- See Also:
contains(org.locationtech.jts.geom.Geometry)
,coveredBy(org.locationtech.jts.geom.Geometry)
-
coveredBy
public boolean coveredBy(Geometry g)
Tests whether this geometry is covered by the argument geometry.The
coveredBy
predicate has the following equivalent definitions:- Every point of this geometry is a point of the other geometry.
- The DE-9IM Intersection Matrix for the two geometries matches
at least one of the following patterns:
[T*F**F***]
[*TF**F***]
[**FT*F***]
[**F*TF***]
g.covers(this) = true
(coveredBy
is the converse ofcovers(org.locationtech.jts.geom.Geometry)
)
false
.This predicate is similar to
within(org.locationtech.jts.geom.Geometry)
, but is more inclusive (i.e. returnstrue
for more cases).- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if thisGeometry
is covered byg
- See Also:
within(org.locationtech.jts.geom.Geometry)
,covers(org.locationtech.jts.geom.Geometry)
-
relate
public boolean relate(Geometry g, java.lang.String intersectionPattern)
Tests whether the elements in the DE-9IMIntersectionMatrix
for the twoGeometry
s match the elements inintersectionPattern
. The pattern is a 9-character string, with symbols drawn from the following set:- 0 (dimension 0)
- 1 (dimension 1)
- 2 (dimension 2)
- T ( matches 0, 1 or 2)
- F ( matches FALSE)
- * ( matches any value)
- Parameters:
g
- theGeometry
with which to compare thisGeometry
intersectionPattern
- the pattern against which to check the intersection matrix for the twoGeometry
s- Returns:
true
if the DE-9IM intersection matrix for the twoGeometry
s matchintersectionPattern
- See Also:
IntersectionMatrix
-
relate
public IntersectionMatrix relate(Geometry g)
Returns the DE-9IMIntersectionMatrix
for the twoGeometry
s.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
- an
IntersectionMatrix
describing the intersections of the interiors, boundaries and exteriors of the twoGeometry
s
-
equals
public boolean equals(Geometry g)
Tests whether this geometry is topologically equal to the argument geometry.This method is included for backward compatibility reasons. It has been superseded by the
equalsTopo(Geometry)
method, which has been named to clearly denote its functionality.This method should NOT be confused with the method
equals(Object)
, which implements an exact equality comparison.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
- true if the two
Geometry
s are topologically equal - See Also:
equalsTopo(Geometry)
-
equalsTopo
public boolean equalsTopo(Geometry g)
Tests whether this geometry is topologically equal to the argument geometry as defined by the SFSequals
predicate.The SFS
equals
predicate has the following equivalent definitions:- The two geometries have at least one point in common, and no point of either geometry lies in the exterior of the other geometry.
- The DE-9IM Intersection Matrix for the two geometries matches
the pattern
T*F**FFF*
T*F **F FF*
equalsExact(Geometry)
.- Parameters:
g
- theGeometry
with which to compare thisGeometry
- Returns:
true
if the twoGeometry
s are topologically equal- See Also:
equalsExact(Geometry)
-
equals
public boolean equals(java.lang.Object o)
Tests whether this geometry is structurally and numerically equal to a givenObject
. If the argumentObject
is not aGeometry
, the result isfalse
. Otherwise, the result is computed usingequalsExact(Geometry)
.This method is provided to fulfill the Java contract for value-based object equality. In conjunction with
hashCode()
it provides semantics which are most useful for usingGeometry
s as keys and values in Java collections.Note that to produce the expected result the input geometries should be in normal form. It is the caller's responsibility to perform this where required (using
norm()
ornormalize()
as appropriate).- Overrides:
equals
in classjava.lang.Object
- Parameters:
o
- the Object to compare- Returns:
- true if this geometry is exactly equal to the argument
- See Also:
equalsExact(Geometry)
,hashCode()
,norm()
,normalize()
-
hashCode
public int hashCode()
Gets a hash code for the Geometry.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- an integer value suitable for use as a hashcode
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
toText
public java.lang.String toText()
Returns the Well-known Text representation of thisGeometry
. For a definition of the Well-known Text format, see the OpenGIS Simple Features Specification.- Returns:
- the Well-known Text representation of this
Geometry
-
buffer
public Geometry buffer(double distance)
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 radiusabs(distance)
.Mathematically-exact buffer area boundaries can contain circular arcs. To represent these arcs using linear geometry they must be approximated with line segments. The buffer geometry is constructed using 8 segments per quadrant to approximate the circular arcs. The end cap style is
CAP_ROUND
.The buffer operation always returns a polygonal result. The negative or zero-distance buffer of lines and points is always an empty
Polygon
. This is also the result for the buffers of degenerate (zero-area) polygons.- Parameters:
distance
- the width of the buffer (may be positive, negative or 0)- Returns:
- a polygonal geometry representing the buffer region (which may be empty)
- Throws:
TopologyException
- if a robustness error occurs- See Also:
buffer(double, int)
,buffer(double, int, int)
-
buffer
public Geometry buffer(double distance, int quadrantSegments)
Computes a buffer area around this geometry having the given width and with a specified accuracy of approximation for circular arcs.Mathematically-exact buffer area boundaries can contain circular arcs. To represent these arcs using linear geometry they must be approximated with line segments. The
quadrantSegments
argument allows controlling the accuracy of the approximation by specifying the number of line segments used to represent a quadrant of a circleThe buffer operation always returns a polygonal result. The negative or zero-distance buffer of lines and points is always an empty
Polygon
. This is also the result for the buffers of degenerate (zero-area) polygons.- Parameters:
distance
- the width of the buffer (may be positive, negative or 0)quadrantSegments
- the number of line segments used to represent a quadrant of a circle- Returns:
- a polygonal geometry representing the buffer region (which may be empty)
- Throws:
TopologyException
- if a robustness error occurs- See Also:
buffer(double)
,buffer(double, int, int)
-
buffer
public Geometry buffer(double distance, int quadrantSegments, int endCapStyle)
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.Mathematically-exact buffer area boundaries can contain circular arcs. To represent these arcs using linear geometry they must be approximated with line segments. The
quadrantSegments
argument allows controlling the accuracy of the approximation by specifying the number of line segments used to represent a quadrant of a circleThe end cap style specifies the buffer geometry that will be created at the ends of linestrings. The styles provided are:
BufferParameters.CAP_ROUND
- (default) a semi-circleBufferParameters.CAP_FLAT
- a straight line perpendicular to the end segmentBufferParameters.CAP_SQUARE
- a half-square
The buffer operation always returns a polygonal result. The negative or zero-distance buffer of lines and points is always an empty
Polygon
. This is also the result for the buffers of degenerate (zero-area) polygons.- Parameters:
distance
- the width of the buffer (may be positive, negative or 0)quadrantSegments
- the number of line segments used to represent a quadrant of a circleendCapStyle
- the end cap style to use- Returns:
- a polygonal geometry representing the buffer region (which may be empty)
- Throws:
TopologyException
- if a robustness error occurs- See Also:
buffer(double)
,buffer(double, int)
,BufferOp
-
convexHull
public Geometry convexHull()
Computes the smallest convexPolygon
that contains all the points in theGeometry
. This obviously applies only toGeometry
s which contain 3 or more points; the results for degenerate cases are specified as follows:Number of Point
s in argumentGeometry
Geometry
class of result0 empty GeometryCollection
1 Point
2 LineString
3 or more Polygon
- Returns:
- the minimum-area convex polygon containing this
Geometry
' s points
-
reverse
public Geometry reverse()
Computes a new geometry which has all component coordinate sequences in reverse order (opposite orientation) to this one.- Returns:
- a reversed geometry
-
intersection
public Geometry intersection(Geometry other)
Computes aGeometry
representing the point-set which is common to both thisGeometry
and theother
Geometry.The intersection of two geometries of different dimension produces a result geometry of dimension less than or equal to the minimum dimension of the input geometries. The result geometry may be a heterogeneous
GeometryCollection
. If the result is empty, it is an atomic geometry with the dimension of the lowest input dimension.Intersection of
GeometryCollection
s is supported only for homogeneous collection types.Non-empty heterogeneous
GeometryCollection
arguments are not supported.- Parameters:
other
- theGeometry
with which to compute the intersection- Returns:
- a Geometry representing the point-set common to the two
Geometry
s - Throws:
TopologyException
- if a robustness error occursjava.lang.IllegalArgumentException
- if the argument is a non-empty heterogeneousGeometryCollection
-
union
public Geometry union(Geometry other)
Computes aGeometry
representing the point-set which is contained in both thisGeometry
and theother
Geometry.The union of two geometries of different dimension produces a result geometry of dimension equal to the maximum dimension of the input geometries. The result geometry may be a heterogeneous
GeometryCollection
. If the result is empty, it is an atomic geometry with the dimension of the highest input dimension.Unioning
LineString
s has the effect of noding and dissolving the input linework. In this context "noding" means that there will be a node or endpoint in the result for every endpoint or line segment crossing in the input. "Dissolving" means that any duplicate (i.e. coincident) line segments or portions of line segments will be reduced to a single line segment in the result. If merged linework is required, theLineMerger
class can be used.Non-empty
GeometryCollection
arguments are not supported.- Parameters:
other
- theGeometry
with which to compute the union- Returns:
- a point-set combining the points of this
Geometry
and the points ofother
- Throws:
TopologyException
- if a robustness error occursjava.lang.IllegalArgumentException
- if either input is a non-empty GeometryCollection- See Also:
LineMerger
-
difference
public Geometry difference(Geometry other)
Computes aGeometry
representing the closure of the point-set of the points contained in thisGeometry
that are not contained in theother
Geometry.If the result is empty, it is an atomic geometry with the dimension of the left-hand input.
Non-empty
GeometryCollection
arguments are not supported.- Parameters:
other
- theGeometry
with which to compute the difference- Returns:
- a Geometry representing the point-set difference of this
Geometry
withother
- Throws:
TopologyException
- if a robustness error occursjava.lang.IllegalArgumentException
- if either input is a non-empty GeometryCollection
-
symDifference
public Geometry symDifference(Geometry other)
Computes aGeometry
representing the closure of the point-set which is the union of the points in thisGeometry
which are not contained in theother
Geometry, with the points in theother
Geometry not contained in thisGeometry
. If the result is empty, it is an atomic geometry with the dimension of the highest input dimension.Non-empty
GeometryCollection
arguments are not supported.- Parameters:
other
- theGeometry
with which to compute the symmetric difference- Returns:
- a Geometry representing the point-set symmetric difference of this
Geometry
withother
- Throws:
TopologyException
- if a robustness error occursjava.lang.IllegalArgumentException
- if either input is a non-empty GeometryCollection
-
union
public Geometry union()
Computes the union of all the elements of this geometry.This method supports
GeometryCollection
s (which the other overlay operations currently do not).The result obeys the following contract:
- Unioning a set of
LineString
s has the effect of fully noding and dissolving the linework. - Unioning a set of
Polygon
s always returns aPolygonal
geometry (unlikeunion(Geometry)
, which may return geometries of lower dimension if a topology collapse occurred).
- Returns:
- the union geometry
- Throws:
TopologyException
- if a robustness error occurs- See Also:
UnaryUnionOp
- Unioning a set of
-
equalsExact
public abstract boolean equalsExact(Geometry other, double tolerance)
Returns true if the twoGeometry
s are exactly equal, up to a specified distance tolerance. Two Geometries are exactly equal within a distance tolerance if and only if:- they have the same structure
- they have the same values for their vertices, within the given tolerance distance, in exactly the same order.
GeometryFactory
, theSRID
, or theuserData
fields.To properly test equality between different geometries, it is usually necessary to
normalize()
them first.- Parameters:
other
- theGeometry
with which to compare thisGeometry
tolerance
- distance at or below which twoCoordinate
s are considered equal- Returns:
true
if this and the otherGeometry
have identical structure and point values, up to the distance tolerance.- See Also:
equalsExact(Geometry)
,normalize()
,norm()
-
equalsExact
public boolean equalsExact(Geometry other)
Returns true if the twoGeometry
s are exactly equal. Two Geometries are exactly equal iff:- they have the same structure
- they have the same values for their vertices, in exactly the same order.
equalsTopo(Geometry)
, which is more useful in certain situations (such as using geometries as keys in collections).This method does not test the values of the
GeometryFactory
, theSRID
, or theuserData
fields.To properly test equality between different geometries, it is usually necessary to
normalize()
them first.- Parameters:
other
- theGeometry
with which to compare thisGeometry
- Returns:
true
if this and the otherGeometry
have identical structure and point values.- See Also:
equalsExact(Geometry, double)
,normalize()
,norm()
-
equalsNorm
public boolean equalsNorm(Geometry g)
Tests whether two geometries are exactly equal in their normalized forms. This is a convenience method which creates normalized versions of both geometries before computingequalsExact(Geometry)
.This method is relatively expensive to compute. For maximum performance, the client should instead perform normalization on the individual geometries at an appropriate point during processing.
- Parameters:
g
- a Geometry- Returns:
- true if the input geometries are exactly equal in their normalized form
-
apply
public abstract void apply(CoordinateFilter filter)
Performs an operation with or on thisGeometry
's coordinates. If this method modifies any coordinate values,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).- Parameters:
filter
- the filter to apply to thisGeometry
's coordinates
-
apply
public abstract void apply(CoordinateSequenceFilter filter)
Performs an operation on the coordinates in thisGeometry
'sCoordinateSequence
s. If the filter reports that a coordinate value has been changed,geometryChanged()
will be called automatically.- Parameters:
filter
- the filter to apply
-
apply
public abstract void apply(GeometryFilter filter)
Performs an operation with or on thisGeometry
and its subelementGeometry
s (if any). Only GeometryCollections and subclasses have subelement Geometry's.- Parameters:
filter
- the filter to apply to thisGeometry
(and its children, if it is aGeometryCollection
).
-
apply
public abstract void apply(GeometryComponentFilter filter)
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.- Parameters:
filter
- the filter to apply to thisGeometry
.
-
clone
public java.lang.Object clone()
Deprecated.Creates and returns a full copy of thisGeometry
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.- Returns:
- a clone of this instance
-
copy
public Geometry copy()
Creates a deep copy of thisGeometry
object. Coordinate sequences contained in it are copied. All instance fields are copied (i.e.envelope
, SRID and userData).NOTE: the userData object reference (if present) is copied, but the value itself is not copied. If a deep copy is required this must be performed by the caller.
- Returns:
- a deep copy of this geometry
-
normalize
public abstract void normalize()
Converts thisGeometry
to normal form (or canonical form ). Normal form is a unique representation forGeometry
s. It can be used to test whether twoGeometry
s 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.NOTE that this method mutates the value of this geometry in-place. If this is not safe and/or wanted, the geometry should be cloned prior to normalization.
-
norm
public Geometry norm()
Creates a new Geometry which is a normalized copy of this Geometry.- Returns:
- a normalized copy of this geometry.
- See Also:
normalize()
-
compareTo
public int compareTo(java.lang.Object o)
Returns whether thisGeometry
is greater than, equal to, or less than anotherGeometry
.If their classes are different, they are compared using the following ordering:
- Point (lowest)
- MultiPoint
- LineString
- LinearRing
- MultiLineString
- Polygon
- MultiPolygon
- GeometryCollection (highest)
Geometry
s have the same class, their first elements are compared. If those are the same, the second elements are compared, etc.- Specified by:
compareTo
in interfacejava.lang.Comparable
- Parameters:
o
- aGeometry
with which to compare thisGeometry
- Returns:
- a positive number, 0, or a negative number, depending on whether
this object is greater than, equal to, or less than
o
, as defined in "Normal Form For Geometry" in the JTS Technical Specifications
-
compareTo
public int compareTo(java.lang.Object o, CoordinateSequenceComparator comp)
Returns whether thisGeometry
is greater than, equal to, or less than anotherGeometry
, using the givenCoordinateSequenceComparator
.If their classes are different, they are compared using the following ordering:
- Point (lowest)
- MultiPoint
- LineString
- LinearRing
- MultiLineString
- Polygon
- MultiPolygon
- GeometryCollection (highest)
Geometry
s have the same class, their first elements are compared. If those are the same, the second elements are compared, etc.- Parameters:
o
- aGeometry
with which to compare thisGeometry
comp
- aCoordinateSequenceComparator
- Returns:
- a positive number, 0, or a negative number, depending on whether
this object is greater than, equal to, or less than
o
, as defined in "Normal Form For Geometry" in the JTS Technical Specifications
-
-