Geo3d spatial context: a line string's buffer is read as radians, so a 1-degree buffer is 57 degrees wide

spatial4j's documented geographic conventions put distances in degrees (LineStringBuilder.buffer itself names no unit, so its unit is inferred from those conventions and spatial4j's readers). The spatial-extras Geo3dShapeFactory, the shape factory of the opt-in, experimental Geo3dSpatialContextFactory, converts degrees to radians at its boundary for circles, 2-D points and rectangle buffers, but its line-string builder does not: buffer(distance) stores the value as given and build() passes it to spatial3d's GeoPathFactory.makeGeoPath, whose width "is the width of the path, measured as an angle", in radians. So the line (0,0) to (10,0) with buffer(1) reaches 57.3 degrees from the line: bounding box [-57.3, 67.3] x [-57.3, 57.3] instead of [-1, 11] x [-1, 1], and it contains the point (5, 20), which spatial4j's own geo context and the same factory's 1-degree circle leave outside. The same happens when the Geo3d context reads spatial4j's polyshape string of that line. Any buffer above about 1.5708 throws IllegalArgumentException: Cutoff angle out of bounds. In an index, an Intersects query with the 1-degree line returned 3 of 4 points where 1 is right. The code dates from LUCENE-7951; every release from 7.1.0 (2017) to 10.6.0 (10.6.0 by reading) and main are affected, and the fix is one multiplication in build().

• Spatial context: spatial4j's SpatialContext fixes the units and builds shapes through its ShapeFactory. In a geographic context x is longitude, y is latitude, and distances are in degrees (1 degree is about 111 km).
• Geo3d spatial context: Geo3dSpatialContextFactory in lucene-spatial-extras (@lucene.experimental, opt-in; default planet model: the sphere) makes a context whose Geo3dShapeFactory builds lucene-spatial3d shapes. spatial3d works in radians, so the factory converts at its boundary.
• Buffered line string: lineString().pointXY(...).buffer(d).build(), the corridor of all points within d of the line. In the Geo3d context it becomes a spatial3d GeoStandardPath.

1. Geo3dLineStringBuilder.buffer(distance) stores the value unchanged: this.distance = distance; (Geo3dShapeFactory.java:308-312).
2. build() calls GeoPathFactory.makeGeoPath(planetModel, distance, points.toArray(GeoPoint[]::new)) (:314-319).
3. makeGeoPath documents its width as "the width of the path, measured as an angle" (GeoPathFactory.java:34), a spatial3d angle in radians, and builds a GeoStandardPath. That constructor rejects widths outside (0, pi/2] with "Cutoff angle out of bounds" (GeoStandardPath.java:80-81).
4. Elsewhere the factory converts degrees for circles, 2-D points and rectangle buffers: circle() passes distance * DistanceUtils.DEGREES_TO_RADIANS (Geo3dShapeFactory.java:175-197), pointXY converts coordinates (:278-286; pointXYZ has a different boundary bug, LFV-679), and Geo3dRectangleShape.getBuffered converts its distance (Geo3dRectangleShape.java:169-173). The context's distance calculator and circle radii report degrees. normDist is the identity (:114-117).
5. spatial4j's readers feed the same builder: the polyshape reader passes the same normDist(arg) to a circle's radius and to a line's buffer, and the GeoJSON reader converts a km buffer to degrees before calling buffer(). So one polyshape document gives a 1-degree circle but a 1-radian line. The deprecated lineString(List, double) and the multi-line builder use the same builder too (both executed: the 57.3-degree corridor, CONTAINS (5, 20)). spatial4j registers the GeoJSON reader only when Noggit's org.noggit.JSONParser is on the classpath; it was not on the tested classpaths, so that path was read, not run.

• Line (0,0) to (10,0), buffer(1), default sphere: bounding box [-57.3, 67.3] x [-57.3, 57.3] (spatial4j: [-1, 11] x [-1, 1]). Along x = 5 the edge lies between y = 57.0 (inside) and 57.5 (outside): 1 radian is 57.2958 degrees.
• The same line with buffer(Math.toRadians(1)) is the 1-degree corridor (bounding box [-1, 11] x [-1, 1]).
• buffer(1.5708) (just above pi/2), buffer(1.6), buffer(2) and buffer(90.01): IllegalArgumentException: Cutoff angle out of bounds; buffer(1.5707) builds. Exactly Math.PI / 2 passes that check and, for the probe's two-point line, fails later with "path too wide". The bounding box of buffer(1.5) spans all longitudes.
• WGS84 behaves the same: a point 2.98 degrees from the 1-degree line is inside.
• Not affected: unbuffered lines (a zero width becomes a degenerate path), circles, rectangles, polygons, and spatial4j's default geo context. WKT BUFFER(LINESTRING(...), d) is not supported in the Geo3d context at all.

