spafilt.m

阵列信号处理的工具箱

function [sigOut, basisMat, beamPosOut] = spafilt(sigIn, method, model, modelParam, beamChoice, taperCoeff, interCorrMat, steVecFlag, extraParam, orthBeamFlag, normType, normLevel, snapshotDim)

%SPAFILT Spatial linear filtering (i.e. beamforming).
%
%--------
%Synopsis:
%  sigOut = spafilt(sigIn)
%
%  [sigOut, basisMat, beamPosOut] = spafilt(sigIn, method,
%    {antenna, waveform}, {subArrPoint, focusDist}, beamChoice,
%    taperCoeff, interCorrMat, steVecFlag, extraParam, orthBeamFlag, normType)
%
%  [sigOut, basisMat, beamPosOut] = spafilt(sigIn, keywordList)
%
%Description:
%  Spatial linear filtering. This means conventional beamforming with 
%  beamforming weights according to several basic methods. Tapering 
%  (uniform, Taylor, Chebychev and user defined), adaptive sidelobe
%  cancellation and beam orthogonalization are possible.
%
%  This function calls the functions "calcfiltinit" and "calcfiltproc".
%  See the function "calcfiltinit" for more information about the different 
%  beamforming methods.
%
%Output and Input:
%  sigOut (RxRadarSigT): Output radar signal.
%  basisMat ():
%  beamPosOut (Vector of DoaT): The directions of the created main beams.
%
%  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): Beamforming method. See help text of function 
%    "calcfiltinit" for sections about each method.
%    = 'cbf': Conventional beamforming.
%    = '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.
%  subArrPoint [D](DoaT): Pointing direction of subarrays. (Default = 0).
%  focusDist [D](RealVectorT): Focusing distance of the antenna [m].
%  beamChoice [D](Vector of DoaT): Directions of one or several main beams.
%  taperCoeff [D](CxVectorT): Tapering coefficients to use. They can be 
%    delivered by the function "gettap1".
%  interCorrMat [D](CxMatrixT or RxCorrMatT): Interference antenna signal 
%    correlation matrix. 
%    This is used to adaptively suppress the interference.
%  steVecFlag [D](BoolT): Specifies whether the steering vector (= 1, default) 
%    or beamforming weights (= 0) will be used in the beamforming.
%  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.
%  snapshotDim [D](IntScalarT): 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 pulse dimension.
%    Not implemented.
%
%--------
%Conventional Beamforming.
%Synopsis:
%
%Output and Input:
%
%Description:
%  This function calls the functions "calcfiltinit" and "calcfiltproc".
%  See the function "calcfiltinit" for more information about this 
%  beamforming methods.
%
%Algoritm:
%
%--------
%Adaptive Beamforming.
%Synopsis:
%
%Output and Input:
%
%Description:
%  This function calls the functions "calcfiltinit" and "calcfiltproc".
%  See the function "calcfiltinit" for more information about this 
%  beamforming methods.
%
%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.)
%  This function is not tested yet.
%
%Known Bugs:
%  *) When 'fft' is chosen, the field "doaPos" in the ouput signal
%  will not have the right values.
%  *) This function do not use the function "calcfiltsig".
%
%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, beamform, gettap1, pulfilt, ranfilt

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

 
% ----------------------------------------------------------------------- %
% 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)
  beamChoice = [];
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;


% *************** 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.

if (iscell(method))
  keywordList = method;
  lenExtra = length(keywordList);
  if (mod(lenExtra,2) ~= 0), error('DBT-Error: Keyword value missing.'),end%if
  for n = 1:2:length(keywordList)
    eval([keywordList{n} '= keywordList{n+1};' ]);
  end%for n
end
arginNo = arginNo +1;


% ****************** Default values ******************

if isempty(method)
  method = 'cbf';
end%if
if isempty(model)
  model = {sigIn.antenna, sigIn.waveform};
end%if

antenna = model{1};
waveform = model{2};
noChannels = antenna.noElem;

if isempty(modelParam)
  modelParam = {[] []};
end%if

subArrPoint = modelParam{1};
focusDist = modelParam{2};
if isempty(subArrPoint)
  subArrPoint = [0 0].';
end%if
if isempty(focusDist)
  focusDist = Inf;
end%if

if isempty(beamChoice)
  beamChoice = d2r(-80:2:80);
  beamChoice = [beamChoice; zeros(1,length(beamChoice))];
end%if
if isempty(taperCoeff)
  taperCoeff = [];
