TrainTensorFlowPixelModel Task

This task trains a TensorFlow pixel segmentation model. A pre-trained model may be optionally provided as a starting point for training.

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 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 TrainTensorFlowPixelModelExample.pro.
Compile and run the program.

; Start the application

e = ENVI()

LabelRasterList = List()

; Change the path to the directory

; containing the tutorial data

Path = 'C:\MyTutorialFiles\'

; Open training rasters and ROIs

FOR i = 1,4 DO BEGIN

  ; Open training raster

  File = Path + 'TrainingRaster' + StrTrim(i,2) + '.dat'

  Raster = e.OpenRaster(File)

  ; Open ROI file

  ROIFile = Path + 'TrainingRaster' + StrTrim(i,2) + 'ROIs.xml'

  ROI = e.OpenROI(ROIFile)

  ; Create label raster

  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]

; Get the task from the catalog of ENVITasks

Task = ENVITask('TrainTensorFlowPixelModel')

; Define inputs

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

; Run the task

Task.Execute

Print, Task.OUTPUT_MODEL, /IMPLIED_PRINT

END

Syntax

Result = ENVITask('TrainTensorFlowPixelModel')

Input properties (Set, Get): AUGMENT_ROTATION, AUGMENT_SCALE, BACKGROUND_PATCH_RATIO, BLUR_DISTANCE, CLASS_NAMES, CLASS_WEIGHT, EPOCHS, FEATURE_PATCH_PERCENTAGE, LOSS_WEIGHT, MODEL_ARCHITECTURE, MODEL_DESCRIPTION, MODEL_NAME, OUTPUT_LAST_MODEL_URI, OUTPUT_MODEL_URI, PATCH_SIZE, PATCHES_PER_BATCH, SOLID_DISTANCE, TRAINED_MODEL, 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 by zooming in on 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.

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 property 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 a model architecture to use during training. Default is SegUNet++ which does better at paying attention to structural objects, for example vehicles, buildings, shipping containers. Specify SegUNet for features that are more inconsistent in appearance, for example debris and clouds. DeepLabV3+ based on ResNet50 is fast to train providing good results.

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.

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 that will contain the best trained model according to validation loss.

PATCH_SAMPLING_RATE (optional)

Specify the average number of patches that each pixel in TRAINING_RASTERS and VALIDATION_RASTERS will belong to. The default value is 16.

PATCH_SIZE (optional)

Specify the edge length in pixels of the square patches used for training. The default value is 464. Valid values are:

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.

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 previously trained model, the model weights will be used as a starting point for the model being trained. If a trained model is not provided, the model in training will initialize using random weights.

TRAINING_RASTERS (required)

Specify one or more labeled rasters to use as training data.

VALIDATION_RASTERS

Specify one or more labeled rasters to use as validation data after each epoch.

Version History

Deep Learning 3.0

Renamed from TrainTensorFlowMaskModel task.

Added properties: BACKGROUND_PATCH_RATIO, FEATURE_PATCH_PERCENTAGE, MODEL_ARCHITECTURE, MODEL_DESCRIPTION, MODEL_NAME, PATCH_SIZE, TRAINED_MODEL

Removed properties: VALIDATION_F1, VALIDATION_LOSS, VALIDATION_PRECISION, VALIDATION_RECALL