• Who is hit. Users of Geo3dSpatialContextFactory (any planet model) who build buffered line strings: lineString().buffer(d), the deprecated lineString(List, double), multi-line builders (all executed), the polyshape format (executed) or the GeoJSON "buffer" extension when the optional Noggit JSON parser is on the classpath (by code reading). As document shapes or as query shapes ("documents within d of this route"); RecursivePrefixTreeStrategy with Geohash or S2 trees and SerializedDVStrategy all see the wide shape.
• Default vs opt-in. Opt-in twice: the Geo3d context is not the default, and only buffered lines are wrong. WKT, one of spatial4j's default input formats, cannot express a buffered line in this context.
• Effect. Buffers below about 1.57: a corridor 57.2958 times wider than requested, with no error. In an index of 4 points an Intersects query with the 1-degree line returned 3 where 1 is right; in a 600-document index (514 live) it matched 359 documents on Geohash and S2 prefix trees and 354 on SerializedDVStrategy, where the fix matches 0 (a synthetic uniform sample of points: the counts show that every strategy sees the wide shape, not how often real queries over-match). Indexed buffered lines can give false positives for intersection queries that touch the extra area. Buffers above about 1.57 (callers mean about 175 km) throw IllegalArgumentException while the shape is built; a 200 km GeoJSON buffer (about 1.8 degrees) is in that range.
• Still honoured. Other filter clauses and deletions: 0 documents from another tenant and 0 deleted documents were returned.
• Lasting. SerializedDVStrategy stores the path with its angle and prefix-tree terms encode the wide corridor, so documents indexed while the bug is present stay wide after a fix until they are reindexed (code reading, not executed).
• How likely. Rare: the context is opt-in and buffered lines need the builder, polyshape or GeoJSON. For those callers every buffered line is wrong, and conspicuously so; no report was found in the nine years since 7.1.0.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<DISJOINT> but was:<CONTAINS>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.spatial.spatial4j.TestGeo3dLineStringBuffer.testBufferIsInDegrees(TestGeo3dLineStringBuffer.java:28)

• Contract (inferred from spatial4j, not quoted from buffer()). spatial4j ShapeFactory.circle: "The units of "distance" should be the same as x & y." lineString(List<Point> points, double buf): "with a buffer distance along the line in all directions". LineStringBuilder.buffer(double) itself has no javadoc. spatial4j's FORMATS.md: "The BUFFER keyword ... The 2nd argument is the buffer distance in degrees."
• Lucene's description of the bridge. CHANGES: "LUCENE-7951: Spatial-extras has much better Geo3d support by implementing Spatial4j abstractions: SpatialContextFactory, ShapeFactory, BinaryCodec, DistanceCalculator." The package: "Spatial4j stuff that ideally belongs in Spatial4j (isn't related to Lucene)." No javadoc, CHANGES or MIGRATE text says line buffers are radians.
• The factory itself. Circles, 2-D points, rectangles, rectangle buffers, the distance calculator and circle radii all use degrees at the boundary. Only the line buffer does not. Its own javadoc names the unit for circles: setCircleAccuracy sets "the accuracy for circles in decimal degrees" (Geo3dShapeFactory.java:82-85).
• The readers. The polyshape reader passes the same normDist(arg) to circles and line buffers, and normDist is the identity here; GeoJSON converts km to degrees before buffer(). A radians-only builder is wrong for every parsed input, whatever is documented.
• Maintainer remarks. In the LUCENE-8086 review, dsmiley asked whether the factory's circleAccuracy means "decimal degrees as is used in other parts of the Spatial4j API"; in the LUCENE-7951 review they wrote that verification can "assume decimal degrees here (-/+ 180 etc.) since Geo3d assumes this". Nobody discussed the line buffer's unit.

