Train Point Cloud Classification Model (3D Analyst)

Summary

Trains a deep learning model for point cloud classification using the PointCNN architecture.

Usage

• This tool uses the PointCNN implementation using deep learning frameworks.

  To set up your machine to use deep learning frameworks in ArcGIS Pro, see Install deep learning frameworks for ArcGIS.

• The point classification model can be trained using either a CUDA-capable NVIDIA graphics card or the CPU. The tool will attempt to use the fastest CUDA-capable graphics card on the computer. If multiple GPUs are present and the tool does not use the fastest card, you can specify the GPU using the GPU ID environment setting. If the selected GPU is also being used for the display, its available memory will be decreased by the operating system and any other applications using the display at the time. To maximize the GPU memory for training, use a graphics card that will not be used for training to drive the computer's display.

  Using the GPU is typically faster than using the CPU. Use the CPU only if no available GPU is present. If the CPU is used for training, provide the smallest possible training sample to estimate the time it will take to process the data prior to performing the training operation.

  Learn more about training a point cloud classification model

• When a pretrained model is specified, the model that will be trained will adopt the weights from the pretrained model and fine-tune the weights to classify the same objects in the pretrained model. For this reason, the training data must have the same attributes and class codes as the pretrained model. If the training data uses different class codes to represent the same objects in the pretrained model, remap the training data's class codes accordingly.

• A folder is created to store the checkpoint models, which are models that are created at each epoch. The name of this folder is the same as the Output Model Location parameter value with a suffix of .checkpoints and is created in the same location. Once the training is finished, a CSV table with a name that is the same as the Output Model Name parameter value with a suffix of _stats.csv is created and added to the checkpoint folder. This table provides the following fields regarding the results obtained for each class code and epoch:

  • Epoch—The epoch number associated with the results in the row. This value corresponds to the model created in the checkpoint models directory. The results are obtained by applying the model trained in the epoch on the validation data.
  • Class_Code—The class code for which the results are being reported.
  • Precision—The ratio of points that were correctly classified (true positives) over all the points that were classified (true positives and false positives).
  • Recall—The ratio of correctly classified points (true positives) over all the points that should have been classified with this value (true positives and false negatives).
  • F1_Score—The harmonic mean of the precision and recall value.

• During training, PointCNN learns patterns from the training data and minimizes the entropy loss function. When the tool is running, the progress message returns the following statistical summary of the training results that were achieved for each epoch:

  • Epoch—The epoch number with which the result is associated.
  • Training Loss—The result of the entropy loss function that was averaged for the training data.
  • Validation Loss—The result of the entropy loss function that was determined when applying the model trained in the epoch on the validation data.
  • Accuracy—The ratio of points in the validation data that were correctly classified by the model trained in the epoch (true positives) over all the points in the validation data.
  • Precision—The macro average of the precision for all class codes.
  • Recall—The macro average of the recall for all class codes.
  • F1 Score—The harmonic mean of the macro average of the precision and recall values for all class codes.

  A model that achieves low training loss but high validation loss is considered to be overfitting the training data, whereby it detects patterns from artifacts in the training data that result in the model not working well for the validation data. A model that achieves a high training loss and a high validation loss is considered to be underfitting the training data, whereby no patterns are being learned effectively to produce a usable model.

  Learn more about assessing point cloud training results

• The dedicated memory used during training is the sum of memory allocated for the deep learning framework and the size of the data processed in each batch of an iteration in a given epoch. The size of the data in each batch depends on the number of additional point attributes specified in the Attribute Selection parameter, the total number of points in any given block, and the number of blocks that will be processed in each batch as specified by the Batch Size parameter. The maximum number of points per block is determined when the training data is exported, and this value should be assumed when estimating the potential memory footprint of the training operation.

• The Relative Height option of the Attribute Selection parameter adds an attribute that identifies a point's height from a reference surface, such as a bare earth elevation model. This attribute can potentially improve the model's ability to infer directional relationships between the points being used for training.

Parameters

Dialog

