% histo.m
% h = histo(x) bins each element of x into
% the container for the nearest whole integer
% and returns the number of elements in each container.
%
% If X is a matrix, histo(x) works down the columns.
%
% The first container h(1)
% is the count of all values (including negative integers) below 0.5,
% h(2) is the count of all "ones" (0.5 to 1.5),
% h(3) is the count of all "twos" (1.5 to 2.5), etc.
%	h =  histo( [ 11 11 11 11 2 2 3 3 4 5 11 ] )'
% returns h = [ 0 0 2 2 1 1 0 0 0 0 0 5 ]
% meaning that
% "0" never occurred,
% "1" never occurred,
% "2" occurred twice,
% ...
% "11" occurred 5 times.
% Usage:
%	cameraman =  imread('cameraman.tif');
%	histogram = histo( cameraman(:) );
%	figure; stem(histogram)
%	diff_cameraman = diff(double(cameraman));
%	minimum = min(diff_cameraman(:));
%	histogram2 = histo( diff_cameraman(:)-minimum );
%	figure; stem(histogram2, minimum + 1:length(histogram2) )
%
% Does exactly the same thing as h=hist( x,0:max(x(:)) )
% but in about 1/5 the time.
% See also HIST, EQUALIZE, HUFFMANLENGTH.

% Change log:
% 1999-06-29:DAV: completely changed; reduced time
%    a factor of 10 on cameraman
%   (from 21 seconds to 2.4 seconds on my machine).
% 1999-06-29:DAV: factored "frequency" into 2 routines,
%   "frequency" and "histo".
% 1999-06-24:DAV: David Cary <d.cary@ieee.org> added documentation
% ???:JCK: John C. Kieffer wrote original "frequency.m"
%   http://www.ee.umn.edu/users/kieffer/programs.html

function histogram = histo(raw_data)
% Create a single column vector containing all the values of the object.
% Round to nearest integer.
x = round(double(raw_data(:)));
% make sure all values less than 0 get collapsed to 0.
x = x .* (0 < x);
bins = 1+max(x(:));
% append "-1" and 1 extra copy of each letter, then sort
x = [x(:); (-1:bins)'];
x = sort(x);
% get the *locations* of each transition to the next letter
x = find(diff(x));
% finally, get the frequency (the distance between transitions)
% and subtract off the extra letters we added.
histogram = diff(x)-1;

% This straightforward method
% (according to profile)
% is actually slower in MatLab:
%x = round(double(raw_data(:)));
%x = (x .* (0 < x)) + 1;
%bins = max(x(:));
%histogram = zeros(bins,1);
%for i = 1:length(x),
%    t = x(i);
%    histogram(t) = histogram(t) + 1;
%end;

% end histo.m