end%if
if isempty(interCorrMat)
  interCorrMat = [];
end%if
if isempty(steVecFlag)
  steVecFlag = 1;
end%if
if isempty(extraParam)
  extraParam = [];
end%if
if isempty(orthBeamFlag)
  orthBeamFlag = 0;
end%if
if isempty(normType)
  normType = [];
end%if

% ************* Pick out some more fields from input parameters. *************

%lambda = waveform.wavelength(1);
if (length(waveform.wavelength) > 1)
  error('DBT-Error: Can only handle one wavelength.')
end%if
lambda = waveform.wavelength;


% ****************** Error check input parameters ******************

chkdtype(sigIn, 'RxRadarSigT')
chkdtype(method, 'StringT')
chkdtype(model, 'CellArrayT')
%chkdtype(modelParam, 'CellArrayT')
chkdtype(subArrPoint, 'Vector of DoaT')
chkdtype(taperCoeff, 'CxVectorT')
chkdtype(interCorrMat, 'CxMatrixT', 'RxCorrMatT', 'EmptyT')


% ----------------------------------------------------------------------- %
% Preparations before calculations.
% ----------------------------------------------------------------------- %


% ****************** Get signals sizes. ******************
sigSizeIn = sigsize(sigIn);

noTrials  = sigSizeIn(6);
noCpis    = sigSizeIn(5);
noExtras  = sigSizeIn(4);
noBeamsIn = sigSizeIn(3);
noRanges  = sigSizeIn(2);
noPulses  = sigSizeIn(1);


% *************** Get interference correlation matrix. ***************

if (~chkdtyph(interCorrMat,'RxCorrMatT'))
  interCorrMat = squeeze(interCorrMat.corrMat(:,:,1,1,1,1));
end%if


% *************** Adjustments for different methods. ***************

if (strcmp(method,'fft') | strcmp(method,'ifft'))
  % Special case when the number of beams are not determined by "beamChoice".
  if isempty(extraParam)
    extraParam = noBeamsIn;
  end%if
  extraParam = extraParam;
  noBeamsOut = extraParam;
  steMatIn = [];
  interCorrMat = [];
else
  steMatIn = spastemat(antenna, beamChoice, lambda, focusDist, subArrPoint);
  noBeamsOut = size(beamChoice,2);
end%if


% ****************** Calculate beamforming weights. ******************


sizeSigIn = [noBeamsIn, noPulses];
[methodCalc, weightMatrix, basisMat, freqPos] = calcfiltinit(method, ...
  sizeSigIn, steMatIn, taperCoeff, interCorrMat, orthBeamFlag, ...
  extraParam, normType);
%basisMat = weightMatrix;


% ****************** Create output variable. ******************

sigOut = sigIn;		% Copy all fields to output signal.
sigOut.signals = zeros(noPulses,noRanges, noBeamsOut, noExtras, noCpis, ...
  noTrials);


% ----------------------------------------------------------------------- %
% Loops for several range gates and trials.
% ----------------------------------------------------------------------- %

% ****************** Loops. ******************

for trialLoop = 1:noTrials
for cpiLoop = 1:noCpis
  for extraLoop = 1:noExtras
  for rangeLoop = 1:noRanges
    %sigMatIn = sigIn.signals(:,rangeLoop,:,extraLoop,cpiLoop, trialLoop);
    sigMatIn = getm3(sigIn.signals, 3, [], ':',rangeLoop,':', ...
      extraLoop, cpiLoop, trialLoop);

    sigMatOut = calcfiltproc(sigMatIn, methodCalc, weightMatrix, ...
      taperCoeff, orthBeamFlag, extraParam, normType);

    sigOut.signals(':',rangeLoop,':',extraLoop,cpiLoop,trialLoop) ...
      = sigMatOut.';
    infoStr = sprintf('spafilt: cpi = %d(%d), range = %d(%d) \r',...
      cpiLoop, noCpis, rangeLoop, noRanges);
    dbtinfo(infoStr,1);
  end%for rangeLoop
  end%for extraLoop
end%for cpiLoop
dbtinfo('');	%New line.
end%for trialLoop


% ----------------------------------------------------------------------- %
% Output variables.
% ----------------------------------------------------------------------- %

sigOut = setspatrans(sigOut, basisMat);

% For Capon, only the non-adapted steering matrix is stored. See the function
% "calcfiltinit".


beamPosOut = beamChoice;
sigOut.doaPos = beamPosOut;