phased.CFARDetector2D
Twodimensional CFAR detector
Description
phased.CFARDetector2D
System object™ implements a constant falsealarm rate detector (CFAR) for selected
elements (called cells) of twodimensional image data. A detection is declared when an
image cell value exceeds a threshold. To maintain a constant false alarmrate, the
threshold is set to a multiple of the image noise power. The detector estimates noise
power for a cellundertest (CUT) from surrounding cells using
one of three cell averaging methods, or an order statistics method. The cellaveraging
methods are cell averaging (CA), greatestof cell averaging (GOCA), or smallestof cell
averaging (SOCA).
For each test cell, the detector:
Estimates the noise statistic from the cell values in the training band surrounding the CUT cell.
Computes the threshold by multiplying the noise estimate by the threshold factor.
Compares the CUT cell value to the threshold to determine whether a target is present or absent. If the value is greater than the threshold, a target is present.
creates a
2D CFAR detector System object, detector
= phased.CFARDetector2Ddetector
.
To run the 2D CFAR detector:
Create the
phased.CFARDetector2D
object and set its properties.Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
Creation
Description
detector = phased.CFARDetector2D
creates a 2D CFAR
detector object, detector
.
creates a 2D CFAR System object, detector
= phased.CFARDetector2D(Name
,Value
)detector
, with each specified property
Name
set to the specified Value
.
You can specify additional namevalue pair arguments in any order as
(Name1
,Value1
,...,NameN
,ValueN
).
Properties
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release
function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects.
Method
— Twodimensional CFAR averaging method
'CA'
(default)  'GOCA'
 'SOCA'
 'OS'
Twodimensional CFAR averaging method, specified as
'CA'
, 'GOCA'
,
'SOCA'
, or 'OS'
. For
'CA'
, 'GOCA'
,
'SOCA'
, the noise power is the sample mean derived
from the training band. For 'OS'
, the noise power is the
kth cell value obtained from numerically ordering all
training cell values. Set k using the
Rank
property.
Averaging Method  Description 

CA — Cellaveraging
algorithm  Computes the sample mean of all training cells surrounding the CUT cell. 
GOCA — Greatestof
cellaveraging algorithm  Splits the 2D training window surrounding the CUT cell into left and right halves. Then, the algorithm computes the sample mean for each half and selects the largest mean. 
SOCA — Smallestof
cellaveraging algorithm  Splits the 2D training window surrounding the CUT cell into left and right halves. Then, the algorithm computes the sample mean for each half and selects the smallest mean. 
OS — Order statistic
algorithm  Sorts training cells in ascending order of numeric
values. Then the algorithm selects the
kth value from the list.
k is the rank specified by the

Example: 'OS'
Data Types: char
GuardBandSize
— Widths of guard band
[1 1]
(default)  nonnegative integer  2element vector of nonnegative integers
The number of rows and columns of the guard band cells on each side of the
CUT cell, specified as nonnegative integers. The first element specifies the
guard band size along the row dimension. The second element specifies the
guard band size along the column dimension. Specifying this property as a
single integer is equivalent to specifying a guard band with the same value
for both dimensions. For example, a value of [1 1]
,
indicates that there is a one guardcellwide region surrounding each CUT
cell. A value of zero indicates there are no guard cells.
Example: [2 3]
Data Types: single
 double
TrainingBandSize
— Widths of training band
[1 1]
(default)  positive integer  2element vector of positive integers
The number of rows and columns of the training band cells on each side of
the CUT cell, specified as a positive integer or a 1by2 matrix of positive
integers. The first element specifies the training band size along the row
dimension. The second element specifies the training band size along the
column dimension. Specifying this property as a scalar is equivalent to
specifying a training band with the same value for both dimensions. For
example, a value of [1 1]
indicates a 1
trainingcellwide region surrounding the CUT cell.
Example: [30:0.1:30]
Data Types: single
 double
