ssdObjectDetector

Detect objects using SSD deep learning detector

Since R2020a

Description

The ssdObjectDetector detects objects from an image, using a single shot detector (SSD) object detector. To detect objects in an image, pass the trained detector to the detect function. You can also use the trained detector for multiclass object detection. For information about SSD object detection, see Getting Started with SSD Multibox Detection.

Creation

Syntax

detector = ssdObjectDetector(net,classes,aboxes)

detector = ssdObjectDetector(baseNet,classes,aboxes,DetectionNetworkSource=layer)

detector = ssdObjectDetector(___,Name=Value)

Description

detector = ssdObjectDetector(net,classes,aboxes) creates an object detector using the SSD deep learning network net.

If net is a pretrained SSD deep learning network, the function creates a pretrained SSD object detector. The classes and aboxes are the classes and anchor boxes used when the network was trained.

If net is an untrained SSD deep learning network, the function creates a SSD object detector to use for training and inference. classes and aboxes specify the object classes and the anchor boxes, respectively, for training the SSD network. Use the trainSSDObjectDetector function to train the network before performing object detection.

detector = ssdObjectDetector(baseNet,classes,aboxes,DetectionNetworkSource=layer) creates a SSD object detector by adding detection heads to specified feature extraction layers within a base network, baseNet.

If baseNet is a pretrained deep learning network, then the function creates a SSD object detector and configures it to perform transfer learning with the specified object classes and anchor boxes.

If baseNet is an untrained deep learning network, then the function creates a SSD object detector and configures it for object detection. classes and aboxes specify the object classes and the anchor boxes, respectively, for training the SSD network.

You must train the detector on a training dataset before performing object detection. Use the trainSSDObjectDetector function to train the detector.

Before R2021a, use the equivalent syntax detector = ssdObjectDetector(baseNet,classes,aboxes,"DetectionNetworkSource",layer).

detector = ssdObjectDetector(___,Name=Value) sets the InputSize and ModelName properties of the object detector by using name-value arguments. Name is the property name and Value is the corresponding value.

Input Arguments

net — SSD deep learning network

dlnetwork object

SSD deep learning network, specified as a dlnetwork (Deep Learning Toolbox) object. The input network can be either an untrained or a pretrained deep learning network. The input network must not have loss layers.

baseNet — Base network

dlnetwork object

Base network for creating the SSD deep learning network, specified as a dlnetwork (Deep Learning Toolbox) object. The network can be either an untrained or a pretrained deep learning network. When you specify this argument, you must also specify the feature extraction layers by using the layer input argument.

classes — Names of object classes

string vector | cell array of character vectors | categorical vector

Names of object classes for training the detector, specified as a string vector, cell array of character vectors, or categorical vector. This argument sets the ClassNames property of the ssdObjectDetector object.

Data Types: char | string | categorical

aboxes — Anchor boxes

N-by-1 cell array

Anchor boxes for training the detector, specified as an N-by-1 cell array. N is the number of output layers in the SSD deep learning network. Each cell contains an M-by-2 matrix, where M is the number of anchor boxes in that layer. Each row in the M-by-2 matrix denotes the size of an anchor box in the form [height width].

The first element in the cell array specifies the anchor boxes to associate with the first output layer, the second element in the cell array specifies the anchor boxes to associate with the second output layer, and so on. For accurate detection results, specify large anchor boxes for the first output layer and small anchor boxes for the last output layer. That is, the anchor box sizes must decrease for each output layer in the order in which the layers appear in the SSD deep learning network.

This argument sets the AnchorBoxes property of the ssdObjectDetector object.

Data Types: cell

layer — Names of feature extraction layers

cell array of character vectors | string array

Names of the feature extraction layers in the base network, specified as a cell array of character vectors or a string array.

Example: layer = {'conv10','fire9-concat'}

Example: layer = ["conv10","fire9-concat"]

Data Types: char | string | cell

Properties

ModelName — Name of classification model

character vector | string scalar

This property is read-only.

Name of the classification model, specified as a character vector or string scalar. By default, the name is set to the heading of the second column of the trainingData table specified in the trainSSDObjectDetector function. You can modify this name after creating your ssdObjectDetector object.

Network — Trained SSD multibox object detection network

dlnetwork object

This property is read-only.

Trained SSD multibox object detection network, specified as a dlnetwork (Deep Learning Toolbox) object. The dlnetwork object stores the layers that define the convolutional neural network used within the SSD detector.

AnchorBoxes — Size of anchor boxes

P-by-1 cell array

This property is read-only.

Size of anchor boxes, specified as a P-by-1 cell array for P number of feature extraction layers used for object detection in the SSD network. Each element of the array contains an M-by-2 matrix of anchor box sizes, in the format [height width]. Each cell can contain a different number of anchor boxes.

