function theResult = cdotsafe(x, y, z, theColorMap, theDotSize, ...
									doShowLabel, theRange)

% cdotsafe -- Draw colored dots spanning a range of data.
%  cdotsafe('demo') demonstrates itself with unlabeled dots
%   of various sizes and colors.
%  cdotsafe(x, y, z, theColorMap, theDotSize, doShowLabel, theRange)
%   draws colored dots at the (x, y) locations, whose color is
%   based on the given z-values, distributed uniformly across
%   theColorMap, using theDotSize.  Dot-sizes are individually
%   controlled if theDotSize is a vector.  Wherever doShowLabel
%   is TRUE, the corresponding z-value will be shown as a text-label
%   as well.  If theRange is given, the colors will be made to span it;
%   otherwise, the existing z-range will be used.  The handles of the
%   drawn lines are returned, if an output argument is supplied.
%  Note: Labels are shown in "%5.1f" format by default, or in the
%   format given by doShowLabels, if a string.
%
% Adapted from "cdot.m", Rich Signell, U.S. Gelogical Survey.
 
% Copyright (C) 2000 Dr. Charles R. Denham, ZYDECO.
%  All Rights Reserved.
%   Disclosure without explicit written consent from the
%    copyright owner does not constitute publication.
 
% Version of 24-Jan-2000 11:38:05.
% Updated    25-Jan-2000 11:33:43.

if nargin < 1, x = 'demo'; help(mfilename), end

if isequal(x, 'demo')
	delete(get(gcf, 'Children'))
	s = '[x, y, z] = peaks(20);';
	disp([' ## ' s])
	eval(s)
	subplot(2, 1, 1)
	surf(x, y, z), view(2)
	subplot(2, 1, 2)
	s = 'feval(mfilename, x(:), y(:), z(:), jet, 3*abs(z), 0, [-8 8])';
	disp([' ## ' s])
	eval(s)
	figure(gcf)
	set(gcf, 'Name', [mfilename ' demo'])
	return
end

if nargin < 3, help(mfilename), return, end
if nargin < 4, theColorMap = jet; end
if nargin < 5, theDotSize = 10; end
if nargin < 6, doShowLabel = 0; end
if nargin < 7, theRange = []; end

theFormat = '%5.1f';
if ischar(doShowLabel)
	theFormat = doShowLabel;
	doShowLabel = 1;
end

if length(theDotSize) == 1
	theDotSize = theDotSize + zeros(size(x));
end
if length(doShowLabel) == 1
	doShowLabel = doShowLabel + zeros(size(x));
end

if isstr(theColorMap), theColorMap = eval(theColorMap); end

[m, n] = size(theColorMap);
r = linspace(min(z(:)), max(z(:)), m+1);

h = [];

for i = 1:length(r)-1
	c = theColorMap(i, :);
	f = find(z >= r(i) & z <= r(i+1));
	if any(f)
		d = theDotSize(f);
		if length(d) == 1
			h(end+1) = line(x(f), y(f), z(f), ...
							'LineStyle', 'none', ...
							'Marker', '.', ...
							'MarkerSize', d, ...
							'Color', c);
		else
			for j = 1:length(f)
				h(end+1) = line(x(f(j)), y(f(j)), z(f(j)),  ...
							'LineStyle', 'none', ...
							'Marker', '.', ...
							'MarkerSize', d(j), ...
							'Color', c);
			end
		end
	end
end

if any(doShowLabel(:))
	f = find(doShowLabel);
	for i = 1:length(doShowLabel)
		theLabel = sprintf(theLabel, z(f(i)));
		text(x(f(i)),y(f(i)), theLabel, ...
				'HorizontalAlignment', 'left', ...
				'VerticalAlignment', 'bottom')
	end
end