function surface_plot(mat, lon, lat, val_min, val_max, ...
    cont_val, position, ifig)

%function err = surface_plot(mat, lon, lat, val_min, val_max, ...
%    cont_val, position, ifig)
%
%surface_plot draws a pseudo-color plot of a matrix.  Black contours
%may be drawn over the top of this and the user can then label as many
%of these as required. As well, a legend is drawn.
%
%           Input variables.
%mat: a matrix of values to be shown in a 2-d pseudo-color plot.
%lon: a vector of longitude values (columns in mat).
%lat: a vector of latitude values (rows in mat).
%val_min: the numeric value that maps to the first color in the
%         colormap used for the pseudo-color plot. It is also used
%         to create the legend.
%val_max: the numeric value that maps to the last color in the
%         colormap used for the pseudo-color plot.  It is also used
%         to create the legend.
%cont_val: an array of contour values used by the contour map.
%position: a 4 element row vector of the form [ left, bottom, width,
%          height]. It is used to define the position of the
%          pseudo-color plot.  Any negative elements are replaced with
%          sensible defaults.
%ifig: if ifig > 0 then the pseudo-color plot will be in figure(ifig).
%      Otherwise a new figure will be used.
%
%          Output variables
%  none
%
%     Copyright J. V. Mansbridge, CSIRO, june 30 1993

global HPOP POSNEG_N POSNEG_P

% Put up a plot contours button.

%plot_cont = menu('Do you want contours to be plotted?', 'yes', 'no');

% Calculate the number of colormap rows that are negative & positive
% assuming a 64 row colormap.  These values are used in the posneg
% colormap where all negative values are dark gray and all positive
% ones a lighter gray.  Note that because because the colormap has a
% finite number of rows then some values very near to zero can be
% mapped to the wrong shade of gray.

if val_min < 0 & val_max > 0
  POSNEG_N = fix(64 - 63*val_max/(val_max - val_min));
  POSNEG_P = 64 - POSNEG_N;
elseif val_min < 0
  POSNEG_N = 64;
  POSNEG_P =  0;
else
  POSNEG_N =  0;
  POSNEG_P = 64;
end

% Initialise the position of the window.

if position(1) < 0
  position(1) = 100;
end
if position(2) < 0
  position(2) = 100;
end
if position(3) < 0
  position(3) = 900;
end
if position(4) < 0
  position(4) = 800;
end
width = position(3);
height = position(4);

% Draw a legend.  This shows how the colors used in the plot relate to
% the range of posible values of mat.

if ifig > 0
  figure(ifig);
else
  handle_fig = figure;
end
set(gcf, 'Position', position);
axes('Position', [ 0.92 0.25 0.04 0.5 ]);
inc = (val_max - val_min )/9;
array = val_min:inc:val_max;
flat_pcolor( [0], array, array');
caxis([ val_min val_max ]);
set(gca, 'XTickLabels', [' '; ' '])
colormap(jet)

% Produce a pseudo color plot of the data.

axes('Position', [ 0.08 0.1 0.77 0.77 ]);
flat_pcolor(lon, lat, mat)
caxis([ val_min val_max ]);
colormap(jet);
hold on

% Put up a radio buttons box to enable the colormap to be reset.

HPOP = uicontrol('Style', 'Popup', 'String', ...
    'hsv|hot|cool|jet|pink|gray|posneg', 'Callback', 'color_fig');

% Put up a done button.

h2 = uimenu('Label', 'done', 'Callback', 'close');

% Put up a plot contours button.

plot_cont = menu('Do you want contours to be plotted?', 'yes', 'no');

% Draw labelled, black contours if required.

if plot_cont == 1
  [ cs, handle_cont ] = contour(lon, lat, mat, cont_val);
  set(handle_cont, 'Color', [ 0, 0, 0 ]);
  clabel(cs, 'manual');
end

hold off