You can set this property by using the input argument aboxes.

ClassNames — Names of object classes

cell array

This property is read-only.

Names of the object classes that the SSD detector is trained to find, specified as a cell array. You can set this property by using the input argument classes.

Object Functions

detect

Detect objects using SSD multibox object detector

Examples

Create Custom SSD Object Detector

This example shows how to create a SSD object detection network by using a pretrained ResNet-50 convolutional neural network as the base network.

Load a pretrained deep learning network to use as the base network. This example uses a ResNet-50 pretrained network as the base network. For information about other available pretrained networks, see Pretrained Deep Neural Networks (Deep Learning Toolbox).

baseNet = imagePretrainedNetwork("resnet50");

Use analyzeNetwork to display the architecture of the base network.

analyzeNetwork(baseNet)

Specify the class names and anchor boxes to use for training the SSD deep learning network created using ResNet-50 as the base network.

classNames = ["person" "car" "dog"];
anchorBoxes = {[30 60;60 30;50 50;100 100], ...
               [40 70;70 40;60 60;120 120], ...
               [50 80;80 60;70 70;140 140]};

Specify the names of the feature extraction layers in the base network to use as the detection heads.

featureExtractionLayers = ["activation_11_relu" "activation_22_relu" "activation_40_relu"];

Create an SSD object detector by using the specified base network and the detection heads.

detector = ssdObjectDetector(baseNet,classNames,anchorBoxes,DetectionNetworkSource=featureExtractionLayers);

Display and inspect the properties of the SSD object detector.

disp(detector)

  ssdObjectDetector with properties:

        Network: [1×1 dlnetwork]
    AnchorBoxes: {3×1 cell}
     ClassNames: [3×1 string]
      InputSize: [224 224 3]
      ModelName: ''

Use analyzeNetwork to display the SSD network architecture and get information about the network layers.

analyzeNetwork(detector.Network)

Detect Vehicles Using SSD Object Detector

Load a pretrained single shot detector (SSD) object to detect vehicles in an image. The detector is trained with images of cars on a highway scene.

vehicleDetector = load("ssdVehicleDetector.mat","detector");
detector = vehicleDetector.detector;

Read a test image into the workspace.

I = imread("highway.png");

Display the test image.

imshow(I)

Run the pretrained SSD object detector by using the detect function. The output contains the bounding boxes, scores, and the labels for vehicles detected in the image. The labels are derived from the ClassNames property of the detector.

[bboxes,scores,labels] = detect(detector,I)

bboxes = 2×4

   139    78    96    81
    99    67   165   146

scores = 2×1 single column vector

    0.8349
    0.6302

labels = 2×1 categorical
     vehicle 
     vehicle 

Annotate the image with the detection results.

if ~isempty(bboxes)
    detectedI = insertObjectAnnotation(I,"rectangle",bboxes,cellstr(labels));
else
   detectedI = insertText(I,[10 10],"No Detections");
end
   
imshow(detectedI)

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Only the detect method of the ssdObjectDetector is supported for code generation.

• The roi argument to the detect method must be a codegen constant (coder.const()) and a 1-by-4 vector.

• Only the Threshold, SelectStrongest, MinSize, MaxSize, and MiniBatchSize name-value arguments are supported. All name-value arguments must be compile-time constants.

• The channel and batch size of the input image must be fixed size.

• The labels output is returned as a categorical array.

• In the generated code, the input is rescaled to the size of the input layer of the network. But the bounding box that the detect method returns is in reference to the original input size.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

For code generation,

• Only the detect method of the ssdObjectDetector is supported for code generation.

• The roi argument to the detect method must be a codegen constant (coder.const()) and a 1-by-4 vector.

• Only the Threshold, SelectStrongest, MinSize, MaxSize, and MiniBatchSize name-value arguments are supported.

• The channel and batch size of the input image must be fixed size.

• The labels output is returned as a categorical array.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

Introduced in R2020a

R2024b: Returns Network property as dlnetwork object

The Network property now returns a dlnetwork object instead of a DAGNetwork (Deep Learning Toolbox) object.

R2024b: LayerGraph objects are not recommended

Starting in R2024b, LayerGraph (Deep Learning Toolbox) objects are not recommended. If you want to use a pretrained SSD network or a base feature extraction network, specify net or baseNet as a dlnetwork (Deep Learning Toolbox) object instead.

There are no plans to remove support for LayerGraph objects. However, dlnetwork objects have these advantages and are recommended instead:

• dlnetwork objects are a unified data type that supports network building, prediction, built-in training, visualization, compression, verification, and custom training loops.

• dlnetwork objects support a wider range of network architectures that you can create or import from external platforms.

• Training and prediction with dlnetwork objects is typically faster than with LayerGraph objects.