function varargout = clusterImg(imgin,Clusters,varargin)
% Copyright 2010 The MathWorks, Inc.
% [IDX,C,sumd,D] = clusterImg(imgin,nClusters,inMask,labels)
%
% This function implements kmeans clustering on an input RGB (m x n x 3)
% image. The user inputs at least two inputs: IMGIN and
% NCLUSTERS, and this
% function will step through an interactive color segmentation using kmeans
% clustering. It is interactive in that the user will be prompted to
% click-define the target colors in the segmentation. (There will be
% NCLUSTERS prompts.) Optionally, the user can also input a third argument
% containing a binary mask of the input image, in which case the program
% will operate on a subimage defined by the BOUNDING BOX of the (true)
% inMask.
%
% NOTE 1: Following segmentation (clustering), the user can EXPORT THE CLUSTERED
% IMAGE TO THE WORKSPACE, along with its corresponding colormap. Additionally,
% the user can opt to EXPORT A BINARY MASK OF A SINGLE COLOR CLUSTER TO THE
% WORKSPACE. Both of these options are initiated by press of a uicontrol
% pushbutton. The naming convention is automatic; the clustered image and
% corresponding colormap will be named CLUSTERED1 and CLUSTEREDMAP1,
% respectively. If those variables already exist in the workspace, they
% will NOT be overwritten. Rather, the names will be modified by
% incrementing the integer value on the end (e.g., CLUSTERED2,
% CLUSTERMAP2). Similarly, the binary mask on a cluster will be named
% CLUSTERMASK, CLUSTERMASK1, CLUSTERMASK2,....
%
% NOTE 2: To reconstruct the image from workspace variables, use the command:
% imshow(clustered,clusterMap);
%
% ***************************************
% SYNTAX:
%
% [IDX,C,sumd,D] = clusterImg(imgin,nClusters,inMask,labels);
%
% ***************************************
% INPUTS:
%
% Imgin:
% an m x n x 3 (RGB) image
%
% Clusters:
% Either A) an integer number of target clusters. (Note
% that you will be prompted to click-define--using
% IMPIXEL syntax--at least one pixel in each target
% color cluster; you probably want this to be a
% "reasonable" number (more than 1, less than, say,
% 20); or B) an nx3 array of predefined colors. Using
% option B will skip the interactive selection process
% and use the colors in Clusters as the bin targets.
%
% inMask (OPTIONAL)
% a binary mask of size m x n. If a mask is included, this function
% will operate on a sub-image defined by IMCROP(imgin,BoundingBox),
% where BoundingBox is the rectangular extent of the true mask.
%
% labels (OPTIONAL)
% a cell array of labels for the colormap display of the
% segmented image. Note that the number of strings must
% be equal to the number of colors.
%
% ***************************************
% OUTPUTS:
%
% IDX, C, sumd, D
% All as returned by KMEANS. Please refer to the help for that
% function. Note, however, that the size of the outputs may be modified
% by the inclusion of optional inMask input argument. (See NOTE 2
% below.)
%
% clustered
% an indexed image of size p x q x 1 (see NOTE 4 below), segmented using kmeans
% clustering. (See description of optional inMask input argument). If no
% mask is provided, the CLUSTERED image is m x n x 1.
%
% clusteredMap
% an Clusters x 3 matrix of RGB colors. These colors comprise the mean
% values returned by each IMPIXEL selection when the user defines the
% target cluster colors.
%
% clusterMask
% a binary mask of size p x q x 1 (see NOTE 2 below). Once the input has been
% clustered, it will be displayed in a figure with a pushbutton prompt
% to create a mask on a clustered color. If the button is pressed, the
% user will be prompted to click-select a single cluster color (using
% IMPIXEL syntax). CLUSTER_MASK will return a binary image with ones in
% the location of the selected color, and zeros elsewhere.
%
% NOTE 3: OUTPUT ARGUMENTS [CLUSTERED, CLUSTEREDMAP, CLUSTERMASK] ARE
% PROMTED BY UICONTROLS, and do not require the presence of output
% arguments. Nomenclature is automatic, as described in NOTE 1 above.)
%
% NOTE 4: OUTPUT IMAGE (AND MAP) SIZES are p x q, if a binary mask is provided
% as an optional input, where p and q are defined by the extent of the
% bounding box of the (true) input mask. If no input mask is provided, p=m
% and q=n.
%
%
% ***************************************
% EXAMPLES:
%
% 1)
% clusterImg(imread('peppers.png'),6);
% segments the image in 'peppers.png' into 6 color
% clusters.
% 2)
% a=[0.2902 0.1647 0.2824;
% 0.9137 0.7922 0.6784;
% 0.3725 0.4392 0.1412;
% 0.5961 0.1529 0.2039;
% 1.0000 0.7843 0.0431;
% 0.9686 0.5294 0];
% clusterImg(imread('peppers.png'),a,[],{'One','Two','Three','Four','Five','Six'});
%
% 3)
% [IDX, C, sumd, D] = clusterImg(x, 5, x(:,:,1) < 100);
% masks image x with "red plane less than 100", finds the bounding box
% of the resulting (logically true) inMask, and segments the IMCROPped
% image x(inMask) into 5 color clusters. Returns the variables IDX, C,
% sumd, and D, as described by the documentation for KMEANS.
%
% ***************************************
% ***************************************
% DEPENDENCIES:
% Image Processing Toolbox, Statistics Toolbox
%
% ***************************************
% Written by Brett Shoelson, PhD
% brett.shoelson@mathworks.com
%
% Ver 2.0
% Revisions:
% Ver 1.1; 11/12/06. Bounding box detection on imcrop modified.
% Ver 1.2; 1/31.07. The second input argument has been
% renamed from nClusters to Clusters to reflect the fact
% that one can now either A) specify the number of clusters
% and select them interactively (as before); or B)input an
% nx3 array of colors, skipping the interactive
% selection. ALSO, the function now takes an additional
% optional input argument to specify the labels on the
% colormap of the segmented image.
% Ver 2.0; 11/29/07. Now includes a pushbutton for the auto-generation of
% all segmented colormap. Also, included description of LABELS as input
% argument, and fixed incorrect capitalization of "clusterMaskn"
% indicator.
% ***************************************
%Parse and initialize input and output arguments
if ndims(imgin)~=3
error('Input image must be m x n x 3 (RGB)');
end
if nargin == 3
inMask = varargin{1};
if all(inMask(:))
%NO OP: inMask is all 1's...no masking performed
inMask = [];
end
else
inMask = [];
end
if ~isempty(inMask) %at least one excluded point; operate on masked sub-image
[r,c]=find(inMask);
bb = [min(c) min(r) max(c)-min(c) max(r)-min(r)];
imgin = imcrop(imgin,bb);
%bb = regionprops(bwlabel(inMask),'BoundingBox');
%imgin = imcrop(imgin,bb.BoundingBox);
end
%Operate on image as double, regardless of input type
if ~isa(imgin,'double')
imgin = im2double(imgin);
end
%Get individual RGB colors included in segmentation
rc = imgin(:,:,1);
gc = imgin(:,:,2);
bc = imgin(:,:,3);
tmpimg = imgin;
segcolors = double([rc(:) gc(:) bc(:)]);
tmpfig=figure('numbertitle','off','name','Cluster RGB Image','visible','off');
imshow(tmpimg);
set(tmpfig,'units','pixels','position',[0 0 1000 800]);
centerfig(tmpfig);
set(tmpfig,'visible','on');
if numel(Clusters)==1
% Prompt for target cluster colors
colors = zeros(Clusters,3);
for ii=1:Clusters
figure(tmpfig);
title(sprintf('Select sample pixel(s) in cluster %d of %d:',ii,Clusters));
tmp = impixel;
colors(ii,:) = mean(tmp,1);
end
elseif size(Clusters,2) == 3
% User passed in the target colors; skip interactive
% selection
colors = Clusters;
Clusters = size(colors,1);
end
title('Segmenting. Please wait.......');
drawnow;
%Operate on colors (and image) as doubles()
colors = im2double(colors);
% CALL KMEANS with appropritate output arguments.
if nargout < 2
Idx = kmeans(segcolors,Clusters,'distance','sqEuclidean','start',colors,'emptyaction','singleton');
elseif nargout == 2
[Idx,varargout{2}] = ...
kmeans(segcolors,Clusters,'distance','sqEuclidean','start',colors,'emptyaction','singleton');
elseif nargout == 3
[Idx, varargout{2}, varargout{3}] = ...
kmeans(segcolors,Clusters,'distance','sqEuclidean','start',colors,'emptyaction','singleton');
elseif nargout == 4
[Idx, varargout{2}, varargout{3}, varargout{4}] = ...
kmeans(segcolors,Clusters,'distance','sqEuclidean','start',colors,'emptyaction','singleton');
else
error('Inappropriate number of outputs requested in ClusterImg.');
end
if nargout >= 2
varargout{1} = Idx;
end
pixel_labels = reshape(Idx,size(rc));
imshow(pixel_labels,[]);
title('Image labeled by cluster index');
set(tmpfig,'units','pixels','position',[0 0 1000 800]);
centerfig(tmpfig);
colormap(colors);
tmp = colorbar;
set(tmp,'ytick',1:Clusters);
if nargin == 4
set(tmp,'yticklabel',varargin{2});
end
uicontrol('style','pushbutton','string','Export Clustered Image and Map to Workspace','units','normalized',...
'pos',[0.05 0.05 0.3 0.05],'callback',@exportMain);
uicontrol('style','pushbutton','string','Export Mask on Single Color','units','normalized',...
'pos',[0.35 0.05 0.3 0.05],'callback',@exportClusterMask);
uicontrol('style','pushbutton','string','Export All Color Masks','units','normalized',...
'pos',[0.65 0.05 0.3 0.05],'callback',{@exportAllClusterMasks,colors});
%Subfunctions local to clustering only. Isn't MATLAB wonderful?
function exportMain(varargin)
n = 0; tmp = 1;
while tmp
n = n + 1;
tmp = evalin('base',['exist(''clustered', num2str(n), ''')']);
end
fprintf('Image written to clustered%d and associated colormap written to clusteredMap%d\n',n,n);
fprintf('Display with: imshow(clustered%d,clusteredMap%d);\n',n,n);
assignin('base',['clustered' num2str(n)],pixel_labels);
assignin('base',['clusteredMap' num2str(n)],colors);
end
function exportClusterMask(varargin)
title('Click on any pixel in the desired region.');
p=impixel;
if ~all(p(:)==p(1))
beep;
disp('Select a SINGLE region!!!');
else
n = 0; tmp = 1;
while tmp
n = n + 1;
tmp = evalin('base',['exist(''clusterMask', num2str(n), ''')']);
end
title('Image labeled by cluster index');
fprintf('Mask of region %d written to clusterMask%d\n',p(1),n);
assignin('base',['clusterMask' num2str(n)],pixel_labels==p(1));
end
end
function exportAllClusterMasks(varargin)
colors = varargin{3};
n = 0; tmp = 1;
while tmp
n = n + 1;
tmp = evalin('base',['exist(''clusterMask', num2str(n), ''')']);
end
for ii = 1:size(colors,1)
fprintf('Mask of region %d written to clusterMask%d\n',ii,n+ii-1);
assignin('base',['clusterMask' num2str(n+ii-1)],pixel_labels==ii);
end
end
end
