% -*- texinfo -*-
% @deftypefn {Function File} {[@var{table}, @var{codes}] = } lloyds (@var{sig},@var{init_codes})
% @deftypefnx {Function File} {[@var{table}, @var{codes}] = } lloyds (@var{sig},@var{len})
% @deftypefnx {Function File} {[@var{table}, @var{codes}] = } lloyds (@var{sig},@var{...},@var{tol})
% @deftypefnx {Function File} {[@var{table}, @var{codes}] = } lloyds (@var{sig},@var{...},@var{tol},@var{type})
% @deftypefnx {Function File} {[@var{table}, @var{codes}, @var{dist}] = } lloyds (@var{...})
% @deftypefnx {Function File} {[@var{table}, @var{codes}, @var{dist}, @var{reldist}] = } lloyds (@var{...})
%
% Optimize the quantization table and codes to reduce distortion. This is
% based on the article by Lloyd
%
% S. Lloyd @emph{Least squared quantization in PCM}, IEEE Trans Inform
% Thoery, Mar 1982, no 2, p129-137
%
% which describes an iterative technique to reduce the quantization error
% by making the intervals of the table such that each interval has the same
% area under the PDF of the training signal @var{sig}. The initial codes to
% try can either be given in the vector @var{init_codes} or as scalar
% @var{len}. In the case of a scalar the initial codes will be an equi-spaced
% vector of length @var{len} between the minimum and maximum value of the
% training signal.
%
% The stopping criteria of the iterative algorithm is given by
%
% @example
% abs(@var{dist}(n) - @var{dist}(n-1)) < max(@var{tol}, abs(@var{eps}*max(@var{sig}))
% @end example
%
% By default @var{tol} is 1.e-7. The final input argument determines how the
% updated table is created. By default the centroid of the values of the
% training signal that fall within the interval described by @var{codes}
% are used to update @var{table}. If @var{type} is any other string than
% 'centroid', this behaviour is overriden and @var{table} is updated as
% follows.
%
% @example
% @var{table} = (@var{code}(2:length(@var{code})) + @var{code}(1:length(@var{code}-1))) / 2
% @end example
%
% The optimized values are returned as @var{table} and @var{code}. In
% addition the distortion of the the optimized codes representing the
% training signal is returned as @var{dist}. The relative distortion in
% the final iteration is also returned as @var{reldist}.
%
% @end deftypefn
% @seealso{quantiz}