Back to Top

Extract Features Using AI Models (GeoAI)

In this topic

  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information

Available with Image Analyst license.

Summary

Runs one or more pretrained deep learning models on an input raster to extract features and automate the postprocessing of the inferenced outputs.

Learn more about how Extract Features Using AI Models works

Usage

  • This tool requires ArcGIS pretrained models from ArcGIS Living Atlas of the World or custom deep learning model packages (.dlpk file).

  • You must install the proper deep learning framework for Python in ArcGIS AllSource.

    Learn how to install deep learning frameworks for ArcGIS

  • The time it takes for the tool to produce the outputs depends on the following:

    • The area of interest used for inference
    • The number of models selected

  • To run this tool, a GPU-equipped machine is required. If you have more than one GPU, specify the GPU ID instead.

  • Potential use cases for the tool include creating a basemap using multiple models and postprocessing model outputs using algorithms to clean extracted features.

  • For information about requirements for running this tool and issues you may encounter, see Deep Learning frequently asked questions.

Parameters

DialogPython

LabelExplanationData Type
Input Raster

The input raster on which processing will be performed.

If the Mode parameter is specified as Only Postprocess, a raster with binary classification is required for this parameter.

Raster Layer; Raster Dataset; Mosaic Layer
Mode

Specifies the mode that will be used for the processing of the input raster.

  • Infer and Postprocess—Features will be extracted from the imagery and postprocessed. This is the default.
  • Only Postprocess—The input raster will be directly postprocessed. A single band raster with binary classification is required for this option.
String
Output Location

The file geodatabase where the intermediate output from the models and the final postprocessed output will be stored.

Workspace
Output Prefix

A prefix that will be added to the name of the outputs that will be saved to the output location. The prefix will also be used as the name of a group layer that will be used to display all outputs.

String
Area of Interest
(Optional)

The geographical extent that will be used to extract features. Only features within the area of interest will be extracted.

Feature Set
Pretrained Models
(Optional)

The ArcGIS pretrained models from ArcGIS Living Atlas of the World that can be used on the provided input raster. This parameter requires an internet connection to download the pretrained models.

String
Additional Models
(Optional)

The deep learning models that can be used on the provided input raster and the postprocessing workflow that will be used for additional model files (.dlpk and .emd). Available postprocessing workflows are as follows:

  • Line Regularization—The postprocessing workflow will extract line features from a single band raster with binary classification and generate a polyline feature class after refining it. This workflow also supports deep learning models that generate polyline feature classes.
  • Parcel Regularization—The postprocessing workflow will extract parcels from a single band raster with binary classification and generate a polygon feature class after refining it.
  • Polygon Regularization—The postprocessing workflow will generate a polygon feature class after refining it. This workflow is only compatible with object detection models.
  • Polygon Segmentation—The postprocessing workflow will generate a polygon feature class containing the detected objects using their centroid or bounding box. The segmentation method is specified using the Prompt parameter.
  • None—No postprocessing workflow will be applied. This is the default.

Value Table
Confidence Threshold
(Optional)

The minimum confidence of deep learning model that will be used when detecting objects. The value must be between 0 and 1.

Double
Save Intermediate Output
(Optional)

Specifies whether the intermediate outputs will be saved to the output location. The term intermediate outputs refers to the results generated after the model has been inferenced.

  • Checked—The intermediate outputs will be saved to the output location.
  • Unchecked—The intermediate outputs will not be saved. This is the default.
Boolean
Test Time Augmentation
(Optional)

Specifies whether predictions of flipped and rotated variants of the input image will be merged into the final output.

  • Checked—Predictions of flipped and rotated variants of the input image will be merged into the final output.
  • Unchecked—Predictions of flipped and rotated variants of the input image will not be merged into the final output. This is the default.

Boolean
Buffer Distance
(Optional)

The distance that will be used to buffer polyline features before they are used in postprocessing. The default is 15 meters.

Linear Unit
Extend Length
(Optional)

The maximum distance a line segment will be extended to an intersecting feature. The default is 25 meters.

Linear Unit
Smoothing Tolerance
(Optional)

The tolerance used by the Polynomial Approximation with Exponential Kernel (PAEK) algorithm. The default is 30 meters.

Linear Unit
Dangle Length
(Optional)

The length at which line segments that do not touch another line at both endpoints (dangles) will be trimmed. The default is 5 meters.

Linear Unit
Input Road Features
(Optional)

A road feature class that will be used for refining the parcels. The input can be a polygon or polyline feature class.

Feature Layer; Feature Class
Road Buffer Width
(Optional)

The buffer distance that will be used for the input road features. The default value is 5 meters for polyline features and 0 meters for polygon features.

Linear Unit
Regularize Parcels
(Optional)

Specifies whether extracted parcels will be normalized by eliminating undesirable artifacts in their geometry.

  • Checked—Extracted parcels will be normalized. This is the default.
  • Unchecked—Extracted parcels will not be normalized.
