[Doc] update geoJSON example file to prevent errors (#1277)

* for geoJSON file that has same start/endpoints for each polygon. see issue with more info #794 (comment) Signed-off-by: alicejw <[email protected]> * for additional images with borders and fixed errors in example GeoJSON file so it is cut and paste ready to use Signed-off-by: alicejw <[email protected]> * rename new image file because replacing file with same name caused build conflict Signed-off-by: alicejw <[email protected]> * image rename Signed-off-by: alicejw <[email protected]> * for doc reviewer edits and more clarification to procedural steps Signed-off-by: alicejw <[email protected]> * fix typo in UI name 'Region Map' visualization type Signed-off-by: alicejw <[email protected]> * to add prerequisite callout for the two required plugins Signed-off-by: alicejw <[email protected]> * remove commented-out note for link. unnecessary Signed-off-by: alicejw <[email protected]> * for doc review updates - changed example JSON file to include only 2 counties, and other rewrites Signed-off-by: alicejw <[email protected]> * remove modified region map and use original map with 2 counties Signed-off-by: alicejw <[email protected]> * we decided to show the grey outlined regions in the image Signed-off-by: alicejw <[email protected]> Signed-off-by: alicejw <[email protected]> (cherry picked from commit a1d79db)
opensearch-project · Sep 26, 2022 · 0006b2d · 0006b2d
1 parent 95e8d3b
commit 0006b2d
Show file tree

Hide file tree

Showing 6 changed files with 24 additions and 25 deletions.
diff --git a/_dashboards/geojson-regionmaps.md b/_dashboards/geojson-regionmaps.md
@@ -8,19 +8,25 @@ nav_order: 7
 
 OpenSearch Dashboards provides basic map tiles with a standard vector map that you can use to create your region map visualizations. You can configure the base map tiles using the Web Map Service (WMS) map server.
 
-You cannot configure a server to support user-defined vector map layers. However, you can configure your own GeoJSON file and upload it for this purpose. 
+You can't configure a server to support user-defined vector map layers. However, you can configure your own GeoJSON file and upload it for this purpose.
 {: .note}
 
 OpenSearch also has a standard set of GeoJSON files to provide a vector map with your regional maps.
 
 ## Custom vector maps with GeoJSON
 
-If you have a specific locale that is not provided by OpenSearch Dashboards vector maps, such as a US county or US ZIP Code, you can create your own custom vector map with a GeoJSON file. To use this feature, you have to install both the [Dashboards-Maps frontend plugin](https://github.com/opensearch-project/dashboards-maps) and the [OpenSearch Geospatial backend plugin](https://github.com/opensearch-project/geospatial).
+If you have a specific locale that is not provided by OpenSearch Dashboards vector maps, such as a US county or US ZIP Code, you can create your own custom vector map with a GeoJSON file. To create a custom region map you would define a geographic shape such as a polygon with multiple coordinates. To learn more about the various geographic shapes that support a custom region map location, see [Geoshape field type]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/).
 
 GeoJSON format allows you to encode geographic data structures. To learn more about the GeoJSON specification, go to [geojson.org](https://geojson.org/).
 
 You can use [geojson.io](https://geojson.io/#map=2/20.0/0.0) to extract GeoJSON files.
-{: .tip}
+
+>   **PREREQUISITE**
+>   To use a custom vector map with GeoJSON, install these two required plugins:
+>   * OpenSearch Dashboards Maps [`dashboards-maps`](https://github.com/opensearch-project/dashboards-maps) front-end plugin
+>   * OpenSearch [`geospatial`](https://github.com/opensearch-project/geospatial) backend plugin
+{: .note}
+### Step 1: Create a region map visualization
 
 To create your own custom vector map, upload a JSON file that contains GEO data for your customized regional maps. The JSON file contains vector layers for visualization.
 
@@ -29,42 +35,35 @@ To create your own custom vector map, upload a JSON file that contains GEO data
 1. Select the **Create Visualization** button.
 1. Select **Region Map**.
 1. Choose a source. For example, **[Flights] Flight Log**.
-1. In the right panel, select **Import Vector Map**. 
+1. In the right panel, select **Import Vector Map**.
 1. In **Upload map**, select or drag and drop your JSON file.
-Enter **Map name prefix** (for example, `us-county`). Your map will have the prefix that you defined followed by the `-map` suffix (for example, `us-county-map`). 
-Select the **Import file** button. 
-Once the upload is successful, you will see a pop-up prompting you to refresh the map. Select the **Refresh** button.
+Enter **Map name prefix** (for example, `usa-counties`). Your map will have the prefix that you defined followed by the `-map` suffix (for example, `usa-counties-map`). <img src="{{site.url}}{{site.baseurl}}/images/import-geojson-file.png" alt="import a Geo .json file" width="340"/>
+1. Select the **Import file** button.
+Once the upload is successful, you will see a pop-up prompting you to refresh the map. Select the **Refresh** button. <img src="{{site.url}}{{site.baseurl}}/images/upload-success.png" alt="message upon a successful file upload" width="280"/>
 
-<img src="{{site.url}}{{site.baseurl}}/images/import-vector-map.png" alt="import a Geo .json file" width="380"/>
+### Step 2: View the custom region map in OpenSearch Dashboards
 
-## Layer options
+After you upload a custom GeoJSON file, you need to set the vector map layer to custom, and select your vector map:
 
-If you upload a custom GeoJSON file, you can toggle between two layer options: **Default vector map** or **Custom vector map**. To use your custom vector map, follow the steps below.
-
-1. On the top menu bar, go to **OpenSearch Dashboards > Visualize**.
-1. Select the **Create Visualization** button.
-1. Select **Region Map**.
-1. Choose a source. For example, **[Flights] Flight Log**.
-1. In the right panel, select **Layer Options**. 
-1. In the **Layer settings** section, under **Choose a vector map layer**, select the **Custom vector map** option. In **Vector map**, select the custom map you created. Select the **Update** button.
-
-Under **Layer settings > Style settings**, you may want to increase **Border thickness** to see the borders more clearly.
-{: .tip}
+1. From **Layer Options > Layer settings**, select **Custom vector map**.
+1. Under **Vector map**, select the name of the vector map that you just uploaded.
+1. *(Optional):* Under **Style settings**, increase **Border thickness** to see the borders more clearly.
+1. Select the **Update** button.
+1. View your region map in the Dashboards. For example, the following image shows the Los Angeles and San Diego county regions:
+<img src="{{site.url}}{{site.baseurl}}/images/county-region-map.png" alt="view a custom GeoJSON region map" width="700"/>
 
 ### Example GeoJSON file
 
-The following example GeoJSON file provides coordinates for five US counties.
+The following example GeoJSON file provides coordinates for two US counties.
 
 ```json
 {
   "type": "FeatureCollection",
   "name": "usa counties",
   "features": [
-    { "type": "Feature", "properties": { "iso2": "US", "iso3": "KC-WA", "name": "King County", "country": "US", "county": "KC" }, "geometry": { "type": "Polygon", "coordinates":[[[-122.43713378906249,48.57842428752037],[-122.43713378906249,48.57842428752037],[-122.3712158203125,48.26491251331118],[-122.36022949218749,48.14043243818811],[-122.244873046875,48.026672195436014],[-122.2723388671875,47.916342040161155],[-122.4151611328125,47.82053186746053],[-122.4591064453125,47.69867153529717],[-122.398681640625,47.56911375866714],[-122.3272705078125,47.48380086737799],[-122.3382568359375,47.368594345213374],[-122.45361328124999,47.29040793812928],[-122.607421875,47.26804770458176],[-122.574462890625,47.09630525444073],[-122.50305175781249,46.924007100770275],[-122.354736328125,46.86394700508323],[-122.1185302734375,46.856434763486966],[-121.65710449218749,46.89023157359399],[-121.4483642578125,46.976504510552],[-121.3604736328125,47.05515408550348],[-121.28356933593749,47.212105775622426],[-121.2176513671875,47.35371061951363],[-121.0748291015625,47.468949677672484],[-120.9979248046875,47.56540738772852],[-120.9210205078125,47.724544549099676],[-120.8551025390625,48.026672195436014],[-120.87158203125,48.184401125107684],[-120.948486328125,48.37449671682332],[-121.1077880859375,48.542068763606466],[-121.5087890625,48.56388521347092],[-121.87683105468749,48.545705491847464],[-122.06909179687501,48.55297816440071],[-122.3052978515625,48.5493419587775],[-122.43713378906249,48.57842428752037]]] } },
-    { "type": "Feature", "properties": { "iso2": "US", "iso3": "SJ-WA", "name": "San Juan County", "country": "US", "county": "SJ" }, "geometry": { "type": "Polygon", "coordinates":[[[-122.96173095703125,48.73807825631017],[-123.04962158203124,48.71452483966837],[-123.1512451171875,48.66012869453836],[-123.19244384765625,48.61656946813302],[-123.17596435546876,48.56206753526866],[-123.14849853515625,48.5275192374508],[-123.07708740234374,48.480204398955145],[-122.98645019531249,48.45653041501911],[-122.8875732421875,48.44195631996267],[-122.8106689453125,48.438312142641244],[-122.78594970703126,48.44560023585716],[-122.78594970703126,48.505687108189804],[-122.78320312499999,48.545705491847464],[-122.79144287109375,48.59477574898104],[-122.77496337890625,48.62383195130112],[-122.7557373046875,48.65105695744785],[-122.73651123046874,48.69821216562637],[-122.84637451171874,48.72358515157852],[-122.96173095703125,48.73807825631017]]] } },
-    { "type": "Feature", "properties": { "iso2": "US", "iso3": "WW-WA", "name": "Walla Walla County", "country": "US", "county": "WW" }, "geometry": { "type": "Polygon", "coordinates":[[[-118.33442687988281,46.09204333606358],[-118.34884643554688,46.088709905656856],[-118.37047576904297,46.07561233580712],[-118.38249206542967,46.0653702518009],[-118.3838653564453,46.05298193687039],[-118.3787155151367,46.04416548185682],[-118.3656692504883,46.03558595870985],[-118.35159301757811,46.030818981314766],[-118.33339691162111,46.02819696848244],[-118.3114242553711,46.02938880791639],[-118.29666137695312,46.03201076421151],[-118.2784652709961,46.038922598236],[-118.2722854614258,46.0536967228988],[-118.2619857788086,46.076564991185734],[-118.25752258300781,46.092757616368665],[-118.2630157470703,46.10513700514936],[-118.29288482666016,46.10085214663405],[-118.31794738769531,46.09680503002718],[-118.33442687988281,46.09204333606358]]] } },
     { "type": "Feature", "properties": { "iso2": "US", "iso3": "LA-CA", "name": "Los Angeles County", "country": "US", "county": "LA" }, "geometry": { "type": "Polygon", "coordinates":[[[-118.71826171875,34.07086232376631],[-118.69628906249999,34.03445260967645],[-118.56994628906249,34.02990029603907],[-118.487548828125,33.957030069982316],[-118.37219238281249,33.86129311351553],[-118.45458984375,33.75631505992707],[-118.33923339843749,33.715201644740844],[-118.22937011718749,33.75631505992707],[-118.1414794921875,33.678639851675555],[-117.9107666015625,33.578014746143985],[-117.75146484375,33.4955977448657],[-117.55920410156249,33.55512901742288],[-117.3065185546875,33.5963189611327],[-117.0703125,33.67406853374198],[-116.69677734375,34.06176136129718],[-116.9439697265625,34.28445325435288],[-117.18017578125,34.42956713470528],[-117.3779296875,34.542762387234845],[-117.62512207031251,34.56990638085636],[-118.048095703125,34.615126683462194],[-118.44909667968749,34.542762387234845],[-118.61938476562499,34.38877925439021],[-118.740234375,34.21180215769026],[-118.71826171875,34.07086232376631]]] } },
-    { "type": "Feature", "properties": { "iso2": "US", "iso3": "SD-CA", "name": "San Diego County", "country": "US", "county": "SD" }, "geometry": { "type": "Polygon", "coordinates":[[[-117.23510742187501,32.861132322810946],[-117.2406005859375,32.75494243654723],[-117.1636962890625,32.68099643258195],[-117.14172363281251,32.58384932565662],[-117.09228515624999,32.46342595776104],[-117.0538330078125,32.29177633471201],[-116.96044921875,32.194208672875384],[-116.85607910156249,32.16631295696736],[-116.6748046875,32.20350534542368],[-116.3671875,32.319633552035214],[-116.1474609375,32.55144352864431],[-116.1639404296875,32.80574473290688],[-116.4111328125,33.073130945006625],[-116.72973632812499,33.08233672856376],[-117.09228515624999,32.99484290420988],[-117.2515869140625,32.96258644191747]]] } }
+    { "type": "Feature", "properties": { "iso2": "US", "iso3": "SD-CA", "name": "San Diego County", "country": "US", "county": "SD" }, "geometry": { "type": "Polygon", "coordinates":[[[-117.23510742187501,32.861132322810946],[-117.2406005859375,32.75494243654723],[-117.1636962890625,32.68099643258195],[-117.14172363281251,32.58384932565662],[-117.09228515624999,32.46342595776104],[-117.0538330078125,32.29177633471201],[-116.96044921875,32.194208672875384],[-116.85607910156249,32.16631295696736],[-116.6748046875,32.20350534542368],[-116.3671875,32.319633552035214],[-116.1474609375,32.55144352864431],[-116.1639404296875,32.80574473290688],[-116.4111328125,33.073130945006625],[-116.72973632812499,33.08233672856376],[-117.09228515624999,32.99484290420988],[-117.2515869140625,32.96258644191747], [-117.23510742187501,32.861132322810946]]] } }
   ]
 }
+
 ```
diff --git a/images/county-region-map.png b/images/county-region-map.png
diff --git a/images/county-regionmap.png b/images/county-regionmap.png
diff --git a/images/import-geojson-file.png b/images/import-geojson-file.png
diff --git a/images/import-vector-map.png b/images/import-vector-map.png
diff --git a/images/upload-success.png b/images/upload-success.png