We often hear from users that they have data that they would like to add to their Collect Earth Online (CEO) projects. Fortunately, CEO provides two easy ways to add your own imagery to your projects. The first is by connecting your own imagery via Web Map Service (WMS) or Web Map Tile Service (WMTS), and the second is by connecting your imagery hosted in Google Earth Engine (GEE). In a previous blog post, we discussed connecting WMS/WMTS data sources. In this blog post, we will discuss connecting GEE raster data sources to CEO.
GEE is a cloud based geospatial processing service. The platform includes a large Data Catalog of publicly hosted data, and also allows users to upload their own raster data. If you want to upload your own data to GEE to connect to CEO, you will need to create an account.
GEE divides raster data into two categories. The first are GEE Image Assets, which are single raster images. They can be either single band, like a classification, or multi-band, like satellite imagery. The second are GEE Image Collection Assets. As the name suggests, these are collections of raster images. Image Collection Assets are often time series. For example, the Landsat 8 dataset includes all images from Landsat 8.
CEO can connect to both types of assets. Connecting to either one requires the Asset ID from GEE, which tells CEO where to find the data, and the Visualization Parameters, which tell CEO how to display the data. Connecting GEE Image Collection Assets to CEO also requires a Start Date and End Date (CEO uses these dates to create a composite image by reducing the collection of images into a single image to display, using GEE’s mean reducer).
We need to collect a few pieces of information to successfully connect your GEE data to CEO.
The first step for connecting your GEE imagery with CEO is to determine the Asset ID for your Image Asset or Image Collection asset. If you are using your own imagery, be sure that the imagery is either shared publicly or if your asset must stay private, that you have given read access to “gateway1 [AT] ceo-production.iam.gserviceaccount [DOT COM]”.
For Image Assets, using your own imagery is more common (rather than the Data Catalog), as most publicly hosted data in GEE are Image Collections. You can find the Asset ID for your own data by clicking on the asset to bring up the Asset Details pane. The Asset ID is located on the left side as “Image ID”.
For Image Collections, if you are using your own data, you can use the instructions above to find the Asset ID. If you are using data from the Data Catalog, you can find the Asset ID on the information page under “Earth Engine Snippet” between the quotation marks.
The second piece of information you will need are the visualization parameters. CEO uses GEE’s image visualization parameters to display your Image Asset or Image Collection Asset. The most important of these parameters are “bands”, “min” and “max”.
The bands argument is needed only for multi-band images. This should either be a single band or a list of three bands to be mapped to RGB.
Min is the value from your data that will be mapped to 0, or black. Max is the value from your data that will be mapped to 255, or white.
For single band images, the “palette” argument is important, as you can use it to specify custom colors. For continuous variables (like tree height), this will create a stretch palette, while for discrete variables (like land cover classifications), this will allow you to assign custom colors to the different classes.
If you don’t know what you would like your visualizations parameters to be, you can use GEE to determine them. If not mapping the image, the Asset Details pane can be helpful. Band information, including the approximate min and max band values, is available in the Asset Details pane under “Bands”. If you do map the image, you can use the Layer Manager to adjust the visualization parameters to your liking. You can also use the Inspector and click on the mapped image to see different band values to help you decide on appropriate min and max values. More information on parameters can be found in GEE’s help files, including on customizing layer visualizations, and color palettes.
The final piece of information, needed for Image Collection Assets only, is your start date and end date. Note that in GEE, the start date is inclusive and the end date is exclusive, so you should provide an end date one day after your desired imagery end date. For most image collections, this is pretty straightforward. However, for image collections with only sporadic dates, you should examine the information in the Data Catalog or the Image Asset Details page (brought up by clicking on your Image Collection Asset).
With all of this information, we can proceed. We can now add all of our information to the Institutional Imagery pane by clicking “Add New Imagery.” Once you select either “GEE Image Asset” or “GEE Image Collection Asset” as the Type, the basic steps to connect your Image Asset to CEO are:
For Image Collection Assets, you will also need to specify your Start Date and End Date.
Remember that you must input your visualization parameters in JSON format into CEO. This means you need to place straight double quotes around the parameter, separate the parameter and argument with a colon, and separate parameter/argument pairs with a comma. You do not need to place quotes around single numbers, and you should not include a semicolon (;) at the end of the parameters.
Once you’ve added the layer from GEE, you can add it to any of your projects and leverage the imagery during data collection.
Hopefully after following these steps, your imagery is working! If instead you see “Source Not Found” instead of your expected imagery, here are some things you can do to try to fix the imagery connection.
First, double check that your image asset or image collection asset is public. For more information on how to do this, see GEE’s guide to managing assets.
Next, double check that both your Asset ID and your band names are correct.
After that, check that your JSON formatting for your parameters is correct. If you’re having trouble with this, there are many tools online to help you check your formatting (e.g. https://www.jsonformatter.io/).
For Image Collection Assets, you will need to check your dates as well. Date is filtered based on a field in the GEE Image Collection Asset dataset. If you have an image collection with one image per year, for example, the Date assigned to the image may be January 1 or another date. You may need to include the entire year to be sure to include the assigned date of your image. In addition, the date may be incorrect in GEE, so you may need to double check your Image Collection Asset. Note that this is really only true for Image Collection Assets you have created, not those available through the Data Catalog.
Also check that you are trying to connect an Image Asset or Image Collection Asset and not a polygon layer–called tables in GEE. If you try to connect this, CEO will show “Source Not Found” in the data collector view and an error “Image.load: Asset ‘Asset_ID’ is not an Image.” in the developer tools console.
If none of these worked, look at the developer tools in your browser. In Windows, you can access these by pressing F12; you can also search for “developer tools” with your browser name and operating system in any search engine. It may show you what is going wrong with your connection. For example, in the below screenshot there are two errors in the developer tools console. The first error is an issue with quotes. The second error is an issue with band names. Fixing these issues results in a successful connection.
If your imagery is showing (no “Source Not Found” error) but it is either entirely black, entirely white, or the wrong colors, you likely need to change your image visualization parameters.
Very dark imagery means that you have included a “;” character after your closing curly bracket in your visualization parameters. Make sure that you do not have a semicolon in your visualization parameters.
All black imagery means that all of your imagery’s values are getting mapped to 0 in the color space. This may indicate that your “max” value is too high or that your “min” value is too high.
All white or very light imagery means the opposite–that all of your imagery’s values are getting mapped to 255 in the color space. This may indicate that your “max” value is too low.
The Data Collection interface in your CEO project allows you to rapidly test different parameters. Once you find parameters you like, copy and paste them from this interface into your Institutional Imagery page by using the “Edit” functionality.
If this fails, the best way to troubleshoot your image visualization is to come up with a scheme in GEE that you like, and then translate it into JSON for CEO.
CEO would like to thank its ongoing funders FAO, NASA–USAID SERVIR, and SilvaCarbon, a US government program. Thanks also to CEO’s technology partners: Norway’s International Climate & Forests Initiative for funding open high-resolution data availability; Planet for providing high-resolution imagery; and the Google Earth Engine team for creating a platform for Earth science data and analysis.
Collect Earth Online is working constantly to improve the user experience, and your feedback is invaluable. If you have ideas to share, please write to firstname.lastname@example.org.