pulfilt.m

阵列信号处理的工具箱

function [sigOut, basisMat, freqPosOut] = pulfilt(sigIn, method, model, modelParam, freqChoice, taperCoeff, interCorrMat, steVecFlag, extraParam, orthBeamFlag, normType, normLevel, sampleDim, interChoice, modCorrmParam)

%PULFILT Pulse linear filtering (i.e. Doppler filtering).
%
%--------
%Synopsis:
%  sigOut = pulfilt(sigIn)
%
%  [sigOut, basisMat, freqPosOut] = pulfilt(sigIn, method, 
%    {antenna, waveform}, [], freqChoice, taperCoeff, interCorrMat,
%    steVecFlag, extraParam, orthBeamFlag, normType)
%
%  [sigOut, basisMat, freqPosOut] = pulfilt(sigIn, keywordList)
%
%Description:
%  Pulse linear filtering (Doppler/slow-time filtering).
%
%  This function works like beamforming functions in the way that Doppler 
%  steering vectors are created which then are correlated with the input
%  signal. The Doppler frequencies of the steering vectors are specified
%  by the input parameter "freqChoice". It is not necessary that the
%  frequencies span all possible frequencies in the input signal.
%  This function calls the general functions "calcfiltinit" and "calcfiltproc" 
%  for the actual processing. This means that the methods implemented in
%  these functions can be used See also below about the input parameter 
%  "method".
%
%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.
%  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. More methods are described in the help
%    text of the function "calcfiltinit".
%    = '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.
%  freqChoice [D](RealVectorT.'): Frequencies of the doppler channels.
%  taperCoeff [D](CxVectorT): Tapering coefficients to use. The number of 
%    coefficient must be equal to the number of pulses of the radar signal 
%    "sigIn".
%  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 "dbtex25.m". 
%  The use of some input parameters is not tested.
%
%Known Bugs:
%  *) The default value of input parameter "freqChoice" is calculated to a
%  wrong value.
%  *) For Capon, only the non-adapted steering matrix is stored as the basis
%  matrix. See the function "calcfiltinit" for more information.
%  *) There is lacking a special treatment, as with 'fft', of the method
%  'dataeigvec because the number of output channels cannot be chosen by 
%  "freqChoice".  The number of output channels must be equal to the
%  number of input channels.
%
%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, dfb2, gettap1, spafilt, 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/11/17 12:45:12 $ $Author: svabj $.
%  $Revision: 1.12 $
% *****************************************************************************

% The comment "NFF" stands for "New filter function" and gives tips to
% 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 = 1;	
  % Filtering in this dimension. 1 = filtering in pulse dimension.
sigDim2 = only1DDim;
  % = only1DDim means 1D filtering using only "sigDim1" implying 1D filtering.

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

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

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

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)
  freqChoice = [];
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.

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%if
arginNo = arginNo +1;


% ****************** Get signals sizes. ******************
sigSizeIn = sigsize(sigIn);
sigSizeIn(7) = 1;
  % To make possible to use the same code for 1D- and 2D-filtering.
  % When 1D-filtering assign sigDim2 = 7. When 2D-filtering assign
  % sampleDim = 7. Then we only want to filt one sample at a time
  % because of memory usage and because the program cannot handle
  % several samples when 2D-filtering.
  % The constant "only1DDim" is equal to 7 and should be used when testing
  % the value of sigDim1, sigDim2 and sampleDim.

noTrials  = sigSizeIn(6);
noCpis    = sigSizeIn(5);
noExtras  = sigSizeIn(4);
noBeams   = sigSizeIn(3);
noRanges  = sigSizeIn(2);
noPulses  = sigSizeIn(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};
if (length(waveform.wavelength) > 1)
  error('DBT-Error: Can only handle one wavelength.')
end%if
%lambda = waveform.wavelength;
  % NFF
PRI = waveform.noRangeBins * waveform.sampleTime;
PRF = 1/PRI;
  % NFF


if isempty(modelParam)
  modelParam = {[] []};
    % NFF: Change to suitable default values. See function "sparanfilt"
    % for tips.
end%if

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

if isempty(freqChoice)
  freqChoice = genfreqaxis(0,PRF,noPulses).';
    % NFF: Change to a suitable default value.
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
if isempty(normLevel)
  normLevel = [];
end%if
if isempty(sampleDim)
  sampleDim = 3;
    % 3 = The samples or snapshots are taken from the spatial dimension,
    % i.e. from the antenna channels.
    % NFF: Change to a suitable dimension.
end%if

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

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


% ****************** 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', 'EmptyT')
  % NFF: Check any special input parameters.



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


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

%In: method, extraParam, sigSizeIn, sigDim1, sigDim2, PRF, waveform, freqChoice, interCorrMat 
%Out: steMatIn, freqPosOut, noFreqsOut, interCorrMat

if (strcmp(method,'fft') | strcmp(method,'ifft'))
  % Special case when the number of frequencies are not determined by 
  % "freqChoice".
  if isempty(extraParam)
    extraParam = sigSizeIn(sigDim1) * sigSizeIn(sigDim2);
      sigSizeIn(sigDim2);
  end%if
  extraParam = extraParam;
  noFreqsOut = extraParam;
  steMatIn = [];
  interCorrMat = [];
  freqPosOut = genfreqaxis(0,PRF,noFreqsOut).';
    % NFF: 
else
  % The case when the number of frequencies are  determined by 
  % the size of "freqChoice".
  %steMatIn = spastemat(antenna, freqChoice, lambda, focusDist, subArrPoint);
  steMatIn = pulstemat(waveform, freqChoice);
    % NFF: Call the right function with right parameters.
  noFreqsOut = size(freqChoice,2);
    % NFF: Choose the size of the right dimension.
  freqPosOut = freqChoice;
end%if


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

sigOut = sigIn;		% Copy all fields to output signal.
sigSizeOut = [noFreqsOut,noRanges, noBeams, noExtras, noCpis,noTrials];
  % NFF: Move "noFreqsOut" to the right subscript.


% ----------------------------------------------------------------------- %
% Do the filtering.
% ----------------------------------------------------------------------- %

calcInitParams = {taperCoeff, interCorrMat, orthBeamFlag, extraParam, ...
  normType, normLevel};
  % This parameter contains all input parameters 
  % after "steMat" to function "calcfiltinit". See the help text of the 
  % function "calcfiltinit" for more information. Most of these parameters
  % are also used by the function "calcfiltproc".


[signalsOut, basisMat, freqPos] = calcfiltsig(sigIn.signals, 'pulfilt',...
  [sigDim1, sigDim2], sampleDim, sigSizeIn, sigSizeOut, steMatIn,...
  method, calcInitParams, interChoice, modCorrmParam);
  % Filter the whole radar signal. A signal vector sample or snapshot
  % consists of the dimensions "sigDim1". All samples from
  % the dimension "sampleDim" are filtered simultaneously.


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

sigOut.signals = signalsOut;
sigOut = setpultrans(sigOut, basisMat);
  % NFF: Call the right function.


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

sigOut.freqPos = freqPosOut.';
  % NFF: Assign the right field in the output function.

%endfunction pulfilt