/matlab_tools/Converted/kkkmeans.m

%kkkmeans 'Perform K-Means Clustering'
% This MatLab function was automatically generated by a converter (KhorosToMatLab) from the Khoros kkmeans.pane file
%
% Parameters: 
% InputFile: i1 'Input data object', required: 'input data object'
% InputFile: i2 'Cluster center input object', optional: 'cluster center input object'
% Toggle: map 'Generate output map', default: 0: 'generate output map'
% Toggle: spectrum 'SPECTRUM compatable map segment', default: 0: 'SPECTRUM compatable map segment'
% Integer: n 'Max number of iterations', default: 50000: 'max number of iterations'
% Integer: k 'Number of clusters', default: 2: 'number of clusters'
% OutputFile: o1 'Cluster number output object', required: 'cluster number output object'
% OutputFile: o2 'Cluster center output object', optional: 'cluster center output object'
% OutputFile: o3 'Cluster variance output object', optional: 'cluster variance output object'
% OutputFile: o4 'Cluster membership count output', optional: 'Cluster membership count output'
% OutputFile: o5 'K-means statistics output (ASCII)', optional: 'K-means statistics output (ASCII)'
%
% Example: [o1, o2, o3, o4, o5] = kkkmeans({i1, i2}, {'i1','';'i2','';'map',0;'spectrum',0;'n',50000;'k',2;'o1','';'o2','';'o3','';'o4','';'o5',''})
%
% Khoros helpfile follows below:
%
%  PROGRAM
% kkmeans - Perform K-Means Clustering
%
%  DESCRIPTION
% .I kkmeans
% accepts an input data object containing vectors of equal size and performs
% the K-means clustering algorithm on the vectors.  The length of each vector is 
% determined by the elements (E) dimension of the input data object.
% 
% The K-means algorithm is based on minimization of the sum of
% the squared distances from all points in a cluster to a cluster
% center.  The user chooses K initial cluster centers and the input
% vectors are iteratively distributed among the K cluster domains.
% New cluster centers are computed from these results, such that
% the sum of the squared distances from all points in a cluster to
% the new cluster center is minimized.
% 
% Although the K-means algorithm does not really converge (in a continuous
% space), it may converge in a discrete space or a
% practical upper limit can be chosen for convergence. The user has
% the option of specifying the maximum number of iterations using
% the -n option.  The default is 50000 iterations.
% 
% There are two ways to specify the initial cluster centers. If the -i2
% argument is supplied, then the cluster centers are read from the specified
% object. The vectors are assumed to be stored along the E direction. Only the
% first K centers (as specified by the -k argument) will be read. If the -i2
% argument is "not\fR present, then the first K vectors in the -i1
% object will be used as the initial cluster centers.
% 
% It should be noted that it is possible to specify an initial cluster that
% lies at a sufficient distance from all input vectors that it will have no
% vectors assigned to it during a pass of the K-means algorithm. If this
% happens, "kkmeans\fR will reinitialize the value of that cluster to
% the mean value of a moving pair of the existing cluster centers, thus avoiding 
% degeneracy.
% 
% If no options are selected, the output object specified by the -o1
% argument will contain a value segment specifying the cluster number to
% which each input vector was assigned. If the -map flag is also specified,
% then a map segment will also be generated. The final cluster centers will
% be stored row by row in the map. The values in the value segment can
% be interpreted as "pointing" to a particular row in the map where the
% associated cluster for that input vector can be found.
% 
% If the -spectrum flag is specified, then the -o1 output object will 
% contain a special map segment (regardless of the -map flag) with additional
% information required for use with the "spectrum\fR program in the most
% general sense. Here, not only the cluster centers are stored, but so are the
% number of vectors associated with each cluster and the packed upper triangle
% of the covariance matrix for each cluster. See the "spectrum\fR manual for
% additional information on how this data is used and the additional capabilities
% that become available when the extra data supplied by the -spectrum flag
% is present.
% 
% The -o2 optional argument will generate an output data object containing the
% cluster centers (mean vectors), stored row by row in the value segment.
% The dimensions of the value segment will be WxHx1x1x1 where W is the number of
% elements in each mean vector and W is the number of clusters.
% 
% The -o3 optional argument will generate an output data object containing the
% cluster variances, stored row by row in the value segment.
% The dimensions of the value segment will be WxHx1x1x1 where W is the number of
% elements in each vector of variances and W is the number of clusters.
% 
% The -o4 optional argument will generate an output data object containing the
% cluster membership counts, stored row by row in the value segment.
% The dimensions of the value segment will be 1xHx1x1x1 where H is the number of
% clusters. The membership counts simply state the number of vectors that
% were present in the input object that were assigned to each of the final
% cluster centers.
% 
% The statistics file (-o5) contains statistics obtained during the execution of
% "kkmeans\fR. This file includes the following information:
% 	
% 	Total Number of K-means Iterations
% 	Total Number of Clusters
% 	Number of Vectors Per Cluster
% 	Cluster Center Values
% 	Cluster Center Variance Values
% 	Trace of Covariance Matrix
% 
% 
% Results obtained by the K-means algorithm can be influenced by the
% number and choice of initial cluster centers and the geometrical
% properties of the data.
% 
% For the -o2, and -o3, output objects, the data will be stored as type
% KDOUBLE. For the -o4 output object, the data will be stored as type KINT.
% For the -o1 output object, the value data will be stored as type
% KSHORT and all map data as type KDOUBLE.
% 
% "kkmeans\fR was converted from the K1.5 vkmeans program, which was written
% by Tom Sauer and Charlie Gage, with assistance and ideas from
% Dr. Don Hush, University of New Mexico, Dept. of EECE. Significant modifications
% were made to the algorithm by Scott Wilson during conversion to K2.
%
%  
%
%  EXAMPLES
% kkmeans -i1 image1 -n 10000 -k 6 -o1 image2 -o2 image3
% 
% this will apply the K-means clustering algorithm to image1 using
% the first K vectors as cluster centers.  The number of iterations
% selected is 10000, and the number of clusters selected is 6.
% Image2 will contain a map linking each input vector to it's
% respective cluster center, while image3 will contain the
% actual cluster centers.
% 
% kkmeans -i1 image1 -i2 file1 -k 8 -o1 image2 -o2 image3 -o5 file2 -map
% 
% this will apply the K-means clustering algorithm to image1 using
% the cluster centers specified in file1.  The -k
% option specifies 8 cluster centers.  An ASCII file containing
% the K-means statistics (file2) is created. The other output objects are
% as specified above, except that image2 will also have a map attached containing
% the cluster centers.
% 
% kkmeans -i1 object1 -i2 object2 -k 8 -o1 object3 -spectrum
% 
% this will apply the K-means clustering algorithm to object1 using
% as input object2  to specify the initial cluster centers.  The -k option
% specifies 8 cluster centers. Object3 will contain not only the mapping
% from vectors to clusters (in the value segment), but an extended map segment
% containing the cluster centers, counts, and covariance matrices. This
% object can be automatically classified using the AutoClassify utilities in
% "spectrum\fR.
%
%  "SEE ALSO"
% spectrum(1)
%
%  RESTRICTIONS 
% "kkmeans\fR will not operate on any form of COMPLEX data. Mask data is
% currently ignored. If map data is present, then the value data is pulled through
% the map prior to application of the K-means algorithm.
% 
% A maximum of 32767 clusters can be requested due to the use of the KSHORT
% output data type. If more clusters than this are desired, then the code can
% be easily modified to change the output data type to KINT.
%
%  REFERENCES 
% 
% The K-means algorithm is also called out as the Basic Isodata algorithm in
% R. Duda and P. Hart, \fBPattern Classification and Scene Analysis\fR, Wiley,
% N.Y., 1973, p. 201. ISBN 0-471-22361-1. This is a dated, by very useful 
% reference.
%
%  COPYRIGHT
% Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI")  All rights reserved.
% 


