1
0
Эх сурвалжийг харах

Update docs on vertex ordering (#27963)

At time of writing, GeoJSON did not enforce a specific ordering of vertices in
a polygon, but it now does. We occasionally get reports of Elasticsearch
rejecting apparently-valid GeoJSON because of badly oriented polygons, and it's
helpful to be able to point at this bit of the documentation when responding.
David Turner 7 жил өмнө
parent
commit
3ca9310aee

+ 18 - 16
docs/reference/mapping/types/geo-shape.asciidoc

@@ -378,22 +378,24 @@ POST /example/doc
 // CONSOLE
 // TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]
 
-*IMPORTANT NOTE:* GeoJSON and WKT do not enforce a specific order for vertices
-thus ambiguous polygons around the dateline and poles are possible. To alleviate
-ambiguity the Open Geospatial Consortium (OGC)
-http://www.opengeospatial.org/standards/sfa[Simple Feature Access] specification
-defines the following vertex ordering:
-
-* Outer Ring - Counterclockwise
-* Inner Ring(s) / Holes - Clockwise
-
-For polygons that do not cross the dateline, vertex order will not matter in
-Elasticsearch. For polygons that do cross the dateline, Elasticsearch requires
-vertex ordering to comply with the OGC specification. Otherwise, an unintended polygon
-may be created and unexpected query/filter results will be returned.
-
-The following provides an example of an ambiguous polygon.  Elasticsearch will apply
-OGC standards to eliminate ambiguity resulting in a polygon that crosses the dateline.
+*IMPORTANT NOTE:* WKT does not enforce a specific order for vertices thus
+ambiguous polygons around the dateline and poles are possible.
+https://tools.ietf.org/html/rfc7946#section-3.1.6[GeoJSON] mandates that the
+outer polygon must be counterclockwise and interior shapes must be clockwise,
+which agrees with the Open Geospatial Consortium (OGC)
+http://www.opengeospatial.org/standards/sfa[Simple Feature Access]
+specification for vertex ordering.
+
+Elasticsearch accepts both clockwise and counterclockwise polygons if they
+appear not to cross the dateline (i.e. they cross less than 180° of longitude),
+but for polygons that do cross the dateline (or for other polygons wider than
+180°) Elasticsearch requires the vertex ordering to comply with the OGC and
+GeoJSON specifications. Otherwise, an unintended polygon may be created and
+unexpected query/filter results will be returned.
+
+The following provides an example of an ambiguous polygon.  Elasticsearch will
+apply the GeoJSON standard to eliminate ambiguity resulting in a polygon that
+crosses the dateline.
 
 [source,js]
 --------------------------------------------------