rename centroid as regionCentroids and add support for spatial calibration

Author: dlegland

src/@Image/centroid.m

@@ -1,6 +1,8 @@
 function [points, labs] = centroid(obj, varargin)
 %CENTROID Centroid(s) of a binary or label image.
 %
+%   Deprecated: renamed as regionCentroids
+%
 %   C = centroid(I)
 %   Returns the centroid C of the binary image I. C is a 1-by-2 or 1-by-3
 %   row vector, depending on the dimension of the image.
@@ -31,6 +33,8 @@
 % Created: 2018-07-03,    using Matlab 9.4.0.813654 (R2018a)
 % Copyright 2018 INRA - Cepia Software Platform.
 
+warning('deprecated, use ''regionCentroids'' instead');
+
 % check image type
 if ~(isLabelImage(obj) || isBinaryImage(obj))
     error('Requires a label of binary image');

src/@Image/findLabels.m

@@ -27,7 +27,7 @@
 end
 
 if ~isLabelImage(obj)
-    error('Reqsuires a label image');
+    error('Requires a label image');
 end
 
 % special case of CC structure, not used at the moment

src/@Image/regionCentroids.m

@@ -0,0 +1,88 @@
+function [points, labels] = regionCentroids(obj, varargin)
+% Centroid of region(s) in a binary or label image.
+%
+%   C = regionCentroids(I)
+%   Returns the centroid C of the binary image I. C is a 1-by-2 or 1-by-3
+%   row vector, depending on the dimension of the image.
+%
+%   C = regionCentroids(LBL)
+%   If LBL is a label D-dimensional image, returns an array of N-by-D
+%   values, corresponding to the centroids of the N regions within the
+%   image.
+%
+%   [C, LABELS] = regionCentroids(LBL)
+%   Also returns the labels of the regions that were measured.
+%
+%   Example
+%     % Compute centroids of coins particles
+%     img = Image.read('coins.png');            % read image
+%     bin = opening(img > 80, ones([3 3]));     % binarize
+%     lbl = componentLabeling(bin);             % compute labels
+%     figure; show(img);                        % display image
+%     pts = regionCentroids(lbl);               % compute centroids
+%     hold on; plot(pts(:,1), pts(:,2), 'b+');  % display centroids
+%
+%   See also
+%     analyzeRegions, findRegionLabels, componentLabeling, regionprops
+ 
+% ------
+% Author: David Legland
+% e-mail: david.legland@inrae.fr
+% Created: 2018-07-03,    using Matlab 9.4.0.813654 (R2018a)
+% Copyright 2018 INRA - Cepia Software Platform.
+
+% check image type
+if ~(isLabelImage(obj) || isBinaryImage(obj))
+    error('Requires a label of binary image');
+end
+
+% check if labels are specified
+labels = [];
+if ~isempty(varargin) && size(varargin{1}, 2) == 1
+    labels = varargin{1};
+end
+
+% extract the set of labels, without the background
+if isempty(labels)
+    labels = findRegionLabels(obj);
+end
+nLabels = length(labels);
+
+% allocate memory for result
+nd = ndims(obj);
+points = zeros(nLabels, nd);
+
+% switch processing depending on image dimensionality
+if nd == 2
+    for i = 1:nLabels
+        % extract points of the current particle
+        [x, y] = find(obj.Data == labels(i));
+
+        % coordinates of particle regionCentroids
+        xc = mean(x);
+        yc = mean(y);
+
+        points(i, :) = [xc yc];
+    end
+  
+elseif nd == 3
+    dim = size(obj.Data);
+    for i = 1:nLabels
+        % extract points of the current particle
+        inds = find(obj.Data == labels(i));
+        [x, y, z] = ind2sub(dim, inds);
+
+        % coordinates of particle regionCentroids
+        xc = mean(x);
+        yc = mean(y);
+        zc = mean(z);
+
+        points(i, :) = [xc yc zc];
+    end
+    
+else
+    error('Requires an image of dimension 2 or 3');
+end
+
+% calibrate result
+points = bsxfun(@plus, bsxfun(@times, points-1, obj.Spacing), obj.Origin);

src/@Image/regionElementCounts.m

@@ -1,12 +1,24 @@
 function [counts, labels] = regionElementCounts(obj, varargin)
 % Count the number of pixels/voxels within each region of a label image.
 %
-%   output = regionElementCounts(input)
+%   CNT = regionElementCounts(LBL)
+%   For each region on the label image LBL, count the number of elements
+%   (pixels or voxels) that constitute this region. Return a column vector
+%   with as many elements as the number of regions.
+%
+%   [CNT, LABELS] = regionElementCounts(LBL)
+%   Also returns the labels of the regions.
 %
 %   Example
-%   regionElementCounts
+%     img = Image.read('coins.png');
+%     bin = fillHoles(img > 100);
+%     lbl = componentLabeling(bin);
+%     regionElementCounts(lbl)'
+%     ans =
+%       2563   1899   2598   1840   2693   1906   2648   2725   1935   2796
 %
 %   See also
+%     regionCentroids, findRegionLabels
 %
 
 % ------

tests/image/test_regionCentroids.m

@@ -0,0 +1,37 @@
+function tests = test_regionCentroids
+% Test suite for the file regionCentroids.
+%
+%   Test suite for the file regionCentroids
+%
+%   Example
+%   test_regionCentroids
+%
+%   See also
+%     regionCentroids
+
+% ------
+% Author: David Legland
+% e-mail: david.legland@inrae.fr
+% Created: 2021-02-02,    using Matlab 9.8.0.1323502 (R2020a)
+% Copyright 2021 INRAE - BIA-BIBS.
+
+tests = functiontests(localfunctions);
+
+function test_Simple(testCase) %#ok<*DEFNU>
+% Test call of function without argument.
+
+data = zeros([10 10], 'uint8');
+data(2:4, 2:4) = 3;
+data(6:10, 2:4) = 4;
+data(2:4, 6:10) = 7;
+data(6:10, 6:10) = 8;
+img = Image('Data', data, 'Type', 'Label');
+
+[centroids, labels] = regionCentroids(img);
+
+assertEqual(testCase, size(centroids), [4 2]);
+assertEqual(testCase, centroids, [3 3;8 3;3 8;8 8]);
+assertEqual(testCase, size(labels), [4 1]);
+assertEqual(testCase, labels, [3;4;7;8]);
+
+