com.revolsys.jts.geom

Class IntersectionMatrix

java.lang.Object

com.revolsys.jts.geom.IntersectionMatrix

All Implemented Interfaces:

Cloneable

public class IntersectionMatrix
extends Object
implements Cloneable

Models a Dimensionally Extended Nine-Intersection Model (DE-9IM) matrix. DE-9IM matrices (such as "212FF1FF2") specify the topological relationship between two Geometrys. This class can also represent matrix patterns (such as "T*T******") which are used for matching instances of DE-9IM matrices. 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 to see if a matrix matches a given pattern string.

For a description of the DE-9IM and the spatial predicates derived from it, see the OGC 99-049 OpenGIS Simple Features Specification for SQL, as well as OGC 06-103r4 OpenGIS Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture (which provides some further details on certain predicate specifications).

The entries of the matrix are defined by the constants in the Dimension class. The indices of the matrix represent the topological locations that occur in a geometry (Interior, Boundary, Exterior). These are provided as constants in the Location class.

Version:

1.7

Field Summary

Fields

Modifier and Type	Field and Description
static int	BOUNDARY
static int	EXTERIOR
static int	INTERIOR

Constructor Summary

Constructors

Constructor and Description
IntersectionMatrix() Creates an IntersectionMatrix with FALSE dimension values.
IntersectionMatrix(IntersectionMatrix other) Creates an IntersectionMatrix with the same elements as other.
IntersectionMatrix(String elements) Creates an IntersectionMatrix with the given dimension symbols.

Method Summary

Methods

