Skip to content

[DOCS] Clarify orientation usage for WKT and GeoJSON polygons #84025

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 7 commits into from
Feb 17, 2022
Merged

[DOCS] Clarify orientation usage for WKT and GeoJSON polygons #84025

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
dcd81e5
[DOCS] Re-add note about WKT and GeoJSON vertex order
jrodewig Feb 16, 2022
996a4ed
Clarify `orientation` usage for WKT and GeoJSON polygons
jrodewig Feb 16, 2022
4184263
reword
jrodewig Feb 16, 2022
7df3b5d
reword
jrodewig Feb 16, 2022
093428e
Address review feedback
jrodewig Feb 17, 2022
a667f3e
More corrections
jrodewig Feb 17, 2022
8f65b14
fix geoshape inconsistency
jrodewig Feb 17, 2022
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
35 changes: 21 additions & 14 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 @@ -26,7 +26,7 @@ type.

|`orientation`
a|Optional. Default <<polygon-orientation,orientation>> for the field's
polygons.
WKT polygons.

This parameter sets and returns only a `RIGHT` (counterclockwise) or `LEFT`
(clockwise) value. However, you can specify either value in multiple ways.
Expand Down Expand Up @@ -257,15 +257,22 @@ POST /example/_doc
===== Polygon orientation

A polygon's orientation indicates the order of its vertices: `RIGHT`
(counterclockwise) or `LEFT` (clockwise).
(counterclockwise) or `LEFT` (clockwise). {es} uses a polygon’s orientation to
determine if it crosses the international dateline (+/-180° longitude).

You can set a default orientation for a `geo_shape` field using the
<<geo-shape-mapping-options,`orientation` mapping parameter>>. You can override
this default for specific polygons using the document-level `orientation`
parameter.
You can set a default orientation for WKT polygons using the
<<geo-shape-mapping-options,`orientation` mapping parameter>>. This is because
the WKT specification doesn't specify or enforce a default orientation.

For example, the following indexing request specifies a document-level
`orientation` of `LEFT`.
GeoJSON polygons use a default orientation of `RIGHT`, regardless of
`orientation` mapping parameter's value. This is because the
https://tools.ietf.org/html/rfc7946#section-3.1.6[GeoJSON specification]
mandates that an outer polygon use a counterclockwise orientation and interior
shapes use a clockwise orientation.

You can override the default orientation for WKT and GeoJSON polygons using the
document-level `orientation` parameter. For example, the following indexing
Copy link
Contributor

@iverase iverase Feb 17, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is true for WKT as you cannot add a document level orientation, that's the reason you need to do it in the mapping.

For GeoJson it is done as shown in the example

request specifies a document-level `orientation` of `LEFT`.

[source,console]
----
Expand All @@ -282,15 +289,15 @@ POST /example/_doc
----

{es} only uses a polygon’s orientation to determine if it crosses the
international dateline (+/-180° longitude). If the difference between a
polygon’s minimum longitude and the maximum longitude is less than 180°, the
polygon doesn't cross the dateline and its orientation has no effect.
international dateline. If the difference between a polygon’s minimum longitude
and the maximum longitude is less than 180°, the polygon doesn't cross the
dateline and its orientation has no effect.

If the difference between a polygon’s minimum longitude and the maximum
longitude is 180° or greater, {es} checks whether the polygon's document-level
`orientation` differs from the default in the `orientation` mapping parameter.
If the orientation differs, {es} considers the polygon to cross the
international dateline and splits the polygon at the dateline.
`orientation` differs from the default orientation. If the orientation differs,
{es} considers the polygon to cross the international dateline and splits the
polygon at the dateline.

[discrete]
[[geo-multipoint]]
Expand Down