This task trains a Deep Learning pixel segmentation model. A pre-trained model may be optionally provided as a starting point for training.
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 to a local directory. Files are located in the tornado directory.
This example builds label rasters from four input rasters and ROIs. It trains a deep learning model using three of the label rasters as training rasters and one as a validation raster. Follow these steps:
- Copy and paste the code below into a new file in the IDL Editor.
- Change the Path variable to the directory on your computer that contains the tutorial data.
- Save the file as TrainDeepLearningPixelModelExample.pro.
- Compile and run the program.
e = ENVI()
LabelRasterList = List()
Path = 'C:\MyTutorialFiles\'
FOR i = 1,4 DO BEGIN
File = Path + 'TrainingRaster' + StrTrim(i,2) + '.dat'
Raster = e.OpenRaster(File)
ROIFile = Path + 'TrainingRaster' + StrTrim(i,2) + 'ROIs.xml'
ROI = e.OpenROI(ROIFile)
LabelTask = ENVITask('BuildLabelRasterFromROI')
LabelTask.INPUT_RASTER = Raster
LabelTask.INPUT_ROI = ROI
LabelTask.CLASS_NAMES = ['Roof Damage', $
'Structural Damage', 'Rubble', 'Blue Tarps']
LabelTask.Execute
LabelRasterList.Add, LabelTask.OUTPUT_RASTER
ENDFOR
LabelRasters = LabelRasterList.ToArray()
TrainingRasters = LabelRasters[0:2]
ValidationRasters = LabelRasters[3]
Task = ENVITask('TrainDeepLearningPixelModel')
Task.TRAINING_RASTERS = TrainingRasters
Task.VALIDATION_RASTERS = ValidationRasters
Task.EPOCHS = 20
Task.FEATURE_PATCH_PERCENTAGE = 1.0
Task.BACKGROUND_PATCH_RATIO = 0.15
Task.BLUR_DISTANCE = [1,10]
Task.SOLID_DISTANCE = [0]
Task.CLASS_WEIGHT = [0,2]
Task.LOSS_WEIGHT = 0.8
Task.Execute
Print, Task.OUTPUT_MODEL, /IMPLIED_PRINT
Syntax
Result = ENVITask('TrainDeepLearningPixelModel')
Input parameters (Set, Get): AUGMENT_FLIP, AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, BLUR_DISTANCE, CLASS_NAMES, CLASS_WEIGHT, EPOCHS, FEATURE_PATCH_PERCENTAGE, LOSS_WEIGHT, MODEL_ARCHITECTURE, MODEL_AUTHOR, MODEL_DESCRIPTION, MODEL_LICENSE, MODEL_NAME, OUTPUT_LAST_MODEL_URI, OUTPUT_MODEL_URI, PATCH_SIZE, 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 by zooming in on 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.
BLUR_DISTANCE (optional)
Specify a [2, *] double-precision array with the minimum and maximum distance in pixels to expand feature (non-background) areas beyond the solid distance expansion. The area expanded is blurred, diminishing from the edges of the feature areas to the blur distance. The maximum blur distance is used at the beginning of training and decreased to the minimum blur distance at the end of training. If not set, the value will be read from INPUT_MODEL if it was previously trained; otherwise, the value will default to [10.0,0.0]. The number of elements in the array should be twice the number of classes in CLASS_NAMES. If you specify only one set of minimum and maximum distance values, those values will be used for all classes associated with CLASS_NAMES.
CLASS_NAMES (optional)
Specify a string array with the list of class names the model will be trained to find. Training and validation rasters will be checked for consistency against this list.
If using old label rasters created from Deep Learning 1.0, this parameter is required. If the raster metadata does not contain dlclassnames, you will be required to provide the class names using this parameter.
CLASS_WEIGHT (optional)
Specify a double-precision array with the minimum and maximum weights for having a more even balance of classes (including background) during patch selection. Balancing of patch selection is weighted by the maximum value at the beginning of training and decreased to the minimum value at the end of training. In general, set the maximum higher for sparser training sets. The useful range for the maximum value is between 0.0 and 3.0. If not set, the value will be read from INPUT_MODEL if it was previously trained; otherwise, the value will default to [2.0,0.0].
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 is 25.
FEATURE_PATCH_PERCENTAGE (optional)
Specify the percentage of patches containing labeled features to use during training. This applies to both the training and validation datasets, 100% of the data will be used by default.
LOSS_WEIGHT (optional)
Specify the weight of feature (non-background) pixels when calculating how well the model is fitting the training data. The useful range is between 0.0 and 3.0. If not set, the value will be read from INPUT_MODEL if it was previously trained; otherwise, the value will default to 1.0.
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:
- DeepLabV3+ trains quickly and offers solid results across a wide range of features.
- SegUNet can perform better on features that vary more in shape or texture.
- SegUNet++ (default) When the features have strong structural patterns. It is good for roads, buildings, and other well-defined objects.
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.
PATCH_SIZE (optional)
Specify the edge length in pixels of the square patches used for training. The default value is 464. Valid values are:
| 208 |
512 |
| 224 |
528 |
| 240 |
544 |
| 256 |
560 |
| 272 |
576 |
| 288 |
592 |
| 304 |
608 |
| 320 |
624 |
| 336 |
640 |
| 352 |
656 |
| 368 |
672 |
| 384 |
688 |
| 400 |
704 |
| 416 |
720 |
| 432 |
736 |
| 448 |
752 |
| 464 |
768 |
| 480 |
784 |
| 496 |
|
PATCHES_PER_BATCH (optional)
Specify the max number of PATCH_SIZE patches that can fit into your GPUs memory to run per batch. A batch is group of patches randomly selected based on FEATURE_PATCH_PERCENTAGE and BACKGROUND_PATCH_RATIO. The default is 2.
SOLID_DISTANCE (optional)
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. If not set, the value will be read from INPUT_MODEL if it was previously trained; otherwise, the value will default to 0.0. The number of elements in the array should match the number of classes in CLASS_NAMES. If you only specify one distance value, that value will be used for all classes associated with CLASS_NAMES.
TRAINED_MODEL (optional)
Specify a trained ENVIDeepLearningKerasModel for pixel segmentation 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 raster images where each pixel value in the label band represents a class. These rasters teach the model what to look for 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
|
Renamed from TrainTensorFlowMaskModel task.
Added parameters: BACKGROUND_PATCH_RATIO, FEATURE_PATCH_PERCENTAGE, MODEL_ARCHITECTURE, MODEL_DESCRIPTION, MODEL_NAME, PATCH_SIZE, TRAINED_MODEL
Removed parameters: VALIDATION_F1, VALIDATION_LOSS, VALIDATION_PRECISION, VALIDATION_RECALL
|
|
Deep Learning 4.0
|
Renamed from TrainTensorFlowPixelModel task.
Added parameters: AUGMENT_FLIP, MODEL_AUTHOR, MODEL_LICENSE, and MODEL_VERSION.
The MODEL_NAME parameter is now required.
|
See Also
DeepLearningPixelClassification Task, ENVIDeepLearningKerasModel, ENVIDeepLearningOnnxModel, ENVITensorBoard