detect
Syntax
Description
detects objects within a single image or a batch of images,
bboxes
= detect(detector
,I
)I
, using a YOLOX object detector,
detector
. The detect
function
returns the locations of objects detected in the input image as a set of
bounding boxes.
Note
This functionality requires Deep Learning Toolbox™ and the Automated Visual Inspection Library for Computer Vision Toolbox™. You can install the Automated Visual Inspection Library for Computer Vision Toolbox from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.
returns object detection predictions within all the images returned by the
detectionResults
= detect(detector
,ds
)read
function of
the input datastore ds
, as a table.
[___] = detect(___,
detects objects within the rectangular search region roi
)roi
,
in addition to any combination of arguments from previous syntaxes.
[___] = detect(___,
specifies options using one or more name-value arguments, in addition to any
combination of arguments from previous syntaxes.. For example,
Name=Value
)Threshold=0.25
specifies a detection threshold of
0.25.
Examples
Detect Objects Using Pretrained YOLOX Object Detector
Specify the name of a pretrained YOLOX deep learning network.
name = "tiny-coco";
Create YOLOX object detector by using the pretrained YOLOX network.
detector = yoloxObjectDetector(name);
Detect objects in a test image by using the pretrained YOLOX object detector.
img = imread("tima.png");
[bboxes,scores,labels] = detect(detector,img,Threshold=0.6)
bboxes = 1x4 single row vector
185.1392 255.8597 119.6875 217.3187
scores = single
0.7775
labels = categorical
cat
Display the detection results.
detectedImg = insertObjectAnnotation(img,"Rectangle",bboxes,labels);
figure
imshow(detectedImg)
Detect Objects in Image Datastore Using YOLOX Detector
Load a pretrained YOLOX object detector.
detector = yoloxObjectDetector("small-coco");
Read the test datastore and store it as an image datastore object.
location = fullfile(matlabroot,"toolbox","vision","visiondata","vehicles"); imds = imageDatastore(location);
Detect objects in the test datastore. Set the Threshold
parameter value to 0.4 and MiniBatchSize
parameter value to 32.
detectionResults = detect(detector,imds,Threshold=0.4,MiniBatchSize=32);
Read an image from the test dataset and extract the corresponding detection results.
num = 20; I = readimage(imds,num); bboxes = detectionResults.Boxes{num}; labels = detectionResults.Labels{num}; scores = detectionResults.Scores{num};
Perform non-maximal suppression to select strongest bounding boxes from the overlapping clusters. Set the OverlapThreshold
parameter value to 0.5.
[bboxes,scores,labels] = selectStrongestBboxMulticlass(bboxes,...
scores,labels,OverlapThreshold=0.5);
Display the detection results.
results = table(bboxes,labels,scores)
results=5×3 table
bboxes labels scores
____________________________________ ______ _______
2.0755 69.251 16.852 9.0757 car 0.61246
19.219 70.205 21.257 10.847 car 0.77888
75.165 65.773 25.769 23.227 car 0.75951
96.479 54.215 16.175 24.654 bus 0.67867
1 104.91 225.57 22.663 car 0.43216
detectedImg = insertObjectAnnotation(I,"Rectangle",bboxes,labels);
figure
imshow(detectedImg)
Detect Objects Within ROI by Using YOLOX Detector
Load a pretrained YOLOX object detector.
detector = yoloxObjectDetector("small-coco");
Read a test image.
img = imread("aruba.png");
Specify a region of interest (ROI) within the test image.
roiBox = [250 180 300 250];
Detect objects within the specified ROI.
[bboxes,scores,labels] = detect(detector,img,roiBox,Threshold=0.55);
Display the ROI and the detection results.
img = insertObjectAnnotation(img,"Rectangle",roiBox,"ROI",AnnotationColor="yellow"); detectedImg = insertObjectAnnotation(img,"Rectangle",bboxes,labels); figure imshow(detectedImg)
Input Arguments
detector
— YOLOX object detector
yoloxObjectDetector
object
YOLOX object detector, specified as a yoloxObjectDetector
object.
I
— Test images
numeric array
Test images, specified as a numeric array of size H-by-W-by-C or H-by-W-by-C-by-B. You must specify real and nonsparse grayscale or RGB images.
H — Height of the input images.
W — Width of the input images.
C — Number of channels. The channel size of each image must be equal to the input channel size of the network. For example, for grayscale images, C must be
1
. For RGB color images, it must be3
.B — Number of test images in the batch. The
detect
function computes the object detection results for each test image in the batch.
When the test image size does not match the network input size, the
detector resizes the input image to the value of the InputSize
property of
detector
, unless you specify AutoResize
as false
.
Data Types: uint8
| uint16
| int16
| double
| single
ds
— Datastore of test images
ImageDatastore
object | CombinedDatastore
object | TransformedDatastore
object
Datastore of test images, specified as an imageDatastore
object,
CombinedDatastore
object, or TransformedDatastore
object containing full filenames of the
test images. The images in the datastore must be grayscale or RGB images.
roi
— Region of interest to search
vector of form [x
y
width
height]
Region of interest (ROI) to search, specified as a vector of form
[x
y
width
height]. The vector specifies the upper-left corner and
size of a region, in pixels. If the input data is a datastore, the
detect
function applies the same ROI to every
image.
Note
You can specify the ROI to search only when the
detect
function automatically resizes the
input test images to the network input size. To use
roi
, reset AutoResize
to its default value.
Name-Value Arguments
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: detect(detector,I,Threshold=0.25)
specifies a detection
threshold of 0.25.
Threshold
— Detection threshold
0.25
(default) | scalar in the range [0, 1]
Detection threshold, specified as a scalar in the range [0,
1]
. The function removes detections that have scores less
than this threshold value. To reduce false positives, increase this
value at the possible expense of missing some objects.
SelectStrongest
— Strongest bounding box selection
true
or
1
(default) | false
or 0
Strongest bounding box selection for each detected object, specified
as a numeric or logical 1
(true
)
or 0
(false
).
true
— Return the strongest bounding box for each object. Thedetect
function calls theselectStrongestBboxMulticlass
function, which uses nonmaximal suppression to eliminate overlapping bounding boxes based on their confidence scores.By default, the
detect
function uses this call to theselectStrongestBboxMulticlass
.selectStrongestBboxMulticlass(bboxes,scores, ... RatioType="Union", ... OverlapThreshold=0.45);
false
— Return all the detected bounding boxes. You can write a custom function to eliminate overlapping bounding boxes.
MinSize
— Minimum region size
[1 1]
(default) | vector of form [height
width]
Minimum region size containing an object, specified as a vector of the
form [height
width]. Units are in pixels. The minimum region size
defines the size of the smallest object that can be detected by the
trained network. When the minimum size is known, you can reduce
computation time by setting MinSize
to that
value.
MaxSize
— Maximum region size
size
(I
) (default) | vector of form [height
width]
Maximum region size, specified as a vector of the form [height width]. Units are in pixels. The maximum region size defines the size of the largest object that can be detected by the trained network.
By default, MaxSize
is set to the height and
width of the input image I
. To reduce computation
time, set this value to the known maximum region size for the objects
that can be detected in the input test image.
MiniBatchSize
— Minimum batch size
128
(default) | positive integer
Minimum batch size, specified as a positive integer. Adjust the
MiniBatchSize
value to help process a large
collection of images. The detect
function groups
images into minibatches of the specified size and processes them as a
batch, which can improve computation efficiency at the cost of increased
memory demand. Increase the minibatch size to decrease processing time.
Decrease the minibatch size to use less memory.
AutoResize
— Automatic resizing of input images
true
or
1
(default) | false
or 0
Automatic resizing of input images to preserve the aspect ratio,
specified as a numeric or logical 1
(true
) or 0
(false
). When AutoResize
is
set to 1
(or true
), the
detect
function resizes images to the nearest
InputSize
and the aspect ratio is
preserved. Set AutoResize
to logical
false
or 0
when performing
image tiling-based training or inference at full test image size.
ExecutionEnvironment
— Hardware resource
"auto"
(default) | "gpu"
| "cpu"
Hardware resource on which to run the detector, specified as one of these values:
"auto"
— Use a GPU if Parallel Computing Toolbox™ is installed and a supported GPU device is available. Otherwise, use the CPU."gpu"
— Use the GPU. To use a GPU, you must have Parallel Computing Toolbox and a CUDA®-enabled NVIDIA® GPU. If a suitable GPU is not available, the function returns an error. For information about the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox)."cpu"
— Use the CPU.
Acceleration
— Performance optimization
"auto"
(default) | "mex"
| "none"
Performance optimization, specified as one of these options:
"auto"
— Automatically apply a number of compatible optimizations suitable for the input network and hardware resource."mex"
— Compile and execute a MEX function. This option is available only when using a GPU. Using a GPU requires Parallel Computing Toolbox and a CUDA enabled NVIDIA GPU. If Parallel Computing Toolbox or a suitable GPU is not available, then thedetect
function returns an error. For information about the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox)."none"
— Disable all acceleration.
Using the Acceleration
options
"auto"
and "mex"
can offer
performance benefits on subsequent calls with compatible parameters, at
the expense of an increased initial run time. Use performance
optimization when you plan to call the function multiple times using new
input data.
The "mex"
option generates and executes a MEX
function based on the network and parameters used in the function call.
You can have several MEX functions associated with a single network at
one time. Clearing the network variable also clears any MEX functions
associated with that network.
The "mex"
option is available only for input data
specified as a numeric array, cell array of numeric arrays, table, or
image datastore. No other types of datastore support the
"mex"
option.
The "mex"
option is available only when you are
using a GPU. You must also have a C/C++ compiler installed. For setup
instructions, see MEX Setup (GPU Coder).
"mex"
acceleration does not support all layers. For
a list of supported layers, see Supported Layers (GPU Coder).
Output Arguments
bboxes
— Locations of objects detected
M-by-4 matrix | B-by-1 cell array
Locations of objects detected within the input image or images, returned as one of these options:
M-by-4 matrix — The input is a single test image. M is the number of bounding boxes detected in an image.
B-by-1 cell array — The input is a batch of images, where B is the number of test images in the batch. Each cell in the array contains an M-by-4 matrix specifying the detected bounding boxes.
scores
— Detection confidence scores
M-by-1 numeric vector | B-by-1 cell array
Detection confidence scores for each bounding box, returned as one of these options:
M-by-1 numeric vector — The input is a single test image. M is the number of bounding boxes detected in the image.
B-by-1 cell array — The input is a batch of test images, where B is the number of test images in the batch. Each cell in the array contains an M-element row vector, where each element indicates the detection score for a bounding box in the corresponding image.
A higher score indicates higher confidence in the detection. The confidence score for each detection is a product of the corresponding objectness score and maximum class probability. The objectness score is the probability that the object in the bounding box belongs to a class in the image. The maximum class probability is the largest probability that a detected object in the bounding box belongs to a particular class.
labels
— Labels for bounding boxes
M-by-1 categorical vector | B-by-1 cell array
Labels for bounding boxes, returned as one of these options:
M-by-1 categorical vector — The input is a single test image. M is the number of bounding boxes detected in an image.
B-by-1 cell array — The input is an array of test images. B is the number of test images in the batch. Each cell in the array contains an M-by-1 categorical vector containing the names of the object classes.
detectionResults
— Detection results
three-column table
Detection results when the input is a datastore of test images, ds
, returned as a table with these columns:
bboxes | scores | labels |
---|---|---|
Predicted bounding boxes, defined in spatial coordinates as an M-by-4 numeric matrix with rows of the form [x y w h], where:
| Class-specific confidence scores in the range
| Predicted object labels assigned to bounding boxes, returned as an M-by-1 categorical vector. All categorical data returned by the datastore must contain the same categories. |
info
— Class probabilities and objectness scores
structure array
Class probabilities and objectness scores of the detections, returned as a structure array with these fields.
ClassProbabilities
— Class probabilities for each of the detections, returned as a B-by-1 cell array. B is the number of images in the input batch of images,I
. Each cell in the array contains the class probabilities as an M-by-N numeric matrix. M is the number of bounding boxes and N is the number of classes. Each class probability is a numeric scalar, indicating the probability that the detected object in the bounding box belongs to a class in the image.ObjectnessScores
— Objectness scores for each of the detections, returned as a B-by-1 cell array. B is the number of images in the input batch of images,I
. Each cell in the array contains the objectness score for each bounding box as an M-by-1 numeric vector. M is the number of bounding boxes. Each objectness score is a numeric scalar, indicating the probability that the bounding box contains an object belonging to one of the classes in the image.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
To prepare a
yoloxObjectDetector
object for CPU code generation, usevision.loadYOLOXObjectDetector
.The
roi
argument to thedetect
method must be a code generation constant (coder.const()
) and a 1x4 vector.The
AutoResize
argument to thedetect
method must be a code generation constant (coder.const()
).Only the
Threshold
,SelectStrongest
,MinSize
,MaxSize
,MiniBatchSize
, andAutoResize
name-value pairs fordetect
are supported.
GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.
Usage notes and limitations:
To prepare a
yoloxObjectDetector
object for GPU code generation, usevision.loadYOLOXObjectDetector
.The
roi
argument to thedetect
method must be a code generation constant (coder.const()
) and a 1x4 vector.The
AutoResize
argument to thedetect
method must be a code generation constant (coder.const()
).Only the
Threshold
,SelectStrongest
,MinSize
,MaxSize
, andMiniBatchSize
, andAutoResize
name-value pairs fordetect
are supported.
Version History
Introduced in R2023bR2024a: Option to return class probabilities and objectness scores
Specify the info
output argument to return information about the class probability and objectness
score for each detection.
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)