trainYOLOXObjectDetector

Train YOLOX object detector

Since R2023b

collapse all in page

Syntax

detector = trainYOLOXObjectDetector(trainingData,detectorIn,options)
[detector,info] = trainYOLOXObjectDetector(___)
[___] = trainYOLOXObjectDetector(___,Name=Value)

Description

Add-On Required: This feature requires the Automated Visual Inspection Library for Computer Vision Toolbox add-on.

detector = trainYOLOXObjectDetector(trainingData,detectorIn,options) trains a YOLOX object detector using the untrained or pretrained YOLOX network, specified by detectorIn. The options input specifies the network training parameters.

You can also use this syntax for fine-tuning a pretrained YOLOX object detector.

Note

This functionality requires Deep Learning Toolbox™.

example

[detector,info] = trainYOLOXObjectDetector(___) returns information on training progress, such as training loss, for each iteration using the input arguments from the previous syntax.

[___] = trainYOLOXObjectDetector(___,Name=Value) specifies options using one or more name-value arguments. For example, trainYOLOXObjectDetector(trainingData,ExperimentMonitor=[]) specifies not to track metrics with Experiment Manager.

Examples

collapse all

This example uses:

Open Live Script

Prepare Training Data

Load a MAT file containing information about a vehicle data set to use for training into the workspace. The MAT file stores the information stored as a table. The first column contains the training images and the remaining columns contain the labeled bounding boxes for those images.

data = load("vehicleTrainingData.mat");
trainingData = data.vehicleTrainingData;

Specify the directory that contains the training sample image data files and box labels. Add the full path to the filenames in the training data.

dataDir = fullfile(toolboxdir("vision"),"visiondata");
trainingData.imageFilename = fullfile(dataDir,trainingData.imageFilename);

Create an imageDatastore object using the files from the table.

imds = imageDatastore(trainingData.imageFilename);

Create a boxLabelDatastore object using the label columns from the table.

blds = boxLabelDatastore(trainingData(:,2:end));

Combine the image datastore and box label datastore.

ds = combine(imds,blds);

Specify the input size to use for resizing the training images.

inputSize = [128 228 3];

Partition Data

Split the data set into training and validation sets. Allocate approximately 80% of the data for training, and the rest for validation.

numImages = numpartitions(ds);
shuffledIndices = randperm(numImages);
dsTrain = subset(ds,shuffledIndices(1:round(0.8*numImages)));
dsVal = subset(ds,shuffledIndices(numpartitions(dsTrain)+1:end));

Define YOLOX Object Detector Network Architecture

Create a YOLOX object detector by using the yoloxObjectDetector function. Specify "tiny-coco" as the pretrained network to use as the base network. Specify the class names and the network input size.

classes = {'vehicle'};
detector = yoloxObjectDetector("tiny-coco",classes,InputSize=inputSize);

Train YOLOX Object Detection Network

Specify network training options using the trainingOptions (Deep Learning Toolbox) function. Use the mAPObjectDetectionMetric object to track the mean average precision (mAP) metric when you train the detector.

options = trainingOptions("sgdm", ...
    InitialLearnRate=0.001, ...
    MiniBatchSize=16,...
    MaxEpochs=4, ...
    ResetInputNormalization=false, ...
    Metrics=mAPObjectDetectionMetric(Name="mAP50"), ...
    ObjectiveMetricName="mAP50", ...
    ValidationData=dsVal, ...
    ValidationFrequency=20, ...
    VerboseFrequency=2);

Train the pretrained YOLOX network on the new data set by using the trainYOLOXObjectDetector function.

trainedDetector = trainYOLOXObjectDetector(dsTrain,detector,options);
 
    Epoch    Iteration    TimeElapsed    LearnRate    TrainingYoloXLoss    ValidationYoloXLoss    Validationmap50
    _____    _________    ___________    _________    _________________    ___________________    _______________
      1          2         00:00:20        0.001           5.1181                                                
      1          4         00:00:25        0.001           5.0637                                                
      1          6         00:00:29        0.001           2.9549                                                
      1          8         00:00:33        0.001           4.5492                                                
      1         10         00:00:37        0.001           3.3555                                                
      1         12         00:00:41        0.001           3.1534                                                
      1         14         00:00:46        0.001            2.812                                                
      2         16         00:00:50        0.001           2.4134                                                
      2         18         00:00:55        0.001            2.203                                                
      2         20         00:00:59        0.001           2.1435                2.4607               0.94962    
      2         22         00:01:20        0.001            2.276                                                
      2         24         00:01:25        0.001           2.4464                                                
      2         26         00:01:31        0.001           2.3203                                                
      2         28         00:01:36        0.001           2.0818                                                
      3         30         00:01:42        0.001           1.9096                                                
      3         32         00:01:48        0.001           2.1849                                                
      3         34         00:01:54        0.001            1.888                                                
      3         36         00:01:59        0.001           1.9287                                                
      3         38         00:02:04        0.001            1.944                                                
      3         40         00:02:09        0.001           2.3037                2.1339               0.96241    
      3         42         00:02:32        0.001           1.7938                                                
      4         44         00:02:37        0.001           2.3005                                                
      4         46         00:02:42        0.001           1.9379                                                
      4         48         00:02:46        0.001           2.0413                                                
      4         50         00:02:50        0.001           1.9138                                                
      4         52         00:02:54        0.001           1.9997                                                
      4         54         00:02:58        0.001           1.9646                                                
      4         56         00:03:03        0.001           2.0116                2.1982               0.96451

