Skip to content
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

[7.15] [DOCS] Clarify orientation usage for WKT and GeoJSON polygons (#84025) #84134

Merged
merged 1 commit into from
Feb 17, 2022
Merged

[7.15] [DOCS] Clarify orientation usage for WKT and GeoJSON polygons (#84025) #84134

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
77 changes: 42 additions & 35 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 @@ -5,7 +5,7 @@
++++

The `geo_shape` data type facilitates the indexing of and searching
with arbitrary geo shapes such as rectangles and polygons. It should be
with arbitrary geoshapes such as rectangles and polygons. It should be
used when either the data being indexed or the queries being executed
contain shapes other than just points.

Expand Down Expand Up @@ -98,7 +98,7 @@ greater false positives. Note: This parameter is only relevant for `term` and

|`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 @@ -147,7 +147,7 @@ and reject the whole document.
[[geoshape-indexing-approach]]
[discrete]
==== Indexing approach
GeoShape types are indexed by decomposing the shape into a triangular mesh and
Geoshape types are indexed by decomposing the shape into a triangular mesh and
indexing each triangle as a 7 dimension point in a BKD tree. This provides
near perfect spatial resolution (down to 1e-7 decimal degree precision) since all
spatial relations are computed using an encoded vector representation of the
Expand Down Expand Up @@ -332,7 +332,7 @@ API. The following is an example of a point in GeoJSON.
POST /example/_doc
{
"location" : {
"type" : "point",
"type" : "Point",
"coordinates" : [-77.03653, 38.897676]
}
}
Expand All @@ -352,23 +352,23 @@ POST /example/_doc
[[geo-linestring]]
===== http://geojson.org/geojson-spec.html#id3[LineString]

A `linestring` defined by an array of two or more positions. By
specifying only two points, the `linestring` will represent a straight
A linestring defined by an array of two or more positions. By
specifying only two points, the linestring will represent a straight
line. Specifying more than two points creates an arbitrary path. The
following is an example of a LineString in GeoJSON.
following is an example of a linestring in GeoJSON.

[source,console]
--------------------------------------------------
POST /example/_doc
{
"location" : {
"type" : "linestring",
"type" : "LineString",
"coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]]
}
}
--------------------------------------------------

The following is an example of a LineString in WKT:
The following is an example of a linestring in WKT:

[source,console]
--------------------------------------------------
Expand All @@ -378,7 +378,7 @@ POST /example/_doc
}
--------------------------------------------------

The above `linestring` would draw a straight line starting at the White
The above linestring would draw a straight line starting at the White
House to the US Capitol Building.

[discrete]
Expand All @@ -387,22 +387,22 @@ House to the US Capitol Building.

A polygon is defined by a list of a list of points. The first and last
points in each (outer) list must be the same (the polygon must be
closed). The following is an example of a Polygon in GeoJSON.
closed). The following is an example of a polygon in GeoJSON.

[source,console]
--------------------------------------------------
POST /example/_doc
{
"location" : {
"type" : "polygon",
"type" : "Polygon",
"coordinates" : [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
]
}
}
--------------------------------------------------

The following is an example of a Polygon in WKT:
The following is an example of a polygon in WKT:

[source,console]
--------------------------------------------------
Expand All @@ -421,7 +421,7 @@ of a polygon with a hole:
POST /example/_doc
{
"location" : {
"type" : "polygon",
"type" : "Polygon",
"coordinates" : [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
[ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
Expand All @@ -430,7 +430,7 @@ POST /example/_doc
}
--------------------------------------------------

The following is an example of a Polygon with a hole in WKT:
The following is an example of a polygon with a hole in WKT:

[source,console]
--------------------------------------------------
Expand All @@ -445,22 +445,29 @@ 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 GeoJSON polygons using the
document-level `orientation` parameter. For example, the following indexing
request specifies a document-level `orientation` of `LEFT`.

[source,console]
----
POST /example/_doc
{
"location" : {
"type" : "polygon",
"type" : "Polygon",
"orientation" : "LEFT",
"coordinates" : [
[ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ]
Expand All @@ -470,15 +477,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 All @@ -491,7 +498,7 @@ The following is an example of a list of GeoJSON points:
POST /example/_doc
{
"location" : {
"type" : "multipoint",
"type" : "MultiPoint",
"coordinates" : [
[102.0, 2.0], [103.0, 2.0]
]
Expand Down Expand Up @@ -520,7 +527,7 @@ The following is an example of a list of GeoJSON linestrings:
POST /example/_doc
{
"location" : {
"type" : "multilinestring",
"type" : "MultiLineString",
"coordinates" : [
[ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0] ],
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0] ],
Expand Down Expand Up @@ -551,7 +558,7 @@ The following is an example of a list of GeoJSON polygons (second polygon contai
POST /example/_doc
{
"location" : {
"type" : "multipolygon",
"type" : "MultiPolygon",
"coordinates" : [
[ [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]] ],
[ [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
Expand Down Expand Up @@ -582,14 +589,14 @@ The following is an example of a collection of GeoJSON geometry objects:
POST /example/_doc
{
"location" : {
"type": "geometrycollection",
"type": "GeometryCollection",
"geometries": [
{
"type": "point",
"type": "Point",
"coordinates": [100.0, 0.0]
},
{
"type": "linestring",
"type": "LineString",
"coordinates": [ [101.0, 0.0], [102.0, 1.0] ]
}
]
Expand Down