Detect Change Using Deep Learning (Image Analyst)—ArcGIS Pro

Available with Image Analyst license.

Summary

Runs a trained deep learning model to detect change between two rasters.

This tool requires a model definition file containing trained model information. The model definition file can be an Esri model definition JSON file (.emd) or a deep learning model package, and it must contain the path to the Python raster function to be called to process each object and the path to the trained binary deep learning model file.

Usage

The inputs for this tool are two images: an image of a previous time and an image of a more recent time. The output is a classified raster dataset that shows the change between the two raster inputs.
You must install the proper deep learning framework Python API (such as TensorFlow or PyTorch) in the ArcGIS Pro Python environment; otherwise, an error will occur when you add the Esri model definition file to the tool. Obtain the appropriate framework information from the creator of the Esri model definition file.
To set up your machine to use deep learning frameworks in ArcGIS Pro, see Install deep learning frameworks for ArcGIS.
This tool calls a third-party deep learning Python API (such as TensorFlow, PyTorch, or Keras) and uses the specified Python raster function to process each object.
The Model Definition parameter value can be an Esri model definition JSON file (.emd), a JSON string, or a deep learning model package (.dlpk). A JSON string is useful when this tool is used on the server so you can paste the JSON string rather than upload the .emd file. The .dlpk file must be stored locally.
Additional input parameters may be necessary such as mini-batch size, padding size, and so on.

See the sample below for a model definition JSON file (.emd).

Sample model definition JSON file


{
   "Framework": "",
   "ModelConfiguration":" ",
   "ModelFile":"",
   "InferenceFunction":"",
   "ModelType":"",
   "ImageHeight":256,
   "ImageWidth":256,
   "ExtractBands":[0,1,2],
   "CropSizeFixed": 1,
   "BlackenAroundFeature": 1,
      "Classes": [
      {
         "Value": 0,
            "Name": "Building",
            "Color": [255, 0, 0]
           	}
   ]
}

Increasing the batch size can improve tool performance; however, as the batch size increases, more memory is used. If an out of memory error occurs, use a smaller batch size. The batch_size value can be adjusted using the Arguments parameter.
Batch sizes are square numbers, such as 1, 4, 9, 16, 25, 64 and so on. If the input value is not a perfect square, the highest possible square value is used. For example, if a value of 6 is specified, it means that the batch size is set to 4.
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.

Parameters

Label	Explanation	Data Type
From Raster	The input raster before the change.	Raster Dataset; Raster Layer; Mosaic Layer; Image Service; Map Server; Map Server Layer; Internet Tiled Layer
To Raster	The input raster after the change.	Raster Dataset; Raster Layer; Mosaic Layer; Image Service; Map Server; Map Server Layer; Internet Tiled Layer
Output Classified Raster	The output classified raster that shows the change.	Raster Dataset
Model Definition	The Model Definition parameter value can be an Esri model definition JSON file (.emd), a JSON string, or a deep learning model package (.dlpk). A JSON string is useful when this tool is used on the server so you can paste the JSON string rather than upload the .emd file. The .dlpk file must be stored locally. It contains the path to the deep learning binary model file, the path to the Python raster function to be used, and other parameters such as preferred tile size or padding.	File; String
Arguments (Optional)	The information from the Model Definition parameter will be used to populate this parameter. These arguments vary, depending on the model architecture. The following are supported model arguments for models trained in ArcGIS. ArcGIS pretrained models and custom deep learning models may have additional arguments that the tool supports. padding—The number of pixels at the border of image tiles from which predictions are blended for adjacent tiles. To smooth the output while reducing artifacts, increase the value. The maximum value of the padding can be half of the tile size value. The argument is available for all model architectures. batch_size—The number of image tiles processed in each step of the model inference. This depends on the memory of your graphic card. The argument is available for all model architectures.	Value Table

DetectChangeUsingDeepLearning(from_raster, to_raster, out_classified_raster, in_model_definition, {arguments})

Name	Explanation	Data Type
from_raster	The input raster before the change.	Raster Dataset; Raster Layer; Mosaic Layer; Image Service; Map Server; Map Server Layer; Internet Tiled Layer
to_raster	The input raster after the change.	Raster Dataset; Raster Layer; Mosaic Layer; Image Service; Map Server; Map Server Layer; Internet Tiled Layer
out_classified_raster	The output classified raster that shows the change.	Raster Dataset
in_model_definition	The in_model_definition parameter value can be an Esri model definition JSON file (.emd), a JSON string, or a deep learning model package (.dlpk). A JSON string is useful when this tool is used on the server so you can paste the JSON string rather than upload the .emd file. The .dlpk file must be stored locally. It contains the path to the deep learning binary model file, the path to the Python raster function to be used, and other parameters such as preferred tile size or padding.	File; String
arguments [arguments,...] (Optional)	The information from the in_model_definition parameter will be used to set the default values for this parameter. These arguments vary, depending on the model architecture. The following are supported model arguments for models trained in ArcGIS. ArcGIS pretrained models and custom deep learning models may have additional arguments that the tool supports. padding—The number of pixels at the border of image tiles from which predictions are blended for adjacent tiles. To smooth the output while reducing artifacts, increase the value. The maximum value of the padding can be half of the tile size value. The argument is available for all model architectures. batch_size—The number of image tiles processed in each step of the model inference. This depends on the memory of your graphic card. The argument is available for all model architectures.	Value Table

Code sample

DetectChangeUsingDeepLearning example 1 (Python window)

This example runs a deep learning model to find the difference between two images.

# Import system modules 
import arcpy 
from arcpy.ia import * 


# Check out the ArcGIS Image Analyst extension license 
arcpy.CheckOutExtension("ImageAnalyst")


DetectChangeUsingDeepLearning("c://detectchange//input_image1.tif", 
     "c://detectchange//input_image2.tif", "c://detectchange//output_difference.tif", 
     "c://detectchange/detectBuilding.emd", "padding 0;score_threshold 0.6;batch_size 4")

DetectChangeUsingDeepLearning example 2 (stand-alone script)

This example runs a deep learning model to find the difference between two images.

# Import system modules 
import arcpy 
from arcpy.ia import * 

""" 
Usage: DetectObjectsUsingDeepLearning(from_raster, to_raster, out_classified_raster, 
    in_model_definition, {model_arguments}) 
"""

# Check out the ArcGIS Image Analyst extension license 
arcpy.CheckOutExtension("ImageAnalyst")

# Set local variable
from_raster = r"c:/detectchange/input_image1.tif"
to_raster = r"c:/detectchange/input_image2.tif"
out_classified_raster = r"c:/detectchange/output_difference.tif"
in_model_definition = r"c:/ detectchange/detectbuilding.emd"

# arcpy.env.processorType = "GPU"
# arcpy.env.gpuId = 0

# Execute
DetectChangeUsingDeepLearning(from_raster, to_raster, out_classified_raster, 
    in_model_definition, "padding 0;score_threshold 0.6;batch_size 4")

Environments

Cell Size, Current Workspace, Extent, Geographic Transformations, GPU ID, Output Coordinate System, Parallel Processing Factor, Processor Type, Scratch Workspace

Licensing information

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