function hndl = imagem(varargin)

%IMAGEM  Display a regular matrix map as an image
%
%  IMAGEM(map,maplegend) allows the display of regular matrix
%  maps as images.  As such, the displayed map is a Platte Carre
%  projection.  This projection produces significant distortion at the
%  poles.  IMAGEM produces quick displays of matrix maps, but
%  it is generally not recommended for final output due
%  to the distortion of the image display.  A regular matrix map is
%  defined using map and maplegend.
%
%  IMAGEM(map,maplegend,'PropertyName',PropertyValue,...) uses the
%  specified image properties to display the map.
%
%  h = IMAGEM(...) returns the handle of the image object displayed.
%
%  See also MESHM, SURFM, SURFACEM

%  Copyright 1996-2000 Systems Planning and Analysis, Inc. and The MathWorks, Inc.
%  Written by:  E. Byrns, E. Brown
%   $Revision: 1.10 $    $Date: 2000/01/18 02:03:31 $


string = [];
if nargin < 2
     error('Incorrect number of arguments')

else
     map = varargin{1};     maplegend = varargin{2};
	 varargin(1:2) = [];
end

%  Compute the graticule

[lat,lon] = imgrat(map,maplegend);

%  Make sure that the axes are not a map axes

if ismap(gca);  error('Image displays do not go in map axes');   end

%  Display the map

hndl0 = image(lon,lat,map);

%  Set the necessary properties of the axes

set(gca,'Ydir','Normal');

%  Set properties if necessary

if ~isempty(varargin);  set(hndl0,varargin{:});  end

xlabel('Longitude'); ylabel('Latitude');

%  Set handle return argument if necessary

if nargout == 1;   hndl = hndl0;    end


%************************************************************************
%************************************************************************
%************************************************************************


function [lat,lon] = imgrat(map,maplegend,lonlim)

%IMGRAT  Construct a graticule for a image map object
%
%  Purpose
%
%  IMGRAT constructs a graticule for a image map object.
%  These graticule points correspond to the centers of each
%  cell to be displayed using the imagem command.  The inputs
%  map and maplegend describe a regular matrix map.  The inputs
%  latlim and lonlim are 2 element vectors describing the latitude
%  and longitude limits of the map respectively.  The outputs are
%  vectors, where latgrat corresponds to the rows of map, and longrat
%  corresponds to the columns of map.
%
%  Synopsis
%
%       [latgrid,longrid] = imgrat(map,maplegend)
%       [latgrid,longrid] = imgrat(map,latlim,lonlim)
%
%       See also IMAGEM, MESHGRAT

%  Copyright 1996-2000 Systems Planning and Analysis, Inc. and The MathWorks, Inc.
%  Written by:  E. Byrns, E. Brown




if nargin < 2
	  error('Incorrect number of arguments')

elseif nargin == 2

     if ndims(map) > 2
         error('Input map can not have pages')
     elseif ~isequal(sort(size(maplegend)),[1 3])
         error('Input maplegend must be a 3 element vector')
     end

%  Get the map dimensions

	 [r,c] = size(map);
     rows = 1:r;    cols = 1:c;

%  Get the limits of the map

     [latlim,lonlim] = limitm(map,maplegend);

%  Compute the latitude and longitude of the row/col data
%  Assume that each point is in the center of the specified
%  cell (hence the use of delta/2 below).  The center of the
%  cell is what the imagem (image) command expects.

     delta = 1/maplegend(1);
     lat   = min(latlim) + (rows-1)*delta + delta/2;
     lon   = min(lonlim) + (cols-1)*delta + delta/2;

elseif nargin == 3

	 npts = size(map);
     latlim = maplegend;

	 if any([ndims(latlim)  ndims(lonlim)] > 2)
	      error('Input vectors can not contain pages')
	 end

	 if length(latlim) ~= 2         %  Enforce two element vectors
	      latlim = [min(latlim) max(latlim)];
	 end
	 if length(lonlim) ~= 2         %  Enforce two element vectors
	      lonlim = [min(lonlim) max(lonlim)];
	 end

	 latlim = latlim + diff(latlim)*[0.5 -0.5]/npts(1);
	 lonlim = lonlim + diff(lonlim)*[0.5 -0.5]/npts(2);

	 lat = linspace(min(latlim), max(latlim), npts(1));
	 lon = linspace(min(lonlim), max(lonlim), npts(2));
end