Label	Explanation	Data Type
Input Training Data	The point cloud training data (*.pctd file) that will be used to train the classification model.	File
Output Model Location	The existing folder that will store the new directory containing the deep learning model.	Folder
Output Model Name	The name of the output Esri model definition file (*.emd), deep learning package (*.dlpk), and the new directory that will be created to store them.	String
Pre-trained Model (Optional)	The pretrained model that will be refined. When a pretrained model is provided, the input training data must have the same attributes, class codes, and maximum number of points that were used by the training data that generated this model.	File
Attribute Selection (Optional)	Specifies the point attributes that will be used with the classification code when training the model. Only the attributes that are present in the point cloud training data will be available. No additional attributes are included by default. Intensity—The measure of the magnitude of the lidar pulse return will be used. Return Number—The ordinal position of the point obtained from a given lidar pulse will be used. Number of Returns—The total number of lidar returns that were identified as points from the pulse associated with a given point will be used. Red Band—The red band's value from a point cloud with color information will be used. Green Band—The green band's value from a point cloud with color information will be used. Blue Band—The blue band's value from a point cloud with color information will be used. Near Infrared Band—The near infrared band's value from a point cloud with near infrared information will be used. Relative Height—The relative height of each point in relation to a reference surface, which would typically be a bare earth DEM.	String
Minimum Points Per Block (Optional)	The minimum number of points that must be present in a given block for it to be used when training the model. The default is 0.	Long
Class Remapping (Optional)	Defines how class code values will map to new values prior to training the deep learning model.	Value Table
Class Codes Of Interest (Optional)	The class codes that will be used to filter the blocks in the training data. When class codes of interest are specified, all other class codes are remapped to the background class code.	Long
Background Class Code (Optional)	The class code value that will be used for all other class codes when class codes of interest have been specified.	Long
Class Description (Optional)	The descriptions of what each class code in the training data represents.	Value Table
Model Selection Criteria (Optional)	Specifies the statistical basis that will be used to determine the final model. Validation Loss—The model that achieves the lowest result when the entropy loss function is applied to the validation data will be used. Recall—The model that achieves the best macro average of the recall for all class codes will be used. Each class code's recall value is determined by the ratio of correctly classified points (true positives) over all the points that should have been classified with this value (expected positives). This is the default. F1 Score—The model that achieves the best harmonic mean between the macro average of the precision and recall values for all class codes will be used. This provides a balance between precision and recall, which favors better overall performance. Precision—The model that achieves the best macro average of the precision for all class codes will be used. Each class code's precision is determined by the ratio of points that are correctly classified (true positives) over all the points that are classified (true positives and false positives). Accuracy—The model that achieves the highest ratio of corrected classified points over all the points in the validation data will be used.	String
Maximum Number of Epochs (Optional)	The number of times each block of data is passed forward and backward through the neural network. The default is 25.	Long
Iterations Per Epoch (%) (Optional)	The percentage of the data that is processed in each training epoch. The default is 100.	Double
Learning Rate (Optional)	The rate at which existing information will be overwritten with new information. If no value is specified, the optimal learning rate will be extracted from the learning curve during the training process. This is the default.	Double
Batch Size (Optional)	The number of training data blocks that will be processed at any given time. The default is 2.	Long
Stop training when model no longer improves (Optional)	Specifies whether the model training will stop when the metric specified in the Model Selection Criteria parameter does not register any improvement after 5 consecutive epochs. Checked—The model training will stop when the model is no longer improving. This is the default. Unchecked—The model training will continue until the maximum number of epochs has been reached.	Boolean
Learning Rate Strategy (Optional)	Specifies how the learning rate will be modified during training. One Cycle Learning Rate—The learning rate will be cycled throughout each epoch using Fast.AI's implementation of the 1cycle technique for training neural networks to help improve the training of a convolutional neural network. This is the default. Fixed Learning Rate—The same learning rate will be used throughout the training process.	String

Derived Output

Label	Explanation	Data Type
Output Model	The resulting model generated by this tool.	File
Output Model Statistics	The .csv file containing the precision, recall, and F1 scores for each class code and epoch.	Text File
Output Epoch Statistics	The .csv file containing the training loss, validation loss, accuracy, precision, recall, and F1 scores obtained in each epoch.	Text File

Python

arcpy.ddd.TrainPointCloudClassificationModel(in_training_data, out_model_location, out_model_name, {pretrained_model}, {attributes}, {min_points}, {class_remap}, {target_classes}, {background_class}, {class_descriptions}, {model_selection_criteria}, {max_epochs}, {epoch_iterations}, {learning_rate}, {batch_size}, {early_stop}, {learning_rate_strategy})

