EPIC: SFA / ISO 19125-2 Curve Awareness in JTS

[grootstebozewolf]

Epic: SFA / ISO 19125-2 Curve Awareness in JTS

AI Disclosure (per the Eclipse Foundation Generative AI Usage Guidelines for Committers)

This document and the companion red-test class
modules/curved/src/test/java/org/locationtech/jts/spec/curveawareness/CurveAwarenessSpecTest.java
were largely AI-generated. The human contributor has reviewed and verified the
technical content (cross-module impact, risk register, phase dependencies, TAG
scope) for correctness. The AI-generated portions are made available under
CC0-1.0 (public domain dedication) and are not subject to the project's
licence; human curation and edits are subject to the JTS dual licence.

SPDX-License-Identifier: (EPL-2.0 OR EDL-1.0) AND CC0-1.0
Assisted-by: xAI Grok (grok-4.3)
Assisted-by: Claude (Opus-4.7)

Status: Draft v3.
Source branch: feature/sfa-curve-buffer-spike on grootstebozewolf/jts.
Audience: locationtech/jts maintainers and contributors. Lift verbatim into a GitHub Epic / Discussion.

1. Goal

Make JTS preserve OGC SFA / ISO 19125-2 curve geometries — CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE, MULTISURFACE, TRIANGLE — through every algorithm where the math is sound, instead of silently linearising to flat parents on the way in.

Today jts-curved is a Phase-1 stand-in: types parse, round-trip WKT coordinates, and exist in the type hierarchy, but jts-core ignores their identity and densifies on contact. This epic tracks the lift, operation by operation.

2. Why

• Performance. Each densification step expands a typical arc to many chord points (≥50 for a half-circle at 1% chord-tolerance); pipelines that buffer → simplify → union compound the cost.
• Precision. Densify → operate → densify drifts control points by ULPs and breaks snap-to-grid round-trips against external SFA producers.
• Interop. PostGIS, Oracle Spatial, NetTopologySuite emit and consume curve geometries; today JTS round-trips them as visibly different shapes after every operation.
• Discoverability. TestBuilder cannot show a curved buffer or a curved boundary today; users of the spec types never see what their input was for.

3. Scope decisions

In scope (this epic):

• Algorithms operating on the six SFA curve types in 2-D.
• WKT round-trip with member structure (already partially landed).
• TestBuilder rendering and drawing tools.

Deferred to sibling epics — explicitly tracked, not pretended-not-to-exist:

• WKB curve-aware extensions (extended geometry-type codes 1000-series). PostGIS interop runs on WKB, so the interop benefit listed in §2 is incomplete without it. Not blocking the algorithm work, but the epic isn't complete without a tracked sibling. Action: open a child issue "WKB curve types" before this epic ships.
• 3-D solids (POLYHEDRALSURFACE, TIN). Their structural / drawing support landed in the spike for visualisation; no 3-D semantics here.
• Elliptic arcs (ELLIPSARC) — JTS has no ellipse model; adding one is bigger than this epic.
• Z / M ordinate interpolation across densified arcs (today they propagate from the 3 control points unchanged; every TAG that produces densified output should leave room for a future interpolation policy).

4. What's already landed (feature/sfa-curve-buffer-spike)

Bucket	Summary
arch:	Structural CompoundCurve — segment-aware copy / toLinear
arch:	Member-structured WKT round-trip for CompoundCurve
arch:	CurvedShapeWriter walks CompoundCurve members, arc-renders
feat:	LineHandlingFunctions.mergeCurves (arc-aware sibling of mergeLines)
fix:	Anchor member control points in CompoundCurve.toLinear (no junction drift)
fix:	Block-comment paste regression in WKT panel
spec:	This epic + 49-method CurveAwarenessSpecTest red-test suite
(orig)	bufferCurveWithParams linearisation hook (Phase-5 spike entry)

These are foundations the rest of the work builds on, not separate sub-issues.

5. Tracking model

We are not opening 49 separate issues. Fragmenting the project board, spamming notifications, and forcing every reviewer to reconstruct the dependency graph is the wrong shape for work this large.

Single source of truth: CurveAwarenessSpecTest

• Path: modules/curved/src/test/java/org/locationtech/jts/spec/curveawareness/CurveAwarenessSpecTest.java
• Run: mvn -pl modules/curved test -Dtest=CurveAwarenessSpecTest
• Starts with 49 failing methods, one per TAG. Each fail("TAG: …") documents the spec.
• When a TAG ships, delete its red-test method — don't edit it green. Remaining method count is the live progress meter.
• Local silence while working: mvn -Dtest='!CurveAwarenessSpecTest' test.

GitHub layout

