Example: End-to-end deep learning workflow—ArcGIS Notebook Server

Deep learning models are typically large and require significant computational power. By integrating the training of models with ArcGIS API for Python, you can create deep learning models that are both compact and suitable for mobile deployment.

In this example notebook workflow, the Multi-task Road Extractor model is used to extract a road network from satellite imagery.

Requirements

To perform this workflow, you must meet the following requirements:

The training dataset, comprised of SpaceNet data for road centerlines in the Paris region.
Note:
If you cannot access the training dataset, Raster Server is required to generate suitable training data in the required format.
To run this workflow, the maximum memory limit of your notebook environment must be set to 15GB. The memory limit in Standard and Advanced notebook environments are set to 4GB and 6GB respectively by default. To change this limit, sign in to ArcGIS Notebook Server Manager with administrative access and click Settings > Runtimes.
Note:
The memory limit necessary for this workflow depends on the size of the training data.
Deep learning is computationally intensive, and it is recommended that you use a powerful GPU to process large datasets.

Python library imports

Import the following Python libraries:

from arcgis.gis import GIS
gis = GIS("home")

import os, zipfile
from pathlib import Path

from arcgis.learn import prepare_data, MultiTaskRoadExtractor

Upload data to your workspace

Upload the dataset into your notebook workspace under Files as a .zip file containing labeled images chips in a folder named images.

#Adding zipped file from workspace
filepath = training_data = gis1.content.get('itemID')
filepath = training_data.download(save_path='/arcgis/home/input', file_name=training_data.name)
filepath
assert os.path.exists(filepath) == 1

#Extract zip
with zipfile.ZipFile(filepath, 'r') as zip_ref:
    zip_ref.extractall(Path(filepath).parent)
 
#Get the data path
output_path = Path(os.path.join(os.path.splitext(filepath)[0]))

Prepare your data

The prepare_data() function in the ArcGIS API for Python prepares data for deep learning workflows. The function reads training samples and automates the data preparation process by applying various transformations and augmentations to the training data. These augmentations allow for models to be trained with limited data and prevent overfitting of models.

data = prepare_data(
    path=output_path,
    batch_size=4,
    chip_size=512
)
data.classes

For information on the prepare_data() function parameters, see the arcgis.learn API reference.

Visualize your data

Once you have prepared your data, you can use the show_batch() function to visualize samples from it.

data.show_batch(alpha=1)

Load the model architecture

The Multi-task Road Extractor framework in arcgis.learn supports two architectures that can be set using the parameter mt1_model. The parameter can be set to either the linknet or hourglass architecture.

Model specific advanced parameters can optionally be set at this stage:

gaussian_thresh— Sets the gaussian threshold, which allows you to set the required road width.
orient_bin_size— Sets the bin size for orientation angles.
orient_theta— Sets the width of the orientation mask.

model = MultiTaskRoadExtractor(data, mtl_model="hourglass")

Calculate the learning rate

ArcGIS API for Python uses fast.ai's learning rate finder to find an optimal learning rate for training your models. Use the lr_find() method to find an optimal learning rate to train a robust model. Once you have determined the learning rate with the first run of your model, you can pass it as a fixed value for further runs while retraining the model.

lr = model.lr_find()
#lr =  0.0005754 #from the first run

Model fitting

The fit() method is used to train your model. The method requires an input for the epoch parameter. An epoch defines the number of times the model will be exposed to the entire training dataset. Each epoch allows the model to learn and adjust its weights based on the data. In the following example, the model is run for three epochs for testing purposes.

It is recommended that you start with 25 epochs to obtain a more accurate model for deployment.

model.fit(3, lr=lr, early_stopping=True)

Visualize the results

To validate the results of your model in your notebook, you can use the show_results() method to compare your model's predictions with random ground truth images.

model.show_results(rows=4, thresh=0.2)

Save the model

Once you have confirmed the accuracy of your trained model, save it for future deployment. By default the model will be saved as a .dlpk file to the models subfolder within the training data folder.

model.save('/arcgis/home/road_model_for_spacenet_data')

Deploy the model

Your saved .dlpk file can now be deployed with other datasets and shared within your organization. For information on how to consume a .dlpk file, see Example: Inferencing using a pretrained model.

Feedback on this topic?