Shape doc values report the centroid (0, 0) for a line or polygon whose length or area is zero after encoding

A shape doc value (LatLonShape.createDocValueField, XYShape.createDocValueField) stores a bounding box and one centroid, returned by getCentroid(). The centroid averages the shape's pieces, each piece's midpoint weighted by its length (segments) or area (triangles), computed from the decoded (quantized) coordinates. When every piece has weight 0, the weighted sum is 0, and ShapeDocValues.buildTree skips the division (if (totalLength != 0), if (totalSignedArea != 0)) and stores the 0: the centroid becomes (0, 0). That happens for a line whose points are all equal, for two points in the same encoding cell (a few millimetres apart), for a polygon whose vertices become collinear after encoding (for example thinner than one latitude step), and for an XYLine of repeated points. A repeated-point line at (40, -70) gets its centroid 8,319 km away, outside the bounding box the same field returns; a 10-degree sliver polygon gets it at least 7,503 km off. The other public factory, createDocValueField(name, createIndexableFields(name, line)), returns the real point for the same line. Queries, relate() and the bounding box are unaffected, nothing throws, and the wrong value is stored in the index. Present in every release since 9.4.0, where the API was added.

• Shape doc value: LatLonShape.createDocValueField and XYShape.createDocValueField build a binary doc value holding the shape's pieces as a tree, plus a header with the bounding box, one centroid and the highest dimension (point, line or triangle). getCentroid() and getBoundingBox() read the header. The shape doc-values classes and fields are @lucene.experimental; the factory classes LatLonShape and XYShape are not tagged.
• Pieces: a line becomes one LINE piece per segment; a polygon is tessellated into TRIANGLE pieces; a point is one POINT piece.
• Encoding step: LatLonShape stores a latitude in steps of 4.190951585769653E-8 degrees and a longitude in steps of 8.381903171539307E-8 degrees (about 4.7 mm and 9.3 mm at the equator). Encoding rounds down (Math.floor), so points that fall into the same cell are one point in the index.

1. createDocValueField(name, Line) types every segment LINE, also a segment whose two ends encode to the same point (LatLonShape.java:153-174; XYShape.java:151-172 for XYLine). createDocValueField(name, Polygon) types every tessellated triangle TRIANGLE (LatLonShape.java:110-132).
2. The TreeNode constructor weights each piece's midpoint by its length or area, computed from the decoded encoded corners (ShapeDocValues.java:439-454). Equal corners give length 0, collinear corners area 0, so the weighted midpoint is 0.
3. buildTree divides by the total weight only if it is not 0, for one piece (:191-204) and for several (:265-288, if (totalLength != 0), if (totalSignedArea != 0)). Otherwise the 0 numerator stays as the centroid.
4. The writer encodes that centroid into the doc value (:491-493); the field and any value read back from the index decode it (:72-93, LatLonShapeDocValues.java:58-63, XYShapeDocValues.java:58-64), so (0, 0) is persisted.
5. The Field[] factory decodes each indexed triangle with ShapeField.resolveTriangleType (ShapeField.java:371, :374-399), which turns a triangle with all corners equal into a POINT; a single POINT piece keeps its decoded corner (ShapeDocValues.java:434-436) and several are averaged without weights (:266-268). So that route gets lines right, but for the sliver polygon it keeps a zero-area TRIANGLE and also gives (0, 0), in both winding orders.
6. One real segment is enough to make the total non-zero: a line (40, -70) (40, -70) (41, -69) gets the right centroid (40.5, -69.5). XYShape encodes a float exactly (XYEncodingUtils.encode is floatToSortableInt), so an XYLine triggers it only when all its points are identical; XYPolygons were not bounded (the three collinear or rounding-collinear ones tried were rejected by the tessellator). A LatLonShape polygon could also collapse along a meridian or a slanted line; only the latitude-thin sliver was executed.
7. relate() skips the stored centroid and the highest dimension before it walks the tree (ShapeDocValues.java:767-770), so shape doc-values queries do not use the wrong value.

Distances are great-circle distances on a sphere of radius 6371.0088 km. A doc-values box query around (40, -70) still matches the repeated-point line, and one around (0, 0) does not.

