diff --git a/guide/10-mapping-and-visualization/part5_saving_updating_and_embedding_map_widget.ipynb b/guide/10-mapping-and-visualization/part5_saving_updating_and_embedding_map_widget.ipynb index e0b09188c..2b7b7a13b 100644 --- a/guide/10-mapping-and-visualization/part5_saving_updating_and_embedding_map_widget.ipynb +++ b/guide/10-mapping-and-visualization/part5_saving_updating_and_embedding_map_widget.ipynb @@ -1 +1,531 @@ -{"cells":[{"cell_type":"markdown","metadata":{},"source":["# Part 5 - Saving, embedding and exporting the map widget\n"]},{"cell_type":"markdown","metadata":{"toc":true},"source":["

Table of Contents

\n","
\n"]},{"cell_type":"markdown","metadata":{},"source":["## Saving a web map\n","\n","Starting with the Python API version 1.3, you can save the map widget as a web map in your `GIS`. This process persists the basemaps, layers added (with or without your custom symbology, including smart mapping), pop-ups, extent, and graphics drawn (with or without custom symbols) as layers in your `web map`.\n","\n","To save the map, call the `save()` method. This method creates and returns a new `Web Map Item` object. As parameters, you can specify all valid Item properties as shown below:\n"]},{"cell_type":"code","execution_count":1,"metadata":{},"outputs":[],"source":["from arcgis.gis import GIS\n","# gis = GIS(\"your_online_profile\")\n","gis = GIS()"]},{"cell_type":"code","execution_count":2,"metadata":{},"outputs":[{"data":{"text/plain":[""]},"execution_count":2,"metadata":{},"output_type":"execute_result"}],"source":["world_countries_item = gis.content.get('ac80670eb213440ea5899bbf92a04998')\n","world_countries_layer = world_countries_item.layers[0]\n","world_countries_layer"]},{"cell_type":"code","execution_count":5,"metadata":{},"outputs":[{"data":{"text/html":[""],"text/plain":[""]},"metadata":{},"output_type":"display_data"}],"source":["map1 = gis.map(\"USA\")\n","map1"]},{"cell_type":"code","execution_count":4,"metadata":{},"outputs":[],"source":["map1.add_layer(world_countries_layer)"]},{"cell_type":"code","execution_count":5,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["\n"]}],"source":["webmap_properties = {'title': 'World Countries 2022-01-06 16:33pm',\n"," 'snippet': 'Jupyter notebook widget saved as a web map',\n"," 'tags': ['automation', 'python']}\n","\n","webmap_item = map1.save(webmap_properties, thumbnail=r\".\\webmap_thumbnail.PNG\")\n","print(webmap_item)"]},{"cell_type":"markdown","metadata":{},"source":["## Updating a web map\n","\n","Similarly, if you created the `WebMap` object from an existing web map item, you can call the `update()` method to update it.\n","\n","Note, the `save()` method always creates a new item with an updated web map definition, so this is a great way to create a copy of an existing web map. For instance, the cell below calls the `save()` method and creates a new web map item with the new set of layers, without disturbing the original web map item.\n"]},{"cell_type":"markdown","metadata":{},"source":["We can search for web maps just like any other item:\n"]},{"cell_type":"code","execution_count":14,"metadata":{},"outputs":[],"source":["webmap_search = gis.content.search(\n"," \"COVID AND UK\", item_type=\"Web Map\", outside_org=True)\n","covid_map_item = webmap_search[0]"]},{"cell_type":"markdown","metadata":{},"source":["You can also create a WebMap object from an existing web map item by passing the web map item as the parameter to the constructor:\n"]},{"cell_type":"code","execution_count":13,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["Coronavirus COVID-19 Cases V2 - Deaths\n","Coronavirus COVID-19 Cases V2 - Cases\n","Coronavirus COVID-19 Cases V2 - Cases_country\n","Coronavirus COVID-19 Cases V2 - Cases_state\n","\n"]}],"source":["from arcgis.mapping import WebMap\n","\n","covid_map = WebMap(covid_map_item)\n","for layer in covid_map.layers:\n"," print(layer.title)"]},{"cell_type":"markdown","metadata":{},"source":["You can update a web map by adding or removing layers. For instance, the cell below removes one of the layers from the web map and adds a different layer.\n"]},{"cell_type":"code","execution_count":50,"metadata":{},"outputs":[],"source":["# remove the first - unclassed layer from the map\n","covid_map.remove_layer(covid_map.layers[1])"]},{"cell_type":"code","execution_count":58,"metadata":{},"outputs":[{"data":{"text/plain":["True"]},"execution_count":58,"metadata":{},"output_type":"execute_result"}],"source":["covid_map.add_layer(world_countries_layer, options={\n"," 'title': 'World Countries'})"]},{"cell_type":"code","execution_count":59,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["Coronavirus COVID-19 Cases V2 - Deaths\n","Coronavirus COVID-19 Cases V2 - Cases_country\n","Coronavirus COVID-19 Cases V2 - Cases_state\n","World Countries\n"]}],"source":["for layer in covid_map.layers:\n"," print(layer.title)"]},{"cell_type":"markdown","metadata":{},"source":["Next, let's add a layer to the existing `map1` and update the web map item:\n"]},{"cell_type":"code","execution_count":8,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["\n","\n"]}],"source":["from arcgis.features import FeatureLayer\n","# add layer via\n","# map1.add_layer(covid_map.layers[6])\n","# or alternatively\n","map1.add_layer(FeatureLayer(\n"," \"https://services.arcgis.com/qHLhLQrcvEnxjtPr/arcgis/rest/services/UK_COVID_19_Data/FeatureServer/1\"), )\n","\n","for layer in map1.layers:\n"," print(layer)"]},{"cell_type":"code","execution_count":46,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["\n","\n"]}],"source":["from arcgis.features import FeatureLayer\n","# add layer via\n","# map1.add_layer(covid_map.layers[6])\n","# or alternatively\n","map1.add_layer(FeatureLayer(\n"," \"https://services.arcgis.com/qHLhLQrcvEnxjtPr/arcgis/rest/services/UK_COVID_19_Data/FeatureServer/1\"), )\n","\n","for layer in map1.layers:\n"," print(layer)"]},{"cell_type":"markdown","metadata":{},"source":["Using the `save` method will create a new web map item, while using the `update` method will make updates to the previous web map item:\n","\n","```\n","update(mode=None, item_properties=None, thumbnail=None, metadata=None)\n","```\n","\n","The `update` method uses the following parameters:\n","\n"," --------------- --------------------------------------------------------------------\n"," item_properties Optional dictionary. See table below for the keys and values.\n"," --------------- --------------------------------------------------------------------\n"," mode Optional string. Whether to save this map instance as a 2D WebMap,\n"," or a 3D WebScene. Possible strings: ``2D``, ``webmap``, ``3D``, or\n"," ``webscene``.\n"," --------------- --------------------------------------------------------------------\n"," thumbnail Optional string. Either a path or URL to a thumbnail image.\n"," --------------- --------------------------------------------------------------------\n"," metadata Optional string. Either a path or URL to the metadata.\n"," --------------- --------------------------------------------------------------------\n","\n","\n","The `update` method will update the Web Map/Web Scene item that was used to create the `Map Widget` object. In addition, you are also able to update the item's other properties, thumbnail, and metadata.\n"]},{"cell_type":"code","execution_count":50,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["True\n"]}],"source":["webmap_item_properties = {'title': 'COVID-19 Cases in UK (Updated 2022-01-06)',\n"," 'snippet': 'Map created using Python API showing COVID cases in UK',\n"," 'tags': ['automation', 'world health', 'python']}\n","\n","new_map_item = map1.update(item_properties=webmap_item_properties,\n"," mode=\"2D\", thumbnail='./webmap_thumbnail.png')\n","print(new_map_item)"]},{"cell_type":"code","execution_count":52,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["\n"]}],"source":["# We can see from the output that the title is being updated:\n","print(webmap_item)"]},{"cell_type":"markdown","metadata":{},"source":["## Creating static maps via `take_screenshot`\n","\n","Since version 1.5.2, the ArcGIS API for Python supports the `take_screenshot()` method, which will create a screenshot of the current widget view. Note that the method only works in a Jupyter Notebook environment.\n","\n","```\n","take_screenshot(output_in_cell=True, set_as_preview=True, file_path='')\n","```\n","\n","The method takes the following arguments:\n","\n","- `output_in_cell`: Optional boolean that defaults to True. This will display the screenshot in the output area of the cell where this function is called.\n","- `set_as_preview`: Optional boolean that defaults to True. This will set the screenshot as the static image preview in the cell where the map widget is being displayed. Use this flag if you want the generated HTML previews of your notebook to have a map image visible.\n","- `file_path`: Optional String that defaults to “”. To output the screenshot to a .png file on disk, set this String to a writeable location file path (Ex. file_path = “/path/to/documents/my_screenshot.png”).\n","\n","In all notebook outputs, each image will be encoded to a base64 data URI and wrapped in an HTML tag. This means that the data for the image lives inside the notebook file itself, allowing for easy sharing of notebooks and generated HTML previews of notebooks.\n","\n","
\n"," Note: This function acts asynchronously, meaning that the Python function will return right away, with the notebook outputs/files being written after an indeterminate amount of time. Avoid calling this function multiple times in a row if the asynchronous portion of the function has not finished yet.\n","
\n","\n","
\n"," Another Note: Some limitations exist for taking screenshots in 2D mode, since the underlying screenshot mechanism is the ArcGIS JS API’s PrintTask object (https://bit.ly/2qRKGJG). If this function fails to create a screenshot, try a slightly different extent and try again. Non-published features with client-side graphics like Spatially Enabled DataFrames might not display in a 2D mode screenshot.\n","
\n"]},{"cell_type":"code","execution_count":6,"metadata":{},"outputs":[{"data":{"text/html":[""],"text/plain":[""]},"metadata":{},"output_type":"display_data"}],"source":["map1.take_screenshot()"]},{"cell_type":"markdown","metadata":{},"source":["## Export live map in a separate HTML file\n","\n","Another new feature in 1.5.0 is the ability to export the current widget as a stand-alone HTML file. This added functionality provides a new workflow for creating standalone HTML maps that can be shared with anyone. All they need is a web browser!\n","\n","The cell below will write the current widget to the file specified by a string path. Run the cell, find the file on your disk, and open it in your favorite web browser.\n","\n","
\n"," Note: By default, only publicly accessible layers will show on the exported HTML maps. You must specify that `credentials_prompt=True` to allow users to authenticate to the GIS to view private layers. See the API reference for more information.\n","
\n"]},{"cell_type":"code","execution_count":90,"metadata":{},"outputs":[{"name":"stdout","output_type":"stream","text":["html saved as C:\\Users\\Username\\Documents\\home\\myWorldMap.html\n"]}],"source":["import os\n","\n","file_dir = os.path.join(os.getcwd(), 'home')\n","if not os.path.isdir(file_dir):\n"," os.mkdir(file_dir)\n","\n","file_path = os.path.join(file_dir, 'myWorldMap.html')\n","\n","map1.export_to_html(file_path)\n","print(\"html saved as \" + file_path)"]},{"cell_type":"markdown","metadata":{},"source":["## Embedding a live map\n","\n","The `embed` method embeds the current state of the map into the underlying notebook as an interactive HTML/JS/CSS element.\n","\n","```\n","embed(output_in_cell=True, set_as_preview=True)\n","```\n","\n","Its arguments include:\n","\n","- `output_in_cell`: Optional boolean that defaults to `True`. This will display the embedded HTML interactive map in the output area of the cell where this function is called.\n","- `set_as_preview`: Optional boolean that defaults to `True`. This will display the embedded HTML interactive map in the cell where the map widget is being displayed. Use this flag if you want the generated HTML previews of your notebook to have an interactive map displayed.\n","\n","
\n"," Note: This element will always display this `snapshot` state of the map, regardless of any future Python code ran.\n","
\n"]},{"cell_type":"markdown","metadata":{},"source":["In all notebook outputs, each embedded HTML element will contain the entire map state and all relevant HTML wrapped in an `