[curved] Add factory, Linearizable, copy() preservation, hook tests, README

Addresses code-review feedback on PR locationtech#1194. All additions are still
purely additive at the jts-core level.

jts-curved
- New CurvedGeometryFactory extends GeometryFactory with creation
  methods for the eight new types (createCircularString, createTriangle,
  etc.). Pair with CurvedWKTReader for the standard read-construct-emit
  flow.
- New Linearizable interface (Geometry toLinear(double tolerance)) for
  converting curved geometries to non-curved approximations. Phase 1
  returns a parent-type geometry built from the same control points; a
  future phase will swap in real arc densification.
- Implement Linearizable on the seven curve / curve-bounded /
  triangulated-surface types (Triangle, PolyhedralSurface, Tin omit
  Linearizable but get correct copyInternal too).
- Override copyInternal() on all eight types so copy() returns the
  correct subclass instead of degrading to the parent.
- Module README: usage example, phase-1 limitations (with explicit
  callout for the CurvePolygon / MultiSurface inner-member round-trip
  degradation), and discovery rationale (explicit instantiation rather
  than ServiceLoader).

WKTMultiSurfaceTest
- testWKTRoundTripXY no longer compares the original CurvePolygon-
  bearing geometry directly to the round-tripped Polygon-bearing one.
  Polygon.isEquivalentClass is strict (LineString's is lenient, which
  is why MultiCurve passes the analogous test); a direct checkEqual
  would fail. Switched to (a) WKT-stability (write -> read -> write
  yields the same WKT) and (b) coordinate-equivalence via toLinear().
  Comment documents the seam.

jts-core
- Add WKTReaderExtensionHookTest with 6 tests that exercise both the
  reader and writer extension hooks via dummy in-test subclasses, with
  no dependency on jts-curved. Confirms the seam is wired and that the
  promoted protected helpers are accessible across packages.
- Class-level Javadoc on WKTReader now documents the extension contract
  and lists the protected helpers available to subclasses. Same for
  WKTWriter (intercept point, parameterised keyword emission, and the
  exposed text-emission helpers).
- Per-field Javadoc on the geometryFactory and csFactory protected
  fields explaining their role in extension subclasses.

Net change: jts-core grows by 6 tests (2288 total, was 2282). jts-curved
holds 54 tests, all green. Combined: 2342 tests, BUILD SUCCESS.

Discovered seam (recorded in MultiSurface test comment + README):
Polygon.isEquivalentClass is strict, so a Polygon and a coord-identical
CurvePolygon are not equalsExact even though LineString solves the
analogous problem leniently. Phase 2 (member-tagged emission in
CurvedWKTWriter) will close this gap; phase 1 documents and works
around it.

Author: grootstebozewolf

modules/core/src/main/java/org/locationtech/jts/io/WKTReader.java

@@ -80,9 +80,34 @@
  * <li>The reader uses <tt>Double.parseDouble</tt> to perform the conversion of ASCII
  * numbers to floating point.  This means it supports the Java
  * syntax for floating point literals (including scientific notation).
- * <li><tt>NaN</tt>, <tt>Inf</tt> and <tt>-Inf</tt> ordinate symbols are supported (case-insensitive), 
+ * <li><tt>NaN</tt>, <tt>Inf</tt> and <tt>-Inf</tt> ordinate symbols are supported (case-insensitive),
  * which convert to the corresponding IEE-754 value
  * </ul>
