Getting Started with GeeMap

ENV 859 - Geospatial Data Analytics   |   Fall 2024   |   Instructor: John Fay  

What is Google Earth Engine (“GEE”)?

GEE is a popular and powerful platform for analyzing spatial data in the cloud. The service leverages Google’s massive cloud computing technology and is offered freely to academic and non-profit group. It is particularly adept at broad scale analyses and requires minimal local resources. In addition to it’s powerful analytical abilities, GEE also provided instant access to a vast amount of remotely sensed and other geospatial data.

For more information on what Earth Engine is and what it can do, have a look here: https://earthengine.google.com/faq/

GEE is natively controlled via JavaScript commands. You can write and execute JavaScript code in its on-line interface, saving scripts to linked GitHub accounts. We, however, we leverage our existing knowledge of Python to run GEE via Jupyter notebooks using Quisheng Wu’s wonderful and amazing geemap package. This package not only provides access to virtually all of GEE’s capability via Python commands, but it include excellent documentation, tutorials, and even recorded workshops.

Lesson Objectives

Fully mastering all the GEE (and Geemap) has to offer would take much more time than we have here, so we will concentrate on building a foundation of knowledge that will make subsequent learning paths much easier. We will start from ground zero, even leveraging Google’s Colaboratory - another free Google resource, this one enabling use to create, execute, and manage Jupyter notebooks on Google’s cloud.

In particular, we will cover:

  • Signing up for access to Google Earth Engine (via a Google Account).
  • A brief look at using GEE’s native JavaScript interface for running Earth Engine analyses.
  • An introduction to the Google Colaboratory for writing, running, and managing Jupyter notebooks.
  • How to install packages in Google Colab notebooks.
  • How to authenticate and initialize the Geemap package.
  • Running GEE commands in Python using Geemap and other Python packages.
  • Where to go from here.

1. Signing up for access to Google Earth Engine

  1. Open a web browser and log in to your Google account.
  2. Navigate to https://earthengine.google.org
  3. Click on the Get Started button in the upper right.
  4. In the next windows, select the Google account you want to link to GEE.
  5. In the next window, select “Use with a Cloud Project”
    :point_right: A cloud project allows us to organize our project resources. It’s essentially required for doing any long term, in-depth analysis in GEE. And fortunately, it’s free for us in the academic community!
  6. In the next window, select “Create a new Google Cloud Project”
  7. Give your project a unique Project ID (keep as is or create a custom name, but be sure it’s unique so add something like your Duke NetID).
  8. Click “Continue to Summary”; A link to accept terms of service may appear, which you must accept to proceed.
  9. In the next window, Confirm your Cloud Project information.
  10. You should then be taken to the code editor: https://code.earthengine.google.com/

You can now go directly to the GEE code editor by navigating to https://code.earthengine.google.com/ and logging in with your Google Account

2. A brief overview of the JavaScript code editor

A quick overview

The University of Colorado’s EarthLab has an excellent introductory overview of GEE’s JavaScript code interface:
https://earthlab.colorado.edu/introduction-google-earth-engine-code-editor

Run through this document, being sure you understand the following:

  • The four components of the code interface and what purpose each serves: Manager; Code Editor; Console; Map
  • How to write and run code in the Code Editor (even if you don’t yet understand the code)

Going deeper…

Example scripts

The GEE code editor comes with a number of example scripts to allow you to dive into the code. These are found under the Scripts tab in the Manager by expanding the Examples menu item.

  • Expand the Image item under the Examples heading.
  • Double click the “From Name” script to load it into your Code Editor
  • Run the code.

Now comes the learning…

  • In the Code Editor, modify the code to center the map on Durham (Lat = 36, Long = -79), changing the Zoom from 5 to 10.

  • In the Map, hover over the Layers control and toggle off the SRTM layer. Then toggle it back on.

  • Again the Map, open up the properties of the SRTM layer by selecting the :gear: icon.

    • How many bands does this image have?
    • Change its stretch from the default of 0-3000 to “Stretch 98%”. The stretch values should change to 51.88-276.12.

  • Back in the Code Editor, modify the code to use these new values when displaying the image. Re-run your code.

  • In the Console interface, switch to the “Inspector” view, then click anywhere on the map.

    • What is the coordinate of the location you clicked?
    • What is the zoom level?
    • What is the elevation at that location?
    • What other information is listed?

    → What have you just learned?

    • You can control the location and zoom of the map
    • You can control how the image is displayed via the map
    • You can control how the image is displayed via the code
    • You can query data at specific locations in your map via the Inspector

    Learning by doing is an effective approach to exploring and understanding what you can do and how things work in Earth Engine…