• Who is hit. Applications that index LatLonShape or XYShape doc values (createDocValueField, default codec and IndexWriterConfig) and read getCentroid(), at index time or from a value read back with LatLonShape.createLatLonShapeDocValues(BytesRef) / XYShape.createXYShapeDocValues(BytesRef). The introducing PR's author said the centroid and bounding box were added for downstream aggregations. Lucene itself has no caller of the shape getCentroid() outside the getters. The shape doc-values classes and fields are @lucene.experimental; the factory classes LatLonShape and XYShape are not tagged.
• What it takes. One document whose whole length or area is zero after encoding: a line of repeated points or of points in one encoding cell built with createDocValueField(name, Line) / (name, XYLine), or a polygon that is flat after encoding (for example thinner than one latitude step) through either factory. Deterministic, with assertions on and off.
• What goes wrong. That document's centroid is (0, 0), an ordinary-looking location, so a caller cannot tell it from a real shape there; getHighestDimensionType() still says LINE or TRIANGLE. Anything computed from it is off by thousands of kilometres.
• Persistent. The value is stored in the doc value and read back unchanged, so a writer fix leaves documents already indexed at (0, 0) until they are re-indexed, unless a read-time fallback is added too.
• Not affected. Shape doc-values queries (relate() skips the centroid; the hunt's 499,269,156 relate() checks found 0 mismatches), the bounding box, other documents, the indexed shape and its queries. Nothing throws and nothing costs more.
• How likely. Rare: the experimental API, a reader of getCentroid(), and a zero-length or zero-area shape. Such shapes are legal input; no report was found in the searches (see Prior reports), four years after 9.4.0.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: latitude expected:<40.0> but was:<0.0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:555)
       org.apache.lucene.document.TestShapeDocValuesRepeatedPointCentroid.testCentroidOfLineWithRepeatedPoint(TestShapeDocValuesRepeatedPointCentroid.java:13)