Strongest case for "intended" (built by a devil's advocate; the reviews from another model family, OpenAI GPT-5.6, rated it moderate and strong): LineStringBuilder.buffer states no unit; spatial3d is radians-native; the bridge is @lucene.experimental; the behaviour has not changed since 2017; and the only caller of the builder's buffer() outside the factory, ShapeRectRelationTestCase.testGeoPathRect, passes (random().nextInt(89) + 1) * DEGREES_TO_RADIANS, a range that lies within GeoStandardPath's (0, pi/2] bound (1 to 89 degrees, at most 1.553 rad).

Why it fails: the radian width is older than the builder. It dates from LUCENE-6196 (2015), when the test built spatial3d's new GeoPath(width) directly, before the Geo3d spatial context existed; in 7.2.0 the test still called GeoPathFactory.makeGeoPath(planetModel, width, points) directly, where radians are right; LUCENE-8086 (2017-12-13, first in 7.3.0) moved it onto the builder and kept the radian width. The same test passes its circle radius in degrees, and it checks relation consistency, which does not depend on the width's unit. spatial4j's readers can only ever pass degrees. @lucene.experimental allows API changes, not wrong results, and nine quiet years speak to compatibility, not intent. Every verdict calls it a defect; what remains is the compatibility cost for callers who already pass radians.

Built and validated in a scratch worktree at a9779ef3c193 with gradle, and with the standalone runner against the finder's, the independent reproducer's, the devil's advocate's and the cross-model reviewer's tests. Any option changes the unit for callers who already pass radians, so it needs a CHANGES entry that says so.

One multiplication in Geo3dLineStringBuilder.build(), the conversion circle() already does. In ShapeRectRelationTestCase.testGeoPathRect, pass the width in degrees (and drop the now unused DEGREES_TO_RADIANS static import), so the test keeps building the same 1-89 degree corridors as today. Add this page's test as the regression test. Patch: +116/-4 in 3 files (5 lines in the factory, 4 in the old test, the new 111-line test).

// Geo3dShapeFactory.Geo3dLineStringBuilder.build()
GeoPath path =
    GeoPathFactory.makeGeoPath(
        planetModel,
        distance * DistanceUtils.DEGREES_TO_RADIANS,
        points.toArray(GeoPoint[]::new));

// ShapeRectRelationTestCase.testGeoPathRect
final double width = random().nextInt(89) + 1; // degrees, like the circle radius above

Trade-offs

• Behaviour change: callers who already pass radians, as testGeoPathRect does today, get lines 57.3 times narrower. A CHANGES entry should say so (for example under "Changes in Runtime Behavior").
• Documents indexed with buffered lines keep the wide shape until they are reindexed (code reading, not executed).
• Without the test update testGeoPathRect still passes (run), but it would build corridors of 0.017 to 1.55 degrees instead of 1 to 89 and stop covering wide paths.
• Cost: one multiplication per line built.

What the checks validated

• Gradle, scratch worktree at a9779ef3c193, seed DEADBEEF: with the factory fix alone, the new test 3/3 with assertions on and off and the whole spatial-extras module 120 tests, 0 failures, 5 skipped (4 @Nightly, 1 @Ignore: TestBBoxStrategy.testBasicOperations); with the fix and the test update, the module again 120 tests, 0 failures, the same 5 skipped, the rect-relation suites with two more seeds (assertions on and off) and with -Ptests.nightly=true (15 tests, including testGeoPathRect on the sphere and on the ellipsoidal class, which picks WGS84 or CLARKE_1866 at random, 0 failures), and :lucene:spatial-extras:check -x test (google-java-format, ecjLint, forbiddenApis) passes. The nightly rect-relation tests also pass with the fix alone and on stock. The fourth @Nightly test, TestGeo3dRpt, passes with the full patch (4 tests, run by the fact check), so only the @Ignore test never ran.
• Standalone runner, patched class shadowed: this page's test 3/3 (assertions on and off), the finder's 2/2, the independent reproducer's 5/5, the devil's advocate's 5/5, and the index check 2/2 (1 hit instead of 3).

Store the converted value: this.distance = distance * DistanceUtils.DEGREES_TO_RADIANS;. Same behaviour as A; a matter of taste (A keeps the field in the caller's unit).

Trade-offs

Same compatibility and reindexing notes as A; it also needs the testGeoPathRect update.

What the checks validated

Standalone runner only, patched class shadowed: this page's test 3/3 with assertions on and off.

After A, a buffer above 90 degrees (90.01 in the probe) still fails with "Cutoff angle out of bounds", which names a spatial3d parameter the caller never passed. A check in build() with the limit in degrees would be clearer.

Trade-offs

Not written or tested. For the probe's two-point equatorial line, a buffer of exactly 90 degrees already fails later with "path too wide"; other lines were not tried.

Keep the behaviour and state on Geo3dShapeFactory that line buffers are radians.

Trade-offs

Leaves every parsed buffered line wrong: spatial4j's polyshape and GeoJSON readers pass degrees, and normDist cannot convert for lines alone, because the polyshape reader uses the same normDist for circle radii, which circle() already converts.

Method: code reading plus differential testing (the non-formal tier), in a hunt unit on the spatial-extras bridge between spatial4j and spatial3d.

• The unit's harness compares shapes built by the Geo3d context with the same shapes built by spatial4j's SpatialContext.GEO and by the same factory's circles. While writing its line generator the finder checked each factory method's degrees-to-radians handling and found none for line buffers; the harness now passes buffers in radians so that its other checks do not depend on this question.
• A differential probe and then a JUnit confirmed it on the stock jars: the 1-degree line contains (5, 20) in the Geo3d context and not in spatial4j's, also when read from spatial4j's polyshape string.
• A later verifier found the second symptom: buffers above about 1.57 throw.