ATOptimize(img,model,free,Eext,params,fopt)

function opt = ATOptimize(img,model,free,Eext,params,fopt)
%ATOPTIMIZE  Optimizes a shape model over an image.
%
% function opt = ATOptimize(img,model,free,Eext,params,fopt)
%
%  This function optimizes a shape model (a GeoML model) over an image
% using a given external energy function. The external energy function can
% generate an environment that is mantained during th process and passed in
% as a sequence of additional parameters: the first time that the Eext si
% called a 0 is passed as first parameter, then the img and a set of 
% parameters; so the environment can be generated. In the path and the
% generated environment are passed. The environment cannot be modified.
%
%  Params
%  ------
% IN:
%  img      = The input image.
%  model    = The GeoML model.
%  free     = The cell of free parameters.
%  Eext     = The exernal energy function.
%  params   = Initial parameters for the fopt (def={}).
%  fopt     = The optimization function. (def=@fminsearch)
% OUT:
%  opt      = The optimal values for the parameters.

% Check params:
if nargin<4; error('At least 4 parameters are required!'); end
if nargin<5; params={}; end
if nargin<6; fopt=@fminsearch; end

% Converting to cell the free vars array:
if ~iscell(free)
    % Conversion:
    free = mat2cell(free,ones(1,numel(free)),1);
end

% Compute the environment:
env{:} = Eext(0,img,params{:});

% The optimization function:
f = @(X)(EvaluateEnergy(X,model,free,Eext,env));

% The initial solution:
X = InitialSolution(free);

% Optimization:
opt = fopt(f,X);

% ------------------------ LOCAL FUNCTIONS ------------------------

% The function that evaluates the energy of a configuration:
function E = EvaluateEnergy(X,model,free,Eext,env)

% Check params:
if numel(X)~=numel(free)
    error('The number of values and free parameters must be the same!');
end

% Set the params:
for ind=1:numel(X)
    % Set and update a value:
    free{ind}.setValueUpdate(X(ind));
end

% Computing the path:
pts = GeoMLIterate(model);

% Compute the energy:
E = Eext(pts,env{:});

% -----------------------------------------------------------------

% Get the initial solution:
function X = InitialSolution(free)

% Allocate the vector:
X = zeros(size(free));

% Inserting values:
for ind=1:numel(X)
    X(ind) = free{ind}.getValue;
end