Saving your work…

  • Click the Get Link button at the top of the Code Editor window.
    → This link will open up your code in any GEE workspace! (Here’s my link)

  • Under the Save button, select Save As…

    • You’ll likely be asked to create a new repository. Follow the instructions to do so calling the new repository “env790”.
    • When the Save File dialog appears, use the default path and name (“Image/From name (copy)”)

  • In the Manager pane, under the Owner item you’ll see your new repository, and under that you’ll see a folder (“Image”), and then your script.

  • Rename your script something else (e.g. “My First GEE Script”)

    • Note you can also view the script’s edit history or delete the script.

  • Hover your mouse over your repository in the Manager pane and select the :gear: icon. This provides access to your GEE git repository. Your scripts are being stored in a repository accessible via [https://earthengine.googlesource.com/users/](https://earthengine.googlesource.com/users/), which can be shared with others. Or you can simply continue to access your scripts via the GEE manager pane.

    → What have you learned?

    • You can easily share your code with others via a web link
    • Your saved scripts are stored in a Google Git repository, which you can access via GEE or access/share via a direct link to the repo

    The GEE interface, while fairly simple in appearance, is actually quite a powerful development environment for learning and coding with GEE resources!

Even Deeper…

I am a huge proponent of learning though exploration, and the sample code documents Google provides under the Scripts/Examples tab provide much to explore. At some point, however, you’ll want to better understand the overall structure of GEE: viewing the organization and hierarchy of objects and methods (i.e, functions or actions) that comprise GEE will enhance your intuition and experimentation of the code. This is best done by exploring the documentation provided with GEE.

  • First, look at the organization of the example scripts found within the Scripts/Examples of the Manager pane. You’ll see examples for various topics: Image, Image Collections, Feature Collection, etc. This gives you some idea of the different types of data you can work with in GEE.

  • Next, click on the Docs tab in the Manager pane. This it the complete list of methods available in GEE.

    • Expand the ee.Image entry and click on ee.Image(args). This reveal the documenation for ways to create a GEE Image object.
    • Scroll down and expand the divide(image2) entry under ee.Image. This explains how to divide one image object by another.

    You may not understand yet how these methods are implemented, but perhaps you at least see that an Image is something you can define and work with in GEE. And that and Image Collection is something different as it has its own entry at the same level of the Docs menu as Image.

    The amount to learn may still seem daunting, but understanding how things organized should dampen the learning curve.

Too deep!!

Ok, having got your feet with GEE, it’s time to step back a bit. Click the :grey_question: icon in the upper right, next to your project name, and select the User Guide. This might feel like a breath of fresh air after tinkering in the bowels of the GEE JavaScript interface. Still, you may feel overwhelmed by all the documentation listed here. Don’t! It’s best to think of this resource as a reference, not something you’ll need to read from cover to cover! B

However, as a reference, take some time to understand its structure so that you might use this resource effectively.

  • Click on the Guides tab. Note how the sections are organized. Skim a few. Different people will want different entry points to familiarizing themselves with how this technology works.
  • Click on the Reference tab. Expand the tabs and look for familiar patterns. What can you clearly ignore (for now), and what might you likely come back to? Maybe you can answer that now, maybe not; but at least make some mental notes…
  • Repeat with the other tabs, again making mental notes of what resources are available and thinking why and when you might return to these resources.

What next?

Certainly there’s much to learn with respect to learning how to use GEE. One thing we’ll take out of the equation, however, is JavaScript. While it’s not a terribly complex language to learn, we will stick with the language we’ve been dabbling with already, namely Python.

So, in the next section we’ll fire up Google’s Colaboratory where we will write some Jupyter Notebooks that provide us with an alternative to the JavaScript coding interface.

3. Getting started with Google’s Colab

Earth engine offers an alternative to the world of ESRI, so it wouldn’t quite make sense to use the Jupyter Notebook environment provided by ArcGIS Online to write our Geemap code. So instead, we’ll set up and use Google’s Colab. It’s slightly different, but effectively the same.

Here’s how to set up your Colab environment.

  • Sign in to your Google account.

  • Navigate to https://colab.research.google.com

  • In the popup that appears, click the “Welcome to Colaboratory” link.

    This will open up a Jupyter notebook written to introduce to you the Colab! You’ll see it has the familiar formatted text cells (with embedded videos!) as well as code cells where you can write and run Python.

    You are encouraged to browse the information here…

  • From the File menu, select New Notebook.

  • In the code cell, type print("hello world!") and run the code by clicking the arrow on the left side of the cell.

  • Insert a text cell below the cell you just edited. Add some text and format it. Navigate away from the cell (e.g. add a new cell) to exit the editing mode. Or hit <shift>-<enter>

  • Rename your notebook by clicking on the title at the top of the page.

To return to your Colab environment:

That’s pretty much it! As you go, you will learn more about how notebooks are managed and where they are stored. We, however, will move forward with learning the Geemap package…

Installing and configuring the Geemap package in Colab

The documentation for Geemap is excellent on its own, let alone for for a free Python package. View it’s main page for information on what its and what it does: https://geemap.org/.

Diving right in, we’ll write and run some code in a new notebook to install and configure Geemap.

1. Mounting your Google Drive from Colab

This first step allows your notebooks to save information to your Google Drive, enabling logins and settings to persist so you don’t have to keep authenticating each time you open your notebook.

  • Open a new notebook in Colab.
  • Click the folder icon on the left side of the screen to access the Files menu.
  • Then click the folder with the triangle logo in it:
    map-drive
  • A message asking you to “Permit this notebook to access your Google Drive files” appears. Allow this.
  • Your drive will appear in the Files menu indicating it has been mounted.

2. Installing the geemap package

Now we must install the Geemap package into our Colab environment. We have to do this each time we re-visit our notebook in a new Colab session.

  • In the first code cell, write and run the following command to install GeeMap:

    !pip install geemap
    • The pip install command fetches the installation files for Geemap and install them into your environment.
    • Once complete, you can comment out the line as you won’t need to install Geemap again for this coding session. (:exclamation: After you exit this notebook, you will have to reinstall the package, i.e. re-run the pip install command…)
    • You can also remove the output via the X under the run arrow in the code cell.

  • Add a new code cell to your notebook.

  • Add and run the command to load the packages we’ll use in our analyses:

    import geemap
import ee
import pandas as pd

    This will run with no output, but now the packages are accessible in our coding environment.

3. Authenticating Geemap

  • Add a new code cell to your notebook.

  • Add and run the command to install the packages we’ll use in our analyses

    ee.Authenticate()

    When run, follow the instructions to authenticate Geemap to access your Google Earth Engine account…

    1. Click the link provided in the notebook.
    2. In the page that opens, click Generate Token
    3. In the page that opens, choose the account you used to run GEE
    4. In the page that opens, select Continue
    5. In the page that opens, put a check in both boxes to allow Geemap to fully access your GEE account. Then click Continue.
    6. In the page that opens, copy the Authorization code to your machine’s clipboard.
    7. Navigate back to your notebook and paste this code into the box asking for it and hit enter.

    Your Colab account is now authorized to use Geemap! This authentication will last one week, after which you’ll have to repeat this procedure. For now, you can comment out that command:

    #ee.Authenticate()

4. Activating Geemap

  • Under the commented #ee.Authenticate() command enter the command ee.Initialize() and run the command.

5. Issuing geemap commands

  • In a new code cell run the following command:

    Map = geemap.Map(center=[40,-100], zoom=4)
Map

    A new map should appear.

  • See if you can move this map to Durham (Lat/Lng = 36,-79), at a zoom level of 10.

    Note the similarity to the command issued in the GEE JavaScript interface. Geemap is essentially allows us to write GEE commands but from Python. Thus, if you decide to switch back to GEE in JavaScript, your work here won’t be in vain!

  • Recalling that our JavaScript code to add the SRTM image in the GEE console was as follows:

    var image = ee.Image('CGIAR/SRTM90_V4');
// Center the Map.
Map.setCenter(-79, 36, 10);
// Display the image.
Map.addLayer(image, {min: 52, max: 276}, 'SRTM');

    Try writing the same code in a new Python code cell. There are three things you’ll have to adapt:

    • First, JavaScript comments are // and will have to be swapped with #
    • Second, the var command is not used in Python. Just remove that.
    • Third, the values min and max need to be in quotes.
    image = ee.Image('CGIAR/SRTM90_V4');
# Center the Map.
Map.setCenter(-79, 36, 10);
# Display the image.
Map.addLayer(image, {"min": 52, "max": 276}, 'SRTM');

  • Explore the map interface within Geemap. It’s quite powerful! More so than the one in GEE!

  • Rename your notebook and save it.

Where to go from here

If you are new to GEE, this is a lot to take in, but I’m hopeful that you are engaged and excited about the opportunity to access petabytes of remotely sensed data via these interfaces. The pathways from here go in many directions, but the next steps will be to gain command of the data formats and how Python can be used to wrangle and analyzed these datasets to your needs.