Name	Explanation	Data Type
in_training_data	The point cloud training data (*.pctd file) that will be used to train the classification model.	File
out_model_location	The existing folder that will store the new directory containing the deep learning model.	Folder
out_model_name	The name of the output Esri model definition file (*.emd), deep learning package (*.dlpk), and the new directory that will be created to store them.	String
pretrained_model (Optional)	The pretrained model that will be refined. When a pretrained model is provided, the input training data must have the same attributes, class codes, and maximum number of points that were used by the training data that generated this model.	File
attributes [attributes,...] (Optional)	Specifies the point attributes that will be used with the classification code when training the model. Only the attributes that are present in the point cloud training data will be available. No additional attributes are included by default. INTENSITY—The measure of the magnitude of the lidar pulse return will be used. RETURN_NUMBER—The ordinal position of the point obtained from a given lidar pulse will be used. NUMBER_OF_RETURNS—The total number of lidar returns that were identified as points from the pulse associated with a given point will be used. RED—The red band's value from a point cloud with color information will be used. GREEN—The green band's value from a point cloud with color information will be used. BLUE—The blue band's value from a point cloud with color information will be used. NEAR_INFRARED—The near infrared band's value from a point cloud with near infrared information will be used. RELATIVE_HEIGHT—The relative height of each point in relation to a reference surface, which would typically be a bare earth DEM.	String
min_points (Optional)	The minimum number of points that must be present in a given block for it to be used when training the model. The default is 0.	Long
class_remap [class_remap,...] (Optional)	Defines how class code values will map to new values prior to training the deep learning model.	Value Table
target_classes [target_classes,...] (Optional)	The class codes that will be used to filter the blocks in the training data. When class codes of interest are specified, all other class codes are remapped to the background class code.	Long
background_class (Optional)	The class code value that will be used for all other class codes when class codes of interest have been specified.	Long
class_descriptions [class_descriptions,...] (Optional)	The descriptions of what each class code in the training data represents.	Value Table
model_selection_criteria (Optional)	Specifies the statistical basis that will be used to determine the final model. VALIDATION_LOSS—The model that achieves the lowest result when the entropy loss function is applied to the validation data will be used. RECALL—The model that achieves the best macro average of the recall for all class codes will be used. Each class code's recall value is determined by the ratio of correctly classified points (true positives) over all the points that should have been classified with this value (expected positives). This is the default. F1_SCORE—The model that achieves the best harmonic mean between the macro average of the precision and recall values for all class codes will be used. This provides a balance between precision and recall, which favors better overall performance. PRECISION—The model that achieves the best macro average of the precision for all class codes will be used. Each class code's precision is determined by the ratio of points that are correctly classified (true positives) over all the points that are classified (true positives and false positives). ACCURACY—The model that achieves the highest ratio of corrected classified points over all the points in the validation data will be used.	String
max_epochs (Optional)	The number of times each block of data is passed forward and backward through the neural network. The default is 25.	Long
epoch_iterations (Optional)	The percentage of the data that is processed in each training epoch. The default is 100.	Double
learning_rate (Optional)	The rate at which existing information will be overwritten with new information. If no value is specified, the optimal learning rate will be extracted from the learning curve during the training process. This is the default.	Double
batch_size (Optional)	The number of training data blocks that will be processed at any given time. The default is 2.	Long
early_stop (Optional)	Specifies whether the model training will stop when the metric specified in the model_selection_criteria parameter does not register any improvement after 5 consecutive epochs. EARLY_STOP—The model training will stop when the model is no longer improving. This is the default. NO_EARLY_STOP—The model training will continue until the maximum number of epochs has been reached.	Boolean
learning_rate_strategy (Optional)	Specifies how the learning rate will be modified during training. ONE_CYCLE—The learning rate will be cycled throughout each epoch using Fast.AI's implementation of the 1cycle technique for training neural networks to help improve the training of a convolutional neural network. This is the default. FIXED—The same learning rate will be used throughout the training process.	String

Derived Output

Name	Explanation	Data Type
out_model	The resulting model generated by this tool.	File
out_model_stats	The .csv file containing the precision, recall, and F1 scores for each class code and epoch.	Text File
out_epoch_stats	The .csv file containing the training loss, validation loss, accuracy, precision, recall, and F1 scores obtained in each epoch.	Text File

Code sample

TrainPointCloudClassificationModel example (stand-alone script)

The following sample demonstrates the use of this tool in the Python window.

import arcpy
arcpy.env.workspace = "D:/Deep_Learning_Workspace"
arcpy.ddd.TrainPointCloudClassificationModel("Powerline_Training.pctd", "D:/DL_Models", "Powerline", 
                                             attributes=['INTENSITY', 'RETURN_NUMBER', 'NUMBER_OF_RETURNS'],
                                             target_classes=[14, 15], background_class = 1,
                                             class_descriptions=[[1,"Background"],[14, "Wire Conductor"], [15, "Transmission Tower"]],
                                             model_selection_criteria="F1_SCORE", max_epochs=10)

Environments

Processor Type, GPU ID

Licensing information

• Basic: Requires 3D Analyst
• Standard: Requires 3D Analyst
• Advanced: Requires 3D Analyst