This task trains a TensorFlow model for object detection.
This task is part of ENVI Deep Learning, which requires a separate license and installation.
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.
e = ENVI()
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)
BuildODTask1 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
BuildODTask1.INPUT_RASTER = Raster1
BuildODTask1.INPUT_ANNOTATION_URI = AnnFile1
BuildODTask2 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
BuildODTask2.INPUT_RASTER = Raster2
BuildODTask2.INPUT_ANNOTATION_URI = AnnFile2
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')
Result = ENVITask('TrainTensorFlowObjectDetectionModel')
Input properties (Set, Get): AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, EPOCHS, FEATURE_PATCH_PERCENTAGE, MODEL_DESCRIPTION, MODEL_NAME, OUTPUT_MODEL_URI, PAD_SMALL_FEATURES, PATCHES_PER_BATCH, TRAINING_RASTERS, VALIDATION_RASTERS
Output properties (Get only): 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.
This task inherits the following methods from ENVITask. See the ENVITask topic in ENVI Help.
This task inherits the following properties from ENVITask:
See the ENVITask topic in ENVI Help for details.
This task also contains the following properties:
Specify whether to rotate training inputs during data augmentation. See Data Augmentation. The default value is 'true'.
Specify whether to scale training inputs during data augmentation. See Data Augmentation. The default value is 'true'.
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. The BACKGROUND_PATCH_RATIO parameter allows you to restrict the number of empty patches, relative to those that contain features.
Specify the number of epochs to run. Training inputs are adjusted at the end of each epoch. The default value is 25.
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.
Specify a description of the model's capabilities.
Specify the name of the model. The default value is ENVI Deep Learning OD.
This is the ENVITensorFlowModel extracted from the URI.
Specify a string with the fully qualified filename and path of the output HDF5 file that will contain the best trained model according to validation loss.
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.
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
Specify an array of one or more object detection rasters to use to train the INPUT_MODEL.
Specify an array one or more object detection rasters to use to validate the INPUT_MODEL.
TrainTensorFlowMaskModel Task, TensorFlowObjectClassification Task, ENVIDeepLearningObjectDetectionRaster, BuildObjectDetectionRasterFromAnnotation Task