Train Deep Learning Model (Image Analyst)—ArcGIS Pro

Available with Image Analyst license.

Summary

Trains a deep learning model using the output from the Export Training Data For Deep Learning tool.

Usage

This tool trains a deep learning model using deep learning frameworks.
To set up your machine to use deep learning frameworks in ArcGIS Pro, see Install deep learning frameworks for ArcGIS.
This tool can also be used to fine-tune an existing trained model. For example, an existing model that has been trained for cars can be fine-tuned to train a model that identifies trucks.
To run this tool using GPU, set the Processor Type environment to GPU. If you have more than one GPU, specify the GPU ID environment instead.
The input training data for this tool must include the images and labels folders that are generated from the Export Training Data For Deep Learning tool.
For information about requirements for running this tool and issues you may encounter, see Deep Learning Frequently Asked Questions.
For more information about deep learning, see Deep learning in ArcGIS Pro.

Syntax

TrainDeepLearningModel(in_folder, out_folder, {max_epochs}, {model_type}, {batch_size}, {arguments}, {learning_rate}, {backbone_model}, {pretrained_model}, {validation_percentage}, {stop_training}, {freeze})

Parameter	Explanation	Data Type
in_folder	The folder containing the image chips, labels, and statistics required to train the model. This is the output from the Export Training Data For Deep Learning tool. To train a model, the input images must be 8-bit rasters with three bands.	Folder
out_folder	The output folder location that will store the trained model.	Folder
max_epochs (Optional)	The maximum number of epochs for which the model will be trained. A maximum epoch of one means the dataset will be passed forward and backward through the neural network one time. The default value is 20.	Long
model_type (Optional)	Specifies the model type to use to train the deep learning model. SSD —The Single Shot Detector (SSD) approach will be used to train the model. SSD is used for object detection. The input training data for this model type uses the Pascal Visual Object Classes metadata format. UNET —The U-Net approach will be used to train the model. U-Net is used for pixel classification. FEATURE_CLASSIFIER —The Feature Classifier approach will be used to train the model. This is used for object or image classification. PSPNET —The Pyramid Scene Parsing Network (PSPNET) approach will be used to train the model. PSPNET is used for pixel classification. RETINANET —The RetinaNet approach will be used to train the model. RetinaNet is used for object detection. The input training data for this model type uses the Pascal Visual Object Classes metadata format. MASKRCNN —The MaskRCNN approach will be used to train the model. MaskRCNN is used for object detection. It is used for instance segmentation, which is precise delineation of objects in an image. This model type can be used to detect building footprints. It uses the MaskRCNN metadata format for training data as input. Class values for input training data must start at 1. This model type can only be trained using a CUDA-enabled GPU. YOLOV3 —The YOLOv3 approach will be used to train the model. YOLOv3 is used for object detection. DEEPLAB —The DeepLabV3 approach will be used to train the model. DeepLab is used for pixel classification. FASTERRCNN —The FasterRCNN approach will be used to train the model. FasterRCNN is used for object detection.	String
batch_size (Optional)	The number of training samples to be processed for training at one time. The default value is 2. If you have a powerful GPU, this number can be increased to 8, 16, 32, or 64.	Long
arguments [arguments,...] (Optional)	The function arguments are defined in the Python raster function class. This is where you list additional deep learning parameters and arguments for experiments and refinement, such as a confidence threshold for adjusting sensitivity. The names of the arguments are populated from reading the Python module. When you choose SSD as the model_type parameter value, the arguments parameter will be populated with the following arguments: grids—The number of grids the image will be divided into for processing. Setting this argument to 4 means the image will be divided into 4 x 4 or 16 grid cells. If no value is specified, the optimal grid value will be calculated based on the input imagery. zooms—The number of zoom levels each grid cell will be scaled up or down. Setting this argument to 1 means all the grid cells will remain at the same size or zoom level. A zoom level of 2 means all the grid cells will become twice as large (zoomed in 100 percent). Providing a list of zoom levels means all the grid cells will be scaled using all the numbers in the list. The default is 1.0. ratios—The list of aspect ratios to use for the anchor boxes. In object detection, an anchor box represents the ideal location, shape, and size of the object being predicted. Setting this argument to [1.0,1.0], [1.0, 0.5] means the anchor box is a square (1:1) or a rectangle in which the horizontal side is half the size of the vertical side (1:0.5). The default is [1.0, 1.0]. When you choose any of the pixel classification models such as PSPNET, UNET, or DEEPLAB as the model_type parameter value, the arguments parameter will be populated with the following arguments: USE_UNET—The U-Net decoder will be used to recover data once the pyramid pooling is complete. The default is True. This argument is specific to the PSPNET model. PYRAMID_SIZES—The number and size of convolution layers to be applied to the different subregions. The default is [1,2,3,6]. This argument is specific to the PSPNET model. MIXUP—Specifies whether to use mixup augmentation and mixup loss. The default is False. CLASS_BALANCING—Specifies whether to balance the cross-entropy loss inverse to the frequency of pixels per class. The default is False. FOCAL_LOSS—Specifies whether to use focal loss. The default is False. IGNORE_CLASSES—Contains the list of class values on which the model will not incur loss. When you choose RETINANET as the model_type parameter value, the arguments parameter will be populated with the following arguments: SCALES—The number of scale levels each cell will be scaled up or down. The default is [1, 0.8, 0.63]. RATIOS—The aspect ratio of the anchor box. The default is [0.5,1,2]. All model types support the chip_size argument, which is the chip size of the tiles in the training samples. The image chip size is extracted from the .emd file from the folder specified in the in_folder parameter.	Value Table
learning_rate (Optional)	The rate at which existing information will be overwritten with newly acquired information throughout the training process. If no value is specified, the optimal learning rate will be extracted from the learning curve during the training process.	Double
backbone_model (Optional)	Specifies the preconfigured neural network to be used as an architecture for training the new model. This method is known as Transfer Learning. DENSENET121 —The preconfigured model will be a dense network trained on the ImageNET Dataset that contains more than 1 million images and is 121 layers deep. Unlike RESNET, which combines the layer using summation, DenseNet combines the layers using concatenation. DENSENET161 —The preconfigured model will be a dense network trained on the ImageNET Dataset that contains more than 1 million images and is 161 layers deep. Unlike RESNET, which combines the layer using summation, DenseNet combines the layers using concatenation. DENSENET169 —The preconfigured model will be a dense network trained on the ImageNET Dataset that contains more than 1 million images and is 169 layers deep. Unlike RESNET, which combines the layer using summation, DenseNet combines the layers using concatenation. DENSENET201 —The preconfigured model will be a dense network trained on the ImageNET Dataset that contains more than 1 million images and is 201 layers deep. Unlike RESNET, which combines the layer using summation, DenseNet combines the layers using concatenation. MOBILENET_V2 —This preconfigured model is trained on the ImageNet Database and is 54 layers deep geared toward Edge device computing, since it uses less memory. RESNET18 —The preconfigured model will be a residual network trained on the ImageNET Dataset that contains more than million images and is 18 layers deep. RESNET34 —The preconfigured model will be a residual network trained on the ImageNET Dataset that contains more than 1 million images and is 34 layers deep. This is the default. RESNET50 —The preconfigured model will be a residual network trained on the ImageNET Dataset that contains more than 1 million images and is 50 layers deep. RESNET101 —The preconfigured model will be a residual network trained on the ImageNET Dataset that contains more than 1 million images and is 101 layers deep. RESNET152 —The preconfigured model will be a residual network trained on the ImageNET Dataset that contains more than 1 million images and is 152 layers deep. VGG11 —The preconfigured model will be a convolution neural network trained on the ImageNET Dataset that contains more than 1 million images to classify images into 1,000 object categories and is 11 layers deep. VGG11_BN —This preconfigured model is based on the VGG network but with batch normalization, which means each layer in the network is normalized. It trained on the ImageNet dataset and has 11 layers. VGG13 —The preconfigured model will be a convolution neural network trained on the ImageNET Dataset that contains more than 1 million images to classify images into 1,000 object categories and is 13 layers deep. VGG13_BN —This preconfigured model is based on the VGG network but with batch normalization, which means each layer in the network is normalized. It trained on the ImageNet dataset and has 13 layers. VGG16 —The preconfigured model will be a convolution neural network trained on the ImageNET Dataset that contains more than 1 million images to classify images into 1,000 object categories and is 16 layers deep. VGG16_BN —This preconfigured model is based on the VGG network but with batch normalization, which means each layer in the network is normalized. It trained on the ImageNet dataset and has 16 layers. VGG19 —The preconfigured model will be a convolution neural network trained on the ImageNET Dataset that contains more than 1 million images to classify images into 1,000 object categories and is 19 layers deep. VGG19_BN —This preconfigured model is based on the VGG network but with batch normalization, which means each layer in the network is normalized. It trained on the ImageNet dataset and has 19 layers. DARKNET53 —The preconfigured model will be a convolutional neural network trained on the ImageNET Dataset that contains more than 1 million images and is 53 layers deep.	String
pretrained_model (Optional)	The pretrained model to be used for fine-tune training the new model. The input is an Esri Model Definition file (.emd) or a deep learning package file (.dlpk). A pretrained model with similar classes can be fine-tuned to fit the new model. The pretrained model must have been trained with the same model type and backbone model that will be used to train the new model.	File
validation_percentage (Optional)	The percentage of training samples that will be used for validating the model. The default value is 10.	Double
stop_training (Optional)	Specifies whether early stopping will be implemented. STOP_TRAINING —The model training will stop when the model is no longer improving, regardless of the max_epochs parameter value specified. This is the default. CONTINUE_TRAINING —The model training will continue until the max_epochs parameter value is reached.	Boolean
freeze (Optional)	Specifies whether the backbone layers in the pretrained model will be frozen, so that the weights and biases remain as originally designed. FREEZE_MODEL —The predefined weights and biases will not be altered in the backbone_model parameter. This is the default. UNFREEZE_MODEL —The weights and biases of the backbone_model parameter can be altered to better fit your training samples. This takes more time to process but usually produces better results.	Boolean

