function [v0,Tx,Ty] = irregularsampling(u0,varargin)
%%
% Usage: [v0,Tx,Ty] = irregularsampling(u0,Name,Value)
%
% Input(s)/Output(s):
%
%   u0       : (input complex matrix) complex pseudo-raw image
%   v0       : (output complex matrix) irregularly resampled image
%   Tx       : (output matrix of double) horizontal component of the local
%              displacement field
%   Ty       : (output matrix of double) vertical component of the local
%              displacement field
%
% Optional Name-Value pair arguments:
%
%   'K' K        : (scalar, default K=25) locality parameter
%   'Ntransl' N  : (scalar, default N=20) number of tested translations
%   'verbose' v  : (scalar logical, default v=false) set v=true to display
%                   progression in the Matlab console
%
% Description: irregular resampling scheme for pseudo-raw SAR images.
%
%   This function is an implementation of the irregular resampling scheme
%   proposed in the research paper [1] and also described in [2]
%
%    [1] R. Abergel, S. Ladjal, F. Tupin and J.-M. Nicolas, ``A Complex
%        Spectrum Based SAR Image Resampling Method with Restricted Target
%        Sidelobes and Statistics Preservation'', in proceedings of the
%        2017 IEEE International Geoscience and Remote Sensing Symposium
%        (IGARSS 2017).
%
%    [2] R. Abergel, L. Denis, S. Ladjal and F. Tupin, ``Sub-pixellic Methods
%        for Sidelobes Suppression and Strong Targets Extraction in Single Look
%        Complex SAR Images'', preprint HAL-IMT, submitted in July 2017.
%
%    This irregular resampling algorithm can be used to process pseudo-raw
%    SAR image acquired in stripmap mode (pseudo-raw means non-apodized and
%    non-oversampled SAR images, see [1,2] for more details). It consists
%    in resampling the input (complex-valued) pseudo-raw image (u0) over a
%    non-regular grid such as the resampled image (v0) does not exhibits
%    sidelobes in the vicinity of strong target responses.
%

%% Note about the research paper [2]
%
%  The work [2] corresponds to the revision of the manuscript entitled
%  ``Sidelobes Suppression and Strong Targets Extraction in Single Look Complex
%  SAR Images with Several Applications'' that we submitted in July 2017 (we
%  changed the title according to one Reviewer's recommandation).

%% License & copyright
%
% Copyright (C) 2017, Rémy Abergel (Remy.Abergel AT parisdescartes.fr), Loïc
% Denis (Loic.Denis AT univ-st-etienne.fr), Saïd Ladjal (Said.Ladjal AT
% telecom-paristech.fr) and Florence Tupin (Florence.Tupin AT
% telecom-paristech.fr).
%
% GNU GPL License, see <http://www.gnu.org/licenses/>.

%% usage displayer
function display_usage()
  fprintf('\n Usage: [v0,Tx,Ty] = irregularsampling(u0,Name,Value)\n\n');
  fprintf(' Input(s)/Output(s):\n\n');
  fprintf('   u0       : (input complex matrix) complex pseudo-raw image\n');
  fprintf('   v0       : (output complex matrix) irregularly resampled image\n');
  fprintf('   Tx       : (output matrix of double) horizontal component of the local\n');
  fprintf('              displacement field\n');
  fprintf('   Ty       : (output matrix of double) vertical component of the local\n');
  fprintf('              displacement field\n\n');
  fprintf(' Optional Name-Value pair arguments:\n\n');
  fprintf('   ''K'' K        : (scalar, default K=25) locality parameter\n');
  fprintf('   ''Ntransl'' N  : (scalar, default N=20) number of tested translations\n');
  fprintf('   ''verbose'' v  : (scalar logical, default v=false) set v=true to display\n');
  fprintf('                   progression in the Matlab console\n\n');
  fprintf(' Description: irregular resampling scheme for pseudo-raw SAR images.\n\n');
  fprintf('   This function is an implementation of the irregular resampling scheme\n');
  fprintf('   proposed in the research paper [1] and also described in [2]\n\n');
  fprintf('    [1] R. Abergel, S. Ladjal, F. Tupin and J.-M. Nicolas, ``A Complex Spectrum\n');
  fprintf('        Based SAR Image Resampling Method with Restricted Target Sidelobes and\n');
  fprintf('        Statistics Preservation'', in proceedings of the 2017 IEEE International\n');
  fprintf('        Geoscience and Remote Sensing Symposium (IGARSS 2017).\n\n');
  fprintf('    [2] R. Abergel, L. Denis, S. Ladjal and F. Tupin, ``Sidelobes Suppression\n');
  fprintf('        and Strong Targets Extraction in Single Look Complex SAR Images with\n');
  fprintf('        Several Applications'', preprint HAL-IMT, submitted in July 2017.\n\n');
  fprintf('    This irregular resampling algorithm can be used to process pseudo-raw SAR\n');
  fprintf('    image acquired in stripmap mode (pseudo-raw means non-apodized and\n');
  fprintf('    non-oversampled SAR images, see [1,2] for more details). It consists in\n');
  fprintf('    resampling the input (complex-valued) pseudo-raw image (u0) over a\n');
  fprintf('    non-regular grid such as the resampled image (v0) does not exhibits\n');
  fprintf('    sidelobes in the vicinity of strong target responses.\n\n');
end

if(nargin < 1)
  display_usage();
  error('CPSAR_TOOLBOX:irregularsampling:batinputnumber','Incorrect number of input(s)');
end

%% parser (consistency checks are done after, to allow precise error messages)
p = inputParser;
p.addRequired('u0');
p.addParameter('Ntransl',20);
p.addParameter('K',25);
p.addParameter('verbose',false);
parse(p,u0,varargin{:});
Ntransl = p.Results.Ntransl;
K = p.Results.K;
verbose = p.Results.verbose;

%% consistency checks
% input u0 (matrix of complex double)
if(~ismatrix(u0) || isscalar(u0) || isreal(u0))
  display_usage();
  error('CPSAR_TOOLBOX:irregularsampling:badinputdatatype','input image u0 must be a (non-scalar) matrix of complex double');
end
% input K
if(~isscalar(K) || ~isreal(K))
  display_usage();
  error('CPSAR_TOOLBOX:irregularsampling:badinputdatatype','input ''K'' must be a scalar real number');
end
if(K~=floor(K)), fprintf('Warning: input ''K'' will be casted to integer\n'); end
% input Ntransl
if(~isscalar(Ntransl) || ~isreal(Ntransl))
  display_usage();
  error('CPSAR_TOOLBOX:irregularsampling:badinputdatatype','input ''Ntransl'' must be a scalar real number');
end
if(Ntransl~=floor(Ntransl)), fprintf('Warning: input ''Ntransl'' will be casted to integer\n'); end
% input verbose
if(~isscalar(verbose) || ~islogical(verbose))
  display_usage();
  error('CPSAR_TOOLBOX:irregularsampling:badinputdatatype','input ''verbose'' must be a logical scalar');
end

%% run irregularsampling algorithm (mex interface)
[v0,Tx,Ty] = irregularsampling_mexinterface(double(u0),int32(K),int32(Ntransl),int32(verbose));

end