Javadoc

modules/core/src/main/java/org/locationtech/jts/operation/relateng/IMPatternMatcher.java

@@ -20,15 +20,15 @@
  * A predicate that matches a DE-9IM pattern.
  * 
  * <h3>FUTURE WORK</h3>
- * Extend the DE-9IM pattern language to allow:
+ * Extend the expressiveness of the DE-9IM pattern language to allow:
  * <ul>
  * <li>Combining patterns via disjunction using "|".
  * <li>Limiting patterns via geometry dimension.  
  * A dimension limit specifies the allowable dimensions 
  * for both or individual geometries as [d] or [ab] or [ab;cd]
  * </ul>
  * 
- * @author mdavis
+ * @author Martin Davis
  *
  */
 class IMPatternMatcher extends IMPredicate

modules/core/src/main/java/org/locationtech/jts/operation/relateng/IMPredicate.java

@@ -17,6 +17,13 @@
 
 abstract class IMPredicate extends BasicPredicate {
 
+  public static boolean isDimsCompatibleWithCovers(int dim0, int dim1) {
+    //- allow Points coveredBy zero-length Lines
+    if (dim0 == Dimension.P && dim1 == Dimension.L)
+      return true;
+    return dim0 >= dim1;
+  }
+
   static final int DIM_UNKNOWN = Dimension.DONTCARE;
 
   protected int dimA;

modules/core/src/main/java/org/locationtech/jts/operation/relateng/IntersectionMatrixPattern.java

@@ -30,7 +30,7 @@
  * <li><tt>*</tt> - any topological interaction is allowed, including none
  * </ul>
  * 
- * @author mdavis
+ * @author Martin Davis
  *
  */
 public class IntersectionMatrixPattern {
@@ -54,4 +54,10 @@ public class IntersectionMatrixPattern {
    */
   public static final String INTERIOR_INTERSECTS = "T********";
 
+  /**
+   * Cannot be instantiated.
+   */
+  private IntersectionMatrixPattern() {
+
+  }
 }

modules/core/src/main/java/org/locationtech/jts/operation/relateng/RelateNG.java

@@ -48,11 +48,15 @@
  *     so invalid geometry topology does cause failures)
  * <li>{@link GeometryCollection} inputs containing mixed types and overlapping polygons
  *     are supported, using <i>union semantics</i>.
- * <li>Support for {@link BoundaryNodeRule}s
+ * <li>Support for {@link BoundaryNodeRule}s.
  * </ol>
  * 
  * See {@link IntersectionMatrixPattern} for a description of DE-9IM patterns.
  * 
+ * If not specified, the standard {@link BoundaryNodeRule#MOD2_BOUNDARY_RULE} is used.
+ * 
+ * RelateNG operates in 2D only; it ignores any Z ordinates.
+ * 
  * This implementation replaces {@link RelateOp} and {@link PreparedGeometry}.
  * 
  * <h3>FUTURE WORK</h3>
@@ -69,26 +73,74 @@
 public class RelateNG 
 {
 
+  /**
+   * Tests whether the topological relationship between two geometries
+   * satisfies a topological predicate.
+   * 
+   * @param a the A input geometry
+   * @param b the A input geometry
+   * @param pred the topological predicate
+   * @return true if the topological relationship is satisfied
+   */
   public static boolean relate(Geometry a, Geometry b, TopologyPredicate pred) {
     RelateNG rng = new RelateNG(a, false);
     return rng.evaluate(b, pred);
   } 
 
+  /**
+   * Tests whether the topological relationship between two geometries
+   * satisfies a topological predicate,
+   * using a given {@link BoundaryNodeRule}.
+   * 
+   * @param a the A input geometry
+   * @param b the A input geometry
+   * @param pred the topological predicate
+   * @param bnRule the Boundary Node Rule to use
+   * @return true if the topological relationship is satisfied
+   */
   public static boolean relate(Geometry a, Geometry b, TopologyPredicate pred, BoundaryNodeRule bnRule) {
     RelateNG rng = new RelateNG(a, false, bnRule);
     return rng.evaluate(b, pred);
   } 
 
+  /**
+   * Tests whether the topological relationship to a geometry 
+   * matches a DE-9IM matrix pattern.
+   * 
+   * @param a the A input geometry
+   * @param b the A input geometry
+   * @param imPattern the DE-9IM pattern to match
+   * @return true if the geometries relationship matches the DE-9IM pattern
+   * 
+   * @see IntersectionMatrixPattern
+   */
   public static boolean relate(Geometry a, Geometry b, String imPattern) {
     RelateNG rng = new RelateNG(a, false);
     return rng.evaluate(b, imPattern); 
   }
 
+  /**
+   * Computes the DE-9IM matrix 
+   * for the topological relationship between two geometries.
+   * 
+   * @param a the A input geometry
+   * @param b the A input geometry
+   * @return the DE-9IM matrix for the topological relationship
+   */
   public static IntersectionMatrix relate(Geometry a, Geometry b) {
     RelateNG rng = new RelateNG(a, false);
     return rng.evaluate(b);
   } 
 
+  /**
+   * Computes the DE-9IM matrix 
+   * for the topological relationship between two geometries.
+   * 
+   * @param a the A input geometry
+   * @param b the A input geometry
+   * @param bnRule the Boundary Node Rule to use
+   * @return the DE-9IM matrix for the relationship
+   */
   public static IntersectionMatrix relate(Geometry a, Geometry b, BoundaryNodeRule bnRule) {
     RelateNG rng = new RelateNG(a, false, bnRule);
     return rng.evaluate(b); 
@@ -98,7 +150,7 @@ public static IntersectionMatrix relate(Geometry a, Geometry b, BoundaryNodeRule
    * Creates a prepared RelateNG instance to optimize the
    * evaluation of relationships against a single geometry.
    * 
-   * @param a the input A
+   * @param a the A input geometry
    * @return a prepared instance
    */
   public static RelateNG prepare(Geometry a) {
@@ -107,9 +159,10 @@ public static RelateNG prepare(Geometry a) {
 
   /**
    * Creates a prepared RelateNG instance to optimize the
-   * computation of predicates against a single geometry.
+   * computation of predicates against a single geometry,
+   * using a given {@link BoundaryNodeRule}.
    * 
-   * @param a the input A
+   * @param a the A input geometry
    * @param bnRule the required BoundaryNodeRule
    * @return a prepared instance
    */
@@ -131,9 +184,9 @@ private RelateNG(Geometry inputA, boolean isPrepared, BoundaryNodeRule bnRule) {
   }
 
   /**
-   * Computes the DE-9IM matrix for the relationship to a geometry.
+   * Computes the DE-9IM matrix for the topological relationship to a geometry.
    * 
-   * @param b the geometry to test against
+   * @param b the B geometry to test against
    * @return the DE-9IM matrix
    */
   public IntersectionMatrix evaluate(Geometry b) {
@@ -146,9 +199,9 @@ public IntersectionMatrix evaluate(Geometry b) {
    * Tests whether the topological relationship to a geometry 
    * matches a DE-9IM matrix pattern.
    * 
-   * @param b the geometry to test against
+   * @param b the B geometry to test against
    * @param imPattern the DE-9IM pattern to match
-   * @return true if the geometries relationship matches the DE-9IM pattern
+   * @return true if the geometries' topological relationship matches the DE-9IM pattern
    * 
    * @see IntersectionMatrixPattern
    */
@@ -160,7 +213,7 @@ public boolean evaluate(Geometry b, String imPattern) {
    * Tests whether the topological relationship to a geometry
    * satisfies a topology predicate.
    * 
-   * @param b the geometry to test against
+   * @param b the B geometry to test against
    * @param predicate the topological predicate
    * @return true if the predicate is satisfied
    */