Rank
— Rank of order statistic
1 (default)  positive integer
Rank of the order statistic used in the 2D CFAR algorithm, specified as a positive integer. The value of this property must lie between 1 and N_{train}, where N_{train} is the number of training cells. A value of 1 selects the smallest value in the training region.
Example: 5
Dependencies
To enable this property, set the Method
property
to 'OS'
.
Data Types: single
 double
ThresholdFactor
— Threshold factor method
'Auto'
(default)  'Input port'
 'Custom'
Threshold factor method, specified as 'Auto'
,
'Input port'
, or 'Custom'
.
When you set the ThresholdFactor
property to
'Auto'
, the threshold factor is calculated from the
desired probability of false alarm set in the
ProbabilityFalseAlarm
property. The calculation
assumes that each independent signal in the input is a single pulse coming
out of a square law detector with no pulse integration. In addition, the
noise is assumed to be white Gaussian.
When you set the ThresholdFactor
property to
'Input port'
, the threshold factor is obtained from
an input argument of the object function.
When you set the ThresholdFactor
property to
'Custom'
, the threshold factor is obtained from the
value of the CustomThresholdFactor
property.
Example: 'Custom'
Data Types: char
ProbabilityFalseAlarm
— Required probability of false alarm
0.1
(default)  positive scalar between 0 and 1
Required probability of false alarm, specified as a real positive scalar between 0 and 1. The algorithm calculates the threshold factor from the required probability of false alarm.
Example: 0.001
Dependencies
To enable this property, set the ThresholdFactor
property to 'Auto'
.
Data Types: single
 double
CustomThresholdFactor
— Custom threshold factor
1
(default)  positive scalar
Custom threshold factor, specified as a real positive scalar. This property is tunable.
Dependencies
To enable this property, set the ThresholdFactor
property to 'Custom'
.
Data Types: single
 double
OutputFormat
— Format of detection results
'CUT result'
(default)  'Detection index'
Format of detection results returned by the object function method,
specified as 'CUT result'
or 'Detection
index'
.
When set to
'CUT result'
, the results are logical detection values (1
or0
) for each tested cell.When set to
'Detection index'
, the results form a vector or matrix containing the indices of tested cells that exceed a detection threshold. You can use this format as input to thephased.RangeEstimator
andphased.DopplerEstimator
System objects.
Data Types: char
ThresholdOutputPort
— Enable detection threshold output
false
(default)  true
Option to enable detection threshold output, specified as
false
or true
. Setting this
property to true
returns the detection threshold via an
output argument, th
, of the object function.
Data Types: logical
NoisePowerOutputPort
— Enable noise power output
false
(default)  true
Option to enable output of noise power, specified as
false
or true
. Setting this
property to true
returns the noise power via the output
argument, noise
, of the object function.
Data Types: logical
NumDetectionsSource
— Source of the number of detections
'Auto'
(default)  'Property'
Source of the number of detections, specified as 'Auto'
or 'Property'
. When you set this property to
'Auto'
, the number of detection indices reported is
the total number of cells under test that have detections. If you set this
property to 'Property'
, the number of reported detections
is determined by the value of the NumDetections
property.
Dependencies
To enable this property, set the OutputFormat
property to 'Detection index'
.
Data Types: char
NumDetections
— Maximum number of detection indices to report
1
(default)  positive integer
Maximum number of detection indices to report, specified as a positive integer.
Dependencies
To enable this property, set the OutputFormat
property to 'Detection index'
and the
NumDetectionsSource
property to
'Property'
.
Data Types: double
Usage
Description
[Y,th] = detector(___)
also returns the
detection threshold, th
, applied to detected cells
under test. To enable this syntax, set the
ThresholdOutputPort
property to
true
.
Input Arguments
detector
— Twodimensional CFAR detector
phased.CFARDetector2D
System object
Twodimensional CFAR detector, specified as a phased.CFARDetector2D
System object.
X
— Input image
real MbyN matrix  real
MbyNbyP
array
Input image, specified as a real MbyN matrix or a real MbyNbyP array. M and N represent the rows and columns of a matrix. Each page is an independent 2D signal.
The size of the first dimension of the input matrix can vary to simulate a changing signal length. A size change can occur, for example, in the case of a pulse waveform with variable pulse repetition frequency.
Example: [1,1;2.5,1;0.5,0.1]
Data Types: single
 double
