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

jrodewig · 2022-02-16T13:04:41Z

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.

Preview

https://elasticsearch_84025.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/geo-shape.html#geo-polygon

elasticmachine · 2022-02-16T13:37:23Z

Pinging @elastic/es-docs (Team:Docs)

elasticmachine · 2022-02-16T13:37:24Z

Pinging @elastic/es-analytics-geo (Team:Analytics)

iverase · 2022-02-16T13:54:23Z

What I learnt today goes even further.

The orientation parameter in the geo_shape field only affects geometries indexed using WKT (because WKT does not enforce vertex order). If indexing geojson the parameter is ignored and orientation is assumed to be CCW regardless of that parameter as in the standard.

Still you can enforce the orientation of a geojson geometry by adding the parameter orientation in the geojson itself like in:

POST /example/_doc
{
  "location" : {
    "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] ]
    ]
  }
}

jrodewig · 2022-02-16T19:40:15Z

Thanks for the clarification @iverase. Rather than re-add the previous note as-is, I reworked the current polygon orientation docs to include the relevant content. Let me know what you think.

iverase

We need to do just a small correction.

While we are here, should we update the Geojson examples so the types are properly capitalise?

Check it here: https://en.wikipedia.org/wiki/GeoJSON

iverase · 2022-02-17T08:05:32Z

docs/reference/mapping/types/geo-shape.asciidoc

+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


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

iverase

Thanks for your patience @jrodewig!

jrodewig · 2022-02-17T14:59:08Z

Thanks @iverase!

jrodewig · 2022-02-17T15:35:32Z

💚 All backports created successfully

Status	Branch	Result
✅	8.1
✅	8.0
✅	7.17
✅	7.16
✅	7.15
✅	7.14

Questions ?

Please refer to the Backport tool documentation

…) (#84130) 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)

…) (#84132) 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)

…) (#84131) 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)

…) (#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)

…) (#84133) 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)

…) (#84135) 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)

* upstream/master: (167 commits) Mute FrozenSearchableSnapshotsIntegTests#testCreateAndRestorePartialSearchableSnapshot Mute LdapSessionFactoryTests#testSslTrustIsReloaded Fix spotless violation from last commit Mute GeoGridTilerTestCase#testGeoGridSetValuesBoundingBoxes_UnboundedGeoShapeCellValues Small formatting clean up (elastic#84144) Always re-run Feature migrations which have encountered errors (elastic#83918) [DOCS] Clarify `orientation` usage for WKT and GeoJSON polygons (elastic#84025) Group field caps response by index mapping hash (elastic#83494) Shrink join queries in slow log (elastic#83914) TSDB: Reject the nested object fields that are configured time_series_dimension (elastic#83920) [DOCS] Remove note about partial response from Bulk API docs (elastic#84053) Allow regular data streams to be migrated to tsdb data streams. (elastic#83843) [DOCS] Fix `ignore_unavailable` parameter definition (elastic#84071) Make Metadata extend AbstractCollection (elastic#83791) Add API specs for OpenID Connect APIs Revert "Clean up for superuser role name references (elastic#83627)" (elastic#84096) Update Lucene analysis base url (elastic#84094) Avoid null threadContext in ResultDeduplicator (elastic#84093) Use static empty store files metadata (elastic#84034) Preserve context in snapshotDeletionListeners (elastic#84089) ... # Conflicts: # x-pack/plugin/rollup/build.gradle

…tic#84025) 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 elastic#84009.

elasticsearchmachine added the v8.2.0 label Feb 16, 2022

jrodewig added :Analytics/Geo Indexing, search aggregations of geo points and shapes >docs General docs changes v7.14.3 v7.15.3 v7.16.4 v7.17.1 v8.0.1 v8.1.1 labels Feb 16, 2022

[DOCS] Re-add note about WKT and GeoJSON vertex order

dcd81e5

jrodewig requested a review from iverase February 16, 2022 13:37

jrodewig marked this pull request as ready for review February 16, 2022 13:37

elasticmachine added Team:Docs Meta label for docs team Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) labels Feb 16, 2022

Clarify orientation usage for WKT and GeoJSON polygons

996a4ed

jrodewig changed the title ~~[DOCS] Re-add note about WKT and GeoJSON vertex order~~ [DOCS] Clarify orientation usage for WKT and GeoJSON polygons Feb 16, 2022

jrodewig added 2 commits February 16, 2022 14:35

reword

4184263

reword

7df3b5d

iverase requested changes Feb 17, 2022

View reviewed changes

jrodewig added 2 commits February 17, 2022 09:34

Address review feedback

093428e

More corrections

a667f3e

iverase approved these changes Feb 17, 2022

View reviewed changes

fix geoshape inconsistency

8f65b14

jrodewig merged commit 6ad3f8b into elastic:master Feb 17, 2022

jrodewig deleted the docs__rea-add-vertices-order-note branch February 17, 2022 15:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jrodewig commented Feb 16, 2022 •

edited

Loading

elasticmachine commented Feb 16, 2022

elasticmachine commented Feb 16, 2022

iverase commented Feb 16, 2022 •

edited

Loading

jrodewig commented Feb 16, 2022

iverase left a comment

iverase Feb 17, 2022 •

edited

Loading

iverase left a comment

jrodewig commented Feb 17, 2022

jrodewig commented Feb 17, 2022

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

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

Conversation

jrodewig commented Feb 16, 2022 • edited Loading

Preview

elasticmachine commented Feb 16, 2022

elasticmachine commented Feb 16, 2022

iverase commented Feb 16, 2022 • edited Loading

jrodewig commented Feb 16, 2022

iverase left a comment

Choose a reason for hiding this comment

iverase Feb 17, 2022 • edited Loading

Choose a reason for hiding this comment

iverase left a comment

Choose a reason for hiding this comment

jrodewig commented Feb 17, 2022

jrodewig commented Feb 17, 2022

💚 All backports created successfully

Questions ?

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

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

jrodewig commented Feb 16, 2022 •

edited

Loading

iverase commented Feb 16, 2022 •

edited

Loading

iverase Feb 17, 2022 •

edited

Loading