+ * <h3>Extension</h3>
+ * <p>This class is designed to be subclassed to support OGC SFA / ISO
+ * 19125-2 extended geometry types (such as {@code CIRCULARSTRING},
+ * {@code COMPOUNDCURVE}, {@code CURVEPOLYGON}, {@code TRIANGLE},
+ * {@code POLYHEDRALSURFACE}, {@code TIN}). Subclasses should override
+ * {@link #readOtherGeometryText} to recognise additional type keywords,
+ * and may compose their implementation from the protected helpers
+ * exposed by this class:
+ * <ul>
+ * <li>tokenizer helpers: {@link #getNextEmptyOrOpener},
+ *     {@link #getNextCloserOrComma}, {@link #getNextWord},
+ *     {@link #lookAheadWord};
+ * <li>coordinate helpers: {@link #getCoordinate},
+ *     {@link #getCoordinateSequence},
+ *     {@link #createCoordinateSequenceEmpty};
+ * <li>nested-geometry helpers: {@link #readLineStringText},
+ *     {@link #readLinearRingText}, {@link #readPolygonText},
+ *     {@link #readMultiPolygonText}, and the 3-arg form of
+ *     {@link #readGeometryTaggedText} for dispatching on a known type;
+ * <li>error helper: {@link #parseErrorWithLine};
+ * <li>fields: {@link #geometryFactory}, {@link #csFactory}.
+ * </ul>
+ * The default implementation of {@link #readOtherGeometryText} throws
+ * a {@link ParseException}, preserving the historical behaviour for
+ * direct (non-extending) callers.
  * <h3>Syntax</h3>
  * The following syntax specification describes the version of Well-Known Text
  * supported by JTS.
@@ -178,7 +203,17 @@ public class WKTReader
   private static final String INF_SYMBOL = "Inf";
   private static final String NEG_INF_SYMBOL = "-Inf";
 
+  /**
+   * The factory used to construct the {@link Geometry} return values.
+   * Exposed as {@code protected} so that extension subclasses (see
+   * {@link #readOtherGeometryText}) can construct geometries with the
+   * same factory the reader is parameterised with.
+   */
   protected GeometryFactory geometryFactory;
+  /**
+   * The {@link CoordinateSequenceFactory} of {@link #geometryFactory}.
+   * Exposed as {@code protected} for the same reason.
+   */
   protected CoordinateSequenceFactory csFactory;
   private static CoordinateSequenceFactory csFactoryXYZM = CoordinateArraySequenceFactory.instance();
   private PrecisionModel precisionModel;

modules/core/src/main/java/org/locationtech/jts/io/WKTWriter.java

@@ -46,9 +46,24 @@
  * <p>
  * The SFS WKT spec does not define a special tag for {@link LinearRing}s.
  * Under the spec, rings are output as <code>LINESTRING</code>s.
- * In order to allow precisely specifying constructed geometries, 
- * JTS also supports a non-standard <code>LINEARRING</code> tag which is used 
+ * In order to allow precisely specifying constructed geometries,
+ * JTS also supports a non-standard <code>LINEARRING</code> tag which is used
  * to output LinearRings.
+ * <p>
+ * <b>Extension:</b> this class is designed to be subclassed to support
+ * OGC SFA / ISO 19125-2 extended geometry types. The keyword for each
+ * tagged-text emission is now read from
+ * {@code geometry.getGeometryType().toUpperCase()}, so {@link Geometry}
+ * subclasses with structurally compatible bodies emit their own
+ * keyword without any new dispatch branches. For types that need
+ * different bodies (e.g. preserving member structure in
+ * {@code CompoundCurve}), subclasses should override
+ * {@link #appendOtherGeometryTaggedText}, which is invoked early in
+ * the dispatch ladder. Helpers for composing emission output
+ * ({@link #indent}, {@link #appendOrdinateText},
+ * {@link #appendSequenceText}, {@link #appendPolygonText},
+ * {@link #appendMultiLineStringText}, {@link #appendMultiPolygonText})
+ * are exposed as {@code protected}.
  *
  * @version 1.7
  * @see WKTReader

modules/core/src/test/java/org/locationtech/jts/io/WKTReaderExtensionHookTest.java

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2026 grootstebozewolf
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * and Eclipse Distribution License v. 1.0 which accompanies this distribution.
+ * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v20.html
+ * and the Eclipse Distribution License is available at
+ *
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ */
+package org.locationtech.jts.io;
+
+import java.io.IOException;
+import java.io.StreamTokenizer;
+import java.io.Writer;
+import java.util.EnumSet;
+
+import org.locationtech.jts.geom.Geometry;
+
+import junit.framework.Test;
+import junit.framework.TestSuite;
+import junit.textui.TestRunner;
+import test.jts.GeometryTestCase;
+
+/**
+ * Verifies the {@link WKTReader#readOtherGeometryText} and
+ * {@link WKTWriter#appendOtherGeometryTaggedText} extension hooks added
+ * for SFA / ISO 19125-2 extended geometry support, without taking any
+ * dependency on jts-curved. A dummy subclass of {@link WKTReader}
+ * recognises a made-up keyword and a dummy subclass of
+ * {@link WKTWriter} emits it; this confirms the seam is wired and the
+ * promoted helpers are accessible across packages.
+ */
+public class WKTReaderExtensionHookTest extends GeometryTestCase {
+
+  public static void main(String args[]) {
+    TestRunner.run(suite());
+  }
+
+  public static Test suite() { return new TestSuite(WKTReaderExtensionHookTest.class); }
+
+  public WKTReaderExtensionHookTest(String name) { super(name); }
+
+  /** A reader that recognises a made-up {@code DUMMYTYPE} keyword and
+   *  returns an empty Point. Exercises the protected helpers. */
+  private static class DummyReader extends WKTReader {
+    boolean hookCalled = false;
+
+    @Override
+    protected Geometry readOtherGeometryText(StreamTokenizer t, String type, EnumSet<Ordinate> ord)
+        throws IOException, ParseException {
+      if ("DUMMYTYPE".equals(type)) {
+        hookCalled = true;
+        // Use the promoted-protected helpers from core.
+        String tok = getNextEmptyOrOpener(t);
+        if (!WKTConstants.EMPTY.equals(tok)) {
+          // burn through the body to a balanced ')'
+          int depth = 1;
+          while (depth > 0) {
+            int c = t.nextToken();
+            if (c == '(') depth++;
+            else if (c == ')') depth--;
+            else if (c == StreamTokenizer.TT_EOF)
+              throw parseErrorWithLine(t, "Unexpected EOF in DUMMYTYPE body");
+          }
+        }
+        return geometryFactory.createPoint();
+      }
+      return super.readOtherGeometryText(t, type, ord);
+    }
+  }
+
+  /** A writer that intercepts a dummy custom geometry type. */
+  private static class DummyWriter extends WKTWriter {
+    boolean hookCalled = false;
+
+    @Override
+    protected boolean appendOtherGeometryTaggedText(Geometry geometry, EnumSet<Ordinate> outputOrdinates,
+        boolean useFormatting, int level, Writer writer, OrdinateFormat formatter) throws IOException {
+      // Pretend we have a custom type: any Geometry whose toString starts with "POINT"
+      // (i.e. all Points) should be emitted with our marker. This confirms the hook
+      // runs before the instanceof ladder.
+      if ("Point".equals(geometry.getGeometryType()) && !geometry.isEmpty()) {
+        writer.write("DUMMYTYPE EMPTY");
+        return true;
+      }
+      return false;
+    }
+  }
+
+  public void testReaderHookIsInvokedForUnknownType() throws Exception {
+    DummyReader reader = new DummyReader();
+    Geometry g = reader.read("DUMMYTYPE EMPTY");
+    assertTrue("readOtherGeometryText should have been called", reader.hookCalled);
+    assertEquals("Point", g.getGeometryType());
+  }
+
+  public void testReaderHookHandlesParenthesisedBody() throws Exception {
+    DummyReader reader = new DummyReader();
+    Geometry g = reader.read("DUMMYTYPE (1 2, 3 4)");
+    assertTrue(reader.hookCalled);
+    assertNotNull(g);
+  }
+
+  public void testReaderHookFallsThroughToCoreError() {
+    try {
+      new DummyReader().read("UNKNOWNTYPE EMPTY");
+      fail("Expected ParseException for unknown type");
+    } catch (Throwable e) {
+      assertTrue("Expected ParseException, got: " + e, e instanceof ParseException);
+    }
+  }
+
+  public void testCoreReaderStillThrowsForUnknownType() {
+    try {
+      new WKTReader().read("DUMMYTYPE EMPTY");
+      fail("Expected ParseException from default WKTReader");
+    } catch (Throwable e) {
+      assertTrue("Expected ParseException, got: " + e, e instanceof ParseException);
+    }
+  }
+
+  public void testWriterHookFiresBeforeInstanceofLadder() throws Exception {
+    DummyWriter writer = new DummyWriter();
+    Geometry pt = read("POINT (1 2)");
+    String wkt = writer.write(pt);
+    assertEquals("Hook should have intercepted before the Point branch",
+        "DUMMYTYPE EMPTY", wkt);
+  }
+
+  public void testWriterDefaultHookReturnsFalse() throws Exception {
+    // The default WKTWriter must keep writing "POINT (...)" — confirms the hook
+    // returning false does not skip the standard path.
+    Geometry pt = read("POINT (1 2)");
+    String wkt = new WKTWriter().write(pt);
+    assertTrue("Default writer should emit POINT, got: " + wkt, wkt.toUpperCase().startsWith("POINT"));
+  }
+}

modules/curved/README.md

@@ -0,0 +1,113 @@
+# jts-curved
+
+Opt-in JTS module providing the OGC Simple Features Access (SFA) /
+ISO 19125-2 extended geometry types and a curve-aware WKT reader/writer.
+
+## What it adds
+
+| Geometry type      | Java class                                              | Extends                         |
+|--------------------|---------------------------------------------------------|---------------------------------|
+| `CircularString`   | `org.locationtech.jts.geom.curved.CircularString`       | `LineString`                    |
+| `CompoundCurve`    | `org.locationtech.jts.geom.curved.CompoundCurve`        | `LineString`                    |
+| `CurvePolygon`     | `org.locationtech.jts.geom.curved.CurvePolygon`         | `Polygon`                       |
+| `MultiCurve`       | `org.locationtech.jts.geom.curved.MultiCurve`           | `MultiLineString`               |
+| `MultiSurface`     | `org.locationtech.jts.geom.curved.MultiSurface`         | `MultiPolygon`                  |
+| `Triangle`         | `org.locationtech.jts.geom.curved.Triangle`             | `Polygon`                       |
+| `PolyhedralSurface`| `org.locationtech.jts.geom.curved.PolyhedralSurface`    | `MultiPolygon`                  |
+| `Tin`              | `org.locationtech.jts.geom.curved.Tin`                  | `PolyhedralSurface`             |
+
+Plus:
+
+- `CurvedGeometryFactory` — extends `GeometryFactory`, adds `createCircularString(...)`, `createTriangle(...)`, etc.
+- `CurvedWKTReader` — extends `WKTReader`, recognises the eight new keywords via the core `readOtherGeometryText` extension hook.
+- `CurvedWKTWriter` — extends `WKTWriter`. Phase-1 marker: the core writer already emits subclass keywords via `Geometry.getGeometryType().toUpperCase()`.
+- `Linearizable` interface — `Geometry toLinear(double tolerance)` for converting a curved geometry into a non-curved approximation.
+
+The naming collision with the long-standing static-utility class
+`org.locationtech.jts.geom.Triangle` (centroid, circumradius, etc.) is
+resolved by package separation: that utility is preserved unchanged in
+core; the geometry type lives in `org.locationtech.jts.geom.curved`.
+
+## Usage
+
+```java
+import org.locationtech.jts.geom.Geometry;
+import org.locationtech.jts.geom.curved.CurvedGeometryFactory;
+import org.locationtech.jts.geom.curved.Linearizable;
+import org.locationtech.jts.io.curved.CurvedWKTReader;
+import org.locationtech.jts.io.curved.CurvedWKTWriter;
+
+CurvedGeometryFactory factory = new CurvedGeometryFactory();
+CurvedWKTReader reader = new CurvedWKTReader(factory);
+
+Geometry g = reader.read("CIRCULARSTRING(1 5, 6 2, 7 3)");
+System.out.println(g.getGeometryType());          // CircularString
+
+String wkt = new CurvedWKTWriter().write(g);
+// wkt: CIRCULARSTRING (1 5, 6 2, 7 3)
+
+// Linearise to a non-curved approximation
+Geometry linear = ((Linearizable) g).toLinear(0.0);
+System.out.println(linear.getGeometryType());     // LineString
+```
+
+The standard `WKTReader` continues to throw `ParseException("Unknown
+geometry type: CIRCULARSTRING")` for the new keywords; a caller has to
+opt in by instantiating `CurvedWKTReader`.
+
+## Maven coordinates
+
+```xml
+<dependency>
+  <groupId>org.locationtech.jts</groupId>
+  <artifactId>jts-curved</artifactId>
+  <version>1.20.1-SNAPSHOT</version>
+</dependency>
+```
+
+## Phase 1 limitations
+
+The current implementation is intentionally minimal so the module can
+land alongside the core extension hooks without dragging in a years-long
+algorithm program. Known limitations:
+
+- **Spatial operations fall through to the parent type.** A
+  `CircularString.intersects(g)` is computed against the polyline
+  formed by the control points, not against the actual arcs. Use
+  `Linearizable.toLinear(tolerance)` to make this explicit.
+- **`CompoundCurve` member structure is collapsed** to a flat
+  concatenation of control points on read. The writer emits this flat
+  form too, and the reader accepts both the flat form and the OGC
+  member-structured form on input.
+- **`CurvePolygon` / `MultiSurface` round-trip degrades inner curve
+  members.** Re-reading a written `MULTISURFACE(CURVEPOLYGON(...))`
+  yields `MultiSurface[Polygon]` rather than
+  `MultiSurface[CurvePolygon]`, because the writer does not yet emit
+  inner-member tags. Tests use `Linearizable.toLinear(...)` for
+  structural-fidelity comparison.
+- **Validation is best-effort.** Structural rules (Triangle 4-point
+  ring, CircularString odd point count, CompoundCurve member
+  connectivity, Tin triangle-only patches) are not enforced.
+- **No WKB support.** Defer to a follow-up phase for the SFA-MM type
+  codes (8/9/10/11/12/15/16/17 with Z/M/ZM variants).
+- **`copy()` preserves the subclass** for top-level types via
+  overridden `copyInternal()`, but `Polygon.isEquivalentClass` is
+  strict — a `Polygon` is *not* `equalsExact` to a `CurvePolygon` with
+  identical coordinates. (The same comparison is lenient for
+  `LineString` subclasses.) Tests work around this where it matters.
+- **No `JTSTestBuilder` UI integration yet.**
+
+## Discovery
+
+This module deliberately does **not** register itself via
+`ServiceLoader` or any other automatic-discovery mechanism. Callers
+explicitly instantiate `CurvedWKTReader` / `CurvedWKTWriter` /
+`CurvedGeometryFactory` when they want curve support. This keeps the
+module GraalVM native-image friendly and avoids surprising other
+classpath users.
+
+## References
+
+- Discussion: <https://github.com/locationtech/jts/discussions/1193>
+- Design template: NetTopologySuite/NetTopologySuite#526
+- Specification: OGC Simple Features Access 1.2.1 / ISO 19125-2

modules/curved/src/main/java/org/locationtech/jts/geom/curved/CircularString.java

@@ -12,6 +12,7 @@
 package org.locationtech.jts.geom.curved;
 
 import org.locationtech.jts.geom.CoordinateSequence;
+import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.geom.GeometryFactory;
 import org.locationtech.jts.geom.LineString;
 
@@ -25,7 +26,7 @@
  * operations fall through to the parent's polyline behaviour. Native
  * arc-aware algorithms are out of scope for this module today.
  */
-public class CircularString extends LineString {
+public class CircularString extends LineString implements Linearizable {
   private static final long serialVersionUID = 1L;
 
   public CircularString(CoordinateSequence points, GeometryFactory factory) {
@@ -36,4 +37,14 @@ public CircularString(CoordinateSequence points, GeometryFactory factory) {
   public String getGeometryType() {
     return "CircularString";
   }
+
+  @Override
+  protected CircularString copyInternal() {
+    return new CircularString(getCoordinateSequence().copy(), getFactory());
+  }
+
+  @Override
+  public Geometry toLinear(double tolerance) {
+    return getFactory().createLineString(getCoordinateSequence().copy());
+  }
 }

modules/curved/src/main/java/org/locationtech/jts/geom/curved/CompoundCurve.java

@@ -12,6 +12,7 @@
 package org.locationtech.jts.geom.curved;
 
 import org.locationtech.jts.geom.CoordinateSequence;
+import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.geom.GeometryFactory;
 import org.locationtech.jts.geom.LineString;
 
@@ -20,7 +21,7 @@
  * segments. Phase-1 stand-in: member structure is collapsed to a flat
  * concatenation of control points. A future phase will preserve segments.
  */
-public class CompoundCurve extends LineString {
+public class CompoundCurve extends LineString implements Linearizable {
   private static final long serialVersionUID = 1L;
 
   public CompoundCurve(CoordinateSequence points, GeometryFactory factory) {
@@ -31,4 +32,14 @@ public CompoundCurve(CoordinateSequence points, GeometryFactory factory) {
   public String getGeometryType() {
     return "CompoundCurve";
   }
+
+  @Override
+  protected CompoundCurve copyInternal() {
+    return new CompoundCurve(getCoordinateSequence().copy(), getFactory());
+  }
+
+  @Override
+  public Geometry toLinear(double tolerance) {
+    return getFactory().createLineString(getCoordinateSequence().copy());
+  }
 }