spapulfilt.m

阵列信号处理的工具箱

function [sigOut, basisMat, doaFreqPosOut] = spapulfilt(sigIn, method, model, modelParam, doaFreqChoice, taperCoeff, interCorrMat, steVecFlag, extraParam, orthBeamFlag, normType, normLevel, sampleDim, interChoice, modCorrmParam)

%SPAPULFILT Space-pulse linear filtering (slow-time STAP).
%
%--------
%Synopsis:
%  sigOut = spapulfilt(sigIn)
%
%  [sigOut, basisMat, {beamPosOut, freqPosOut}] = spapulfilt(sigIn, method, 
%    model, modelParam, {beamChoice, freqChoice}, taperCoeff, interCorrMat, 
%    steVecFlag, extraParam, orthBeamFlag, normType, normLevel,
%    sampleDim, interChoice, modCorrmParam)
%
%  [sigOut,basisMat,{beamPosOut,freqPosOut}] = spapulfilt(sigIn, keywordList)
%
%Description:
%  Space-pulse linear filtering (slow-time STAP).
%
%Output and Input:
%  sigOut (RxRadarSigT): Output radar signal.
%  basisMat (CxMatrixT): After the filtering, the signal consists of the 
%    coefficients in the basis, which is made up of the columns of this
%    output matrix. "basisMat" is the memory of what is done with the signal 
%    during the filtering. "basisMat" is stored in the radar signal after
%    the linear filtering, which is necessary to make further processing
%    in the selected dimension possible.
%  beamPosOut (Vector of DoaT): The directions of the created main beams.
%  freqPosOut (RealVectorT): Frequencies of the created Doppler channels.
%
%  sigIn (RxRadarSigT): Input radar signal.
%
%  keywordList [D](CellArrayT): A cell array with input parameter name
%    (keyword) and value pairs, see the example below. All input parameters
%    of this function following "sigIn" can be used. The use of keywords
%    is to make calls simpler to this function with many possible input
%    parameters.
%
%  method (StringT): Filter method. See help text of function "calcfiltinit"
%    for sections about each method.
%    = 'cbf': Conventional beamforming (nonadaptive).
%    = 'acbf': Adaptive beamforming to a desired antenna pattern. This is 
%      beamforming with adaptive sidelobe cancelation (ASLC).
%    = 'arefsig': Adaptive beamforming to a reference time signal.
%      Not implemented
%    = 'capon': Capon's beamformer.
%    = 'fft': Discrete fourier transform.
%    = 'ifft': Inverse discrete fourier transform.
%    = 'music : MUSIC.
%    = 'minnorm': Minimum norm. Not implemented.
%  antenna [D](AntDefT): Antenna model to use. If this parameters is an
%    empty matrix, the antenna model in the input signal "sigIn" is used
%    instead.
%  waveform [D](WaveformT): Waveform (time properties) model to use. 
%    If this parameters is an empty matrix, the waveform model in the input
%    signal "sigIn" is used instead.
%  beamChoice [D](Vector of DoaT): Directions of one or several main beams 
%    [rad].
%  freqChoice [D](RealVectorT.'): Frequencies of one or several doppler 
%    channels [Hz].
%  taperCoeff [D](CxVectorT): Tapering coefficients to use.
%  interCorrMat [D](CxMatrixT): Interference signal correlation matrix. 
%    This is used to adaptively suppress the interference.
%  steVecFlag [D](BoolT): Specifies whether the steering vector (= 1, default) 
%    or filtering weights (= 0) will be used in the filtering.
%  extraParam [D](): The use and data type depend on filter method. See help 
%    text of function "calcfiltinit" for sections about each method.
%  orthBeamFlag [D](BoolT): 1 = orthogonalize the beams. 0 = Do not do it
%    (default).
%  normType [D](StringT): Type of normalization. Not implemented.
%  normLevel [D](RealScalarT): Normalization level. Not implemented.
%  interChoice [D](CellArray): Specifies which dimension in the 
%    (multidimensional) input signal to use when several snapshots are used
%    by the selected method, e.g. 'capon'. Default is the antenna channel
%    dimension.
%    Not implemented.
%  modCorrmParam [D](CellArray):
%
%--------
%Conventional Beamforming.
%Synopsis:
%
%Output and Input:
%
%Description:
%
%Algoritm:
%
%--------
%Notations:
%  Data type names are shown in parentheses and they start with a capital
%  letter and end with a capital T. Data type definitions can be found in [1]
%  or by "help dbtdata".
%  [D] = This parameter can be omitted and then a default value is used.
%  When the [D]-input parameter is not the last used in the call, it must be
%  given the value [], i.e. an empty matrix.
%  ... = There can be more parameters. They are explained under respective
%  metod or choice.
%
%Examples:
%
%Software Quality:
%  (About what is done to ascertain software quality. What tests are done.)
%  The most parts of this function has been tested  by several runs of the 
%  example file "dbtex26.m". 
%  The use of the input parameters "modelParam" and "extraParam" is not tested.
%
%Known Bugs:
%  *) The default values of input parameters "{beamChoice, freqChoice}" are
%  calculated to a wrong values.
%  *) For Capon, only the non-adapted steering matrix is stored as the basis
%  matrix. See the function "calcfiltinit" for more information.
%  *) When 'fft' is chosen, the field "doaPos" in the ouput signal
%  will not have the right values.
%  *) The methods 'fft' and 'ifft' can not be used.
%  *) There is lacking a special treatment, as with 'fft', of the method
%  'dataeigvec because the number of output channels cannot be chosen by 
%  "doaFreqChoice". The number of output channels must be equal to the
%  number of input channels.
%  *) The space-pulse (slow-time) transformation matrix is not set in the
%  output radar signal. This means that further processing in the dimensions
%  in question is not possible.