Detect Vehicles in Test Image

Read a test image.

img = imread("highway.png");

Use the fine-tuned YOLOX object detector to detect vehicles in the test image and display the detection results.

[boxes,scores,labels] = detect(trainedDetector,img,Threshold=0.5);
detectedImage = insertObjectAnnotation(img,"rectangle",boxes,labels);
figure
imshow(detectedImage)

Input Arguments

collapse all

Labeled ground truth images, specified as a datastore. You must configure the datastore so that calling it with the read and readall functions returns a cell array or table with these three columns:

Image DataBounding BoxesBounding Box Labels
Single-cell cell array, which contains the input image.

Single-cell array, which contains the bounding boxes, defined in spatial coordinates as an M-by-4 numeric matrix with rows of the form [x y w h], where:

  • M is the number of axis-aligned rectangles.

  • x and y specify the upper-left corner of the rectangle.

  • w specifies the width of the rectangle, which is its length along the x-axis.

  • h specifies the height of the rectangle, which is its length along the y-axis.

Single-cell cell array, which contains an M-by-1 categorical vector of object class names. All the categorical data returned by the datastore must use the same categories.

Use the combine function on two datastores to create a datastore that returns these three data columns using read. The datastore that returns the first column of data should be an ImageDatastore, while the datastore that returns the second and third columns of data should be a boxLabelDatastore.

Pretrained or untrained YOLOX object detector, specified as a yoloxObjectDetector object.

Training options, specified as a TrainingOptionsSGDM, TrainingOptionsRMSProp, or TrainingOptionsADAM object returned by the trainingOptions (Deep Learning Toolbox) function. To specify the solver name and other options for network training, use the trainingOptions (Deep Learning Toolbox) function.

Note

If you specify the OutputFcn function handle using the OutputFcn (Deep Learning Toolbox) name-value argument, it must use a per-epoch info structure with these fields:

  • Epoch

  • Iteration

  • TimeElapsed

  • LearnRate

  • TrainingLoss

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: ExperimentMonitor=[] specifies not to track metrics with Experiment Manager.

Detector training experiment monitoring, specified as an experiments.Monitor (Deep Learning Toolbox) object for use with the Experiment Manager (Deep Learning Toolbox) app. You can use this object to track the progress of training, update information fields in the training results table, record values of the metrics used by the training, or produce training plots. For more information on using this app, see the Train Object Detectors in Experiment Manager example.

The app monitors this information during training:

  • Training loss at each iteration

  • Learning rate at each iteration

  • Validation loss at each iteration, if the options input contains validation data

Subnetwork to freeze during training, specified as one of these values:

  • "none" — Do not freeze a subnetwork.

  • "backbone" — Freeze the feature extraction subnetwork, including the layers following the region of interest (ROI) align layer.

The weight of layers in frozen subnetworks does not change during training.

Since R2026a

Class weights for the loss function, specified as a positive scalar or as a C-element numeric vector, where C is the number of classes in the ClassNames property of the yoloxObjectDetector object detectorIn, and all elements in the vector are positive.

By default, all classes have a weight of 1, indicating equal weight for all classes. If you specify ClassWeights as any positive scalar, the function assigns equal weight to all classes. To assign different weights to each class, specify ClassWeights as a C-element numeric vector with positive values.

Class imbalance in the training data can affect the accuracy of the detector. You can reduce the effect of this class imbalance by assigning class weights inversely related to the class distribution in the training data. Assign higher weights to rare classes that have lower frequency in the training data and lower weights to common classes that have higher frequency in the training data. Ensure that the weights are approximately in inverse proportion to the class distribution in the training data. If you specify the weights of rare classes extremely higher than the required proportion, the model can become unstable or overfit to rare classes. If you specify the weights of rare classes extremely lower than the required proportion, the model may not reduce the effect of the class imbalance sufficiently.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

collapse all

Trained YOLOX object detector, returned as a yoloxObjectDetector object. You can train a YOLOX object detector to detect multiple object classes.

Training progress information, returned as a structure array with these fields. Each field corresponds to a stage of training.

  • TrainingLoss — Training loss at each iteration. The trainYOLOXObjectDetector function uses mean square error for computing bounding box regression loss and cross-entropy for computing classification loss.

  • BaseLearnRate — Learning rate at each iteration.

  • OutputNetworkIteration — Iteration number of the returned network.

  • ValidationLoss — Validation loss at each iteration.

  • FinalValidationLoss — Final validation loss at the end of the training.

Each field is a numeric vector with one element per training iteration. The function returns a value of NaN for iterations at which it does not calculate that value. The structure contains the ValidationLoss and FinalValidationLoss fields only when options specifies validation data.

Tips

  • To generate the labeled ground truth image data, use the Image Labeler or Video Labeler app. To create a table of training data from the generated ground truth, use the objectDetectorTrainingData function.

  • To help improve prediction accuracy, increase the number of images you use to train the network. You can expand the training data set using data augmentation. For information on how to apply data augmentation for preprocessing, see Preprocess Images for Deep Learning (Deep Learning Toolbox).

Extended Capabilities

expand all

Version History

Introduced in R2023b

expand all

See Also

Apps

Functions

Objects

Topics