• This document is the suggested epic body — adapt as the maintainers see fit.
• Optional milestone-shaped issues per phase with checklists referencing TAGs — at most 8 of them, never 49.
• Day-to-day work via PRs that:
  • Reference this epic.
  • Use the TAG in commit subject + PR title.
  • Delete the corresponding red-test method when behaviour lands (its own commit, see conventions below).

Commit / PR convention

bucket: TAG short description

Buckets: fix:, feat:, arch:, test:, spec:, refactor:. (User-facing docs go under spec:.)

Examples:

• feat: BUF-1 analytical single-arc CircularString buffer → CurvePolygon
• arch: F-CP CurvePolygon stores CompoundCurve shell + holes
• test: drop CurveAwarenessSpecTest#test_BUF_1_* — the dedicated commit that closes a TAG by removing its red-test method.

6. Cross-module impact

Most TAGs ship purely inside jts-curved (extension module, opt-in). A handful require touching jts-core and therefore need a maintainer review up-front. Calling them out before they're proposed:

TAG group	jts-core change?	Notes
F-RD	Possibly	Only if ShapeWriter needs new extension hooks for CurvePolygon rings.
N-AA, N-AL, N-SS	Yes	SegmentString / Noder hierarchy lives in core. Largest core surface in the epic.
OV	Indirect	Depends on N-SS; overlay pipeline itself stays in core.
R-PR, R-CONT	Indirect	RelateOp lives in core; if N-SS is the seam, no further core change needed.
PLG	Yes	Polygonizer lives in core; needs to accept CompoundCurve edges.
PRC-SN	Yes	PrecisionModel.makePrecise integration.
DSF	Yes (or shadow)	Densifier lives in core; alternative is to wrap and shadow it from jts-curved.

Everything else is jts-curved-only or jts-app (TestBuilder).

7. Risks / open questions

• Backwards compatibility on structural composites. Algorithms that don't recognise a curve subtype today silently densify. After F-CP, a third-party algorithm that doesn't know about the new structural CurvePolygon ring will see a CompoundCurve shell where it expected a LinearRing, and may throw. We need a fallback contract: the structural ring must implement enough of LinearRing's contract to keep old code limping (read-only chord coords still available), or the structural CurvePolygon must fail fast with a clear message instead of silently going wrong.
• equalsExact semantic change (R-EQ). Today CIRCULARSTRING(p0,p1,p2).equalsExact(LINESTRING(p0,p1,p2)) returns true via shared coordinates. Making it false is per spec, but it's a behaviour change for any user comparing-by-WKT-text. Needs a release note.
• Non-similarity affine (AT-NS). Sheared arcs are ellipse arcs, which JTS doesn't model. The plan is to detect-and-densify, but: what does getGeometryType() return on the result? If LineString, we've changed the type silently. If still flagged as CircularString, the polyline lies about its identity. Decide before AT-NS lands.
• Performance of public arc-arc / arc-line intersection (N-AA, N-AL). The two-circle solve is fine for low cardinality, but MCIndexNoder-equivalent indexing of arc spans (bounding-box pruning of arcs) is non-trivial. Worth a benchmark before committing to a design.
• Z / M propagation across densified arcs. Out of scope for behaviour changes here, but every TAG that produces densified output (DSF, AT-NS, …) should choose a Z/M policy that doesn't lock us out of a proper interpolation later.

8. Definition of Done (epic-level)

The epic closes when all of:

