Principal Investigator Contact Information

Name: Xihong Lian
Institution: Wuhan University
Email: lianxh@whu.edu.cn

Alternate Contact Information

Name: Limin Jiao
Institution: Wuhan University
Email: lmjiao@whu.edu.cn

1. Overview

This repository contains the identification results of individual urban trees in Africa (IUTAC-1) produced by Lian and Jiao, as well as the data and code required to replicate those results. Dataset (IUTAC-1) includes individual trees across 40 sampled cities in Africa. Global urban boundaries (GUB, ref.1) in 2018 are used to delineate urban boundaries in Africa. In the 40 sampled cities, this study investigated the response of tree cover to the environmental conditions along the degree of urban informality, and estimated the potential impact of future urban expansion on tree crown cover. IUTAC-1 is a 1-m resolution map of individual tree crown cover.

Fig.1 Schematic organization of this repository

|----（This repository）
|
|----|----（Data: IUTAC-1）
|    |----|-------(Info_sheet.xlsx)
|    |
|    |----|-------(IUTAC-1)
|         |----|-------(XX.zip)
|              |----|-------(XX_YYYYYY.tif)
|
|----|----（Code: two-step methodology）
     |----|-------(DownloadImageCode)
     |    |----|-------(GSI_Downloader.py)     
     |    |----|-------(SHP)
     |
     |----|-------(HR-SFANet)
     |    |----|-------(models)
     |    |----|-------(scripts) 
     |    |----|-------(utils)
     |    |----|-------(environment)     
     |         
     |----|-------(IUTC_V1.0_GUI)
          |----|-------(GUI)         
          |----|-------(TestData)  

2. Data.zip: Individual urban trees in African cities (IUTAC-1)

A two-step methodology, including a deep learning model and a segmentation curve, was developed for the identification of individual urban trees. We performed this methodology to examine individual trees across 40 cities from Google satellite imagery with ~0.6 m spatial resolution. IUTAC-1 is a 1-meter spatial resolution raster data obtained by transforming and aggregating the original identification results.

2.1 Data Dates

The dates of the IUTAC-1 dataset are consistent with those of Google imagery. We acquired Google satellite imagery for the July 2023 version.

2.2 Data Spatial Scope

The 40 cities span 25 countries, including 15 in West Africa, 2 in North Africa, 4 in Central Africa, 9 in Southern Africa, and 10 in East Africa, and cover three Köppen-Geiger classes: Zones A (tropical or equatorial; 18 cities), B (arid or dry; 10 cities), C (warm/mild temperate; 12 cities).

2.3 Description of the data and file structure

This repository includes table (Info_sheet.xlsx) for recording city information, and IUTAC-1 Folder.

2.3.1 Info_sheet.xlsx

Number of variables: 10
Number of rows: 41
Variable list:

• ID: (character) is the serial number;
• ID_city_selected (character) is unique for each city and corresponds to each zip file;
• City name: (character) represents the specific name of each city;
• ADMIN: (character) indicates the name of the country where each city is located;
• ‌ADM0: (character) ADMIN code.
• United Nations’ Geoscheme: (character) The continent of Africa is divided into five subregions according to the United Nations’ Geoscheme4, including West Africa (WA), Northern Africa (NA), Central Africa (CA), Southern Africa (SA), and East Africa (EA).
• Köppen-Geiger classes: (character) denotes Köppen-Geiger classes including Zones A (tropical or equatorial), B (arid or dry), and C (warm/mild temperate).
• Types: (character) Sampled cities.
• Image blocks: (numeric) indicates the number of image blocks covered by this city.
• Informal settlements data: (character) indicates whether informal settlements data (i.e., block street access) were acquired. 

Data type: character, numeric

NOTE: The urban boundaries identified in this study do not correspond to administrative boundaries, as exemplified by Vanderbijlpark (ID=46; Africa), which may encompass Vereeniging and Sasolburg.

2.3.2 IUTAC-1 Folder

This section shows individual urban tree datasets in 40 sampled cities.

• IUTAC-1 Folder: contains 40 files in the form of XX.zip;
• XX.zip: XX denotes the unique ID for each city (see Info_sheet.xlsx). These XX.zip files are a total of 1.3GB, each containing a lot of XX_YYYYYY.tif raster data, and these files are about 80-90 GB when unzipped.
• XX_YYYYYY.tif: We divided each city into grids of 0.01 degrees multiplied by 0.01 degrees. Each XX_YYYYYY.tif file thus corresponds to a spatial grid.

XX_YYYYYY.tif

Raster information

• Number of bands: 1;
• Cell size (x, y): 1, 1 (Units: Meters);
• Pixel type: signed integer;
• Pixel depth: 32-bit;
• NoData value: 0;
• Linear Unit: Meter (1.000000).

Attribute table

• OID: Unique ID
• Value: Value response to individual urban trees;
• Count: Total number of statistics for each unique value.

This dataset can be easily opened with the ArcGIS software or the open-source QGIS.

3. Code.zip: a two-step methodology

