Skip to content

Commit

Permalink
[DOCS] Clarify orientation usage for WKT and GeoJSON polygons (#84025…
Browse files Browse the repository at this point in the history 
…) (#84134)

Clarifies that the `orientation` mapping parameter only applies to WKT polygons. GeoJSON polygons use a default orientation of `RIGHT`, regardless of the mapping parameter.

Also notes that the document-level `orientation` parameter overrides the default orientation for both WKT and GeoJSON polygons.

Closes #84009.

(cherry picked from commit 6ad3f8b)
  • Loading branch information
@jrodewig
jrodewig authored Feb 17, 2022
1 parent 9602b3d commit 85b56bf
Showing 1 changed file with 42 additions and 35 deletions.
77 changes: 42 additions & 35 deletions docs/reference/mapping/types/geo-shape.asciidoc
View file
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

0 comments on commit 85b56bf

Please sign in to comment.