function varargout = kkkmeans(varargin)
if nargin ==0
  Inputs={};arglist={'',''};
elseif nargin ==1
  Inputs=varargin{1};arglist={'',''};
elseif nargin ==2
  Inputs=varargin{1}; arglist=varargin{2};
else error('Usage: [out1,..] = kkkmeans(Inputs,arglist).');
end
if size(arglist,2)~=2
  error('arglist must be of form {''ParameterTag1'',value1;''ParameterTag2'',value2}')
 end
narglist={'i1', '__input';'i2', '__input';'map', 0;'spectrum', 0;'n', 50000;'k', 2;'o1', '__output';'o2', '__output';'o3', '__output';'o4', '__output';'o5', '__output'};
maxval={0,1,0,0,100000,2,0,1,1,1,1};
minval={0,1,0,0,0,2,0,1,1,1,1};
istoggle=[0,1,1,1,1,1,0,1,1,1,1];
was_set=istoggle * 0;
paramtype={'InputFile','InputFile','Toggle','Toggle','Integer','Integer','OutputFile','OutputFile','OutputFile','OutputFile','OutputFile'};
% identify the input arrays and assign them to the arguments as stated by the user
if ~iscell(Inputs)
Inputs = {Inputs};
end
NumReqOutputs=1; nextinput=1; nextoutput=1;
  for ii=1:size(arglist,1)
  wasmatched=0;
  for jj=1:size(narglist,1)
   if strcmp(arglist{ii,1},narglist{jj,1})  % a given argument was matched to the possible arguments
     wasmatched = 1;
     was_set(jj) = 1;
     if strcmp(narglist{jj,2}, '__input')
      if (nextinput > length(Inputs)) 
        error(['Input ' narglist{jj,1} ' has no corresponding input!']); 
      end
      narglist{jj,2} = 'OK_in';
      nextinput = nextinput + 1;
     elseif strcmp(narglist{jj,2}, '__output')
      if (nextoutput > nargout) 
        error(['Output nr. ' narglist{jj,1} ' is not present in the assignment list of outputs !']); 
      end
      if (isempty(arglist{ii,2}))
        narglist{jj,2} = 'OK_out';
      else
        narglist{jj,2} = arglist{ii,2};
      end

      nextoutput = nextoutput + 1;
      if (minval{jj} == 0)  
         NumReqOutputs = NumReqOutputs - 1;
      end
     elseif isstr(arglist{ii,2})
      narglist{jj,2} = arglist{ii,2};
     else
        if strcmp(paramtype{jj}, 'Integer') & (round(arglist{ii,2}) ~= arglist{ii,2})
            error(['Argument ' arglist{ii,1} ' is of integer type but non-integer number ' arglist{ii,2} ' was supplied']);
        end
        if (minval{jj} ~= 0 | maxval{jj} ~= 0)
          if (minval{jj} == 1 & maxval{jj} == 1 & arglist{ii,2} < 0)
            error(['Argument ' arglist{ii,1} ' must be bigger or equal to zero!']);
          elseif (minval{jj} == -1 & maxval{jj} == -1 & arglist{ii,2} > 0)
            error(['Argument ' arglist{ii,1} ' must be smaller or equal to zero!']);
          elseif (minval{jj} == 2 & maxval{jj} == 2 & arglist{ii,2} <= 0)
            error(['Argument ' arglist{ii,1} ' must be bigger than zero!']);
          elseif (minval{jj} == -2 & maxval{jj} == -2 & arglist{ii,2} >= 0)
            error(['Argument ' arglist{ii,1} ' must be smaller than zero!']);
          elseif (minval{jj} ~= maxval{jj} & arglist{ii,2} < minval{jj})
            error(['Argument ' arglist{ii,1} ' must be bigger than ' num2str(minval{jj})]);
          elseif (minval{jj} ~= maxval{jj} & arglist{ii,2} > maxval{jj})
            error(['Argument ' arglist{ii,1} ' must be smaller than ' num2str(maxval{jj})]);
          end
        end
     end
     if ~strcmp(narglist{jj,2},'OK_out') &  ~strcmp(narglist{jj,2},'OK_in') 
       narglist{jj,2} = arglist{ii,2};
     end
   end
   end
   if (wasmatched == 0 & ~strcmp(arglist{ii,1},''))
        error(['Argument ' arglist{ii,1} ' is not a valid argument for this function']);
   end
