This task trains a Deep Learning Grid model to locate regions containing targets of interest.
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.
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)
Data_Task_1 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
Data_Task_1.INPUT_RASTER = Raster1
Data_Task_1.INPUT_ANNOTATION_URI = AnnFile1
Data_Task_1.Execute
Data_Task_2 = ENVITask('BuildObjectDetectionRasterFromAnnotation')
Data_Task_2.INPUT_RASTER = Raster2
Data_Task_2.INPUT_ANNOTATION_URI = AnnFile2
Data_Task_2.Execute
Task = ENVITask('TrainDeepLearningGridModel')
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
Task.OUTPUT_MODEL_URI = e.GetTemporaryFilename('h5')
Task.Execute
Syntax
Result = ENVITask('TrainDeepLearningGridModel')
Input parameters (Set, Get): AUGMENT_FLIP, AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, EPOCHS, FEATURE_PATCH_PERCENTAGE, GRID_SIZE, MODEL_ARCHITECTURE, MODEL_DESCRIPTION, MODEL_LICENSE, MODEL_NAME, MODEL_VERSION, OUTPUT_LAST_MODEL_URI, OUTPUT_MODEL_URI, PAD_SMALL_FEATURES, PATCHES_PER_BATCH, SOLID_DISTANCE, TRAINED_MODEL, TRAINING_RASTERS, VALIDATION_RASTERS
Output parameters (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.
Input Parameters
AUGMENT_FLIP (optional)
Specify whether to flip vertically and horizontally 50% of the time during data augmentation.
AUGMENT_ROTATION (optional)
Specify whether to rotate training inputs during data augmentation.
AUGMENT_SCALE (optional)
Specify whether to scale training inputs during 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:
MODEL_AUTHOR (optional)
Specify the individual or team responsible for training the model. This parameter identifies the contributor(s) to document their ownership, efforts, and expertise.
MODEL_DESCRIPTION (optional)
Specify a description for the model. A default description is not provided.
MODEL_LICENSE (optional)
Specify the license under which the model is distributed. This parameter ensures compliance with the legal and permitted use requirements associated with the model.
MODEL_NAME (required)
Specify a short, descriptive name that reflects what the model does. This helps recognize the model when viewing results or reusing again later.
MODEL_VERSION (optional)
Specify a semantic version format (MAJOR.MINOR.PATCH) for the trained model (for example, 1.0.0). The version may indicate the following:
- MAJOR: Breaking changes to the model
- MINOR: Compatibility or new features
- PATCH: Minor adjustments
OUTPUT_LAST_MODEL_URI (optional)
Specify a string with the fully qualified filename and path to the final training epoch in .envi.onnx format. This file may differ from the best-performing model and can be useful for audit purposes of the last epoch's output file.
OUTPUT_MODEL_URI (optional)
Specify a string with the fully qualified filename and path to the best-performing model from training in .envi.onnx format. This model file will reflect the epoch with the highest validation score and is used for inference.
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.
TRAINED_MODEL (optional)
Specify a trained ENVIDeepLearningKerasModel for grid processing that will be used as a starting point for training. If not provided, the model will initialize from random weights.
TRAINING_RASTERS (required)
Specify one or more labeled rasters that will be used to teach the model about labels of interest during training.
VALIDATION_RASTERS (required)
Specify one or more labeled rasters used during training for validating the model's accuracy at the end of each epoch.
Output Parameters
OUTPUT_LAST_MODEL
Specify the path to the best-performing ENVIDeepLearningOnnxModel from training. This model file reflects the epoch with the highest validation score and is used for inference.
OUTPUT_MODEL
This is the in-memory representation of the the best-performing ENVIDeepLearningOnnxModel, constructed from the OUTPUT_MODEL_URI.
Methods
Execute
Parameter
ParameterNames
See ENVI Help for details on these ENVITask methods.
Properties
DESCRIPTION
DISPLAY_NAME
NAME
REVISION
TAGS
See the ENVITask topic in ENVI Help for details.
Version History
|
Deep Learning 3.0
|
Introduced |
|
Deep Learning 4.0
|
Renamed from TrainTensorFlowGridModel task.
Added AUGMENT_FLIP, MODEL_AUTHOR, MODEL_LICENSE, MODEL_VERSION, and TRAINED_MODEL parameters.
The MODEL_NAME parameter is now required.
|
See Also
DeepLearningGridClassification Task, ENVIDeepLearningKerasModel, ENVIDeepLearningOnnxModel, ENVITensorBoard