From 35436405a593f28cbc2eb91687639a9bda7e90fe Mon Sep 17 00:00:00 2001 From: Qiusheng Wu Date: Sat, 30 Sep 2023 22:43:20 -0400 Subject: [PATCH] Add Colab notebook for core features demo (#1744) --- docs/notebooks/00_geemap_colab.ipynb | 286 +++++++++++++++++++++-- examples/notebooks/00_geemap_colab.ipynb | 286 +++++++++++++++++++++-- mkdocs.yml | 1 + 3 files changed, 533 insertions(+), 40 deletions(-) diff --git a/docs/notebooks/00_geemap_colab.ipynb b/docs/notebooks/00_geemap_colab.ipynb index 077b23c175..bd0e12d8d8 100644 --- a/docs/notebooks/00_geemap_colab.ipynb +++ b/docs/notebooks/00_geemap_colab.ipynb @@ -6,18 +6,20 @@ "source": [ "\"Open\n", "\n", - "## Using geemap with Google Colab\n", + "# Using geemap with Google Colab\n", "\n", - "### Instructions\n", + "## Introduction\n", "\n", - "To use geemap and the Earth Engine Python API, you must [register](https://code.earthengine.google.com/register) for an Earth Engine account and follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project. Earth Engine is free for [noncommercial and research use](https://earthengine.google.com/noncommercial)." + "This notebook demonstrates how to use [geemap](https://geemap.org) with Google Colab. To use geemap and the Earth Engine Python API, you must [register](https://code.earthengine.google.com/register) for an Earth Engine account and follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project. Earth Engine is free for [noncommercial and research use](https://earthengine.google.com/noncommercial)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Install geemap" + "## Install geemap\n", + "\n", + "The geemap package has been pre-installed in Google Colab. However, if you would like to install the latest version, you can uncomment and run the following command:" ] }, { @@ -26,14 +28,16 @@ "metadata": {}, "outputs": [], "source": [ - "%pip install geemap" + "# %pip install -U geemap" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Import libraries" + "## Import libraries\n", + "\n", + "Import the Earth Engine Python API and geemap." ] }, { @@ -50,9 +54,32 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Create an interactive map\n", + "## EE Authentication\n", + "\n", + "Run the following cell will start the Earth Engine authentication. Follow the instructions [here](https://book.geemap.org/chapters/01_introduction.html#earth-engine-authentication) to authenticate Earth Engine." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "geemap.ee_initialize()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Core features\n", + "\n", + "You can import the geemap package using the following conventions:\n", "\n", - "Running the following cell will start the Earth Engine authentication. Follow the instructions [here](https://book.geemap.org/chapters/01_introduction.html#earth-engine-authentication) to authenticate Earth Engine." + "- To import only the core features of geemap, use: `import geemap.core as geemap`\n", + "- To import all the features of geemap, use: `import geemap`\n", + "\n", + "Let's import the geemap package using the second option:" ] }, { @@ -61,14 +88,16 @@ "metadata": {}, "outputs": [], "source": [ - "Map = geemap.Map()" + "import geemap.core as geemap" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Add Earth Engine data" + "## Basemap selector\n", + "\n", + "Select a basemap from the dropdown list and add it to the map." ] }, { @@ -77,29 +106,234 @@ "metadata": {}, "outputs": [], "source": [ - "# Add Earth Engine dataset\n", - "image = ee.Image('USGS/SRTMGL1_003')\n", + "m = geemap.Map()\n", + "m.add(\"basemap_selector\")\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Layer Manager\n", "\n", - "# Set visualization parameters.\n", + "Toggle the checkbox to show or hide the layer. Drag and move the slider to change the transparency level of the layer." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", "vis_params = {\n", " 'min': 0,\n", " 'max': 4000,\n", - " 'palette': 'terrain',\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('layer_manager')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Inspector\n", + "\n", + "Click on the map to query Earth Engine data at a specific location." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "landsat7 = ee.Image('LANDSAT/LE7_TOA_5YEAR/1999_2003')\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add_layer(\n", + " landsat7,\n", + " {'bands': ['B4', 'B3', 'B2'], 'min': 20, 'max': 200, 'gamma': 2.0},\n", + " 'Landsat 7',\n", + ")\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('inspector')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Layer Editor\n", + "\n", + "You can change the visualization parameters of the Earth Engine data using the layer editor.\n", + "\n", + "### Single-band image" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add('layer_editor', layer_dict=m.ee_layers['SRTM DEM'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Multi-band image" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "landsat7 = ee.Image('LANDSAT/LE7_TOA_5YEAR/1999_2003')\n", + "m.add_layer(\n", + " landsat7,\n", + " {'bands': ['B4', 'B3', 'B2'], 'min': 20, 'max': 200, 'gamma': 2.0},\n", + " 'Landsat 7',\n", + ")\n", + "m.add('layer_editor', layer_dict=m.ee_layers['Landsat 7'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Feature collection" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('layer_editor', layer_dict=m.ee_layers['US States'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Draw control\n", "\n", - "# Add Earth Engine layers to Map\n", - "Map.addLayer(image, vis_params, 'DEM')\n", + "You can draw shapes on the map using the draw control. The drawn features will be automatically converted to Earth Engine objects, which can be accessed in one of the following ways:\n", "\n", - "# Center the map based on an Earth Engine object or coordinates (longitude, latitude)\n", - "Map.setCenter(86.9250, 27.9881, 4)\n", - "Map" + "- To return the last drawn feature as an `ee.Geometry()`, use: `m._draw_control.last_geometry`\n", + "- To return all the drawn feature as an `ee.Feature()`, use: `m._draw_control.last_feature`\n", + "- To return all the drawn features as an `ee.FeatureCollection()`, use: `m._draw_control.collection`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': 'terrain',\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add('layer_manager')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use the draw control to draw a polygon on the map." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "geometry = m._draw_control.last_geometry\n", + "geometry" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "feature = m._draw_control.last_feature\n", + "feature" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "collection = m._draw_control.collection\n", + "collection" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "If you can see the map above, you have successfully authenticated the Earth Engine Python API. Otherwise, you might need to follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project, which is required to use the Earth Engine Python API." + "Clip the DEM data using the drawn polygon." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "if geometry is not None:\n", + " image = dem.clipToCollection(collection)\n", + " m.layers[1].visible = False\n", + " m.add_layer(image, vis_params, \"Clipped DEM\")\n", + "m" ] } ], @@ -108,6 +342,18 @@ "display_name": "Python 3", "language": "python", "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.5" } }, "nbformat": 4, diff --git a/examples/notebooks/00_geemap_colab.ipynb b/examples/notebooks/00_geemap_colab.ipynb index 077b23c175..bd0e12d8d8 100644 --- a/examples/notebooks/00_geemap_colab.ipynb +++ b/examples/notebooks/00_geemap_colab.ipynb @@ -6,18 +6,20 @@ "source": [ "\"Open\n", "\n", - "## Using geemap with Google Colab\n", + "# Using geemap with Google Colab\n", "\n", - "### Instructions\n", + "## Introduction\n", "\n", - "To use geemap and the Earth Engine Python API, you must [register](https://code.earthengine.google.com/register) for an Earth Engine account and follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project. Earth Engine is free for [noncommercial and research use](https://earthengine.google.com/noncommercial)." + "This notebook demonstrates how to use [geemap](https://geemap.org) with Google Colab. To use geemap and the Earth Engine Python API, you must [register](https://code.earthengine.google.com/register) for an Earth Engine account and follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project. Earth Engine is free for [noncommercial and research use](https://earthengine.google.com/noncommercial)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Install geemap" + "## Install geemap\n", + "\n", + "The geemap package has been pre-installed in Google Colab. However, if you would like to install the latest version, you can uncomment and run the following command:" ] }, { @@ -26,14 +28,16 @@ "metadata": {}, "outputs": [], "source": [ - "%pip install geemap" + "# %pip install -U geemap" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Import libraries" + "## Import libraries\n", + "\n", + "Import the Earth Engine Python API and geemap." ] }, { @@ -50,9 +54,32 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Create an interactive map\n", + "## EE Authentication\n", + "\n", + "Run the following cell will start the Earth Engine authentication. Follow the instructions [here](https://book.geemap.org/chapters/01_introduction.html#earth-engine-authentication) to authenticate Earth Engine." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "geemap.ee_initialize()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Core features\n", + "\n", + "You can import the geemap package using the following conventions:\n", "\n", - "Running the following cell will start the Earth Engine authentication. Follow the instructions [here](https://book.geemap.org/chapters/01_introduction.html#earth-engine-authentication) to authenticate Earth Engine." + "- To import only the core features of geemap, use: `import geemap.core as geemap`\n", + "- To import all the features of geemap, use: `import geemap`\n", + "\n", + "Let's import the geemap package using the second option:" ] }, { @@ -61,14 +88,16 @@ "metadata": {}, "outputs": [], "source": [ - "Map = geemap.Map()" + "import geemap.core as geemap" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Add Earth Engine data" + "## Basemap selector\n", + "\n", + "Select a basemap from the dropdown list and add it to the map." ] }, { @@ -77,29 +106,234 @@ "metadata": {}, "outputs": [], "source": [ - "# Add Earth Engine dataset\n", - "image = ee.Image('USGS/SRTMGL1_003')\n", + "m = geemap.Map()\n", + "m.add(\"basemap_selector\")\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Layer Manager\n", "\n", - "# Set visualization parameters.\n", + "Toggle the checkbox to show or hide the layer. Drag and move the slider to change the transparency level of the layer." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", "vis_params = {\n", " 'min': 0,\n", " 'max': 4000,\n", - " 'palette': 'terrain',\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('layer_manager')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Inspector\n", + "\n", + "Click on the map to query Earth Engine data at a specific location." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "landsat7 = ee.Image('LANDSAT/LE7_TOA_5YEAR/1999_2003')\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add_layer(\n", + " landsat7,\n", + " {'bands': ['B4', 'B3', 'B2'], 'min': 20, 'max': 200, 'gamma': 2.0},\n", + " 'Landsat 7',\n", + ")\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('inspector')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Layer Editor\n", + "\n", + "You can change the visualization parameters of the Earth Engine data using the layer editor.\n", + "\n", + "### Single-band image" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5'],\n", "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add('layer_editor', layer_dict=m.ee_layers['SRTM DEM'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Multi-band image" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "landsat7 = ee.Image('LANDSAT/LE7_TOA_5YEAR/1999_2003')\n", + "m.add_layer(\n", + " landsat7,\n", + " {'bands': ['B4', 'B3', 'B2'], 'min': 20, 'max': 200, 'gamma': 2.0},\n", + " 'Landsat 7',\n", + ")\n", + "m.add('layer_editor', layer_dict=m.ee_layers['Landsat 7'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Feature collection" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "states = ee.FeatureCollection(\"TIGER/2018/States\")\n", + "m.add_layer(states, {}, \"US States\")\n", + "m.add('layer_editor', layer_dict=m.ee_layers['US States'])\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Draw control\n", "\n", - "# Add Earth Engine layers to Map\n", - "Map.addLayer(image, vis_params, 'DEM')\n", + "You can draw shapes on the map using the draw control. The drawn features will be automatically converted to Earth Engine objects, which can be accessed in one of the following ways:\n", "\n", - "# Center the map based on an Earth Engine object or coordinates (longitude, latitude)\n", - "Map.setCenter(86.9250, 27.9881, 4)\n", - "Map" + "- To return the last drawn feature as an `ee.Geometry()`, use: `m._draw_control.last_geometry`\n", + "- To return all the drawn feature as an `ee.Feature()`, use: `m._draw_control.last_feature`\n", + "- To return all the drawn features as an `ee.FeatureCollection()`, use: `m._draw_control.collection`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "m = geemap.Map(center=(40, -100), zoom=4)\n", + "dem = ee.Image('USGS/SRTMGL1_003')\n", + "vis_params = {\n", + " 'min': 0,\n", + " 'max': 4000,\n", + " 'palette': 'terrain',\n", + "}\n", + "m.add_layer(dem, vis_params, 'SRTM DEM')\n", + "m.add('layer_manager')\n", + "m" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use the draw control to draw a polygon on the map." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "geometry = m._draw_control.last_geometry\n", + "geometry" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "feature = m._draw_control.last_feature\n", + "feature" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "collection = m._draw_control.collection\n", + "collection" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "If you can see the map above, you have successfully authenticated the Earth Engine Python API. Otherwise, you might need to follow the instructions [here](https://docs.google.com/document/d/1ZGSmrNm6_baqd8CHt33kIBWOlvkh-HLr46bODgJN1h0/edit?usp=sharing) to create a Cloud Project, which is required to use the Earth Engine Python API." + "Clip the DEM data using the drawn polygon." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "if geometry is not None:\n", + " image = dem.clipToCollection(collection)\n", + " m.layers[1].visible = False\n", + " m.add_layer(image, vis_params, \"Clipped DEM\")\n", + "m" ] } ], @@ -108,6 +342,18 @@ "display_name": "Python 3", "language": "python", "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.5" } }, "nbformat": 4, diff --git a/mkdocs.yml b/mkdocs.yml index 02f5c21361..3b14b6ff86 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,6 +138,7 @@ nav: - workshops/City_Plus_2023.ipynb - workshops/G4G_2023.ipynb - Notebooks: + - notebooks/00_geemap_colab.ipynb - notebooks/00_geemap_key_features.ipynb - notebooks/01_geemap_intro.ipynb - notebooks/02_using_basemaps.ipynb