Class IntersectionMatrix
- java.lang.Object
-
- org.locationtech.jts.geom.IntersectionMatrix
-
- All Implemented Interfaces:
java.lang.Cloneable
public class IntersectionMatrix extends java.lang.Object implements java.lang.Cloneable
Models a Dimensionally Extended Nine-Intersection Model (DE-9IM) matrix. DE-9IM matrix values (such as "212FF1FF2") specify the topological relationship between twoGeometry
s. This class can also represent matrix patterns (such as "T*T******") which are used for matching instances of DE-9IM matrices.DE-9IM matrices are 3x3 matrices with integer entries. The matrix indices {0,1,2} represent the topological locations that occur in a geometry (Interior, Boundary, Exterior). These are provided by the constants
Location.INTERIOR
,Location.BOUNDARY
, andLocation.EXTERIOR
.When used to specify the topological relationship between two geometries, the matrix entries represent the possible dimensions of each intersection:
Dimension.A
= 2,Dimension.L
= 1,Dimension.P
= 0 andDimension.FALSE
= -1. When used to represent a matrix pattern entries can have the additional valuesDimension.TRUE
{"T") andDimension.DONTCARE
("*").For a description of the DE-9IM and the spatial predicates derived from it, see the following references:
- OGC 99-049 OpenGIS Simple Features Specification for SQL , Section 2.1.13
- OGC 06-103r4 OpenGIS Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture , Section 6.1.15 (which provides some further details on certain predicate specifications).
- Wikipedia article on DE-9IM
Methods are provided to:
- set and query the elements of the matrix in a convenient fashion
- convert to and from the standard string representation (specified in SFS Section 2.1.13.2).
- test if a matrix matches a given pattern string.
- test if a matrix (possibly with geometry dimensions) matches a standard named spatial predicate
- Version:
- 1.7
-
-
Constructor Summary
Constructors Constructor Description IntersectionMatrix()
Creates anIntersectionMatrix
withFALSE
dimension values.IntersectionMatrix(java.lang.String elements)
Creates anIntersectionMatrix
with the given dimension symbols.IntersectionMatrix(IntersectionMatrix other)
Creates anIntersectionMatrix
with the same elements asother
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(IntersectionMatrix im)
Adds one matrix to another.int
get(int row, int column)
Returns the value of one of this matrix entries.boolean
isContains()
Tests whether this matrix matches [T*****FF*[.boolean
isCoveredBy()
Tests if this matrix matches[T*F**F***]
or[*TF**F***]
or[**FT*F***]
or[**F*TF***]
boolean
isCovers()
Tests if this matrix matches[T*****FF*]
or[*T****FF*]
or[***T**FF*]
or[****T*FF*]
boolean
isCrosses(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests whether this geometry crosses the specified geometry.boolean
isDisjoint()
Tests if this matrix matches[FF*FF****]
.boolean
isEquals(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests whether the argument dimensions are equal and this matrix matches the pattern [T*F**FFF*].boolean
isIntersects()
Tests ifisDisjoint
returns false.boolean
isOverlaps(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests if this matrix matches [T*T***T**] (for two points or two surfaces) [1*T***T**] (for two curves) .boolean
isTouches(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests if this matrix matches[FT*******]
,[F**T*****]
or[F***T****]
.static boolean
isTrue(int actualDimensionValue)
Tests if the dimension value matches TRUE (i.e.boolean
isWithin()
Tests whether this matrix matches[T*F**F***]
.static boolean
matches(int actualDimensionValue, char requiredDimensionSymbol)
Tests if the dimension value satisfies the dimension symbol.boolean
matches(java.lang.String pattern)
Tests whether this matrix matches the given matrix pattern.static boolean
matches(java.lang.String actualDimensionSymbols, java.lang.String requiredDimensionSymbols)
Tests if each of the actual dimension symbols in a matrix string satisfies the corresponding required dimension symbol in a pattern string.void
set(int row, int column, int dimensionValue)
Changes the value of one of thisIntersectionMatrix
s elements.void
set(java.lang.String dimensionSymbols)
Changes the elements of thisIntersectionMatrix
to the dimension symbols indimensionSymbols
.void
setAll(int dimensionValue)
Changes the elements of thisIntersectionMatrix
todimensionValue
.void
setAtLeast(int row, int column, int minimumDimensionValue)
Changes the specified element tominimumDimensionValue
if the element is less.void
setAtLeast(java.lang.String minimumDimensionSymbols)
For each element in thisIntersectionMatrix
, changes the element to the corresponding minimum dimension symbol if the element is less.void
setAtLeastIfValid(int row, int column, int minimumDimensionValue)
If row >= 0 and column >= 0, changes the specified element tominimumDimensionValue
if the element is less.java.lang.String
toString()
Returns a nine-characterString
representation of thisIntersectionMatrix
.IntersectionMatrix
transpose()
Transposes this IntersectionMatrix.
-
-
-
Constructor Detail
-
IntersectionMatrix
public IntersectionMatrix()
Creates anIntersectionMatrix
withFALSE
dimension values.
-
IntersectionMatrix
public IntersectionMatrix(java.lang.String elements)
Creates anIntersectionMatrix
with the given dimension symbols.- Parameters:
elements
- a String of nine dimension symbols in row major order
-
IntersectionMatrix
public IntersectionMatrix(IntersectionMatrix other)
Creates anIntersectionMatrix
with the same elements asother
.- Parameters:
other
- anIntersectionMatrix
to copy
-
-
Method Detail
-
add
public void add(IntersectionMatrix im)
Adds one matrix to another. Addition is defined by taking the maximum dimension value of each position in the summand matrices.- Parameters:
im
- the matrix to add
-
isTrue
public static boolean isTrue(int actualDimensionValue)
Tests if the dimension value matches TRUE (i.e. has value 0, 1, 2 or TRUE).- Parameters:
actualDimensionValue
- a number that can be stored in theIntersectionMatrix
. Possible values are{TRUE, FALSE, DONTCARE, 0, 1, 2}
.- Returns:
- true if the dimension value matches TRUE
-
matches
public static boolean matches(int actualDimensionValue, char requiredDimensionSymbol)
Tests if the dimension value satisfies the dimension symbol.- Parameters:
actualDimensionValue
- a number that can be stored in theIntersectionMatrix
. Possible values are{TRUE, FALSE, DONTCARE, 0, 1, 2}
.requiredDimensionSymbol
- a character used in the string representation of anIntersectionMatrix
. Possible values are{T, F, * , 0, 1, 2}
.- Returns:
- true if the dimension symbol matches the dimension value
-
matches
public static boolean matches(java.lang.String actualDimensionSymbols, java.lang.String requiredDimensionSymbols)
Tests if each of the actual dimension symbols in a matrix string satisfies the corresponding required dimension symbol in a pattern string.- Parameters:
actualDimensionSymbols
- nine dimension symbols to validate. Possible values are{T, F, * , 0, 1, 2}
.requiredDimensionSymbols
- nine dimension symbols to validate against. Possible values are{T, F, * , 0, 1, 2}
.- Returns:
- true if each of the required dimension symbols encompass the corresponding actual dimension symbol
-
set
public void set(int row, int column, int dimensionValue)
Changes the value of one of thisIntersectionMatrix
s elements.- Parameters:
row
- the row of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the firstGeometry
column
- the column of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the secondGeometry
dimensionValue
- the new value of the element
-
set
public void set(java.lang.String dimensionSymbols)
Changes the elements of thisIntersectionMatrix
to the dimension symbols indimensionSymbols
.- Parameters:
dimensionSymbols
- nine dimension symbols to which to set thisIntersectionMatrix
s elements. Possible values are{T, F, * , 0, 1, 2}
-
setAtLeast
public void setAtLeast(int row, int column, int minimumDimensionValue)
Changes the specified element tominimumDimensionValue
if the element is less.- Parameters:
row
- the row of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the firstGeometry
column
- the column of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the secondGeometry
minimumDimensionValue
- the dimension value with which to compare the element. The order of dimension values from least to greatest is{DONTCARE, TRUE, FALSE, 0, 1, 2}
.
-
setAtLeastIfValid
public void setAtLeastIfValid(int row, int column, int minimumDimensionValue)
If row >= 0 and column >= 0, changes the specified element tominimumDimensionValue
if the element is less. Does nothing if row <0 or column < 0.- Parameters:
row
- the row of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the firstGeometry
column
- the column of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the secondGeometry
minimumDimensionValue
- the dimension value with which to compare the element. The order of dimension values from least to greatest is{DONTCARE, TRUE, FALSE, 0, 1, 2}
.
-
setAtLeast
public void setAtLeast(java.lang.String minimumDimensionSymbols)
For each element in thisIntersectionMatrix
, changes the element to the corresponding minimum dimension symbol if the element is less.- Parameters:
minimumDimensionSymbols
- nine dimension symbols with which to compare the elements of thisIntersectionMatrix
. The order of dimension values from least to greatest is{DONTCARE, TRUE, FALSE, 0, 1, 2}
.
-
setAll
public void setAll(int dimensionValue)
Changes the elements of thisIntersectionMatrix
todimensionValue
.- Parameters:
dimensionValue
- the dimension value to which to set thisIntersectionMatrix
s elements. Possible values{TRUE, FALSE, DONTCARE, 0, 1, 2}
.
-
get
public int get(int row, int column)
Returns the value of one of this matrix entries. The value of the provided index is one of the values from theLocation
class. The value returned is a constant from theDimension
class.- Parameters:
row
- the row of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the firstGeometry
column
- the column of thisIntersectionMatrix
, indicating the interior, boundary or exterior of the secondGeometry
- Returns:
- the dimension value at the given matrix position.
-
isDisjoint
public boolean isDisjoint()
Tests if this matrix matches[FF*FF****]
.- Returns:
true
if the twoGeometry
s related by this matrix are disjoint
-
isIntersects
public boolean isIntersects()
Tests ifisDisjoint
returns false.- Returns:
true
if the twoGeometry
s related by this matrix intersect
-
isTouches
public boolean isTouches(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests if this matrix matches[FT*******]
,[F**T*****]
or[F***T****]
.- Parameters:
dimensionOfGeometryA
- the dimension of the firstGeometry
dimensionOfGeometryB
- the dimension of the secondGeometry
- Returns:
true
if the twoGeometry
s related by this matrix touch; Returns false if bothGeometry
s are points.
-
isCrosses
public boolean isCrosses(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests whether this geometry crosses the specified 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
[T*T******]
(for P/L, P/A, and L/A situations)[T*****T**]
(for L/P, L/A, 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. JTS extends the definition to apply to L/P, A/P and A/L situations as well. This makes the relation symmetric.
- Parameters:
dimensionOfGeometryA
- the dimension of the firstGeometry
dimensionOfGeometryB
- the dimension of the secondGeometry
- Returns:
true
if the twoGeometry
s related by this matrix cross.
-
isWithin
public boolean isWithin()
Tests whether this matrix matches[T*F**F***]
.- Returns:
true
if the firstGeometry
is within the second
-
isContains
public boolean isContains()
Tests whether this matrix matches [T*****FF*[.- Returns:
true
if the firstGeometry
contains the second
-
isCovers
public boolean isCovers()
Tests if this matrix matches[T*****FF*]
or[*T****FF*]
or[***T**FF*]
or[****T*FF*]
- Returns:
true
if the firstGeometry
covers the second
-
isCoveredBy
public boolean isCoveredBy()
Tests if this matrix matches[T*F**F***]
or[*TF**F***]
or[**FT*F***]
or[**F*TF***]
- Returns:
true
if the firstGeometry
is covered by the second
-
isEquals
public boolean isEquals(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests whether the argument dimensions are equal and this matrix matches the pattern [T*F**FFF*].Note: This pattern differs from the one stated in Simple feature access - Part 1: Common architecture. That document states the pattern as [TFFFTFFFT]. This would specify that two identical POINTs are not equal, which is not desirable behaviour. The pattern used here has been corrected to compute equality in this situation.
- Parameters:
dimensionOfGeometryA
- the dimension of the firstGeometry
dimensionOfGeometryB
- the dimension of the secondGeometry
- Returns:
true
if the twoGeometry
s related by this matrix are equal; theGeometry
s must have the same dimension to be equal
-
isOverlaps
public boolean isOverlaps(int dimensionOfGeometryA, int dimensionOfGeometryB)
Tests if this matrix matches- [T*T***T**] (for two points or two surfaces)
- [1*T***T**] (for two curves)
- Parameters:
dimensionOfGeometryA
- the dimension of the firstGeometry
dimensionOfGeometryB
- the dimension of the secondGeometry
- Returns:
true
if the twoGeometry
s related by this matrix overlap. For this function to returntrue
, theGeometry
s must be two points, two curves or two surfaces.
-
matches
public boolean matches(java.lang.String pattern)
Tests whether this matrix matches the given matrix pattern.- Parameters:
pattern
- A pattern containing nine dimension symbols with which to compare the entries of this matrix. Possible symbol values are{T, F, * , 0, 1, 2}
.- Returns:
true
if this matrix matches the pattern
-
transpose
public IntersectionMatrix transpose()
Transposes this IntersectionMatrix.- Returns:
- this
IntersectionMatrix
as a convenience
-
toString
public java.lang.String toString()
Returns a nine-characterString
representation of thisIntersectionMatrix
.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the nine dimension symbols of this
IntersectionMatrix
in row-major order.
-
-