Boolean
Post Processing Workflow
(Optional)

Specifies the postprocessing workflow that will be used.

  • Line Regularization—Line features will be extracted from a single band raster with binary classification and a polyline feature class will be generated after refining it.
  • Parcel Regularization—Parcels will be extracted from a single band raster with binary classification and a polygon feature class will be generated after refining it.
  • Polygon Regularization— A polygon feature class will be generated after refining it. This workflow is only compatible with object detection models.
String
Output Features
(Optional)

The feature class containing the postprocessed output.

Feature Class
Tolerance Between Adjacent Parcels
(Optional)

The minimum distance between coordinates before they are considered equal. This parameter is used to reduce slivers between extracted parcels. The default is 3 meters.

Linear Unit
Regularization Method
(Optional)

Specifies the regularization method that will be used in postprocessing.

  • Right Angles—Shapes composed of 90° angles between adjoining edges will be constructed. This is the default.
  • Right Angles and Diagonals—Shapes composed of 45° and 90° angles between adjoining edges will be constructed.
  • Any Angles—Shapes that form any angles between adjoining edges will be constructed.
  • Circle—The maximum distance from the boundary of the feature being processed will be used.
String
Tolerance
(Optional)

The maximum distance that the regularized footprint can deviate from the boundary of its originating feature. The default is 1 meter.

Linear Unit
Prompt
(Optional)

Specifies the segmentation method that will be used when the Additional Models parameter is set to Polygon Segmentation.

  • Centroid— The centroid of the detections will be used to indicate to the polygon segmentation model what to segment in the input raster.
  • Bounding Box— The bounding box of the detections will be used to indicate to the polygon segmentation model what to segment in the input raster.
  • None—No segmentation method will be used. This is the default
String
Input Features
(Optional)

The feature class on which postprocessing will be performed. This parameter is only supported when the Post Processing Workflow parameter is set to Line Regularization or Polygon Regularization.

The feature class on which postprocessing will be performed. This parameter is only supported when the post_processing_workflow parameter is set to Line Regularization or Polygon Regularization.

Feature Layer; Feature Class
Output Summary
(Optional)

The table that will contain a list of outputs that were generated along with their respective paths.

Table

arcpy.geoai.ExtractFeaturesUsingAIModels(in_raster, mode, out_location, out_prefix, {area_of_interest}, {pretrained_models}, {additional_models}, {confidence_threshold}, {save_intermediate_output}, {test_time_augmentation}, {buffer_distance}, {extend_length}, {smoothing_tolerance}, {dangle_length}, {in_road_features}, {road_buffer_width}, {regularize_parcels}, {post_processing_workflow}, {out_features}, {parcel_tolerance}, {regularization_method}, {poly_tolerance}, {prompt}, {in_features}, {out_summary})
NameExplanationData Type
in_raster

The input raster on which processing will be performed.

If the mode parameter is specified as Only Postprocess, a raster with binary classification is required for this parameter.

Raster Layer; Raster Dataset; Mosaic Layer
mode

Specifies the mode that will be used for the processing of the input raster.

  • Infer and Postprocess—Features will be extracted from the imagery and postprocessed. This is the default.
  • Only Postprocess—The input raster will be directly postprocessed. A single band raster with binary classification is required for this option.
String
out_location

The file geodatabase where the intermediate output from the models and the final postprocessed output will be stored.

Workspace
out_prefix

A prefix that will be added to the name of the outputs that will be saved to the output location. The prefix will also be used as the name of a group layer that will be used to display all outputs.

String
area_of_interest
(Optional)

The geographical extent that will be used to extract features. Only features within the area of interest will be extracted.

Feature Set
pretrained_models
[pretrained_models,...]
(Optional)

The ArcGIS pretrained models from ArcGIS Living Atlas of the World that can be used on the provided input raster. This parameter requires an internet connection to download the pretrained models.

String
additional_models
[additional_models,...]
(Optional)

The deep learning models that can be used on the provided input raster and the postprocessing workflow that will be used for additional model files (.dlpk and .emd). Available postprocessing workflows are as follows:

  • Line Regularization—The postprocessing workflow will extract line features from a single band raster with binary classification and generate a polyline feature class after refining it. This workflow also supports deep learning models that generate polyline feature classes.
  • Parcel Regularization—The postprocessing workflow will extract parcels from a single band raster with binary classification and generate a polygon feature class after refining it.
  • Polygon Regularization—The postprocessing workflow will generate a polygon feature class after refining it. This workflow is only compatible with object detection models.
  • Polygon Segmentation—The postprocessing workflow will generate a polygon feature class containing the detected objects using their centroid or bounding box. The segmentation method is specified using the prompt parameter.
  • None—No postprocessing workflow will be applied. This is the default.

Value Table
confidence_threshold
(Optional)

The minimum confidence of deep learning model that will be used when detecting objects. The value must be between 0 and 1.