This repository provides code and executable programs for downloading high-resolution remote sensing imagery, detecting tree locations, and identifying tree crown cover.

3.1 Downloading Images

This section shows how to download Google satellite imagery (GSI) by using the Python packages and the Google Static Map API. We have provided a script (GSI_Downloader.py), please see the DownloadImageCode folder.

3.1.1 GSI_Downloader

GSI_Downloader can download Google satellite imagery by specifying coordinates or providing a vector file (shapefile polygon). GSI_Downloader is based on work on Stackoverflow.

3.1.2 Script

Prerequisites:

1. Google Cloud Account: You need a Google Cloud account to use the Google Maps API.
2. API Key: Enable the Google Static Maps API and obtain an API key.
3. Python Environment: Ensure the Python environment is installed on your PC.

Using GSI_Downloader to download the imagery, including

1. Download imagery using coordinates;
2. Download imagery using a shapefile;

3.1.3 To create an API key

Steps to Get a Google Maps API Key (Click here):

1. Go to the Google Maps Platform > Credentials page.
2. On the Credentials page, click Create credentials > API key.

3.1.4 Running code

When running the code, the following fields are required:
API key, specify coordinates (southeast and northwest) or provide a shapefile polygon, specify the zoom level, and the output path.

3.2 Detecting tree locations

This section shows how to use the HR-SFANet network to detect tree locations in urban environments with multispectral imagery.

3.2.1 HR-SFANet architecture

HR-SFANet network, developed by Ventura et al. (2024) (ref.2), is employed to detect tree locations using local peak finding in a confidence map.

HR-SFANet network includes a VGG-16 backbone, a confidence head, and an attention head (please see ref.2 for more details).

3.2.2 Scripts

Five Python files for the HR-SFANet network can be found under the subfolder scripts, including 01prepare, 02train, 03tune, 04test, and 05inference.

1. 01prepare: to prepare a dataset
2. 02train: to train the model
3. 03tune: hyperparameter tuning
4. 04test: to compute evaluation metrics
5. 05inference: to detect tree locations in imagery

The source code for HR-SFANet was developed by Ventura et al. (2024), and we modified it and altered the output of 05inference to a shapefile point file and a confidence map raster file.

HR-SFANet network requires only point annotations, which is both an advantage and a disadvantage.

• Advantage: Only point annotations rather than boundary annotations or tree crown covers are required, which greatly alleviates workloads.
• Disadvantage: It is incapable of doing anything to output the crown cover of individual urban trees.

3.2.3 How to prepare data

The location of each tree in the image needs to be labeled manually.

• Images as TIFF files (three/four-band imagery) in a subdirectory;
• For each image, a csv file containing coordinates (x, y) for the tree locations;
• For each image, a GeoJSON file containing geo-referenced tree locations;
• Files train.txt, val.txt, and test.txt specify the splits using all of the data.

3.3 Identifying tree crown cover

This section provides an executable program (i.e., IUTC_V1.0_GUI) for segmenting the crown cover of individual trees. To minimize the time-consuming process of debugging the code, we provide an executable program. This program is free for anyone to quickly segment the crown cover of individual urban trees and also supports batch processing. You can just double-click to run the program, which consists of three main options.

The program used a confidence map and predicted tree locations as inputs and output the crown cover of individual trees.

3.3.1 IUTC_V1.0_GUI

The GUI can be opened on Windows.

Entering option 1 takes you to the segmentation program, where you are then asked to enter the confidence map, point file, threshold parameter, and output path. When finished running the program, two subfolders are generated automatically under the output path, i.e., Tree_point and Tree_polygon.

3.3.2 Input parameters

1. Confidence Map: produced by the HR-SFANet network
2. Tree locations: produced by the HR-SFANet network
3. Threshold: a threshold to distinguish between tree crown cover and non-tree crown cover
4. Output: outputdir

3.3.3 Testing Data

We have provided testing data, please see the TestData folder, including

1. Confidence_MAP
2. Tree_location

Recommended Citation

Lian, X. & Jiao, L. Data for: Mapping of individual urban trees and relationships within informal settlements in Africa. Dryad. https://doi.org:10.5061/dryad.jwstqjqn5 (2025).

References (in this README)

1. Li, X., Gong, P., Zhou, Y., Wang, J., Bai, Y., Chen, B., Hu, T., Xiao, Y., Xu, B., Yang, J., Liu, X., Cai, W., Huang, H., Wu, T., Wang, X., Lin, P., Li, X., Chen, J., He, C., . . . Zhu, Z. (2020). Mapping global urban boundaries from the global artificial impervious area (GAIA) data. Environmental Research Letters, 15(9), 094044.
2. Ventura, J., Pawlak, C., Honsberger, M., Gonsalves, C., Rice, J., Love, N. L. R., Han, S., Nguyen, V., Sugano, K., Doremus, J., Fricker, G. A., Yost, J., & Ritter, M. (2024). Individual Tree Detection in Large-Scale Urban Environments using High-Resolution Multispectral Imagery. International Journal of Applied Earth Observation and Geoinformation, 130, 103848.