%
%References:
%  [1]: Bj鰎klund S.: "DBT, A MATLAB Toolbox for Radar Signal Processing.
%    Reference Guide", FOA-D--9x-00xxx-408--SE, To be published.
%
%See Also:
%  calcfiltinit, dfb, gettap1, spafilt, ranfilt

%   *  DBT, A Matlab Toolbox for Radar Signal Processing  *
% (c) FOA 1994-2000. See the file dbtright.m for copyright notice.
%
%  Start        : 991027 Svante Bj鰎klund (svabj).
%  Latest change: $Date: 2000/10/16 15:22:01 $ $Author: svabj $.
%  $Revision: 1.5 $
% *****************************************************************************

% The comment "NFF" stands for "New filter function" and gives tips of
% necessary changes when using this function as a template for new filter 
% functions (in other dimensions).

only1DDim = 7;	
  % Must not be in the range 1:6 because these are used in RxRadarSigT.
  % "7" is a free "dimension".
sigDim1 = 3;	
sigDim2 = 1;
  % Choosing sigDim1 = 3 and sigDim2 = 1 means that each signal vector
  % will consist of  all ( = the first dimension, = slow-time or pulses) 
  % column vectors of the third dimension, i.e. space or antenna channels,
  % stacked on top of eachother. For example =
  % [allAntennaChannelsFromPulse1;  allAntennaChannelsFromPulse2; ...] .


% ----------------------------------------------------------------------- %
% Handle input parameters
% ----------------------------------------------------------------------- %

arginNo=1;
if (nargin < arginNo)
  error('DBT-Error: To few input parameters.')
end
arginNo = arginNo +1;

% ****************** Add missing input parameters ******************

arginNo=2;
if (nargin < arginNo)
  method = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  model = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  modelParam = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  doaFreqChoice = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  taperCoeff = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  interCorrMat = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  steVecFlag = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  extraParam = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  orthBeamFlag = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  normType = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  normLevel = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  sampleDim = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  interChoice = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  modCorrmParam = [];
end
arginNo = arginNo +1;


% *************** Evalute the list of keywords  ***************
% If the input parameter "method" is a cell array, it is interpreted as a
% list of input parameter name (keyword) and value pairs.
% The values of these keywords are assigned to the local variables with
% the same name as the keywords. The use of keywords is to make calls to
% this function simpler.