phased.CFARDetector2D

Two-dimensional CFAR detector

Description

phased.CFARDetector2D System object™ implements a constant false-alarm rate detector (CFAR) for selected elements (called cells) of two-dimensional image data. A detection is declared when an image cell value exceeds a threshold. To maintain a constant false alarm-rate, the threshold is set to a multiple of the image noise power. The detector estimates noise power for a cell-under-test (CUT) from surrounding cells using one of three cell averaging methods, or an order statistics method. The cell-averaging methods are cell averaging (CA), greatest-of cell averaging (GOCA), or smallest-of 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.

detector = phased.CFARDetector2D creates a 2-D CFAR detector System object, detector.

To run the 2-D 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

Syntax

detector = phased.CFARDetector2D

detector = phased.CFARDetector2D(Name,Value)

Description

detector = phased.CFARDetector2D creates a 2-D CFAR detector object, detector.

example

detector = phased.CFARDetector2D(Name,Value) creates a 2-D CFAR System object, detector, with each specified property Name set to the specified Value. You can specify additional name-value pair arguments in any order as (Name1,Value1,...,NameN,ValueN).

example

Properties

expand all

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` — Two-dimensional CFAR averaging method
`'CA'` (default) | `'GOCA'` | `'SOCA'` | `'OS'`

Two-dimensional 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` — Cell-averaging algorithm	Computes the sample mean of all training cells surrounding the CUT cell.
`GOCA` — Greatest-of cell-averaging algorithm	Splits the 2-D 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` — Smallest-of cell-averaging algorithm	Splits the 2-D 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 `Rank` parameter.

Example: 'OS'

Data Types: char

`GuardBandSize` — Widths of guard band
`[1 1]` (default) | nonnegative integer | 2-element 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 guard-cell-wide 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 | 2-element 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 1-by-2 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 training-cell-wide 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 2-D 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 or 0) 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 the phased.RangeEstimator and phased.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

Syntax

Y = detector(X,cutidx)

Y = detector(X,cutidx,K)

[Y,th] = detector(___)

[Y,noise] = detector(___)

Description

Y = detector(X,cutidx) performs 2-D CFAR detection on input image data, X, for the image cells under test (CUT) specified by cutidx. Y contains the detection results for the CUT cells.

example

Y = detector(X,cutidx,K) also specifies a threshold factor, K, for setting the detection threshold. This syntax applies when the ThresholdFactor property of the detector is set to 'Input port'.

[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.

example

[Y,noise] = detector(___) also returns the estimated noise power, noise, applied to detected cells under test. To enable this syntax, set the NoisePowerOutputPort property to true.

example

Input Arguments

expand all

`detector` — Two-dimensional CFAR detector
`phased.CFARDetector2D` System object

Two-dimensional CFAR detector, specified as a phased.CFARDetector2D System object.

`X` — Input image
real M-by-N matrix | real M-by-N-by-P array

Input image, specified as a real M-by-N matrix or a real M-by-N-by-P array. M and N represent the rows and columns of a matrix. Each page is an independent 2-D 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
2-by-D matrix of positive integers

Test cells, specified as a 2-by-D 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

expand all

`Y` — Detection results
L-by-P logical matrix

Detection results, whose format depends on the OutputFormat property

When OutputFormat is 'Cut result', Y is a D-by-P matrix containing logical detection results for cells under test. D is the length of cutidx and P is the number of pages of X. The rows of Y correspond to the rows of cutidx. For each row, Y contains 1 in a column if there is a detection in the corresponding cell in X. Otherwise, Y contains a 0.
When OutputFormat is 'Detection report', Y is a K-by-L matrix containing detections indices. K is the number of dimensions of X. L is the number of detections found in the input data. When X is a matrix, Y contains the row and column indices of each detection in X in the form [detrow;detcol]. When X is an array, Y contains the row, column, and page indices of each detection in X in the form [detrow;detcol;detpage]. When the NumDetectionsSource property is set to 'Property', L equals the value of the NumDetections property. If the number of actual detections is less than this value, columns without detections are set to NaN.

Data Types: single | double

`th` — Computed detection threshold
real-valued matrix

Computed detection threshold for each detected cell, returned as a real-valued matrix. Th has the same dimensions as Y.

When OutputFormat is 'CUT result', Th returns the detection threshold whenever an element of Y is 1 and NaN whenever an element of Y is 0.
When OutputFormat is 'Detection index', th returns a detection threshold for each corresponding detection in Y. When the NumDetectionsSource property is set to 'Property', L equals the value of the NumDetections property. If the number of actual detections is less than this value, columns without detections are set to NaN.

Dependencies

To enable this output argument, set the ThresholdOutputPort to true.

Data Types: single | double

`noise` — Estimated noise power
real-valued matrix

Estimated noise power for each detected cell, returned as a real-valued matrix. noise has the same dimensions as Y.

When OutputFormat is 'CUT result', noise returns the noise power whenever an element of Y is 1 and NaN whenever an element of Y is 0.
When OutputFormat is 'Detection index', noise returns a noise power for each corresponding detection in Y. When the NumDetectionsSource property is set to 'Property', L equals the value of the NumDetections property. If the number of actual detections is less than this value, columns without detections are set to NaN.

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)

expand all

Common to All System Objects

`step`	Run System object algorithm
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object

Examples

collapse all

Set 2-D CFAR Threshold for Noise-Only Data

Open Live Script

This example shows how to set a 2-D CFAR threshold based upon a required probability of false alarm (pfa).

Perform cell-averaging CFAR detection on a 41-by-41 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 square-law detector and that no pulse integration is performed. Use a training-cell 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.0e-4.

p = 5e-4;
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 41-by-41 image containing random complex data. Then, square the data to simulate a square-law 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

Figure contains an axes object. The axes object contains an object of type image.

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

Figure contains an axes object. The axes object contains an object of type image.

Compute the empirical pfa.

pfa = sum(dets(:))/ntrials/ncutcells

pfa = 
4.5898e-04

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

Open Live Script

Perform cell-averaging CFAR detection on a 41-by-41 matrix of cells containing five closely-spaced 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 law-detector 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 = 5e-4;
rs = RandStream.create('mt19937ar','Seed',5);
N = 41;
ntrials = 1000;

Create 1000 41-by-41 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

Figure contains an axes object. The axes object contains an object of type image.

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 2-D 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 guard-band region has a higher pfa because the noise is more accurately estimated.

More About

expand all

Training Cells

CFAR 2-D 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 cell-under-test (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 order-statistic 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

expand all

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: McGraw-Hill, 2005.

[3] Skolnik, M. Introduction to Radar Systems, 3rd Ed. New York: McGraw-Hill, 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).

Version History

Introduced in R2016b

phased.CFARDetector2D

Description

Creation

Syntax

Description

Properties

Method — Two-dimensional CFAR averaging method 'CA' (default) | 'GOCA' | 'SOCA' | 'OS'

GuardBandSize — Widths of guard band [1 1] (default) | nonnegative integer | 2-element vector of nonnegative integers

TrainingBandSize — Widths of training band [1 1] (default) | positive integer | 2-element vector of positive integers

Rank — Rank of order statistic 1 (default) | positive integer

Dependencies

ThresholdFactor — Threshold factor method 'Auto' (default) | 'Input port' | 'Custom'

ProbabilityFalseAlarm — Required probability of false alarm 0.1 (default) | positive scalar between 0 and 1

Dependencies

CustomThresholdFactor — Custom threshold factor 1 (default) | positive scalar

Dependencies

OutputFormat — Format of detection results 'CUT result' (default) | 'Detection index'

ThresholdOutputPort — Enable detection threshold output false (default) | true

NoisePowerOutputPort — Enable noise power output false (default) | true

NumDetectionsSource — Source of the number of detections 'Auto' (default) | 'Property'

Dependencies

NumDetections — Maximum number of detection indices to report 1 (default) | positive integer

Dependencies

Usage

Syntax

Description

Input Arguments

detector — Two-dimensional CFAR detector phased.CFARDetector2D System object

X — Input image real M-by-N matrix | real M-by-N-by-P array

cutidx — Test cells 2-by-D matrix of positive integers

K — Detection threshold factor positive scalar

Dependencies

Output Arguments

Y — Detection results L-by-P logical matrix

th — Computed detection threshold real-valued matrix

Dependencies

noise — Estimated noise power real-valued matrix

Dependencies

Object Functions

Common to All System Objects

Examples

Set 2-D CFAR Threshold for Noise-Only Data

Detect Targets in Background Noise

More About

Training Cells

Algorithms

Data Precision

References

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

See Also

Functions

Objects

Blocks

Topics

`Method` — Two-dimensional CFAR averaging method
`'CA'` (default) | `'GOCA'` | `'SOCA'` | `'OS'`

`GuardBandSize` — Widths of guard band
`[1 1]` (default) | nonnegative integer | 2-element vector of nonnegative integers

`TrainingBandSize` — Widths of training band
`[1 1]` (default) | positive integer | 2-element vector of positive integers

`Rank` — Rank of order statistic
1 (default) | positive integer

`ThresholdFactor` — Threshold factor method
`'Auto'` (default) | `'Input port'` | `'Custom'`

`ProbabilityFalseAlarm` — Required probability of false alarm
`0.1` (default) | positive scalar between 0 and 1

`CustomThresholdFactor` — Custom threshold factor
`1` (default) | positive scalar

`OutputFormat` — Format of detection results
`'CUT result'` (default) | `'Detection index'`

`ThresholdOutputPort` — Enable detection threshold output
`false` (default) | `true`

`NoisePowerOutputPort` — Enable noise power output
`false` (default) | `true`

`NumDetectionsSource` — Source of the number of detections
`'Auto'` (default) | `'Property'`

`NumDetections` — Maximum number of detection indices to report
`1` (default) | positive integer

`detector` — Two-dimensional CFAR detector
`phased.CFARDetector2D` System object

`X` — Input image
real M-by-N matrix | real M-by-N-by-P array

`cutidx` — Test cells
2-by-D matrix of positive integers

`K` — Detection threshold factor
positive scalar

`Y` — Detection results
L-by-P logical matrix

`th` — Computed detection threshold
real-valued matrix

`noise` — Estimated noise power
real-valued matrix

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.