Skip to content

Update docs on vertex ordering to reflect that this is now specified … #27963

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 2, 2018
Merged

Update docs on vertex ordering to reflect that this is now specified … #27963

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8211d80
Update docs on vertex ordering to reflect that this is now specified …
DaveCTurner Dec 22, 2017
f51f275
Merge branch 'master' into 2017-12-22-vertex-ordering-docs
DaveCTurner Mar 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions docs/reference/mapping/types/geo-shape.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,22 +372,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