You are here: Start » Technical Issues » Deep Learning Training API

Deep Learning Training API

Note:This article is related to the C++ Deep Learning API for Feature Detection and Anomaly Detection techniques in 5.6 version only.

Table of contents:

  1. Overview
  2. Namespaces
  3. Classes and Types
  4. Functions
  5. Handling Events
  6. Usage Example
  7. JSON Configuration Example
  8. Best Practices
  9. Limitations and Notes

Overview

The Deep Learning API provides a comprehensive framework for training and deploying Deep Learning models, focused on feature detection tasks. It offers an object-oriented interface that simplifies the complexities of configuring and managing Deep Learning operations. Whole API declaration is located in Api.h file. under avl namespace.

Namespaces

  • avl: Main namespace containing all public-facing classes and types.

Classes and Types

avl::DetectFeaturesTraining

This is the primary class users should interact with for feature detection training. It is derived from TrainingBase and provides specialized methods and properties for configuring and managing feature detection tasks.

Constructors

DetectFeaturesTraining();
explicit DetectFeaturesTraining(const atl::String& url);

Configuration Methods

Training configuration can be performed in two ways:

  1. Via Set Methods: Configuration can be done using methods like SetDevice, SetNetworkDepth, and other Set* methods. If a specific Set* method is not called, the default value will be used.
  2. Via JSON File: Use the ParseConfigFromFile method to load configuration from a JSON file.

Enums

  • SetType: Specifies the dataset role (Train, Valid, Test, Unknown).
  • DeviceType: Defines the hardware device for training (CUDA, CPU).
  • ModelTypeId: Identifies the model type (e.g., DetectFeatures, AnomalyDetection2SimilarityBased).

Functions

ParseConfigFromFile

Loads configuration from a JSON file.

void ParseConfigFromFile(const atl::String& jsonConfigFilePath);

Example of JSON file configuration below.

StartTraining

Begins the training process.

void StartTraining();

SaveModel

Saves the trained model to disk in two formats:

  • A model state file (.pte) for internal use and training continuation
  • A Weaver model file (.avdlmodel) for deployment in applications

Method Signatures

void SaveModel(const atl::Optional<atl::String>& modelDirectoryPath = atl::NIL, const bool overwritePreviousModel = false);
void SaveModel(const char* modelDirectoryPath, const bool overwritePreviousModel = false);

Parameters

  • modelDirectoryPath: Optional path to a directory where model files will be saved. If not provided (default), models are saved in the default directory: [current working directory]/Model/models/
  • overwritePreviousModel: When set to true, any existing model files at the destination will be overwritten. When false (default), and model files exist, an error will be raised.

Helper Methods

After saving, you can retrieve the exact paths to the saved model files using:

  • GetModelStateFilePath(): Returns the path to the .pte model state file
  • GetModelWeaverFilePath(): Returns the path to the .avdlmodel Weaver model file

Usage Examples

// 1. Save to default location:
training.SaveModel();

// 2. Save to default location and overwrite existing files:
training.SaveModel(atl::NIL, true);

// 3. Save to custom location:
training.SaveModel("C:/My/Models/Path");

// 4. Save to custom location and overwrite existing files:
training.SaveModel("C:/My/Models/Path", true);

// 5. Get saved file paths:
std::cout << "Model State (.pte) saved to: " << training.GetModelStateFilePath().CStr8() << std::endl;
std::cout << "Weaver Model (.avdlmodel) saved to: " << training.GetModelWeaverFilePath().CStr8() << std::endl;

LoadModel

Loads a previously saved model state (.pte) file for inference.

Method Signatures

void LoadModel(const atl::String& modelFilePath);
void LoadModel(const char* modelFilePath);

Parameters

  • modelFilePath: Path to a model state file (.pte) to load. The method will load the specified model file for inference operations.

Functionality

Loading a model allows you to:

  • Perform inference on new images using a trained model

Usage Examples

// 1. Load a specific model file:
training.LoadModel("C:/My/Models/Path/model.pte");

// 2. Load using the path from a previous save operation (PTE file):
training.SaveModel();  // Save first
training.LoadModel(training.GetModelStateFilePath());  // Load the saved model

Important Notes

  • This method loads only the model state (.pte) file used for training and inference within this API
  • The Weaver model (.avdlmodel) files created by SaveModel() are for deployment in production applications
  • After loading, the model is immediately ready for inference with InferAndGrade()

GetModelStateFilePath & GetModelWeaverFilePath

Helper methods to retrieve the paths of saved model files.

Method Signatures

atl::String GetModelStateFilePath();
atl::String GetModelWeaverFilePath();

Return Values

  • GetModelStateFilePath(): Returns the full path to the saved model state file (.pte)
  • GetModelWeaverFilePath(): Returns the full path to the saved Weaver model file (.avdlmodel)

Usage

These methods can be called only after SaveModel() to get the exact file paths where the models were saved:

training.SaveModel("./MyModels");
std::cout << "PTE model saved to: " << training.GetModelStateFilePath().CStr8() << std::endl;
std::cout << "Weaver model saved to: " << training.GetModelWeaverFilePath().CStr8() << std::endl;

InferAndGrade

Performs inference and grades the results. If the InferResultReceived method is overridden, it will be utilized during the inference process.

void InferAndGrade(
    const atl::String& imageFilePath,
    const Annotation& annotation,
    const atl::Optional<avl::Region>& roi = atl::NIL,
    const atl::Optional<atl::Array<atl::String>>& setNames = atl::NIL);

Parameters

  • imageFilePath: Path to the image for inference.
  • annotation: Annotation with class name (and optional region) used for grading or context.
  • roi (optional): Region of interest. When omitted or atl::NIL, the full image is used.
  • setNames (optional): Logical grouping / tag list for evaluation summary (e.g. custom test subsets).

