TrainTensorFlowObjectModel Task

This task trains a TensorFlow model for object detection.

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.

This example trains an object detection model to find parking spots with handicap signs painted on the pavement; for example:

The code example will take several minutes to run. If you do not wish to run this example, a copy of the resulting model is available with the tutorial data mentioned above. The sample model is named ObjectDetectionModel_HandicapSpots.h5.

; Start the application

e = ENVI()

; Select input object detection rasters

; Update the following lines 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

BuildODTask1 = ENVITask('BuildObjectDetectionRasterFromAnnotation')

BuildODTask1.INPUT_RASTER = Raster1

BuildODTask1.INPUT_ANNOTATION_URI = AnnFile1

BuildODTask1.Execute

; Build object detection raster for validation

BuildODTask2 = ENVITask('BuildObjectDetectionRasterFromAnnotation')

BuildODTask2.INPUT_RASTER = Raster2

BuildODTask2.INPUT_ANNOTATION_URI = AnnFile2

BuildODTask2.Execute

; Train the object detection model

Task = ENVITask('TrainTensorFlowObjectModel')

Task.TRAINING_RASTERS = [BuildODTask1.OUTPUT_RASTER]

Task.VALIDATION_RASTERS = [BuildODTask2.OUTPUT_RASTER]

Task.EPOCHS = 60

Task.PATCHES_PER_BATCH = 2

Task.FEATURE_PATCH_PERCENTAGE = 1.0

Task.OUTPUT_MODEL_URI = e.GetTemporaryFilename('h5')

Task.Execute

Syntax

Result = ENVITask('TrainTensorFlowObjectDetectionModel')

Input properties (Set, Get): AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, EPOCHS, FEATURE_PATCH_PERCENTAGE, MODEL_DESCRIPTION, MODEL_NAME, OUTPUT_LAST_MODEL_URI, OUTPUT_MODEL_URI, PAD_SMALL_FEATURES, PATCHES_PER_BATCH, 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. The default value is 'true'.

AUGMENT_SCALE (optional)

Specify whether to scale training inputs during data augmentation. See Data Augmentation. The default value is 'true'.

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 25.

FEATURE_PATCH_PERCENTAGE (optional)

Specify the percentage of patches containing labeled features to use during training. Values should range from 0 to 1. This applies to both the training and validation datasets. The default value is 1, which means that 100% of the patches that contain features will be used for training. The number of resulting patches is used as input to the BACKGROUND_PATCH_RATIO.

Example: Suppose that an object detection raster has 50 patches that contain labeled features. A FEATURE_PATCH_PERCENTAGE value of 0.4 means that 20 of those patches will be used for training (20/50 = 0.4, or 40%).

The default value of 1 ensures that you are training on all of the features that you labeled. In general, if you have a large training dataset (hundreds of images), lowering the FEATURE_PATCH_PERCENTAGE value will reduce training time.

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 OD.

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 output HDF5 file that will contain the trained model from the last epoch.

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 last epoch's output HDF5 file.

PAD_SMALL_FEATURES (optional)

Set this property to true (the default) when features are small; for example: vehicles, utilities, road markings, etc. Features with bounding boxes drawn around them must have at least 25 pixels in the X and Y directions. If the labeled features are smaller than this, the PAD_SMALL_FEATURES property will pad them with extra pixels so they are at least 25 pixels in both directions.

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 1.

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

TRAINING_RASTERS (required)

Specify one or more rasters used during training for teaching the model about objects of interest.

VALIDATION_RASTERS (required)

Specify one or more rasters used during training for validating the model's accuracy at the end of each epoch.

Version History

1.2	Introduced