Skip to content

Commit

Permalink
Update docs on vertex ordering (#27963)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
DaveCTurner authored Apr 2, 2018
1 parent e70cd35 commit 3ca9310
Showing 1 changed file with 18 additions and 16 deletions.
34 changes: 18 additions & 16 deletions docs/reference/mapping/types/geo-shape.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
--------------------------------------------------
Expand Down

0 comments on commit 3ca9310

Please sign in to comment.