1. CurveAwarenessSpecTest is empty — every TAG's red test deleted, replaced by green tests next to its production code.
2. The 6 curve types round-trip through every public Geometry operation in the user guide without producing flat output where curve-preserving output is mathematically possible.
3. The deferred WKB sibling epic has its own tracking issue. (We don't have to ship it inside this epic, but we can't pretend it doesn't exist.)
4. A release note covers the equalsExact change (see §7) and any other user-visible behaviour shifts.

TB-FN (function-tree curve-awareness badges) is a stretch goal, not a DoD criterion. Annotating every entry in TestBuilder's function tree is a multi-week task with low payoff relative to the algorithm work, and shouldn't gate epic closure.

9. Phases — work breakdown

Phases group TAGs that share dependencies or naturally land together. Within a phase, TAGs are usually independently shippable. Cross-phase dependencies are noted explicitly per phase.

Phase 1 — Foundations (jts-curved structural completeness)

Mirror the CompoundCurve work onto the remaining composite types.

• F-CP Structural CurvePolygon — CompoundCurve shell + holes; copyInternal, toLinear, WKT reader/writer preserve structure.
• F-MC Structural MultiCurve — preserves member subtypes (LineString / CircularString / CompoundCurve).
• F-MS Structural MultiSurface — preserves Polygon vs CurvePolygon member subtypes.
• F-RD CurvedShapeWriter for CurvePolygon rings, MultiCurve and MultiSurface members.

Hard prereq for: all of Phase 2 (you can't return a CompoundCurve boundary of a CurvePolygon whose ring isn't a CompoundCurve to begin with).

Phase 2 — Properties (Metrics, Boundary, Validity)

• M-LEN-CS / M-LEN-CC — analytical arc length.
• M-AREA-CP — Green's-theorem area with circular-segment correction.
• M-DIM — empty-curve dimension/coordinate-dimension guards.
• B-CP / B-MS / B-CC — curved boundaries.
• V-CP — CurvePolygon validity (arc self-intersection, sector orientation, holes-in-shell).
• V-CS — CircularString / CompoundCurve simplicity.

Depends on: Phase 1 (F-CP is a hard prereq for B-CP, M-AREA-CP, V-CP).

Phase 3 — Measurement (Distance, Centroid, Interior point)

• D-PT / D-AA — analytical point-arc and arc-arc distance.
• D-OP — DistanceOp accepts curved inputs without forced densification.
• D-HF — DiscreteHausdorffDistance / DiscreteFrechetDistance parameterise by arc length.
• C-LIN / C-AREA / C-IP — centroids and interior point.

Depends on: Phase 1 (F-CP for CurvePolygon cases).

Phase 4 — Construction (Buffer, Hulls, Simplification, Affine, Linear-Ref, Densifier)

• BUF-1 / BUF-N / BUF-NEG — analytical buffer.
• OFF / VBF — offset curve and variable buffer.
• H-CV / H-CC — convex / concave hull.
• S-DP / S-VW / S-TP — simplification preserves arc identity.
• AT-S / AT-NS — affine transforms (similarity preserves; non-similarity densifies — see §7 risk).
• LRF-LEN / LRF-LOC — linear referencing parameterised by arc length.
• DSF — densifier delegates to toLinear.

Depends on: Phase 1 (output may be CurvePolygon).

Phase 5 — Noding foundation

• N-AA — public arc-arc intersection utility.
• N-AL — public arc-line intersection utility.
• N-SS — arc-aware SegmentString / NodedSegmentString and integration with the Noder hierarchy.

Depends on: Phase 1. Touches jts-core — see §6.

Phase 6 — Overlay, Predicates, Polygonizer, Coverage

• OV — arc-preserving overlay output (union / intersection / difference / symDifference).
• R-PR / R-CONT / R-EQ — arc-aware relate, predicates, exact equality.
• PLG — Polygonizer accepts CompoundCurve edges and emits CurvePolygon faces.
• COV — CoverageUnion preserves shared arc edges.

Depends on: Phase 5.

Phase 7 — Independent tracks

Three single-theme tracks that depend only on Phase 1 and have no inter-dependencies; can land in parallel with Phases 2–6 once Phase 1 ships.

• Snapping
  • PRC-SN — snap-to-grid preserves arc when the snapped (R, centre, sweep) still lies on grid; otherwise densify-and-snap chords.
• Triangulation / Voronoi
  • TRI-DT / TRI-VR — DelaunayTriangulationBuilder / VoronoiDiagramBuilder accept curved boundary input (densify internally via toLinear(tolerance)).
• TestBuilder
  • TB-T — CompoundCurveTool, CurvePolygonTool drawing UX.
  • TB-FN — function-tree curve-awareness badges (●/◯/✕). Stretch goal — see §8.

10. Suggested order

Phase 1 (Foundations)
   │
   ├──> Phase 2 (Properties)
   ├──> Phase 3 (Measurement)
   ├──> Phase 4 (Construction)
   ├──> Phase 5 (Noding)  ──>  Phase 6 (Overlay / Predicates / Polygonizer)
   └──> Phase 7 (Independent tracks: snap / triangulation / TestBuilder)

After Phase 1 finishes, Phases 2 / 3 / 4 / 5 / 7 can run in parallel; Phase 6 waits for Phase 5.

flowchart TD
    P1[Phase 1: Foundations]
    P2[Phase 2: Properties<br/>Metrics, Boundary, Validity]
    P3[Phase 3: Measurement<br/>Distance, Centroid, Interior Point]
    P4[Phase 4: Construction<br/>Buffer, Hulls, Simplification, ...]
    P5[Phase 5: Noding<br/>N-AA, N-AL, N-SS]
    P6[Phase 6: Overlay, Predicates,<br/>Polygonizer, Coverage]
    P7[Phase 7: Snapping<br/>PRC-SN]
    P8[Phase 8: Triangulation / Voronoi<br/>TRI-DT, TRI-VR]
    P9[Phase 9: TestBuilder<br/>TB-T, TB-FN]

    P1 --> P2
    P1 --> P3
    P1 --> P4
    P1 --> P5
    P5 --> P6
    P1 --> P7
    P1 --> P8
    P1 --> P9

Loading

11. Conventions

• TAGs are short, unique, and stable. Renaming a TAG renames its test method too.

• One TAG per PR (or a tightly-coupled cluster). The PR deletes the corresponding spec method.

• CI stays green by default. The spec class is excluded from the default Surefire run via:

  <plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
      <excludes>
        <exclude>**/spec/curveawareness/*.java</exclude>
      </excludes>
    </configuration>
  </plugin>

  Contributors run it explicitly with mvn -pl modules/curved test -Dtest=CurveAwarenessSpecTest (which overrides the exclude). The remaining-method count is still the live progress meter, but it doesn't break CI on every push.

12. References

• OGC Simple Feature Access 1.2.1 / ISO 19125-2.
• jts-curved source: modules/curved/.
• Spike branch: feature/sfa-curve-buffer-spike on grootstebozewolf/jts.
• CurveAwarenessSpecTest (live progress meter).

[grootstebozewolf]

Focused spike landed on the fork for one TAG: F-CP — Structural CurvePolygon. Branch: feature/sfa-curve-F-CP-spike (single commit, spike-only, no production-code change yet).

Why F-CP first

Walking the 49 TAGs against the §6 cross-module table, §7 risk register, and the §10 phase graph, F-CP stands out:

• Critical path. Hard Phase-1 prereq for every Phase-2 TAG that needs to talk about a curved boundary, area, or validity (B-CP, M-AREA-CP, V-CP). Phase 2 can't ship until F-CP does.
• §7 risk Deleted unsupported modules: jts-jump, libjts, jts-sde-adapter. #1 lives here. Polygon.getExteriorRing() is typed LinearRing; a structural CurvePolygon's actual shell is a CompoundCurve. Those two facts can't both be true at runtime — the dovetail choice has to be made before the implementation PR, not inside its review.
• Already interacts with shipping code. PR #1194 ships a Phase-1 stand-in that silently linearises CurvePolygon rings on read. Any future structural form has to coexist with or replace that path.
• Precondition met. The feature/sfa-curve-compoundcurve-members branch on the fork (commit 29723a30) restructures CompoundCurve to store LineString[] members with getCurveN(int) / getNumCurves(). F-CP picks up from there — the spike's helpers already bridge to that API by reflection so the red tests compile against the current extension-points head.

What's on the spike

• CurvePolygonStructuralSpec.java — 8 red tests covering 7 F-CP sub-TAGs (FCP-S / FCP-MEM / FCP-H / FCP-CP / FCP-TL / FCP-WKT / FCP-DOVE), each fail() naming its sub-TAG so the message stream stays a live progress meter for the F-CP sub-surface, mirroring the role of CurveAwarenessSpecTest at the epic level.
• SPEC_F_CP.md — captures the FCP-DOVE branching table with trade-offs, where we lean, and what's deferred.
• modules/curved/pom.xml — adds the Surefire exclude **/spec/curveawareness/*.java per §11 so the spike's red tests don't redden default CI. On-demand: mvn -pl modules/curved test -Dtest=CurvePolygonStructuralSpec.

Posture verified: default reactor build BUILD SUCCESS with checkstyle (55 jts-curved tests green); explicit spec run yields 8 failed / 8 run with TAG-tagged messages.

The dovetail decision (FCP-DOVE)

Three live options for what Polygon.getExteriorRing() returns on a structural CurvePolygon:

Option	getExteriorRing()	New accessor	Trade-off summary
A — legacy fallback	LinearRing of densified chord coords at a default tolerance	getExteriorCurve() returns the structural Curve	Two-tier API; old callers keep working but see a polyline approximation. Lowest friction for jts-core.
B — widen return type	LineString (CompoundCurve extends LineString)	none — existing method suffices	Single source of truth, no API doubling. Breaks every caller that does (LinearRing) p.getExteriorRing() — needs a core-wide audit.
C — fail-fast	throws UnsupportedOperationException	getExteriorCurve() returns the structural Curve	Loudest diagnostic; forces every caller to migrate. Probably only acceptable behind a feature flag.

We lean A today (lowest blast radius on jts-core, two-tier API as the deliberate cost). B becomes attractive again if the number of (LinearRing) casts on getExteriorRing() results inside jts-core turns out to be small — that count is the deciding number. Full trade-offs and what's deferred (default tolerance, getCoordinates() policy, hole symmetry) are in SPEC_F_CP.md.

Smallest concrete next step

A one-line A / B / C reply from a maintainer on this issue. After that:

1. An arch: commit on the spike branch deletes the unselected rows from SPEC_F_CP.md to record the decision.
2. A separate implementation PR starts from there: updates to CurvePolygon, CurvedGeometryFactory, CurvedWKTReader.readCurvePolygonText, CurvedWKTWriter, and deletes the now-green methods in CurvePolygonStructuralSpec per the §5 convention.

The door is deliberately left open — if a Phase-2 TAG surfaces a constraint we missed before the implementation PR lands, revisiting the option is fair game. Post-merge it becomes a breaking change.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

F-CP / FCP-DOVE — three option spikes ran; B and C ruled out

Per the request to continue the spike until each option is ruled out or surfaces benchmarks, ran a branch per option. All three spikes are now on the fork; B and C produce strong rule-out evidence, A flips half the F-CP red tests green and exposes only secondary design questions that are implementation-PR scope.

Branches

Option	Branch	Build	F-CP reds
A — legacy fallback (getExteriorCurve() + legacy getExteriorRing())	feature/sfa-curve-F-CP-spike-optionA	BUILD SUCCESS, 55/55 Phase-1 tests green	4 of 8 flip green
B — widen Polygon.getExteriorRing() return type to LineString	feature/sfa-curve-F-CP-spike-optionB	intentionally non-compiling	n/a
C — fail-fast on getExteriorRing()	feature/sfa-curve-F-CP-spike-optionC	compiles, but 2 existing curved tests regress	not measured (probe instead)

Cast survey first

Across modules/core/src/main/java:

Pattern	Count
getExteriorRing() call sites	57
getInteriorRingN() call sites	47
explicit (LinearRing) casts on either result	10

The 10-cast number is what the spec doc bet B on. The real measurement (below) is much larger.

Option A — feasible, minimal, no regressions

Diff: +60 / −8 across CurvePolygon, CurvedWKTReader, and the spike helpers. Adds a new field LineString structuralShell, a new constructor that derives the legacy LinearRing shell via Linearizable.toLinear(0.0), a new getExteriorCurve() accessor, and updates copyInternal() to preserve the structural shell.

Test posture on the A branch:

• 55/55 jts-curved Phase-1 tests stay green — no regressions
• 4 of 8 FCP red tests flip green: FCP-S (compound shell), FCP-S (single-arc), FCP-CP (copy preservation), FCP-DOVE (the design-decision marker)
• 4 reds remain — but each tracks an independent sub-TAG that A/B/C all share equally:
  • FCP-MEM waits on feature/sfa-curve-compoundcurve-members
  • FCP-H is the parallel getInteriorCurveN(int) accessor (cosmetic)
  • FCP-WKT is a writer-side TAG (separate sub-issue)
  • FCP-TL waits on feature/sfa-curve-toLinear-densification

One open question A defers to the implementation PR: the default tolerance source for the linearised getExteriorRing() view. Today's toLinear(0.0) ignores the tolerance argument; a real implementation parameterises on PrecisionModel scale or a CurvedGeometryFactory field. Not an A-vs-B-vs-C decision.

Option B — RULE-OUT for Phase 1

Two-method widening of Polygon from LinearRing to LineString (the entire mechanical surface of B). Then mvn -pl modules/core compile:

Metric	Count
Compile errors in jts-core/main	108
Distinct files affected	25
Highest-impact file	operation/valid/IsValidOp.java (12 errors)
Files with 4+ errors	19 of 25

The original 10-cast number undercounted by 10×. The compiler also flags every implicit assignment (LinearRing r = polygon.getExteriorRing() with no cast) and every pass-through into new Polygon(LinearRing, ...). Full breakdown in NOTE_OPTION_B.md and the raw mvn error log preserved at SPIKE_OPTION_B_compile_errors.txt.

Beyond the 108 sites, B fails the "single source of truth" sales pitch: the Polygon constructor still takes LinearRing shell, LinearRing[] holes, so most of the 108 fix sites end up adding explicit (LinearRing) casts to satisfy the constructor — recreating the two-tier API Option A would have made explicit. And the API change is binary-incompatible for every downstream consumer (PostGIS-Java, GeoTools, etc.).

Verdict for Phase 1: no. B remains viable as a post-A deprecation cycle — widen the API, keep the LinearRing-returning method as a deprecated shim, do the 108-site sweep over multiple PRs.

Option C — RULE-OUT, including as a feature flag

Override getExteriorRing() and getInteriorRingN(int) on CurvePolygon to throw UnsupportedOperationException; route internal copyInternal() / toLinear() via super.* calls.

Blast-radius probe (OptionCBlastRadiusProbe.java) pipes a CURVEPOLYGON(CIRCULARSTRING(0 0, 10 0, 5 5, 0 5, 0 0)) through 32 representative jts-core operations:

total: 32   ok: 16   UOE: 16   other-error: 0

50 % blast radius. What survives: methods that read Polygon's internal shell field directly (getCoordinates, getArea, getLength, getBoundary, copy, normalize, isSimple, plus all geometry-metadata). What breaks: every relational predicate (intersects / contains / intersection / union / difference / distance), buffer, getCentroid, getInteriorPoint, convexHull, reverse, isValid, toText, and the curve-aware CurvedWKTWriter.write() itself.

Empirical confirmation in the unchanged Phase-1 suite: two existing curved-module tests break under Option C without any test-code edit — WKTCurvePolygonTest.testWKTRoundTripXY and WKTMultiSurfaceTest.testWKTRoundTripXY, both via CurvedWKTWriter → appendPolygonText → getExteriorRing() → UOE.

A feature-flagged C reduces to "A with an optional explosion mode" because the flag-off behaviour has to be either A or B. Verdict: rule out as the default contract. C survives as a useful idea in a smaller scope: a CurvedGeometryFactory diagnostic-mode wrapper that strict pipelines opt into to confirm no non-curve-aware code touches their CurvePolygons. That's a separate, smaller feature.

Recommendation

Land F-CP under Option A. A is the only option that ships without a sweeping core PR or a 50% method-availability hole, and the spike shows it's a ~60-LOC additive change with no regressions.

The implementation PR's remaining open questions (default linearisation tolerance, getCoordinates() policy, hole-symmetry timing) are all scoped to A's implementation, not to the A-vs-B-vs-C choice.

If maintainers want to keep B alive as a future cleanup, the right shape is "A now, B-style widening in a follow-up release with a deprecation cycle" — captured at the bottom of NOTE_OPTION_B.md.

The door's still open if a Phase-2 TAG surfaces a constraint that changes the trade-off before the F-CP implementation PR lands.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

Continuing — F-MC + F-MS Phase-1 finish, AT-NS §7-risk-#3 spike

Two more workflow loops on the fork:

TAG group	Branch	Status
F-MC + F-MS (composite-member preservation)	feature/sfa-curve-F-MC-F-MS-spike	Phase-1 reader half already free, writer half closed
AT-NS (affine on curved geometry, §7 risk #3)	feature/sfa-curve-AT-NS-spike	three-option spec + probe; lean Option A

F-MC + F-MS — half-already-free, half-closed

Wrote a 6-test red spec and ran it against the PR-1194 base before touching code. Four of six green on the unchanged base:

• FMC-READ, FMC-COPY — MultiCurve preserves CircularString / CompoundCurve member subtypes via CurvedWKTReader.readCurveMember's dispatch through readGeometryTaggedText; MultiLineString.copy() propagates each member's runtime class through copyInternal() without F-CP-style storage redesign.
• FMS-READ, FMS-COPY — same shape for MultiSurface holding plain Polygon + CurvePolygon members.

The two reds were both writer-side: MULTICURVE and MULTISURFACE round-tripped through CurvedWKTWriter.write() came back as flat polylines/polygons because WKTWriter.appendMultiLineStringText / appendMultiPolygonText emit per-member body-only bodies, dropping the type tag.

Fix: ~75 LOC additive on CurvedWKTWriter, overriding the appendOtherGeometryTaggedText hook from PR #1194 to intercept MultiCurve and MultiSurface. Per-member emission emits body-only (x y, …) for plain LineString / Polygon members and tagged CIRCULARSTRING (…) / COMPOUNDCURVE (…) / CURVEPOLYGON (…) for curve members. No jts-core change — the extension hook already in place handles the seam.

Posture: default mvn -pl modules/curved test is 55/55 green, on-demand spec is 6/6 green, full reactor with checkstyle is BUILD SUCCESS.

Phase-1 status after this branch:

TAG	State
F-CP	pending — Option A recommended in earlier comment
F-MC	reader done on base; writer closed by this spike
F-MS	reader done on base; writer closed by this spike
F-RD	TestBuilder rendering — separate Phase 4-B / lab work

Once F-CP lands under Option A, Phase 1 is structurally complete and Phases 2/3/4/5/7 unlock per the §10 graph.

AT-NS — §7 risk #3 with branching table + probe

Followed the same shape as FCP-DOVE: a SPEC_AT_NS.md with a three-option branching table, an 8-test red spec pinned to the lean option, and a current-behaviour probe so the measurement is reproducible.

Branching table

Option	Non-similarity behaviour	getGeometryType()	Trade-off
A — silent densify	densify via toLinear(tolerance), then transform the polyline	result is LineString	Geometrically faithful; type changes silently. Matches §7's "detect-and-densify".
B — preserve type, accept drift (today)	transform the 3 control points; the new arc is the circle through transformed points	CircularString (lies)	Type stable; geometrically wrong for shears / non-uniform scales.
C — fail-fast	detect non-similarity, throw UnsupportedOperationException	n/a	Loudest diagnostic. Probably only acceptable behind a strict-mode flag.

Probe output, today

transform                  similarity?  out-type        out-pts  control-pts-on-circle?
identity                   true         CircularString  3        true
translate(10, 20)          true         CircularString  3        true
scale(2, 2) uniform        true         CircularString  3        true
rotate(pi/4)               true         CircularString  3        true
reflect x-axis             true         CircularString  3        true
scale(2, 1) non-uniform    false        CircularString  3        true   <-- LIES
scale(3, 1) non-uniform    false        CircularString  3        true   <-- LIES
shear-x 0.5                false        CircularString  3        true   <-- LIES

The probe carries a static isSimilarity(AffineTransformation) helper using the standard linear-algebra test (a² + c² == b² + d² and ab + cd == 0). It correctly flags every non-similarity, but apply(...) still returns a CircularString — Option B in action. The "on-circle" column is the geometric sanity check: 3 distinct non-collinear points always lie on some circle, so the result is a valid CircularString syntactically even when it has nothing to do with the elliptical image of the original arc.

Where we lean

Option A. Three reasons in SPEC_AT_NS.md:

1. It is the only option where the result is a faithful representation of the affine image of the original arc. B's result is a different geometric curve entirely; C avoids the question.
2. The type change is observable and recoverable: a curve-aware caller can branch on g.getGeometryType() after the call.
3. A drops in cleanly with the existing Linearizable contract; the non-similarity branch becomes one call to toLinear(tolerance) followed by transforming the linearised result. The toLinear half is already done on feature/sfa-curve-toLinear-densification.

B remains reachable via a three-line escape hatch for callers who want it (transform the CoordinateSequence directly and rebuild the CircularString). C survives as a CurvedGeometryFactory strict-mode flag — same diagnostic-mode role as FCP-DOVE Option C.

Smallest concrete next step

A one-line A / B / C ack on this issue, then an arch: commit on the spike branch pinning the choice in SPEC_AT_NS.md, then the implementation PR overrides apply(...) on each curve type with the similarity-detection + densify branch. The 8-test spec class shrinks to zero as the implementation lands per the §5 convention.

Phase-1 critical path now

F-CP   (Option A picked, awaiting ack -> implementation PR)
F-MC   (closed by F-MC-F-MS-spike, awaiting merge upstream)
F-MS   (closed by F-MC-F-MS-spike, awaiting merge upstream)
F-RD   (TestBuilder UI, separate track)

AT-NS  (Option A leaning, awaiting ack)

Door is open on every option if a downstream TAG surfaces a constraint that changes the trade-off before the implementation PR lands.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

Continuing — R-EQ §7-risk-#2 spike + PRC-SN Phase-7 spike

Two more rounds, both following the FCP-DOVE / AT-NS shape (spec doc + red-test class + probe + lean):

TAG	Branch	Position
R-EQ (§7 risk #2 — equalsExact semantics)	feature/sfa-curve-R-EQ-spike	Option A implemented and measured; zero regressions
PRC-SN (Phase 7 — snap-to-grid)	feature/sfa-curve-PRC-SN-spike	spec + probe; reveals today's reducer is more aggressive than Option C

R-EQ — measured at minimal cost

Root cause: LineString.isEquivalentClass is lenient (other instanceof LineString) so a CircularString calling equalsExact with a coordinate-identical LineString passes the equivalence gate and returns true. Polygon does not override isEquivalentClass, so CurvePolygon.equalsExact(Polygon) is already correctly false today — R-EQ is narrowly scoped to the two LineString-extending curve types.

Branching table

Option	Approach	Symmetry	Trade-off
A — override isEquivalentClass strict on curve side	curve overrides only	asymmetric (cs.eE(ls)==false, ls.eE(cs)==true)	Minimal, fixes the §7 violation, no jts-core change
B — tighten LineString.isEquivalentClass everywhere	breaks LinearRing↔LineString	symmetric	Much bigger jts-core change; future deprecation cycle
C — new parallel method	preserves all current behaviour	n/a	Adds API; doesn't fix equalsExact for existing callers

Lean: Option A. Implemented on the spike branch: two-method change (isEquivalentClass on CircularString and CompoundCurve).

Probe before/after the override

                              today (Option B baseline)   spike branch (Option A)
cs.equalsExact(ls)            true   <-- WRONG            false  <-- fixed
cc.equalsExact(ls)            true   <-- WRONG            false  <-- fixed
cc.equalsExact(cs)            true   <-- WRONG            false  <-- fixed
cs.equalsExact(cc)            true   <-- WRONG            false  <-- fixed
ls.equalsExact(cs)            true   <-- documented asym  true   <-- unchanged
cs.equalsExact(cs)            true                        true
lr.equalsExact(ls')           true   <-- intentional      true   <-- preserved
ls'.equalsExact(lr)           true   <-- intentional      true   <-- preserved
poly.equalsExact(ls)          false                       false

Posture: default mvn -pl modules/curved test is 55/55 green (zero regressions). On-demand spec is 6/6 green. The asymmetric ls.equalsExact(cs) == true is preserved by design — tightening LineString.isEquivalentClass would break the intentional LinearRing ↔ LineString equivalence, which is a much larger change. Documented in SPEC_R_EQ.md "asymmetry trap" + an explicit test (test_R_EQ_asymmetryIsDocumentedAndAccepted) that documents the contract.

Implementation PR is trivial: cherry-pick the two overrides, add a release-note bullet, add Javadoc on each curve type calling out the asymmetric contract.

PRC-SN — Phase 7 independent track with a surprising discovery

Spike followed the SPEC + probe + red-tests shape. The branching table is in SPEC_PRC_SN.md:

Option	Approach	Type stability
A — snap control points	preserved (type), arc drifts	The §7 "preserve on grid" branch
B — snap (R, centre, sweep)	preserved (type and arc)	Hard; not every snapped arc has control points on grid
C — densify then snap	LineString	The §7 "otherwise densify" branch
D — A when grid-friendly, else C	adaptive	The §7 phrasing made code

Lean: Option D, with a defined "grid-friendly" criterion: the snapped circle through the three snapped control points must have both centre and radius on the grid.

The discovery — today is worse than Option A or C

GeometryPrecisionReducer.reduce unconditionally strips CircularString to LineString via GeometryEditor.GeometryEditorOperation — even when there's nothing to snap:

input description                       out-type        out-pts  arc drift
integer-aligned half-circle             LineString      3        none
sub-cell drift snapping to integers     LineString      3        centre (4.89, 0.61) → (5.00, 0.00); R 4.81 → 5.00
sub-grid arc (off-grid centre)          LineString      3        centre (0.85, -0.31) → (0.50, 0.50); R 0.82 → 0.71
near-degenerate small arc               LineString      0        all coords collapse to origin
quarter-circle on grid                  LineString      3        none

Even the grid-aligned half-circle (CIRCULARSTRING (0 0, 5 5, 10 0)) loses its arc identity because the reducer's GeometryEditor rebuilds via the GeometryFactory.createLineString, which has no CircularString awareness.

So the choice isn't "A vs D" — the current behaviour is more aggressive than C (always degrade type, even when there's nothing to snap). PRC-SN is the right place to introduce any curve-type preservation through the precision reducer. Once the infrastructure exists, layering the grid-friendly check on top is straightforward.

Spec posture: 6 tests, 4 red / 2 green. The two greens pass for the wrong reason (today degrades unconditionally, which happens to match Option D's fallback assertion). The reds capture the gap. Probe runs on demand.

Implementation PR sketch: a new org.locationtech.jts.precision.curved.CurvedPrecisionReducer with isGridFriendly(CircularString, PrecisionModel) and a reduce(Geometry, PrecisionModel) entry point that dispatches curve subclasses through the Option-D branch and delegates to the standard reducer for everything else.

§7 risk register status after this round

Risk	TAG	Status
#1 — F-CP backward compat	FCP-DOVE	Option A recommended (earlier)
#2 — equalsExact semantics	R-EQ	Option A implemented + measured (this round)
#3 — non-similarity affine	AT-NS	Option A leaning (previous round)
#4 — arc-arc/arc-line indexing performance	N-AA / N-AL	not yet — needs benchmark spike (post Phase-5 design)
#5 — Z/M propagation across densified arcs	spans BUF / DSF / AT-NS / PRC-SN	tracked as a deferred policy item per spec docs

Plus PRC-SN (Phase 7) now has a spike and a discovery that informs Phases 2/3/4 too: any operation that goes through GeometryEditor will degrade curve types the same way the reducer does today. Worth flagging when those TAGs come up.

Door's still open on every option.

---

Assisted-by: Claude (Opus-4.7)