calcfiltsig.m

阵列信号处理的工具箱

function [signalsOut, basisMat, freqPos] = calcfiltsig(signalsIn, funcName, sigDim, sampleDim, sigSizeIn, sigSizeOut, steMatIn, method, calcInitParams, interChoice, modCorrmParam)

%CALCFILTSIG Part of the linear filtering of a received signal in functions such as "pulfilt".
%
%--------
%Synopsis:
%  [signalsOut, basisMat, freqPos] = calcfiltsig(signalsIn, funcName,
%    sigDim, sampleDim, sigSizeIn, sigSizeOut, steMatIn, method, 
%    calcInitParams,interChoice, modCorrmParam)
%
%Description:
%  Part of the linear filtering in functions such as "pulfilt".
%
%  Not to be used by the end user but only for the extension programmer
%  in filtering function such as "pulfilt".
%
%  This function uses the function "calcfiltinit" and "calcfiltproc" for
%  the filter weight calculation and the filtering respectively.
%
%  This function was designed to be used in the toolbox DBT but probably
%  it is possible to use it outside DBT also.
%
%Input:
%  signalsIn (CxMultiMatrix): The input signal. In DBT this is the field 
%    "signals" of the data type RxRadarSigT.
%  funcName (StringT): Name of the calling function. The name is used in 
%    information displays on the screen.
%  sigDim (IntVectorT.'): A row vector describing which dimensions of the
%    input parameter "signalsIn" to use as the signal vector.
%  sampleDim (IntScalarT.'): A scalar describing which dimension of the
%    input parameter "signalsIn" to use as samples or snapshots of the
%    signal vector.
%  sigSizeIn (IntVectorT.'): A row vector containing the sizes of the
%    input parameter "signalsIn" with the addition of an extra "1" at the
%    end, e.g.  sigSizeIn = [size(signalsIn), 1]. In DBT, this last "1" is 
%    always in the 7th position (7th dimension size) and any extra necessary 
%    "1"s before the 7th is added also. 
%  sigSizeOut (IntVectorT.'): A row vector containing the sizes of the
%    desired output parameter "signalsOut". An "1" is added at the end 
%    in the same way as with "sigSizeIn"
%  steMatIn (CxMatrixT): Contains the steering matrix for methods using
%    this matrix. Otherwise "steMatIn" can be an empty matrix. See the
%    function "spapulstemat" for an example of a steering matrix for 
%    2D-filtering.
%  method (StringT): The filtering method to use. See the help text of
%    the function "calcfiltinit" for more information. 
%  calcInitParams (CellArrayT): 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".
%  interChoice (???): Specification of which signal vector samples or snapshots
%    in the input parameter "signalsIn" to use for correlation matrix
%    estimation for methods requiring such an matrix. Not implemented.
%  modCorrmParam (CellArrayT): Contains input parameters for the 
%    modification of the correlation matrix which is specified by the
%   input parameter "interChoice" above. See the help text of function 
%   "getcorrmkernel" for more information. Not implemented.
%
%Output
%  signalsOut (CxMultiMatrix): The output signal. In DBT this is the field 
%    "signals" of the data type RxRadarSigT.
%  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.
%  freqPos (): Not implemented.
%
%--------
%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:
%  See the functions "pulfilt" and "spapulfilt" for examples.
%
%Software Quality:
%  (About what is done to ascertain software quality. What tests are done.)
%  This function has been tested for 1D-filtering on simulated radar
%  signals by the example file  "dbtex25" and for 2D-filtering by the
%  example file "dbtex26.m". 
%
%Known Bugs:
%
%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:
%  pulfilt, spapulfilt, calfiltinit, calcfiltproc

%   *  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:20:03 $ $Author: svabj $.
%  $Revision: 1.6 $
% *****************************************************************************


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


%sigSizeIn = sigsize(sigIn);
%sigSizeIn(7) = 1;
  % If the "%" character on the two preceeding lines are removed, it is
  % possible to omit the input parameter "sigSizeIn" .

only1DDim = 7;
  % Must not be in the range 1:6 because these are used in RxRadarSigT.
  % "7" is a free "dimension".

sigDim1 = sigDim(1);
sigDim2 = sigDim(2);
signalsOut = zeros(sigSizeOut);
calcProcParams = [calcInitParams(1), calcInitParams(3:length(calcInitParams))];
  % Parameters to the function "calcfiltproc".
  % Contains the same input parameters as to function "calcfiltinit" except
  % for the second ("interCorrMat"), which is only used in the filter 
  % coefficient calculation in "calcfiltinit".
 
% ****************** Calculate filtering weights. ******************

sizeSigMatIn = [sigSizeIn(sigDim1)*sigSizeIn(sigDim2), sigSizeIn(sampleDim)];

[methodCalc, weightMatrix, basisMat, freqPos] = ...
  calcfiltinit(method, sizeSigMatIn, steMatIn, calcInitParams{:});


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

% ****************** Prepare indices and loop limits ******************

if ((sampleDim == sigDim1) | (sampleDim == sigDim2))
  error('DBT-Error: Sample dimension must not be the same as signal dimension.')
end%if

if ((sigDim1 == 1) | (sigDim2 == 1) | (sampleDim == 1))
  % If any of the variables "sigDim1", "sigDim2" or "sampleDim" is equal
  % to one, we will not loop over this dimension (the pulse dimesnion)
  % but use all elements of the dimension simultaneously in the filtering
  % in function "calcfiltproc".
  pulIx = ':';
  noPulLoop = 1;
else
  noPulLoop = sigSizeIn(1);
end%if
if ((sigDim1 == 2) | (sigDim2 == 2) | (sampleDim == 2))
  ranIx = ':';
  noRanLoop = 1;
else
  noRanLoop = sigSizeIn(2);
end%if
if ((sigDim1 == 3) | (sigDim2 == 3) | (sampleDim == 3))
  spaIx = ':';
  noSpaLoop = 1;
else
  noSpaLoop = sigSizeIn(3);
end%if
if ((sigDim1 == 4) | (sigDim2 == 4) | (sampleDim == 4))
  extraIx = ':';
  noExtraLoop = 1;
else
  noExtraLoop = sigSizeIn(4);
end%if
if ((sigDim1 == 5) | (sigDim2 == 5) | (sampleDim == 5))
  cpiIx = ':';
  noCpiLoop = 1;
else
  noCpiLoop = sigSizeIn(5);
end%if
if ((sigDim1 == 6) | (sigDim2 == 6) | (sampleDim == 6))
  trialIx = ':';
  noTrialLoop = 1;
else
  noTrialLoop = sigSizeIn(6);
end%if


% ****************** Prepare 2D filtering ******************

if (sigDim2 ~= only1DDim)	% If 2D filtering.
  
  % ****************** Display some size information ******************

  sizeOneElem = 8 ; % Size of one element in a MATLAB matrix [bytes].
  sizeSigMatOutElem = sigSizeOut(sigDim1)*sigSizeOut(sigDim2)*...
    sigSizeOut(sampleDim);
  sizeSigMatOutBytes = sizeSigMatOutElem * sizeOneElem;
  infoStr = sprintf(['Size of output filtered vectors = %d elements ',...
    '= %d bytes.'],sizeSigMatOutElem, sizeSigMatOutBytes);
  dbtinfo(infoStr)

  sizeWeightMat = size(steMatIn,1)*size(steMatIn,2); 
  sizeWeightMatBytes = sizeWeightMat * sizeOneElem;
  infoStr = sprintf(['Size of weight matrix = %d elements ',...
    '= %d bytes.'],sizeWeightMat, sizeWeightMatBytes);
  dbtinfo(infoStr)

  % ****************** Prepare permutations and reshaping ******************

  % We want to create a vector with the dimension numbers not contained in 
  % the variables "sigDim1", "sigDim2" or "sampleDim".
  restDims = [];
  for n =1:6
    if ((n ~= sigDim1) & (n ~= sigDim2) & (n ~= sampleDim))
      restDims = [restDims, n];
    end%for n
  end%for
  
  permuteInOrder = [sigDim1, sigDim2, sampleDim, restDims];
  reshapeInSizes = [sigSizeIn(sigDim1)*sigSizeIn(sigDim2),...
    sigSizeIn(sampleDim)];
end%if



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


for trialLoop = 1:noTrialLoop
for cpiLoop   = 1:noCpiLoop
for extraLoop = 1:noExtraLoop
  for spaLoop = 1:noSpaLoop
  for ranLoop = 1:noRanLoop
  for pulLoop = 1:noPulLoop

    % ****************** Prepare index ******************

    if ((sigDim1 ~= 1) & (sigDim2 ~= 1) & (sampleDim ~= 1))
      % When looping over this dimension assign the loop counter "pulLoop" 
      % to the index "pulIx" for indexing in the input parameter
      % "signalsIn". On the contrary, when using all elements of this
      % dimension simultaneously in the filtering (and not looping),
      % we do nothing here implying that "pulIx" will retain its value ':'.
      pulIx = pulLoop;
    end%if
    if ((sigDim1 ~= 2) & (sigDim2 ~= 2) & (sampleDim ~= 2))
      ranIx = ranLoop;
    end%if
    if ((sigDim1 ~= 3) & (sigDim2 ~= 3) & (sampleDim ~= 3))
      spaIx = spaLoop;
    end%if
    if ((sigDim1 ~= 4) & (sigDim2 ~= 4) & (sampleDim ~= 4))
      extraIx = extraLoop;
    end%if
    if ((sigDim1 ~= 5) & (sigDim2 ~= 5) & (sampleDim ~= 5))
      cpiIx = cpiLoop;
    end%if
    if ((sigDim1 ~= 6) & (sigDim2 ~= 6) & (sampleDim ~= 6))
      trialIx = trialLoop;
    end%if

    % ****************** Get a correlation matrix ******************
   

    if (~isempty(interChoice))
      % Gets a correlation matrix and maybe modifies it. The matrix is
      % used by filtering methods requiring it.
      interCorrm = getcorrmkernel(signalsIn,[sigDim1 sigDim2],...
        interChoice, modCorrmParam,...
        pulIx, ranIx, spaIx, extraIx, cpiIx, trialIx);
    else
      interCorrm = [];
    end%if
 
    if (sigDim2 == only1DDim)
    % 1D filtering.
      sigMatIn = getm3(signalsIn, sigDim1, [], pulIx,ranIx,spaIx, ...
        extraIx, cpiIx, trialIx);
    else
    % 2D filtering.
      sigMatIn = signalsIn(pulIx,ranIx,spaIx,extraIx, cpiIx, trialIx);
      sigMatIn = permute(sigMatIn, permuteInOrder);
      sigMatIn = reshape(sigMatIn, reshapeInSizes);
    end%if

    % ****************** Call the filtering function. ******************

    sigMatOut = calcfiltproc(sigMatIn, methodCalc, weightMatrix, ...
      calcProcParams{:}, interCorrm);

    % ****************** **************************** ******************

    if (sigDim2 == only1DDim)
    % 1D filtering.
      signalsOut(pulIx,ranIx,spaIx,extraIx,cpiIx,trialIx) ...
        = sigMatOut;
    else
    % 2D filtering.
      sigMatOut = reshape(sigMatOut, [sigSizeOut(sigDim1), ...
        sigSizeOut(sigDim2), sigSizeOut(sampleDim)]);
      sigMatOut = ipermute(sigMatOut, permuteInOrder);
      signalsOut(pulIx,ranIx,spaIx,extraIx,cpiIx,trialIx) ...
        = sigMatOut;
    end%if

    dbtloopinfo(funcName, [], pulIx, noPulLoop, ranIx, noRanLoop,...
      spaIx, noSpaLoop, extraIx, noExtraLoop, cpiIx, noCpiLoop,...
      trialIx, noTrialLoop)

  end%for pulLoop
  end%for ranLoop
  end%for spaLoop
end%for extraLoop
end%for cpiLoop
dbtinfo('');	%New line.
end%for trialLoop


%endfunction calcfiltsig