Derived Output

Name	Explanation	Data Type
out_model_file	The output trained model file.	File

Code sample

TrainDeepLearningModel example 1 (Python window)

This example trains a tree classification model using the U-Net approach.

# Import system modules  
import arcpy  
from arcpy.ia import *  
 
# Check out the ArcGIS Image Analyst extension license 
arcpy.CheckOutExtension("ImageAnalyst") 
 
# Execute 
TrainDeepLearningModel(r"C:\DeepLearning\TrainingData\Roads_FC", 
     r"C:\DeepLearning\Models\Fire", 40, "UNET", 16, "# #", None, 
     "RESNET34", None, 10, "STOP_TRAINING", "FREEZE_MODEL")

TrainDeepLearningModel example 2 (stand-alone script)

This example trains an object detection model using the SSD approach.

# Import system modules  
import arcpy  
from arcpy.ia import *  
 
# Check out the ArcGIS Image Analyst extension license 
arcpy.CheckOutExtension("ImageAnalyst") 
 
#Define input parameters
in_folder = "C:\\DeepLearning\\TrainingData\\Cars" 
out_folder = "C:\\Models\\Cars"
max_epochs = 100
model_type = "SSD"
batch_size = 2
arg = "grids '[4, 2, 1]';zooms '[0.7, 1.0, 1.3]';ratios '[[1, 1], [1, 0.5], [0.5, 1]]'"
learning_rate = 0.003
backbone_model = "RESNET34" 
pretrained_model = "C:\\Models\\Pretrained\\vehicles.emd"
validation_percent = 10
stop_training = "STOP_TRAINING"
freeze = "FREEZE_MODEL"


# Execute
TrainDeepLearningModel(in_folder, out_folder, max_epochs, model_type, 
     batch_size, arg, learning_rate, backbone_model, pretrained_model, 
     validation_percent, stop_training, freeze)

Environments

Current Workspace, Extent, Processor Type, GPU ID, Parallel Processing Factor, Scratch Workspace

Licensing information

Basic: Requires Image Analyst
Standard: Requires Image Analyst
Advanced: Requires Image Analyst