Double
save_intermediate_output
(Optional)

Specifies whether the intermediate outputs will be saved to the output location. The term intermediate outputs refers to the results generated after the model has been inferenced.

  • TRUE—The intermediate outputs will be saved to the output location.
  • FALSE—The intermediate outputs will not be saved. This is the default.
Boolean
test_time_augmentation
(Optional)

Specifies whether predictions of flipped and rotated variants of the input image will be merged into the final output.

  • TRUE—Predictions of flipped and rotated variants of the input image will be merged into the final output.
  • FALSE—Predictions of flipped and rotated variants of the input image will not be merged into the final output. This is the default.
Boolean
buffer_distance
(Optional)

The distance that will be used to buffer polyline features before they are used in postprocessing. The default is 15 meters.

Linear Unit
extend_length
(Optional)

The maximum distance a line segment will be extended to an intersecting feature. The default is 25 meters.

Linear Unit
smoothing_tolerance
(Optional)

The tolerance used by the Polynomial Approximation with Exponential Kernel (PAEK) algorithm. The default is 30 meters.

Linear Unit
dangle_length
(Optional)

The length at which line segments that do not touch another line at both endpoints (dangles) will be trimmed. The default is 5 meters.

Linear Unit
in_road_features
(Optional)

A road feature class that will be used for refining the parcels. The input can be a polygon or polyline feature class.

Feature Layer; Feature Class
road_buffer_width
(Optional)

The buffer distance that will be used for the input road features. The default value is 5 meters for polyline features and 0 meters for polygon features.

Linear Unit
regularize_parcels
(Optional)

Specifies whether extracted parcels will be normalized by eliminating undesirable artifacts in their geometry.

  • TRUE—Extracted parcels will be normalized. This is the default.
  • FALSE—Extracted parcels will not be normalized.
Boolean
post_processing_workflow
(Optional)

Specifies the postprocessing workflow that will be used.

  • Line Regularization—Line features will be extracted from a single band raster with binary classification and a polyline feature class will be generated after refining it.
  • Parcel Regularization—Parcels will be extracted from a single band raster with binary classification and a polygon feature class will be generated after refining it.
  • Polygon Regularization— A polygon feature class will be generated after refining it. This workflow is only compatible with object detection models.
String
out_features
(Optional)

The feature class containing the postprocessed output.

Feature Class
parcel_tolerance
(Optional)

The minimum distance between coordinates before they are considered equal. This parameter is used to reduce slivers between extracted parcels. The default is 3 meters.

Linear Unit
regularization_method
(Optional)

Specifies the regularization method that will be used in postprocessing.

  • Right Angles—Shapes composed of 90° angles between adjoining edges will be constructed. This is the default.
  • Right Angles and Diagonals—Shapes composed of 45° and 90° angles between adjoining edges will be constructed.
  • Any Angles—Shapes that form any angles between adjoining edges will be constructed.
  • Circle—The maximum distance from the boundary of the feature being processed will be used.
String
poly_tolerance
(Optional)

The maximum distance that the regularized footprint can deviate from the boundary of its originating feature. The default is 1 meter.

Linear Unit
prompt
(Optional)

Specifies the segmentation method that will be used when the additional_models parameter is set to Polygon Segmentation.

  • Centroid— The centroid of the detections will be used to indicate to the polygon segmentation model what to segment in the input raster.
  • Bounding Box— The bounding box of the detections will be used to indicate to the polygon segmentation model what to segment in the input raster.
  • None—No segmentation method will be used. This is the default
String
in_features
(Optional)

The feature class on which postprocessing will be performed. This parameter is only supported when the post_processing_workflow parameter is set to Line Regularization or Polygon Regularization.

Feature Layer; Feature Class
out_summary
(Optional)

The table that will contain a list of outputs that were generated along with their respective paths.

Table

Code sample

ExtractFeaturesUsingAIModels (Python window)

This example demonstrates how to use the ExtractFeaturesUsingAIModels function.

# Name: ExtractFeaturesUsingAIModels.py
# Description: Extract features using pretrained deep learning models on imagery data.
  
# Import system modules
import arcpy

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

# Set local variables
datapath = "path_to_training_data" 
out_gdb = "path_to_gdb"
predictions = "output_prefix"

# Run Extract Features Using AI Models
arcpy.geoai.ExtractFeaturesUsingAIModels(
    in_raster=datapath,
    mode="Infer and Postprocess", 
    out_location=out_gdb, 
    out_prefix=predictions, 
    pretrained_models="'Building Footprint Extraction - USA'", 
    save_intermediate_output="TRUE", 
    buffer_distance="15 Meters", 
    extend_length="25 Meters", 
    smoothing_tolerance="30 Meters", 
    dangle_length="5 Meters",
    regularization_method="Right Angles",
    poly_tolerance="1 Meters",
    prompt="Bounding Box")

Environments

GPU ID

Feedback on this topic?

In this topic
  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information