cutidx
— Test cells
2byD matrix of positive
integers
Test cells, specified as a
2byD matrix of positive
integers, where D is the number of test cells. Each
column of cutidx
specifies the row and column
indices of a CUT cell. The same indices apply to all pages in the input
array. You must restrict the locations of CUT cells so that their
training regions lie completely within the input images.
Example: [10,15;11,15;12,15]
Data Types: single
 double
K
— Detection threshold factor
positive scalar
Threshold factor used to calculate the detection threshold, specified as a positive scalar.
Dependencies
To enable this input argument, set the
ThresholdFactor
property of the detector
object to 'Input port'
.
Data Types: single
 double
Output Arguments
Y
— Detection results
LbyP logical matrix
Detection results, whose format depends on the
OutputFormat
property
When
OutputFormat
is'Cut result'
,Y
is a DbyP matrix containing logical detection results for cells under test. D is the length ofcutidx
and P is the number of pages ofX
. The rows ofY
correspond to the rows ofcutidx
. For each row,Y
contains1
in a column if there is a detection in the corresponding cell inX
. Otherwise,Y
contains a0
.When
OutputFormat
is'Detection report'
,Y
is a KbyL matrix containing detections indices. K is the number of dimensions ofX
. L is the number of detections found in the input data. WhenX
is a matrix,Y
contains the row and column indices of each detection inX
in the form[detrow;detcol]
. WhenX
is an array,Y
contains the row, column, and page indices of each detection inX
in the form[detrow;detcol;detpage]
. When theNumDetectionsSource
property is set to'Property'
, L equals the value of theNumDetections
property. If the number of actual detections is less than this value, columns without detections are set toNaN
.
Data Types: single
 double
th
— Computed detection threshold
realvalued matrix
Computed detection threshold for each detected cell, returned as a
realvalued matrix. Th
has the same dimensions as
Y
.
When
OutputFormat
is'CUT result'
,Th
returns the detection threshold whenever an element ofY
is1
andNaN
whenever an element ofY
is0
.When
OutputFormat
is'Detection index'
,th
returns a detection threshold for each corresponding detection inY
. When theNumDetectionsSource
property is set to'Property'
, L equals the value of theNumDetections
property. If the number of actual detections is less than this value, columns without detections are set toNaN
.
Dependencies
To enable this output argument, set the
ThresholdOutputPort
to
true
.
Data Types: single
 double
noise
— Estimated noise power
realvalued matrix
Estimated noise power for each detected cell, returned as a
realvalued matrix. noise
has the same dimensions
as Y
.
When
OutputFormat
is'CUT result'
,noise
returns the noise power whenever an element ofY
is1
andNaN
whenever an element ofY
is0
.When
OutputFormat
is'Detection index'
,noise
returns a noise power for each corresponding detection inY
. When theNumDetectionsSource
property is set to'Property'
, L equals the value of theNumDetections
property. If the number of actual detections is less than this value, columns without detections are set toNaN
.
Dependencies
To enable this output argument, set the
NoisePowerOutputPort
to
true
.
Data Types: single
 double
