Javadoc, refactoring

dr-jts · May 13, 2024 · 6135336 · 6135336
1 parent 01ebd17
commit 6135336
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 6 deletions.
diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/BasicPredicate.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/BasicPredicate.java
@@ -14,6 +14,15 @@
 import org.locationtech.jts.geom.Envelope;
 import org.locationtech.jts.geom.Location;
 
+/**
+ * The base class for relate topological predicates
+ * with a boolean value.
+ * Implements tri-state logic for the predicate value,
+ * to detect when the final value has been determined.
+ * 
+ * @author Martin Davis
+ *
+ */
 abstract class BasicPredicate implements TopologyPredicate {
 
   private static final int UNKNOWN = -1;
@@ -47,9 +56,11 @@ public static boolean isIntersection(int locA, int locB) {
 
   private int value = UNKNOWN;
 
+  /*
   public boolean isSelfNodingRequired() {
     return false;
   }
+  */
 
   @Override
   public boolean isKnown() {

diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/IMPredicate.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/IMPredicate.java
@@ -15,6 +15,13 @@
 import org.locationtech.jts.geom.IntersectionMatrix;
 import org.locationtech.jts.geom.Location;
 
+/**
+ * A base class for predicates which are
+ * determined using entries in a {@link IntersectionMatrix}.
+ * 
+ * @author Martin Davis
+ *
+ */
 abstract class IMPredicate extends BasicPredicate {
 
   public static boolean isDimsCompatibleWithCovers(int dim0, int dim1) {
@@ -42,10 +49,6 @@ public void init(int dimA, int dimB) {
     this.dimB = dimB;
   }
 
-  public boolean isSelfNodingRequired() {
-    return true;
-  }
-
   @Override
   public void updateDimension(int locA, int locB, int dimension) {
     //-- only record an increased dimension value

diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/NodeSection.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/NodeSection.java
@@ -17,7 +17,6 @@
 import org.locationtech.jts.geom.Coordinate;
 import org.locationtech.jts.geom.Dimension;
 import org.locationtech.jts.geom.Geometry;
-import org.locationtech.jts.geom.Polygon;
 import org.locationtech.jts.io.WKTWriter;
 
 /**

diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/RelatePredicate.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/RelatePredicate.java
@@ -51,6 +51,12 @@ public static TopologyPredicate intersects() {
 
       public String name() { return "intersects"; }
 
+      @Override
+      public boolean isSelfNodingRequired() {
+        //-- self-noding is not required to check for a simple interaction
+        return false;
+      }
+
       @Override
       public void init(Envelope envA, Envelope envB) {
         require(envA.intersects(envB));
@@ -91,6 +97,12 @@ public static TopologyPredicate disjoint() {
 
       public String name() { return "disjoint"; }
 
+      @Override
+      public boolean isSelfNodingRequired() {
+        //-- self-noding is not required to check for a simple interaction
+        return false;
+      }
+
       @Override
       public void init(Envelope envA, Envelope envB) {
         setValueIf(true, envA.disjoint(envB));

diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/RelateSegmentString.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/RelateSegmentString.java
@@ -17,6 +17,12 @@
 import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.noding.BasicSegmentString;
 
+/**
+ * Models a linear edge of a {@link RelateGeometry}.
+ * 
+ * @author mdavis
+ *
+ */
 class RelateSegmentString extends BasicSegmentString {
 
   public static RelateSegmentString createLine(Coordinate[] pts, boolean isA, int elementId, RelateGeometry parent) {

diff --git a/modules/core/src/main/java/org/locationtech/jts/operation/relateng/TopologyPredicate.java b/modules/core/src/main/java/org/locationtech/jts/operation/relateng/TopologyPredicate.java
@@ -33,7 +33,15 @@ public interface TopologyPredicate {
    * Tests whether this predicate requires self-noding for
    * geometries which contain crossing edges
    * (for example, {@link LineString}s, or {@line GeometryCollection}s
-   * containing lines or polygons).
+   * containing lines or polygons which may self-intersect).
+   * Self-noding ensures that intersections are computed consistently
+   * in cases which contain self-crossings and mutual crossings.
+   * <p>
+   * Most predicates require this, but it can
+   * be avoided for simple intersection detection
+   * (such as in {@link RelatePredicate#intersects()}
+   * and {@link RelatePredicate#disjoint()}.
+   * Avoiding self-noding improves performance for polygonal inputs.
    * 
    * @return true if self-noding is required.
    */