examples/notebooks/50_cartoee_quickstart.ipynb

{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<a href=\"https://githubtocolab.com/gee-community/geemap/blob/master/examples/notebooks/50_cartoee_quickstart.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open in Colab\"/></a>\n",
                "\n",
                "Uncomment the following line to install [geemap](https://geemap.org) and [cartopy](https://scitools.org.uk/cartopy/docs/latest/installing.html#installing) if needed. Keep in mind that cartopy can be challenging to install. If you are unable to install cartopy on your computer, you can try Google Colab with this the [notebook example](https://colab.research.google.com/github/gee-community/geemap/blob/master/examples/notebooks/cartoee_colab.ipynb). \n",
                "\n",
                "See below the commands to install cartopy and geemap using conda/mamba:\n",
                "\n",
                "```\n",
                "conda create -n carto python=3.8\n",
                "conda activate carto\n",
                "conda install mamba -c conda-forge\n",
                "mamba install cartopy scipy -c conda-forge\n",
                "mamba install geemap -c conda-forge\n",
                "jupyter notebook\n",
                "```"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# !pip install cartopy scipy\n",
                "# !pip install geemap"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# How to create publication quality maps using `cartoee`\n",
                "\n",
                "`cartoee` is a lightweight module to aid in creating publication quality maps from Earth Engine processing results without having to download data. The `cartoee` package does this by requesting png images from EE results (which are usually good enough for visualization) and `cartopy` is used to create the plots. Utility functions are available to create plot aesthetics such as gridlines or color bars. **The notebook and the geemap cartoee module ([cartoee.py](https://geemap.org/cartoee)) were contributed by [Kel Markert](https://github.com/KMarkert). A huge thank you to him.**"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%pylab inline\n",
                "\n",
                "import ee\n",
                "import geemap\n",
                "\n",
                "# import the cartoee functionality from geemap\n",
                "from geemap import cartoee"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "geemap.ee_initialize()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Plotting an image\n",
                "\n",
                "In this first example we will explore the most basic functionality including plotting and image, adding a colorbar, and adding visual aethetic features. Here we will use SRTM data to plot global elevation."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# get an image\n",
                "srtm = ee.Image(\"CGIAR/SRTM90_V4\")"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# geospatial region in format [E,S,W,N]\n",
                "region = [180, -60, -180, 85]  # define bounding box to request data\n",
                "vis = {'min': 0, 'max': 3000}  # define visualization parameters for image"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig = plt.figure(figsize=(15, 10))\n",
                "\n",
                "# use cartoee to get a map\n",
                "ax = cartoee.get_map(srtm, region=region, vis_params=vis)\n",
                "\n",
                "# add a colorbar to the map using the visualization params we passed to the map\n",
                "cartoee.add_colorbar(ax, vis, loc=\"bottom\", label=\"Elevation\", orientation=\"horizontal\")\n",
                "\n",
                "# add gridlines to the map at a specified interval\n",
                "cartoee.add_gridlines(ax, interval=[60, 30], linestyle=\":\")\n",
                "\n",
                "# add coastlines using the cartopy api\n",
                "ax.coastlines(color=\"red\")\n",
                "\n",
                "show()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "This is a decent map for minimal amount of code. But we can also easily use matplotlib colormaps to visualize our EE results to add more color. Here we add a `cmap` keyword to the `.get_map()` and `.add_colorbar()` functions."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig = plt.figure(figsize=(15, 10))\n",
                "\n",
                "cmap = \"gist_earth\"  # colormap we want to use\n",
                "# cmap = \"terrain\"\n",
                "\n",
                "# use cartoee to get a map\n",
                "ax = cartoee.get_map(srtm, region=region, vis_params=vis, cmap=cmap)\n",
                "\n",
                "# add a colorbar to the map using the visualization params we passed to the map\n",
                "cartoee.add_colorbar(\n",
                "    ax, vis, cmap=cmap, loc=\"right\", label=\"Elevation\", orientation=\"vertical\"\n",
                ")\n",
                "\n",
                "# add gridlines to the map at a specified interval\n",
                "cartoee.add_gridlines(ax, interval=[60, 30], linestyle=\"--\")\n",
                "\n",
                "# add coastlines using the cartopy api\n",
                "ax.coastlines(color=\"red\")\n",
                "\n",
                "ax.set_title(label='Global Elevation Map', fontsize=15)\n",
                "\n",
                "show()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Plotting an RGB image\n",
                "\n",
                "`cartoee` also allows for plotting of RGB image results directly. Here is an example of plotting a Landsat false-color scene."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "# get a landsat image to visualize\n",
                "image = ee.Image('LANDSAT/LC08/C01/T1_SR/LC08_044034_20140318')\n",
                "\n",
                "# define the visualization parameters to view\n",
                "vis = {\"bands\": ['B5', 'B4', 'B3'], \"min\": 0, \"max\": 5000, \"gamma\": 1.3}"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig = plt.figure(figsize=(15, 10))\n",
                "\n",
                "# use cartoee to get a map\n",
                "ax = cartoee.get_map(image, vis_params=vis)\n",
                "\n",
                "# pad the view for some visual appeal\n",
                "cartoee.pad_view(ax)\n",
                "\n",
                "# add the gridlines and specify that the xtick labels be rotated 45 degrees\n",
                "cartoee.add_gridlines(ax, interval=0.5, xtick_rotation=45, linestyle=\":\")\n",
                "\n",
                "# add the coastline\n",
                "ax.coastlines(color=\"yellow\")\n",
                "\n",
                "show()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "By default, if a region is not provided via the `region` keyword the whole extent of the image will be plotted as seen in the previous Landsat example. We can also zoom to a specific region of an image by defining the region to plot."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig = plt.figure(figsize=(15, 10))\n",
                "\n",
                "# here is the bounding box of the map extent we want to use\n",
                "# formatted a [E,S,W,N]\n",
                "zoom_region = [-121.8025, 37.3458, -122.6265, 37.9178]\n",
                "\n",
                "# plot the map over the region of interest\n",
                "ax = cartoee.get_map(image, vis_params=vis, region=zoom_region)\n",
                "\n",
                "# add the gridlines and specify that the xtick labels be rotated 45 degrees\n",
                "cartoee.add_gridlines(ax, interval=0.15, xtick_rotation=45, linestyle=\":\")\n",
                "\n",
                "# add coastline\n",
                "ax.coastlines(color=\"yellow\")\n",
                "\n",
                "show()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Adding north arrow and scale bar"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig = plt.figure(figsize=(15, 10))\n",
                "\n",
                "# here is the bounding box of the map extent we want to use\n",
                "# formatted a [E,S,W,N]\n",
                "zoom_region = [-121.8025, 37.3458, -122.6265, 37.9178]\n",
                "\n",
                "# plot the map over the region of interest\n",
                "ax = cartoee.get_map(image, vis_params=vis, region=zoom_region)\n",
                "\n",
                "# add the gridlines and specify that the xtick labels be rotated 45 degrees\n",
                "cartoee.add_gridlines(ax, interval=0.15, xtick_rotation=45, linestyle=\":\")\n",
                "\n",
                "# add coastline\n",
                "ax.coastlines(color=\"yellow\")\n",
                "\n",
                "# add north arrow\n",
                "cartoee.add_north_arrow(\n",
                "    ax, text=\"N\", xy=(0.05, 0.25), text_color=\"white\", arrow_color=\"white\", fontsize=20\n",
                ")\n",
                "\n",
                "# add scale bar\n",
                "cartoee.add_scale_bar_lite(\n",
                "    ax, length=10, xy=(0.1, 0.05), fontsize=20, color=\"white\", unit=\"km\"\n",
                ")\n",
                "\n",
                "ax.set_title(label='Landsat False Color Composite (Band 5/4/3)', fontsize=15)\n",
                "\n",
                "show()"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": []
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "Python 3",
            "language": "python",
            "name": "python3"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 5
}