This task trains a TensorFlow Grid model to locate regions containing targets of interest.

This task is part of ENVI Deep Learning, which requires a separate license and installation.

Example


Sample data files are available on our ENVI Tutorials web page. Click the "Deep Learning" link in the ENVI Tutorial Data section to download a .zip file containing the data. Extract the contents of the .zip file to a local directory. Files are located in the object_detection folder.

; Start the application
e = ENVI()
 
; Select input object detection rasters
; Update the following line with the correct path
; to the tutorial data files.
File1 = 'C:\MyTutorialFiles\DRCOG_AerialImage1.dat'
AnnFile1 = 'C:\MyTutorialFiles\Handicap_Parking_Spots1.anz'
Raster1 = e.OpenRaster(File1)
 
File2 = 'C:\MyTutorialFiles\DRCOG_AerialImage2.dat'
AnnFile2 = 'C:\MyTutorialFiles\Handicap_Parking_Spots2.anz'
Raster2 = e.OpenRaster(File2)
 
; Build object detection raster for training
Data_Task_1 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
Data_Task_1.INPUT_RASTER = Raster1
Data_Task_1.INPUT_ANNOTATION_URI = AnnFile1
Data_Task_1.Execute
 
; Build object detection raster for validation
Data_Task_2 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
Data_Task_2.INPUT_RASTER = Raster2
Data_Task_2.INPUT_ANNOTATION_URI = AnnFile2
Data_Task_2.Execute
 
; Train the grid detection model
Task = ENVITask('TrainTensorFlowGridModel')
Task.TRAINING_RASTERS = [Data_Task_1.OUTPUT_RASTER]
Task.VALIDATION_RASTERS = [Data_Task_2.OUTPUT_RASTER]
Task.MODEL_ARCHITECTURE = 'ResNet50'
Task.GRID_SIZE = 224
Task.EPOCHS = 100
Task.PATCHES_PER_BATCH = 12
Task.FEATURE_PATCH_PERCENTAGE = 1.0
Task.BACKGROUND_PATCH_RATIO = 0.5
 
; Set the output file path, for example: TensorFlowGridClassification
Task.OUTPUT_MODEL_URI = e.GetTemporaryFilename('h5')
Task.Execute

Syntax


Result = ENVITask('TrainTensorFlowGridModel')

Input properties (Set, Get): AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, EPOCHS, FEATURE_PATCH_PERCENTAGE, GRID_SIZE, MODEL_ARCHITECTURE, MODEL_DESCRIPTION, MODEL_NAME, OUTPUT_LAST_MODEL_URI, OUTPUT_MODEL_URI, PAD_SMALL_FEATURES, PATCHES_PER_BATCH, SOLID_DISTANCE, TRAINING_RASTERS, VALIDATION_RASTERS

Output properties (Get only): OUTPUT_LAST_MODEL, OUTPUT_MODEL

Properties marked as "Set" are those that you can set to specific values. You can also retrieve their current values any time. Properties marked as "Get" are those whose values you can retrieve but not set.

Methods


This task inherits the following methods from ENVITask. See the ENVITask topic in ENVI Help.

  • AddParameter
  • Execute
  • Parameter
  • ParameterNames
  • RemoveParameters

Properties


This task inherits the following properties from ENVITask:

COMMUTE_ON_DOWNSAMPLE

COMMUTE_ON_SUBSET

DESCRIPTION

DISPLAY_NAME

NAME

REVISION

See the ENVITask topic in ENVI Help for details.

This task also contains the following properties:

AUGMENT_ROTATION (optional)

Specify whether to rotate training inputs during data augmentation. See Data Augmentation.

AUGMENT_SCALE (optional)

Specify whether to scale training inputs during data augmentation. See Data Augmentation.

BACKGROUND_PATCH_RATIO (optional)

Specify the ratio of background patches containing zero features to patches with features. A ratio of 1.0 for 100 patches with features would provide 100 patches without features. The default value is 0.15. In cases where features are sparse in a training raster, the training can be biased by empty patches throughout. This property allows you to restrict the number of empty patches, relative to those that contain features.

EPOCHS (optional)

An epoch is a full pass of the entire training dataset through the algorithm's learning process. Specify the number of Epochs to run. Training inputs are adjusted at the end of each epoch. The default value is 100.

FEATURE_PATCH_PERCENTAGE (optional)

Specify the percentage of patches containing labeled features to use during training. Values should range from 0 to 1, and the value applies to both the training and validation datasets. The default value is 1. Example: You have a grid raster with 50 patches that contain labeled features. A value of 0.4 means that 20 of those patches will be used for training (20/50 = 0.4, or 40%), whereas a value of 1 means 100% of those patches will be used for training. The number of resulting patches is used as input to BACKGROUND_PATCH_RATIO. Note that if you have a large training dataset (hundreds of images), lowering the FEATURE_PATCH_PERCENTAGE will reduce training time.

GRID_SIZE (optional)

Specify the size of the grid bounding box. This number is squared and also represents the patch rows and columns dimensions. The grid size must be a multiple of 32. The default is 224.

MODEL_ARCHITECTURE (optional)

Specify the model architecture to use for training the model. Pre-trained weights for the given architecture will be used as a starting point to enhance model performance. The options are:

  • ResNet50

  • ResNet101

MODEL_DESCRIPTION (optional)

Specify a description for the model. A default description is not provided.

MODEL_NAME (optional)

Specify the name of the model. The default value is ENVI Deep Learning Grid.

OUTPUT_LAST_MODEL

This is a reference to the last trained ENVITensorFlowModel.

OUTPUT_LAST_MODEL_URI (optional)

Specify a string with the fully qualified filename and path of the last epoch's output HDF5 file.

OUTPUT_MODEL

This is the ENVITensorFlowModel extracted from the URI.

OUTPUT_MODEL_URI (optional)

Specify a string with the fully qualified filename and path of the output HDF5 file. This will be the model representing the best epoch trained.

PAD_SMALL_FEATURES (optional)

This parameter is applied only when input rasters are of type ENVIDeepLearningObjectDetectionRaster. Specify whether to pad bounding boxes smaller than 40 pixels. The default is true.

PATCHES_PER_BATCH (optional)

Specify the number of patches to run per batch. A batch comprises one iteration of training; model parameters are adjusted at the end of each iteration. Batches are run in an epoch until the number of patches per epoch is met or exceeded. The default value is 5.

This parameter controls how much data you send to the trainer in each batch. This is directly tied to how much GPU memory you have available. With higher amounts of GPU memory, you can increase the value. The following table shows the amount of GPU memory successfully tested with different values:

GPU memory (MB)

Patches per Batch

5099

1

5611

2

9707

3-4

10731

5-8

11711

9-10

SOLID_DISTANCE (optional)

The parameter is applied only when input rasters are type ENVIDeepLearningLabelRaster. Specify a double-precision array with the distance in pixels to expand feature (non-background) areas. SOLID_DISTANCE is typically used for point or line inputs, the default is 0.0.

TRAINING_RASTERS (required)

Specify one or more labeled rasters used during training in order to teach the model about labels of interest.

VALIDATION_RASTERS (required)

Specify one or more labeled rasters used during training for validating the models accuracy at the end of each epoch.

Version History


Deep Learning 3.0

Introduced

See Also


TensorFlowGridClassification Task