Object Functions
To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named obj
, use
this syntax:
release(obj)
Examples
Set 2D CFAR Threshold for NoiseOnly Data
This example shows how to set a 2D CFAR threshold based upon a required probability of false alarm (pfa).
Perform cellaveraging CFAR detection on a 41by41 matrix of cells containing Gaussian noise. Estimate the empirical pfa and compare it to the required pfa. To get a good estimate, perform this simulation on 1000 similar matrices. First, set a threshold using the required pfa. In this case, there are no targets and the pfa can be estimated from the number of cells that exceed the threshold. Assume that the data is processed through a squarelaw detector and that no pulse integration is performed. Use a trainingcell band of 3 cells in width and 4 cells in height. Use a guard band of 3 cells in width and 2 cells in height to separate the cells under test (CUT) from the training cells. Specify a required pfa of 5.0e4.
p = 5e4; rs = RandStream.create('mt19937ar','Seed',5); N = 41; ntrials = 1000; detector = phased.CFARDetector2D('TrainingBandSize',[4,3], ... 'ThresholdFactor','Auto','GuardBandSize',[2,3], ... 'ProbabilityFalseAlarm',p,'Method','SOCA','ThresholdOutputPort',true);
Create a 41by41 image containing random complex data. Then, square the data to simulate a squarelaw detector.
x = 2/sqrt(2)*(randn(rs,N,N,ntrials) + 1i*randn(rs,N,N,ntrials)); x2 = abs(x).^2;
Process all the cells in each image. To do this, find the row and column of each CUT cell whose training region falls entirely within each image.
Ngc = detector.GuardBandSize(2); Ngr = detector.GuardBandSize(1); Ntc = detector.TrainingBandSize(2); Ntr = detector.TrainingBandSize(1); cutidx = []; colstart = Ntc + Ngc + 1; colend = N  ( Ntc + Ngc); rowstart = Ntr + Ngr + 1; rowend = N  ( Ntr + Ngr); for m = colstart:colend for n = rowstart:rowend cutidx = [cutidx,[n;m]]; end end ncutcells = size(cutidx,2);
Display the CUT cells.
cutimage = zeros(N,N); for k = 1:ncutcells cutimage(cutidx(1,k),cutidx(2,k)) = 1; end imagesc(cutimage) axis equal
Perform the detection on all CUT cells. Return the detection classification and the threshold used to classify the cell.
[dets,th] = detector(x2,cutidx);
Find and display an image with a false alarm for illustration.
di = []; for k = 1:ntrials d = dets(:,k); if (any(d) > 0) di = [di,k]; end end idx = di(1); detimg = zeros(N,N); for k = 1:ncutcells detimg(cutidx(1,k),cutidx(2,k)) = dets(k,idx); end imagesc(detimg) axis equal
Compute the empirical pfa.
pfa = sum(dets(:))/ntrials/ncutcells
pfa = 4.5898e04
The empirical and specified pfa agree.
Display the average empirical threshold value over all images.
mean(th(:))
ans = 31.7139
Compute the theoretical threshold factor for the required pfa.
threshfactor = npwgnthresh(p,1,'noncoherent');
threshfactor = 10^(threshfactor/10);
disp(threshfactor)
7.6009
The theoretical threshold factor multiplied by the noise variance should agree with the measured threshold.
noisevar = mean(x2(:)); disp(threshfactor*noisevar);
30.4118
The theoretical threshold and empirical threshold agree to within an acceptable difference.
Detect Targets in Background Noise
Perform cellaveraging CFAR detection on a 41by41 matrix of cells containing five closelyspaced targets in Gaussian noise. Perform this detection on a simulation of 1000 images. Use two detectors with different guard band regions. Set the thresholds manually using the Custom
threshold factor. Assume that the data is processed through a square lawdetector and that no pulse integration is performed. Use a training cell band of 2 cells in width and 2 cells in height. For the first detector, use a guard band of 1 cell all around to separate the CUT cells from the training cells. For the second detector, use a guard band of 8 cells all around.
p = 5e4; rs = RandStream.create('mt19937ar','Seed',5); N = 41; ntrials = 1000;
Create 1000 41by41 images of complex random noise with standard deviation of 1.
s = 1; x = s/sqrt(2)*(randn(rs,N,N,ntrials) + 1i*randn(rs,N,N,ntrials));
Set the target cells values to 1.5. Then, square the cell values.
A = 1.5; x(23,20,:) = A; x(23,18,:) = A; x(23,23,:) = A; x(20,22,:) = A; x(21,18,:) = A; x2 = abs(x).^2;
Display the target cells.
xtgt = zeros(N,N); xtgt(23,20,:) = A; xtgt(23,18,:) = A; xtgt(23,23,:) = A; xtgt(20,22,:) = A; xtgt(21,18,:) = A; imagesc(xtgt) axis equal axis tight
Set the CUT cells to be the target cells.
cutidx(1,1) = 23; cutidx(2,1) = 20; cutidx(1,2) = 23; cutidx(2,2) = 18; cutidx(1,3) = 23; cutidx(2,3) = 23; cutidx(1,4) = 20; cutidx(2,4) = 22; cutidx(1,5) = 21; cutidx(2,5) = 18;
Perform the detection on all CUT cells using two CFAR 2D detectors. The first detector has a small guard band region. The training region can include neighboring targets which can affect the computation of the noise power. The second detector has a larger guard band region, which precludes target cells from being used in the noise computation.
Create the two CFAR detectors.
detector1 = phased.CFARDetector2D('TrainingBandSize',[2,2], ... 'GuardBandSize',[1,1],'ThresholdFactor','Custom','Method','CA', ... 'CustomThresholdFactor',2,'ThresholdOutputPort',true); detector2 = phased.CFARDetector2D('TrainingBandSize',[2,2], ... 'GuardBandSize',[8,8],'ThresholdFactor','Custom','Method','CA', ... 'CustomThresholdFactor',2,'ThresholdOutputPort',true);
Return the detection classifications and the thresholds used to classify the cells. Then, compute the probabilities of detection.
[dets1,th1] = detector1(x2,cutidx); ndets = numel(dets1(:)); pd1 = sum(dets1(:))/ndets
pd1 = 0.6416
[dets2,th2] = detector2(x2,cutidx); pd2 = sum(dets2(:))/ndets
pd2 = 0.9396
The detector with the larger guardband region has a higher pfa because the noise is more accurately estimated.
More About
Training Cells
CFAR 2D requires an estimate of the noise power. Noise power is computed from cells that are assumed not to contain any target signal. These cells are the training cells. Training cells form a band around the cellundertest (CUT) cell but may be separated from the CUT cell by a guard band. The detection threshold is computed by multiplying the noise power by the threshold factor.
For GOCA and SOCA averaging, the noise power is derived from the mean value of one of the left or right halves of the training cell region.
Because the number of columns in the training region is odd, the cells in the middle column are assigned equally to either the left or right half.
When using the orderstatistic method, the rank cannot be larger than the number of cells in the training cell region, N_{train}. You can compute N_{train}.
N_{TC} is the number of training band columns.
N_{TR} is the number of training band rows.
N_{GC} is the number of guard band columns.
N_{GR} is the number of guard band rows.
The total number of cells in the combined training region, guard region, and CUT cell is N_{total} = (2N_{TC} + 2N_{GC} + 1)(2N_{TR}+ 2N_{GR} + 1).
The total number of cells in the combined guard region and CUT cell is N_{guard} = (2N_{GC} + 1)(2N_{GR} + 1).
The number of training cells is N_{train} = N_{total} – N_{guard}.
By construction, the number of training cells is always even. Therefore, to implement a median filter, you can choose a rank of N_{train}/2 or N_{train}/2 + 1.
Algorithms
Data Precision
This System object supports single and double precision for input data, properties, and arguments. If
the input data X
is single precision, the output data is single precision.
If the input data X
is double precision, the output data is double
precision. The precision of the output is independent of the precision of the properties and
other arguments.
References
[1] Mott, H. Antennas for Radar and Communications. New York: John Wiley & Sons, 1992.
[2] Richards, M. A. Fundamentals of Radar Signal Processing. New York: McGrawHill, 2005.
[3] Skolnik, M. Introduction to Radar Systems, 3rd Ed. New York: McGrawHill, 2001.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
See System Objects in MATLAB Code Generation (MATLAB Coder).
This System object supports single and double precision for input data, properties, and arguments. If
the input data X
is single precision, the output data is single precision.
If the input data X
is double precision, the output data is double
precision. The precision of the output is independent of the precision of the properties and
other arguments.
Version History
Introduced in R2016b
See Also
Functions
Objects
Blocks
Topics
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)