Modifier and Type	Method and 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 IntersectionMatrix is T*****FF*.
boolean	isCoveredBy() Returns true if this IntersectionMatrix is T*F**F*** or *TF**F*** or **FT*F*** or **F*TF***
boolean	isCovers() Returns true if this IntersectionMatrix is 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() Returns true if this IntersectionMatrix is FF*FF****.
boolean	isEquals(int dimensionOfGeometryA, int dimensionOfGeometryB) Tests whether the argument dimensions are equal and this IntersectionMatrix matches the pattern T*F**FFF*.
boolean	isIntersects() Returns true if isDisjoint returns false.
boolean	isOverlaps(int dimensionOfGeometryA, int dimensionOfGeometryB) Returns true if this IntersectionMatrix is T*T***T** (for two points or two surfaces) 1*T***T** (for two curves) .
boolean	isTouches(int dimensionOfGeometryA, int dimensionOfGeometryB) Returns true if this IntersectionMatrix is 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 IntersectionMatrix is T*F**F***.
static boolean	matches(int actualDimensionValue, char requiredDimensionSymbol) Tests if the dimension value satisfies the dimension symbol.
boolean	matches(String requiredDimensionSymbols) Returns whether the elements of this IntersectionMatrix satisfies the required dimension symbols.
static boolean	matches(String actualDimensionSymbols, 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 this IntersectionMatrixs elements.
void	set(Location row, Location column, int dimensionValue)
void	set(String dimensionSymbols) Changes the elements of this IntersectionMatrix to the dimension symbols in dimensionSymbols.
void	setAll(int dimensionValue) Changes the elements of this IntersectionMatrix to dimensionValue .
void	setAtLeast(int row, int column, int minimumDimensionValue) Changes the specified element to minimumDimensionValue if the element is less.
void	setAtLeast(String minimumDimensionSymbols) For each element in this IntersectionMatrix, 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 to minimumDimensionValue if the element is less.
void	setAtLeastIfValid(Location row, Location column, int minimumDimensionValue)
String	toString() Returns a nine-character String representation of this IntersectionMatrix .
IntersectionMatrix	transpose() Transposes this IntersectionMatrix.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EXTERIOR

public static final int EXTERIOR

BOUNDARY

public static final int BOUNDARY

INTERIOR

public static final int INTERIOR

Constructor Detail

IntersectionMatrix

public IntersectionMatrix()

Creates an IntersectionMatrix with FALSE dimension values.

IntersectionMatrix

public IntersectionMatrix(IntersectionMatrix other)

Creates an IntersectionMatrix with the same elements as other.

Parameters:

other - an IntersectionMatrix to copy

IntersectionMatrix

public IntersectionMatrix(String elements)

Creates an IntersectionMatrix with the given dimension symbols.

Parameters:

elements - a String of nine dimension symbols in row major order

Method Detail

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 the IntersectionMatrix . 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 the IntersectionMatrix . Possible values are {TRUE, FALSE, DONTCARE, 0, 1, 2}.

requiredDimensionSymbol - a character used in the string representation of an IntersectionMatrix. Possible values are {T, F, * , 0, 1, 2}.

Returns:

true if the dimension symbol matches the dimension value

matches

public static boolean matches(String actualDimensionSymbols,
              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

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

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 the Location class. The value returned is a constant from the Dimension class.

Parameters:

row - the row of this IntersectionMatrix, indicating the interior, boundary or exterior of the first Geometry

column - the column of this IntersectionMatrix, indicating the interior, boundary or exterior of the second Geometry

Returns:

the dimension value at the given matrix position.

isContains

public boolean isContains()

Tests whether this IntersectionMatrix is T*****FF*.

Returns:

true if the first Geometry contains the second

isCoveredBy

public boolean isCoveredBy()

Returns true if this IntersectionMatrix is T*F**F*** or *TF**F*** or **FT*F*** or **F*TF***

Returns:

true if the first Geometry is covered by the second

isCovers

public boolean isCovers()

Returns true if this IntersectionMatrix is T*****FF* or *T****FF* or ***T**FF* or ****T*FF*

Returns:

true if the first Geometry covers the second

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 is
  • 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)

For any other combination of dimensions this predicate returns 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 first Geometry

dimensionOfGeometryB - the dimension of the second Geometry

Returns:

true if the two Geometrys related by this IntersectionMatrix cross.

isDisjoint

public boolean isDisjoint()

Returns true if this IntersectionMatrix is FF*FF****.

Returns:

true if the two Geometrys related by this IntersectionMatrix are disjoint

isEquals

public boolean isEquals(int dimensionOfGeometryA,
               int dimensionOfGeometryB)

Tests whether the argument dimensions are equal and this IntersectionMatrix 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 first Geometry

dimensionOfGeometryB - the dimension of the second Geometry

Returns:

true if the two Geometrys related by this IntersectionMatrix are equal; the Geometrys must have the same dimension to be equal

isIntersects

public boolean isIntersects()

Returns true if isDisjoint returns false.

Returns:

true if the two Geometrys related by this IntersectionMatrix intersect

isOverlaps

public boolean isOverlaps(int dimensionOfGeometryA,
                 int dimensionOfGeometryB)

Returns true if this IntersectionMatrix is

• T*T***T** (for two points or two surfaces)
• 1*T***T** (for two curves)

.

Parameters:

dimensionOfGeometryA - the dimension of the first Geometry

dimensionOfGeometryB - the dimension of the second Geometry

Returns:

true if the two Geometrys related by this IntersectionMatrix overlap. For this function to return true, the Geometrys must be two points, two curves or two surfaces.

isTouches

public boolean isTouches(int dimensionOfGeometryA,
                int dimensionOfGeometryB)

Returns true if this IntersectionMatrix is FT*******, F**T***** or F***T****.

Parameters:

dimensionOfGeometryA - the dimension of the first Geometry

dimensionOfGeometryB - the dimension of the second Geometry

Returns:

true if the two Geometry s related by this IntersectionMatrix touch; Returns false if both Geometrys are points.

isWithin

public boolean isWithin()

Tests whether this IntersectionMatrix is T*F**F***.

Returns:

true if the first Geometry is within the second

matches

public boolean matches(String requiredDimensionSymbols)

Returns whether the elements of this IntersectionMatrix satisfies the required dimension symbols.

Parameters:

requiredDimensionSymbols - nine dimension symbols with which to compare the elements of this IntersectionMatrix. Possible values are {T, F, * , 0, 1, 2}.

Returns:

true if this IntersectionMatrix matches the required dimension symbols

set

public void set(int row,
       int column,
       int dimensionValue)

Changes the value of one of this IntersectionMatrixs elements.

Parameters:

row - the row of this IntersectionMatrix, indicating the interior, boundary or exterior of the first Geometry

column - the column of this IntersectionMatrix, indicating the interior, boundary or exterior of the second Geometry

dimensionValue - the new value of the element

set

public void set(Location row,
       Location column,
       int dimensionValue)

set

public void set(String dimensionSymbols)

Changes the elements of this IntersectionMatrix to the dimension symbols in dimensionSymbols.

Parameters:

dimensionSymbols - nine dimension symbols to which to set this IntersectionMatrix s elements. Possible values are {T, F, * , 0, 1, 2}

setAll

public void setAll(int dimensionValue)

Changes the elements of this IntersectionMatrix to dimensionValue .

Parameters:

dimensionValue - the dimension value to which to set this IntersectionMatrix s elements. Possible values {TRUE, FALSE, DONTCARE, 0, 1, 2} .

setAtLeast

public void setAtLeast(int row,
              int column,
              int minimumDimensionValue)

Changes the specified element to minimumDimensionValue if the element is less.

Parameters:

row - the row of this IntersectionMatrix , indicating the interior, boundary or exterior of the first Geometry

column - the column of this IntersectionMatrix , indicating the interior, boundary or exterior of the second Geometry

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(String minimumDimensionSymbols)

For each element in this IntersectionMatrix, 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 this IntersectionMatrix. 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 to minimumDimensionValue if the element is less. Does nothing if row <0 or column < 0.

Parameters:

row - the row of this IntersectionMatrix , indicating the interior, boundary or exterior of the first Geometry

column - the column of this IntersectionMatrix , indicating the interior, boundary or exterior of the second Geometry

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(Location row,
                     Location column,
                     int minimumDimensionValue)

toString

public String toString()

Returns a nine-character String representation of this IntersectionMatrix .

Overrides:

toString in class Object

Returns:

the nine dimension symbols of this IntersectionMatrix in row-major order.

transpose

public IntersectionMatrix transpose()

Transposes this IntersectionMatrix.

Returns:

this IntersectionMatrix as a convenience