Handling Events

To communicate with the user during training and inference, several events are available:

  • TrainingProgressReceived(double progress): Called to update progress during training.
  • InferResultReceived(const atl::Array<avl::Image>&): Invoked when inference results are available.

Usage Example

Below is an example demonstrating how to use the API for training a feature detection model:


#include "Api.h"
#include <iostream>

using namespace avl;

class MyTraining : public DetectFeaturesTraining
{
public:
	MyTraining()
	{
	}

	void TrainingProgressReceived(double progress) override
	{
		std::cout << "Progress: " << progress << std::endl;
	}

	void InferResultReceived(const atl::Array<avl::Image>& inferResultImages) override
	{
		(void)inferResultImages;
		//  for (const auto& inferResultImage : inferResultImages)
		// std::cout << "InferResult: " << "Width: " << inferResultImage.Width() <<, " Height: " << inferResultImage.Height() << std::endl;
	}
};

int main()
{
	MyTraining training;

	// Training dataset
	auto myTrainingSamples = atl::Array<atl::String>();
	myTrainingSamples.PushBack("Images/train/010.png");
	myTrainingSamples.PushBack("Images/train/011.png");
	myTrainingSamples.PushBack("Images/train/012.png");

	// Validation dataset
	auto myValidationSamples = atl::Array<atl::String>();
	myValidationSamples.PushBack("Images/valid/020.png");
	myValidationSamples.PushBack("Images/valid/021.png");
	myValidationSamples.PushBack("Images/valid/022.png");

	// Test dataset
	auto myTestSamples = atl::Array<atl::String>();
	myTestSamples.PushBack("Images/test/140.png");
	myTestSamples.PushBack("Images/test/141.png");
	myTestSamples.PushBack("Images/test/142.png");

	// Set names for samples used for infer and grade
	auto mySetNames = atl::Array<atl::String>();
	mySetNames.PushBack("my test set 1");
	mySetNames.PushBack("my test set 2");

	// Create a simple annotation mask for the training samples.
	atl::String myClassName = "thread";
	const int width = 648; // Example width and height, should match your training images
	const int height = 486;
	avl::Region myRegion(width, height);
	for (int y = height / 4; y < (height / 4 + height / 2); ++y)
		myRegion.Add(width / 4, y, (width / 4 + width / 2));
	auto myAnnotation = Annotation(myClassName, myRegion);

	// Set training configuration
	// MANUALLY:
	training.SetNetworkDepth(3);
	training.SetIterations(1);
	training.SetDevice(DeviceType::CUDA);
	training.SetToGrayscale(true);
	training.SetAugNoise(5.5);
	// training.SetClassNames(myClassName);  //Optional

	// Or from file:
	// training.ParseConfigFromFile("detect_features_config.json");

	// OPTIONAL:
	// training.Configure(); // Optional 
	// training.GetConfig(); // Call `training.Configure();` before `training.GetConfig()` otherwise it will use default config

	for (const auto& sample : myTrainingSamples)
		training.SetSample(sample, myAnnotation, SetType::Train);

	for (const auto& sample : myValidationSamples)
		training.SetSample(sample, myAnnotation, SetType::Valid);

	training.StartTraining();

	training.SaveModel();
	std::cout << "Model State (.pte) saved into file: " << training.GetModelStateFilePath().CStr8() << std::endl;
	std::cout << "Model Weaver (.avdlmodel) saved into file: " << training.GetModelWeaverFilePath().CStr8() << std::endl;

	// Load the model state for inference (use .pte file, not .avdlmodel)
	training.LoadModel(training.GetModelStateFilePath());

	for (const auto& sample : myTestSamples)
		training.InferAndGrade(sample, myAnnotation, atl::NIL, mySetNames);

	return 0;
}

JSON Configuration Example

Below is an example of JSON Configuration File for a feature detection model:


{
    "device": "cuda",
    "device_id": 0,
    "is_continuation": false,
    "network_depth": 3,
    "iterations": 2,
    "min_number_of_tiles": 6,
    "need_to_convert_samples": false,
    "stop.training_time_s": 0,
    "stop.validation_value": 0.0,
    "stop.stagnant_iterations": 0,
    "feature_size": 96,
    "aug.rotation": 0.0,
    "aug.scale.min": 1.0,
    "aug.scale.max": 1.0,
    "aug.shear.vertical": 0.0,
    "aug.shear.horizontal": 0.0,
    "aug.flip.vertical": false,
    "aug.flip.horizontal": false,
    "aug.noise": 2.0,
    "aug.blur": 0,
    "aug.luminance": 0.04,
    "aug.contrast": 0.0,
    "to_grayscale": false,
    "downsample": 2,
    "is_mega_tiling": false,
    "mega_tile_size": 128,
    "class_names": "thread",
    "adv.class_names_sep": ";"
}

Best Practices

  • Use DetectFeaturesTraining for feature detection tasks instead of directly using TrainingBase.
  • Extend DetectFeaturesTraining for custom behavior during training.
  • Ensure balanced datasets for training and validation.
  • Use callback methods to monitor training progress.

Limitations and Notes

  • The ExportQuantizedModel method is not supported for DetectFeaturesTraining.
  • Configuration can be done through property setters or by loading a JSON configuration file.
  • SaveModel() creates two files: a .pte file for training/inference and a .avdlmodel file for deployment.
  • LoadModel() only loads .pte files for inference operations within this API.
  • Weaver model files (.avdlmodel) are intended for deployment in production applications, not for loading back into the training API.
  • Provide an atl::Optional<avl::Region> ROI to limit inference processing area; pass atl::NIL (or omit parameter) to use the full image.
  • An Annotation without a region is valid for tasks that don't require pixel masks.