• The contract. "retrieves the centroid location for the geometry" (ShapeDocValuesField.java:97-98, LatLonShapeDocValuesField.java:65-69, XYShapeDocValuesField.java:65-69). (0, 0) is not a location of these geometries and lies thousands of kilometres outside the bounding box the same object returns.
• Legal inputs. Line and XYLine check only null arrays, equal lengths, at least 2 points and the value range (Line.java:53-87, XYLine.java:47-79). The tessellator accepts the sliver polygon.
• Lucene disagrees with itself. The Field[] factory returns (40, -70) for the same line that the Line factory maps to (0, 0).
• No fallback is defined. No javadoc, CHANGES entry or test names (0, 0) as a sentinel, and the stored highest dimension still says LINE or TRIANGLE.
• History. The guards came with the feature (d7fd48c9502c, #1017) and never changed. The #1017 review discussed centroid weighting at length (multi-polygon weighting, encoded versus original coordinates, overflow), never zero-length or zero-area shapes.
• Common practice. JTS's Centroid, which a #1017 reviewer used as the reference, documents "Zero-length lines are treated as points" (class javadoc) and computes degenerate geometry "using their effective dimension" (a code comment in getCentroid()). Elasticsearch fixed the same kind of defect in its own, separate centroid code in 2020 by treating zero-area polygons as lines and zero-length lines as points (elastic/elasticsearch#52303, fixed by #52500; also #55851 / #58027).

The strongest case for intended behaviour (the hunt's intended-behaviour checker; the cross-model reviews rated it moderate): the API is @lucene.experimental and #1017 was merged as progress over perfection; a length- or area-weighted centroid of a shape with no length or area is 0/0, undefined, and the guards show the zero case was considered; the upstream test's reference centroid substitutes a denominator of 1 (TestShapeDocValues.java:133, totalSignedArea = totalSignedArea == 0d ? 1 : totalSignedArea;), which also gives (0, 0); a line of identical points is not a valid OGC LineString; the encoding is documented as lossy; and GEOS returns an empty centroid for a zero-length line (shapely#107).

Why it fails: an undefined weighted average still has a well-established fallback, the effective dimension (JTS, Elasticsearch), and Lucene's own Field[] factory already gives it for lines. GEOS's empty centroid is the other precedent, but a caller can detect it; the guard here returns an ordinary location, so callers cannot. No test checks this input against an independent expectation: the centroid test (TestShapeDocValues.java:79-87) compares with a reference that copies the implementation's formula, zero case included (:133), so a zero-area polygon would pass there with (0, 0); the zero-area skip that #13743 added (area(p) != 0, the bounding-box area, :59, :261-263) is in the bounding-box test (:57-66). Lucene neither documents nor enforces OGC validity, and two triggers are valid geometry: two distinct points a few millimetres apart, and a non-collinear sliver polygon the tessellator accepts. The documented precision loss is tens of nanodegrees (about 42 of latitude and 84 of longitude); (0, 0) is thousands of kilometres off.

Option A (recommended) and option B were each applied in a scratch worktree at a9779ef3c193 and run through gradle, and checked as shadowed classes on the main jars; B is the hunt's fix, which an independent reproducer also wrote. C, D and E were not run. None repairs documents already indexed except D. The tests show that A and B remove (0, 0) and keep the existing tests passing; none checks the centroid of a flat polygon cut into several triangles. Workaround (executed): building line doc values with createDocValueField(name, createIndexableFields(name, line)) gives the right centroid for the line triggers (testFactoriesAgree), not for the sliver polygon.

Each of the four zero-weight branches in buildTree (ShapeDocValues.java:191-204, :265-288) calls a new helper instead of keeping 0 (+42 lines). Every piece of the zero-weight shape counts as its edges, length-weighted, and if no edge has a length either, every piece counts as its corners, averaged. A line is stored as the flat triangle (a, b, a) and a point as (a, a, a), and the edges of a flat piece cover it twice, so half a piece's perimeter is the length that piece covers and one formula serves all three types. For a line, a point and a polygon tessellated into one flat triangle this is the effective-dimension answer of JTS and of the Elasticsearch fix. Results: the repeated-point, one-cell and 4-point lines get lat 39.99999996, lon -70.00000002; the sliver polygon gets lon -65.00000007 (its middle) through both factories; the XYLine gets (5.0, 7.0); the controls are unchanged.

      if (totalLength != 0) {
        root.midX /= totalLength;
        root.midY /= totalLength;
+     } else {
+       setDegenerateCentroid(root, tessellation);
      }
...
+  private void setDegenerateCentroid(TreeNode node, List<ShapeField.DecodedTriangle> tessellation) {
+    Encoder encoder = getEncoder();
+    double length = 0, lengthX = 0, lengthY = 0;
+    double pointX = 0, pointY = 0;
+    for (ShapeField.DecodedTriangle t : tessellation) {
+      double ax = encoder.decodeX(t.aX), ay = encoder.decodeY(t.aY);
+      double bx = encoder.decodeX(t.bX), by = encoder.decodeY(t.bY);
+      double cx = encoder.decodeX(t.cX), cy = encoder.decodeY(t.cY);
+      double ab = Math.hypot(ax - bx, ay - by);
+      double bc = Math.hypot(bx - cx, by - cy);
+      double ca = Math.hypot(cx - ax, cy - ay);
+      // edge midpoints weighted by edge length, halved because the edges cover the shape twice
+      length += 0.5d * (ab + bc + ca);
+      lengthX += 0.25d * ((ax + bx) * ab + (bx + cx) * bc + (cx + ax) * ca);
+      lengthY += 0.25d * ((ay + by) * ab + (by + cy) * bc + (cy + ay) * ca);
+      pointX += ax + bx + cx;
+      pointY += ay + by + cy;
+    }
+    if (length != 0) {
+      node.midX = lengthX / length;
+      node.midY = lengthY / length;
+    } else {
+      node.midX = pointX / (3d * tessellation.size());
+      node.midY = pointY / (3d * tessellation.size());
+    }
+  }

Trade-offs

• Behaviour change: only shapes whose total length or area is zero after encoding get a new centroid; every other shape keeps its centroid bit for bit, because only the four branches that keep 0 today change.
• Not exact for a flat polygon of several triangles: it also counts the interior diagonals the triangles share, so its answer depends on how the tessellator cuts the polygon. A sliver of 11 distinct vertices (lon -70 to -60 and back inside one latitude cell) is cut into 2 triangles sharing the diagonal from lon -69.9 to -60: A gives lon -64.9751, B -64.9667, the length-weighted centroid of the polygon's own ring -65.00000002. Counting only the edges the tessellator flags as polygon edges gives the ring's answer there (recomputed by hand), but createDocValueField(name, Polygon) passes the first edge's flag for the second edge too (LatLonShape.java:125, XYShape.java:123), so that variant needs that line fixed as well (not run as a patch). The helper's javadoc and comment ("effective dimension", "the edges cover the shape twice") hold per piece; reword them if you use the patch.
• Inside the box: the result is a weighted average of the shape's own decoded corners. On 800,000 random repeated-point lines of 2, 3, 4 and 7 points it was exactly the point every time.
• Cost: one extra pass over the pieces, only for degenerate shapes. No format or API change.
• Existing data: documents already indexed keep (0, 0) until they are re-indexed (see option D).

What the checks validated

• Gradle in a scratch worktree at a9779ef3c193, seed DEADBEEF: the repro passes 8 of 8 with assertions on and off (stock: 6 of 8 fail).
• TestShapeDocValues and the six Test*ShapeDVQueries classes pass: 37 tests, 6 of them nightly-only and skipped, and all 37 with -Ptests.nightly=true. Every test class of org.apache.lucene.document passes (506 tests, 26 of them skipped). checkGoogleJavaFormat, ecjLintMain and ecjLintTest for lucene:core pass.
• As a shadowed class on the main jars: this repro 8 of 8 (assertions on and off), the independent reproducer's JUnit 10 of 10 and the finder's 5 of 5.

TreeNode also keeps each piece's plain midpoint (segment) or corner average (triangle); when the total length or area is 0, the centroid is the plain average of those (+34 lines). The finder and the independent reproducer wrote it separately. It gives the same results as option A on every input above; for a single line the two always agree, because a zero-length line is one point.

Trade-offs

For a flat polygon cut into several triangles it gives every triangle the same weight however long it is, so its answer depends on how the tessellator cuts the polygon (on the 11-vertex sliver cut into 2 triangles: lon -64.9667 against -64.9751 for option A and -65.00000002 for the polygon's ring); for one flat triangle it gives the average of the three corners, not the middle of the segment the triangle covers (by the patch's code). It adds two fields to every TreeNode.

What the checks validated

Gradle, the same worktree and seed: the repro passes 8 of 8 with assertions on and off, and the closest suites pass (37 tests, 6 of them nightly-only and skipped); as a shadowed class 8 of 8. In the hunt it also passed the finder's and the reproducer's JUnits and the 31 upstream shape doc-values tests.

When the total is 0, set the centroid to the middle of the encoded bounding box (about six lines).

Trade-offs

Not run. Always inside the box and exact for every line trigger, but for a degenerate shape that is not straight (an L-shaped sliver, say) it is not the shape's centroid.

When the decoded stored centroid lies outside the stored bounding box, computeCentroid() (LatLonShapeDocValues.java:58-63, XYShapeDocValues.java:58-64) returns the box centre instead.

Trade-offs

Not run. Repairs old documents without re-indexing, but it is a heuristic: it would also move centroids that are only one encoding step outside the box (the hunt counted 1,116 such non-degenerate shapes) to the box centre, it cannot repair a (0, 0) that lies inside the box, and it would mask other writer bugs.

A javadoc sentence that shapes with zero length or area after encoding get the centroid (0, 0).

Trade-offs

Not recommended. Callers still cannot tell the value from a real location, and the two factories still disagree.

Method: semi-formal, bounded-exhaustive checking of the stock jar (hunt unit on the shape doc-values tree, 2026-10-26, main ea57360912ed).

• A harness enumerated every sequence of up to 4 of 61 pieces on four 2x2 coordinate grids (three LatLon, one XY), up to 3 of 186 pieces on a 3x2 LatLon grid, and 500,000 random trees of 1 to 64 pieces: points (a, a, a), lines (a, b, a) including a = b, and canonical triangles including collinear ones; these are sequences of pieces, not necessarily the pieces of one valid Line or Polygon. 63,276,054 trees in all, run once with assertions on and once off.
• For each tree it decoded the bytes with an independent reference decoder, checked 499,269,156 relate() calls against a brute-force relation (0 mismatches), and recomputed the centroid with the same formula plus a check that the centroid lies inside the bounding box.
• 376,260 trees had zero total weight; 54,182 of them had the centroid (0, 0) outside the box (the rest have boxes that contain (0, 0)). 8 of 8 seeded mutants of ShapeDocValues were killed, so the checks are not vacuous.
• The finder then wrote a JUnit on the public factories and confirmed it on main, 10.5.2, 9.12.3 and 9.4.0. The harness also counted 1,116 shapes with non-zero weight whose centroid lies one encoding step outside the box; that was not triaged and is not part of this bug.