end
% match the remaining inputs/outputs to the unused arguments and test for missing required inputs
 for jj=1:size(narglist,1)
     if  strcmp(paramtype{jj}, 'Toggle')
        if (narglist{jj,2} ==0)
          narglist{jj,1} = ''; 
        end;
        narglist{jj,2} = ''; 
     end;
     if  ~strcmp(narglist{jj,2},'__input') && ~strcmp(narglist{jj,2},'__output') && istoggle(jj) && ~ was_set(jj)
          narglist{jj,1} = ''; 
          narglist{jj,2} = ''; 
     end;
     if strcmp(narglist{jj,2}, '__input')
      if (minval{jj} == 0)  % meaning this input is required
        if (nextinput > size(Inputs)) 
           error(['Required input ' narglist{jj,1} ' has no corresponding input in the list!']); 
        else
          narglist{jj,2} = 'OK_in';
          nextinput = nextinput + 1;
        end
      else  % this is an optional input
        if (nextinput <= length(Inputs)) 
          narglist{jj,2} = 'OK_in';
          nextinput = nextinput + 1;
        else 
          narglist{jj,1} = '';
          narglist{jj,2} = '';
        end;
      end;
     else 
     if strcmp(narglist{jj,2}, '__output')
      if (minval{jj} == 0) % this is a required output
        if (nextoutput > nargout & nargout > 1) 
           error(['Required output ' narglist{jj,1} ' is not stated in the assignment list!']); 
        else
          narglist{jj,2} = 'OK_out';
          nextoutput = nextoutput + 1;
          NumReqOutputs = NumReqOutputs-1;
        end
      else % this is an optional output
        if (nargout - nextoutput >= NumReqOutputs) 
          narglist{jj,2} = 'OK_out';
          nextoutput = nextoutput + 1;
        else 
          narglist{jj,1} = '';
          narglist{jj,2} = '';
        end;
      end
     end
  end
end
if nargout
   varargout = cell(1,nargout);
else
  varargout = cell(1,1);
end
global KhorosRoot
if exist('KhorosRoot') && ~isempty(KhorosRoot)
w=['"' KhorosRoot];
else
if ispc
  w='"C:\Program Files\dip\khorosBin\';
else
[s,w] = system('which cantata');
w=['"' w(1:end-8)];
end
end
[varargout{:}]=callKhoros([w 'kkmeans"  '],Inputs,narglist);