Class 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 two Geometrys. 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, and Location.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 and Dimension.FALSE = -1. When used to represent a matrix pattern entries can have the additional values Dimension.TRUE {"T") and Dimension.DONTCARE ("*").

    For a description of the DE-9IM and the spatial predicates derived from it, see the following references:

    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 an IntersectionMatrix with FALSE dimension values.
      IntersectionMatrix​(java.lang.String elements)
      Creates an IntersectionMatrix with the given dimension symbols.
      IntersectionMatrix​(IntersectionMatrix other)
      Creates an IntersectionMatrix with the same elements as other.
    • 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 if isDisjoint 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 this IntersectionMatrixs elements.
      void set​(java.lang.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​(java.lang.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.
      java.lang.String toString()
      Returns a nine-character String representation of this IntersectionMatrix .
      IntersectionMatrix transpose()
      Transposes this IntersectionMatrix.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • IntersectionMatrix

        public IntersectionMatrix()
        Creates an IntersectionMatrix with FALSE dimension values.
      • IntersectionMatrix

        public IntersectionMatrix​(java.lang.String elements)
        Creates an IntersectionMatrix with the given dimension symbols.
        Parameters:
        elements - a String of nine dimension symbols in row major order
      • IntersectionMatrix

        public IntersectionMatrix​(IntersectionMatrix other)
        Creates an IntersectionMatrix with the same elements as other.
        Parameters:
        other - an IntersectionMatrix 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 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​(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 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​(java.lang.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}
      • 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}.
      • 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}.
      • setAtLeast

        public void setAtLeast​(java.lang.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} .
      • 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} .
      • 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.
      • isDisjoint

        public boolean isDisjoint()
        Tests if this matrix matches [FF*FF****].
        Returns:
        true if the two Geometrys related by this matrix are disjoint
      • isIntersects

        public boolean isIntersects()
        Tests if isDisjoint returns false.
        Returns:
        true if the two Geometrys 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 first Geometry
        dimensionOfGeometryB - the dimension of the second Geometry
        Returns:
        true if the two Geometry s related by this matrix touch; Returns false if both Geometrys 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)
        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 matrix cross.
      • isWithin

        public boolean isWithin()
        Tests whether this matrix matches [T*F**F***].
        Returns:
        true if the first Geometry is within the second
      • isContains

        public boolean isContains()
        Tests whether this matrix matches [T*****FF*[.
        Returns:
        true if the first Geometry 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 first Geometry 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 first Geometry 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 first Geometry
        dimensionOfGeometryB - the dimension of the second Geometry
        Returns:
        true if the two Geometrys related by this matrix are equal; the Geometrys 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 first Geometry
        dimensionOfGeometryB - the dimension of the second Geometry
        Returns:
        true if the two Geometrys related by this matrix overlap. For this function to return true, the Geometrys 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-character String representation of this IntersectionMatrix .
        Overrides:
        toString in class java.lang.Object
        Returns:
        the nine dimension symbols of this IntersectionMatrix in row-major order.